App Intents are a compile-time contract. Xcode runs an "Extract App Intents
Metadata" step over each target and writes Metadata.appintents into the app
bundle; Siri, Spotlight and the Shortcuts app read only that. There is no
runtime registration API, so nothing a Flutter app declares from Dart can ever
become an App Intent on its own.
That means os_intents must generate Swift. The only open question is where
it may put it, and the answer changes the shape of the whole package:
| Outcome | Where generated Swift goes | What install looks like |
|---|---|---|
| Plan A | plugin module, Sources/os_intents_ios/ |
flutter pub get. Nothing else. |
| Plan A′ | plugin module + one bridge file in Runner | pub get plus a single generated file added to the app target |
| Plan B | app's Runner target | CLI must patch project.pbxproj — fragile across Xcode versions |
Writing the emitter before knowing this would mean writing it twice, so the probe runs first.
Two builds of one app, differing by a single compile flag.
Control — ProbeRunnerIntent. Declared in ios/Runner/AppDelegate.swift,
i.e. compiled directly into the app target. This is the arrangement every
existing Flutter App Intents package forces on its users, so it must show up in
both builds. If it does not, the probe is broken and no conclusion about plugin
modules is valid.
Subject — ProbePodIntent. Declared in
packages/os_intents_ios/ios/os_intents_ios/Sources/os_intents_ios/ProbeAppIntents.swift,
inside the plugin module. It is deliberately never referenced from Dart or
from the Runner target — the AppShortcutsProvider lists only the control
intent. The only thing that can pull it into the bundle is metadata extraction
itself.
Variant A. No bridge. Does an intent in the plugin module reach
Metadata.appintents on its own?
Variant B. Runner declares
struct ProbeAppPackage: AppIntentsPackage {
static var includedPackages: [any AppIntentsPackage.Type] { [OsIntentsPackage.self] }
}which is Apple's documented way for an app to opt into intents vended by a
framework or Swift package. Toggled with -D OS_INTENTS_BRIDGE in
OTHER_SWIFT_FLAGS.
SWIFT_ACTIVE_COMPILATION_CONDITIONS would have been the more idiomatic switch,
but Flutter's Runner target sets it in project.pbxproj, where it overrides
anything an .xcconfig says. OTHER_SWIFT_FLAGS is unset at target level, so
the xcconfig wins — that is why the probe uses it.
The probe app's deployment target is raised to iOS 16.0 (App Intents' minimum) so that availability cannot be confounded with visibility.
./probe/risk1_metadata/run_probe.shArtifacts land in probe/risk1_metadata/probe-results/:
build-A.log,build-B.log— full build outputmetadata-A.txt,metadata-B.txt— everyMetadata.appintentsbundle found inRunner.app, plus which intent names occur anywhere in the bundle
Flutter now generates plugins in Swift Package Manager layout
(ios/<name>/Package.swift + Sources/) alongside a CocoaPods podspec pointing
at the same sources. Which integration is active changes how a plugin's code is
linked, and therefore may change this answer. The probe records the Flutter and
Xcode versions in its output for that reason; re-run it when either changes.
PLAN A. Measured 2026-07-30 on Flutter 3.44.8 (stable) / Xcode 26.0,
iOS simulator, debug build, Swift Package Manager integration (no Pods
directory was produced).
control (ProbeRunnerIntent, Runner target): in metadata ✓
variant A (ProbePodIntent, plugin module): in metadata ✓
variant B (ProbePodIntent, plugin module): in metadata ✓
An intent declared inside a Flutter plugin module reaches
Metadata.appintents/extract.actionsdata on its own — no AppIntentsPackage
bridge, no Xcode surgery, and without being referenced from Dart or from the app
target. The entry is complete, not incidental:
"ProbePodIntent": {
"fullyQualifiedTypeName": "os_intents_ios.ProbePodIntent",
"identifier": "ProbePodIntent",
"mangledTypeName": "14os_intents_ios14ProbePodIntentV",
"isDiscoverable": true,
"openAppWhenRun": false,
"title": { "key": "Probe Pod Intent" },
"descriptionMetadata": {
"descriptionText": { "key": "Declared inside the os_intents_ios plugin module." }
},
"availabilityAnnotations": { "LNPlatformNameIOS": { "introducedVersion": "16.0" } }
}Variant B shows the bridge is unnecessary but harmless. Do not adopt it as the
baseline anyway: AppIntentsPackage is iOS 17+, while AppIntent itself is
iOS 16+ — using it as the mechanism would silently cost every iOS 16 user the
feature. (The first run of this probe failed to compile for exactly that reason.)
The generator writes Swift into os_intents_ios/ios/os_intents_ios/Sources/.
flutter pub get is the entire install step, and os_intents_cli install loses
most of its reason to exist — it shrinks to App Group provisioning and the
Android/Gradle wiring.
The probe measured intent discoverability, and that is all it measured.
Metadata.appintents/root.ssu.yaml — the Siri phrase training data — contains
only ProbeRunnerIntent:
intents:
- metadata:
name: ProbeRunnerIntent_0
title: Probe Runner Intent
corpuses:
training:
- locale: Base
utterances:
- Run runner probe in ${+applicationName}That is expected here (the probe's AppShortcutsProvider deliberately lists only
the control intent), so it is not evidence that a provider must live in the
app target — the probe simply never tested it. Apple documents at most one
AppShortcutsProvider per app, which makes it the likely exception to Plan A.
Practical reading for now:
| capability | source needed |
|---|---|
| Shortcuts app, Spotlight, agent invocation | plugin module — confirmed |
| spoken "Hey Siri …" phrases | needs AppShortcutsProvider — untested |
Measured 2026-07-30, same toolchain. ./probe/risk1_metadata/run_probe_1b.sh.
The plugin module always declares ProbePodShortcuts ("Run pod probe in
<app>"); the Runner's own provider is gated by -D PROBE_RUNNER_SHORTCUTS.
variant P — plugin phrases in root.ssu.yaml: absent ✗
variant D — plugin phrases, app also has a provider: absent ✗
variant D — app phrases: PRESENT ✓
Variant P (only the plugin declares a provider) — root.ssu.yaml is not
produced at all, and extract.actionsdata reports:
autoShortcutProviderMangledName: (none)
autoShortcuts: []
Variant D (both declare one) — the app's provider is selected and the plugin's is ignored:
autoShortcutProviderMangledName: 6Runner14ProbeShortcutsV
autoShortcuts: [{ "actionIdentifier": "ProbeRunnerIntent",
"phraseTemplates": [{"key": "Run runner probe in ${applicationName}"}] }]
The mangled name resolves to module Runner — the extractor picks the provider
from the app's own module and nowhere else.
Note the failure mode: variant D built cleanly. A provider declared in a plugin is not rejected, not warned about, just silently dropped. Anyone shipping this without the probe would have found out from bug reports.
| capability | where it must be declared | status |
|---|---|---|
| intents, entities, queries — Shortcuts app, Spotlight, agents | plugin module | free (Plan A) |
| spoken "Hey Siri …" phrases | app target, exactly one provider | needs the CLI |
So os_intents_cli install survives, but its iOS job shrinks to one thing:
write ios/Runner/OsIntentsShortcuts.swift and add that single file to the
Runner target in project.pbxproj. After the first install the file is only
rewritten in place, so the pbxproj is touched exactly once per project.
Two consequences the generator has to respect:
- One provider per app is a hard limit. If the host app already declares an
AppShortcutsProvider, emitting a second is not an error — it is a silent loss. The generator must detect an existing provider and merge its shortcuts into the generated one rather than adding a rival. doctorneeds a check for this, because nothing else in the toolchain will tell the user their phrases went nowhere: readMetadata.appintents/extract.actionsdatafrom the built app and report the selectedautoShortcutProviderMangledNameand the phrase count.
An honest fallback if pbxproj patching proves fragile: ship the provider as a
documented 8-line file the user adds to Runner once by hand. Everything else
still comes from pub get.