11import { isDeepLinkTarget } from './open-target.ts' ;
2- import {
3- LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE ,
4- LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE ,
5- } from './launch-console.ts' ;
2+ import { LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE } from './launch-console.ts' ;
63import type { DeviceInfo } from '@agent-device/kernel/device' ;
74import { isIosFamily } from '@agent-device/kernel/device' ;
85import { AppError } from '@agent-device/kernel/errors' ;
@@ -26,6 +23,13 @@ import type {
2623export type ApplicationLifecycleInteractorBinding = Readonly < {
2724 device : DeviceInfo ;
2825 signal : AbortSignal ;
26+ /**
27+ * True only for a local owner bound to an iOS simulator it controls, i.e. an owner whose direct
28+ * app launch can read simctl's console PTY. The shared open refuses `--launch-console` without
29+ * it, so a provider-backed simulator — same device shape, provider-owned lifecycle — refuses
30+ * rather than silently ignoring the request.
31+ */
32+ supportsLocalSimulatorLaunch : boolean ;
2933 resolveInteractor (
3034 execution : ApplicationLifecycleExecution ,
3135 appBundleId ?: string ,
@@ -84,6 +88,10 @@ function bindApplicationLifecycleInteractor(
8488 return Object . freeze ( {
8589 device,
8690 signal,
91+ // A local owner bound to an iOS simulator controls simctl and can read the console PTY;
92+ // a provider owner never can, whatever the device shape says.
93+ supportsLocalSimulatorLaunch :
94+ ownership === 'local' && isIosFamily ( device ) && device . kind === 'simulator' ,
8795 resolveInteractor : async ( execution , appBundleId ) => {
8896 const runner = applicationLifecycleRunnerContext ( execution , appBundleId , signal ) ;
8997 if ( ownership === 'local' ) return await params . resolveLocalInteractor ( device , runner ) ;
@@ -129,6 +137,108 @@ export function bindProviderApplicationLifecycleInteractor(
129137 } ) ;
130138}
131139
140+ // The owner-admission refusal is private to the admission rule that raises it — the shared message
141+ // home's façade must stay exhaustive, and an unused public message is dead code.
142+ const LAUNCH_CONSOLE_UNADMITTED_MESSAGE =
143+ '--launch-console is supported only for a local iOS simulator app launch; this session owner cannot capture the launch console' ;
144+
145+ /**
146+ * The request-shape rule for the launch-only open options: what only `positionals` and `execution`
147+ * can answer, checked once and enforced twice — by {@link assertOpenAdmitted} before the lifecycle
148+ * touches the device, and by {@link invokeApplicationOpen} for its own folded and follow-up calls.
149+ * One helper per positional shape: no app target, a URL pair, or a single deep-link app target.
150+ * `--launch-console` and `--clear-app-state` act on the app the open launches, so they refuse every
151+ * shape but a direct app target, before any close, clear, or launch runs.
152+ */
153+ function assertOpenRequestShape (
154+ positionals : readonly string [ ] ,
155+ execution : ApplicationLifecycleExecution ,
156+ ) : void {
157+ if ( positionals . length > 2 ) {
158+ throw new AppError ( 'INVALID_ARGS' , 'open accepts at most two arguments: <app|url> [url]' ) ;
159+ }
160+ const app = positionals [ 0 ] ;
161+ const url = positionals [ 1 ] ;
162+ if ( app === undefined ) {
163+ assertOpenDeviceOnlyRequest ( execution ) ;
164+ return ;
165+ }
166+ if ( url !== undefined ) {
167+ assertOpenUrlPairRequest ( app , url , execution ) ;
168+ return ;
169+ }
170+ if ( isDeepLinkTarget ( app ) ) {
171+ assertOpenDeepLinkAppRequest ( execution ) ;
172+ }
173+ }
174+
175+ function assertOpenDeviceOnlyRequest ( execution : ApplicationLifecycleExecution ) : void {
176+ if ( execution . launchConsole ) {
177+ throw new AppError ( 'INVALID_ARGS' , '--launch-console requires an app target' ) ;
178+ }
179+ if ( execution . launchArgs && execution . launchArgs . length > 0 ) {
180+ throw new AppError ( 'INVALID_ARGS' , '--launch-args requires an app target' ) ;
181+ }
182+ }
183+
184+ function assertOpenUrlPairRequest (
185+ app : string ,
186+ url : string ,
187+ execution : ApplicationLifecycleExecution ,
188+ ) : void {
189+ if ( isDeepLinkTarget ( app ) ) {
190+ throw new AppError (
191+ 'INVALID_ARGS' ,
192+ 'open <app> <url> requires an app target as the first argument' ,
193+ ) ;
194+ }
195+ if ( ! isDeepLinkTarget ( url ) ) {
196+ throw new AppError ( 'INVALID_ARGS' , 'open <app> <url> requires a valid URL target' ) ;
197+ }
198+ if ( execution . launchConsole ) {
199+ throw new AppError ( 'INVALID_ARGS' , LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE ) ;
200+ }
201+ }
202+
203+ function assertOpenDeepLinkAppRequest ( execution : ApplicationLifecycleExecution ) : void {
204+ if ( execution . launchConsole ) {
205+ throw new AppError ( 'INVALID_ARGS' , LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE ) ;
206+ }
207+ if ( execution . clearAppState ) {
208+ throw new AppError (
209+ 'INVALID_ARGS' ,
210+ 'Clearing app state requires an app target, not a deep link.' ,
211+ ) ;
212+ }
213+ }
214+
215+ /**
216+ * One admission step for the open command, called by every `openApplication` entry before the
217+ * lifecycle touches the device. It enforces the owner capability and the request shape of the
218+ * launch-only options: `--launch-console` needs an owner that declared it can read simctl's console
219+ * PTY, and every other owner — any provider, any non-iOS-simulator device — is refused with
220+ * `UNSUPPORTED_OPERATION` and a typed reason; the positional and URL-pair checks in
221+ * {@link assertOpenRequestShape} then refuse a launch-only option on a request that cannot carry
222+ * one, with `INVALID_ARGS`. The owner answers first because where an option works at all is the
223+ * more actionable refusal. So no refusal — of an owner that cannot honor an option or of a
224+ * malformed launch-only request — ever follows a relaunch close, a runner stop, or a runtime-hint
225+ * write. The canonical open keeps the same shape rule for its own folded and follow-up dispatches,
226+ * plus the one refusal that needs the platform itself.
227+ */
228+ export function assertOpenAdmitted (
229+ binding : Pick < ApplicationLifecycleInteractorBinding , 'device' | 'supportsLocalSimulatorLaunch' > ,
230+ execution : ApplicationLifecycleExecution ,
231+ positionals : readonly string [ ] ,
232+ ) : void {
233+ if ( execution . launchConsole && ! binding . supportsLocalSimulatorLaunch ) {
234+ throw new AppError ( 'UNSUPPORTED_OPERATION' , LAUNCH_CONSOLE_UNADMITTED_MESSAGE , {
235+ reason : 'launch-console-owner-unadmitted' ,
236+ deviceId : binding . device . id ,
237+ } ) ;
238+ }
239+ assertOpenRequestShape ( positionals , execution ) ;
240+ }
241+
132242/**
133243 * Canonical direct open semantics used only after a package lifecycle binding has admitted the
134244 * operation. It intentionally has no device-resolution or platform-mechanics branches.
@@ -144,11 +254,11 @@ export async function invokeApplicationOpen(
144254 } > ,
145255) : Promise < ApplicationLaunchReport | void > {
146256 const { device, positionals, execution } = params ;
147- assertOpenPositionals ( positionals ) ;
257+ assertOpenRequestShape ( positionals , execution ) ;
148258 const app = positionals [ 0 ] ;
149259 const url = positionals [ 1 ] ;
150260 if ( ! app ) {
151- await invokeDeviceOpen ( params ) ;
261+ await params . interactor . openDevice ( ) ;
152262 return ;
153263 }
154264 assertOpenDeviceSupport ( device , execution ) ;
@@ -165,29 +275,12 @@ type DirectOpenParameters = Readonly<{
165275 terminateRunningApp ?: boolean ;
166276} > ;
167277
168- function assertOpenPositionals ( positionals : readonly string [ ] ) : void {
169- if ( positionals . length > 2 ) {
170- throw new AppError ( 'INVALID_ARGS' , 'open accepts at most two arguments: <app|url> [url]' ) ;
171- }
172- }
173-
174- async function invokeDeviceOpen ( params : DirectOpenParameters ) : Promise < void > {
175- if ( params . execution . launchConsole ) {
176- throw new AppError ( 'INVALID_ARGS' , '--launch-console requires an app target' ) ;
177- }
178- if ( params . execution . launchArgs && params . execution . launchArgs . length > 0 ) {
179- throw new AppError ( 'INVALID_ARGS' , '--launch-args requires an app target' ) ;
180- }
181- await params . interactor . openDevice ( ) ;
182- }
183-
184278function assertOpenDeviceSupport (
185279 device : DeviceInfo ,
186280 execution : ApplicationLifecycleExecution ,
187281) : void {
188- if ( execution . launchConsole && ( ! isIosFamily ( device ) || device . kind !== 'simulator' ) ) {
189- throw new AppError ( 'UNSUPPORTED_OPERATION' , LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE ) ;
190- }
282+ // The launch-only options were admitted by shape and by owner before this point
283+ // (assertOpenAdmitted); what remains here is the one refusal that needs the platform itself.
191284 if ( device . platform === 'linux' && execution . launchArgs && execution . launchArgs . length > 0 ) {
192285 throw new AppError ( 'UNSUPPORTED_OPERATION' , '--launch-args is not supported on Linux.' ) ;
193286 }
@@ -198,18 +291,6 @@ async function invokeApplicationUrlOpen(
198291 app : string ,
199292 url : string ,
200293) : Promise < ApplicationLaunchReport | void > {
201- if ( isDeepLinkTarget ( app ) ) {
202- throw new AppError (
203- 'INVALID_ARGS' ,
204- 'open <app> <url> requires an app target as the first argument' ,
205- ) ;
206- }
207- if ( ! isDeepLinkTarget ( url ) ) {
208- throw new AppError ( 'INVALID_ARGS' , 'open <app> <url> requires a valid URL target' ) ;
209- }
210- if ( params . execution . launchConsole ) {
211- throw new AppError ( 'INVALID_ARGS' , LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE ) ;
212- }
213294 return await params . interactor . open ( app , {
214295 activity : params . execution . activity ,
215296 appBundleId : params . appBundleId ,
@@ -224,16 +305,7 @@ async function invokeApplicationTargetOpen(
224305 app : string ,
225306) : Promise < ApplicationLaunchReport | void > {
226307 const { execution, interactor } = params ;
227- if ( execution . launchConsole && isDeepLinkTarget ( app ) ) {
228- throw new AppError ( 'INVALID_ARGS' , LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE ) ;
229- }
230308 if ( execution . clearAppState ) {
231- if ( isDeepLinkTarget ( app ) ) {
232- throw new AppError (
233- 'INVALID_ARGS' ,
234- 'Clearing app state requires an app target, not a deep link.' ,
235- ) ;
236- }
237309 await interactor . setSetting ( 'clear-app-state' , 'clear' , app ) ;
238310 }
239311 return await interactor . open ( app , {
@@ -302,6 +374,7 @@ async function openDirectApplication(
302374 input : OpenApplicationInput ,
303375) : Promise < OpenApplicationOutcome > {
304376 const { binding } = params ;
377+ assertOpenAdmitted ( binding , input . execution , input . positionals ) ;
305378 const interactor = await binding . resolveInteractor ( input . execution , input . appBundleId ) ;
306379 if ( params . closeBeforeRelaunch && input . relaunch && input . target !== undefined ) {
307380 await invokeApplicationClose ( {
0 commit comments