Apple Intents & Shortcuts

Every published mashin machine can surface as a native Apple capability. Siri can run it. Shortcuts can compose it. Spotlight can find it. The Share Sheet can invoke it. This happens automatically: you write mashinTalk, and the mashin app emits the App Intent.

How it works

The mashin native app (iOS, macOS, watchOS) reads your cell’s machine registry and generates App Intents at runtime. Each machine’s accepts and responds with sections map directly to the App Intent parameter and result types.

.mashin file                    App Intent                    Apple surface
┌────────────────┐              ┌────────────────┐            ┌────────────────┐
│ machine email   │  auto-emit  │ RunMachine      │  register  │ Siri           │
│   accepts       │ ──────────► │   Intent        │ ─────────► │ Shortcuts      │
│     subject     │             │   parameters:   │            │ Spotlight      │
│     body        │             │     subject,    │            │ Share Sheet    │
│   responds with │             │     body        │            │ Focus Filters  │
│     priority    │             │   result:       │            │ Action Button  │
└────────────────┘              │     priority    │            └────────────────┘
                                └────────────────┘

You never write a Swift class. The mashin app handles the App Intent registration, parameter mapping, and result conversion.

Platform coverage

Platform	Capabilities
iOS	Siri voice, Shortcuts app, Share Sheet, Spotlight, widgets, Live Activities, Focus Filters, Action Button, Lock Screen
macOS	Siri, Shortcuts app, Spotlight, menu bar, Share menu, Quick Actions (Finder right-click), Services menu
watchOS	Siri voice, complications, Smart Stack, Action Button (Ultra)
CarPlay	Siri voice, dashboard cards, suggestion prompts

Machine-to-Intent mapping

Inputs become parameters

Each field in accepts becomes a Shortcuts parameter:

machine summarize_document

  accepts
    document as file, is required
    length as text                      // optional, default "medium"
    language as text                    // optional, default "en"

  responds with
    summary as text
    word_count as number

This generates an App Intent with:

• document: A file parameter (Shortcuts shows a file picker)
• length: An optional text parameter (Shortcuts shows a text field with autocomplete)
• language: An optional text parameter

Outputs become results

The responds with section maps to the Intent result. Shortcuts can pass results to subsequent actions:

• text fields become String results
• number fields become numeric results
• boolean fields become toggle results
• list fields become array results (Shortcuts can iterate)
• map fields become dictionary results

Governance carries over

The ensures section determines what the machine can do when invoked via Shortcuts. If a machine is not allowed to send email, it cannot send email when triggered by Siri. The governance boundary is the same regardless of the invocation surface.

Siri integration

Any machine with a clear accepts and responds with contract works with Siri:

"Hey Siri, run my daily brief"
"Hey Siri, classify this email as urgent"
"Hey Siri, summarize this document"

The mashin app registers machine names and descriptions as Siri phrases. Users can customize trigger phrases in Settings > Siri & Search.

Voice input

For machines that accept text input, Siri’s speech-to-text feeds directly into the accepts parameters. For machines that accept file input, Siri prompts the user to select a file.

Conversational patterns

Machines with multiple required inputs trigger a conversational flow:

User: "Hey Siri, triage my email"
Siri: "What's the subject?"
User: "Invoice from Acme Corp"
Siri: "What's the body?"
User: "Payment due in 30 days"
Siri: "Priority: high. Category: finance. Routed to accounting."

Shortcuts app

Machines appear in the Shortcuts app as actions. Users can:

• Drag machine actions into Shortcut workflows
• Connect machine outputs to other actions (Files, Mail, Calendar, etc.)
• Set up automations (time-based, location-based, NFC tag, etc.)
• Share Shortcuts that include mashin machines

Composing machines in Shortcuts

A Shortcut can chain multiple mashin machines:

1. “Get unread emails” (mashin machine)
2. For each email, “Classify email” (mashin machine)
3. If priority is “urgent”, “Send Teams notification” (mashin machine)
4. Log results to a file (native Files action)

Each machine runs through mashin’s governance. The behavioral ledger records each invocation, even when triggered from Shortcuts.

Automation triggers

Shortcuts automations can trigger mashin machines on:

• Time of day (“Run daily brief at 8am”)
• Location (“Summarize nearby restaurants when I arrive at the airport”)
• NFC tag (“Run inventory check when I scan this tag”)
• Focus mode changes (“Pause notification machines when I enter Do Not Disturb”)
• App open/close
• Email received (Mail automation)
• Message received

Spotlight

Machines are indexed in Spotlight. Type a machine name or description in Spotlight and it appears as a search result. Selecting it opens the mashin app at that machine, or runs it directly if it has no required inputs.

Share Sheet

Machines that accept file, text, or url inputs register in the system Share Sheet:

machine analyze_image

  accepts
    image as file, is required

  responds with
    description as text
    tags as list

This machine appears when sharing an image from Photos, Safari, Files, or any app. The user taps “Analyze with mashin” and the machine runs.

On macOS, these also appear as Quick Actions in Finder’s right-click menu and in the Services menu.

watchOS

Complications

Machines that produce simple outputs (a number, a short text, a status) can drive watch complications:

• A “portfolio value” machine updates a complication on the watch face
• A “daily tasks remaining” machine shows a count
• A “system health” machine shows a green/yellow/red indicator

Smart Stack

Machine results appear as cards in the watchOS Smart Stack. The system surfaces them based on relevance: time of day, location, recent usage.

Voice-first

On the watch, interaction is primarily voice. “Hey Siri, run my daily brief” is the primary interface. Results are spoken back or shown as a compact summary.

CarPlay

Dashboard

Machines with short text or numeric results can appear as CarPlay dashboard cards:

• “Daily schedule” shows your next three meetings
• “Traffic summary” shows conditions on your commute
• “Message triage” shows urgent message count

Siri in CarPlay

Voice interaction works the same as on other platforms. “Hey Siri, summarize my inbox” runs the machine and speaks the result.

Suggestion prompts

CarPlay can suggest machine actions based on context:

• When driving to work: “Run commute brief?”
• When parked at a client site: “Check client prep notes?”

Building machines for Apple surfaces

Design for voice

Machines invoked through Siri should:

• Accept simple inputs (text, numbers, selections)
• Return concise results (one or two sentences for voice readback)
• Have clear, speakable names (“daily brief”, not “email_triage_v2_final”)

Design for glanceability

Machines driving widgets, complications, or Live Activities should:

• Return a primary value (number or short text) and a secondary value
• Complete quickly (widgets refresh on a schedule; long-running machines miss the window)
• Handle errors gracefully (show a sensible fallback, not an error trace)

Design for composition

Machines that will be used in Shortcuts should:

• Have typed inputs and outputs (so Shortcuts can wire them together)
• Use common types (text, number, file, list, boolean)
• Include optional inputs with sensible defaults (so the machine works standalone or in a chain)

Local execution preference

When a machine can run locally (using on-device models, local files, or cached data), it should. Apple’s App Intents framework has strict timeout requirements:

Surface	Timeout
Siri	~10 seconds
Shortcuts (foreground)	~30 seconds
Shortcuts (background automation)	~30 seconds
Widget refresh	~15 seconds
Complications	~10 seconds

Machines that call cloud LLMs or external APIs should either respond within these limits or use the await pattern: start the work, return a “processing” status, and notify when complete.

The socket API

The mashin native app communicates with the local cell via a Unix domain socket. This is the same socket that the CLI uses. When an App Intent fires, the app sends a run command over the socket, waits for the result, and returns it to the system.

Siri ──► App Intent ──► mashin app ──► Unix socket ──► cell ──► machine
                                                                    │
Siri ◄── result ◄──── mashin app ◄── Unix socket ◄── cell ◄────────┘

The socket path is ~/.mashin/cells/{cell_name}/mashin.sock. The protocol is JSON-RPC.

Privacy and governance

Every invocation through an Apple surface is governed identically to a CLI or API invocation:

• Permissions are checked (ensures section)
• The behavioral ledger records the invocation, including the source (siri, shortcuts, widget, etc.)
• Budget limits are enforced
• On-device execution keeps data local; the ledger proves nothing left the device

This is the fundamental value proposition on Apple platforms: governed intelligence on the most personal computer. The governance boundary and the device boundary align.