|
| 1 | +import { |
| 2 | + assertCommandPlatformExecution, |
| 3 | + type CommandPlatformExecution, |
| 4 | +} from '@agent-device/contracts/command-platform-execution'; |
| 5 | +import type { DispatchedCommand } from '@agent-device/contracts/command'; |
| 6 | +import type { RefFrameEffect } from '@agent-device/contracts/replay'; |
| 7 | +import { isReadOnlyFindAction, parseFindArgs } from '@agent-device/selectors'; |
| 8 | +import { resolveSettingsRuntimePlan } from '@agent-device/contracts/platform-runtime-operations'; |
| 9 | +import type { DaemonCommandDescriptor } from './daemon-command-descriptor.ts'; |
| 10 | +import type { RecordingEffect } from './types.ts'; |
| 11 | + |
| 12 | +export const NO_PLATFORM_EXECUTION = { kind: 'none' } as const; |
| 13 | +// Host-scoped platform work (ADR 0019): the descriptor consumes a neutral typed host service and |
| 14 | +// binds no device runtime of its own. |
| 15 | +export const HOST_PLATFORM_EXECUTION = { kind: 'host' } as const; |
| 16 | + |
| 17 | +/** |
| 18 | + * Structural on purpose: the gate must see an *absent* discriminator, and the |
| 19 | + * registry's raw descriptor type — which forbids that — lives in this module's |
| 20 | + * consumer. |
| 21 | + */ |
| 22 | +type PlatformExecutionDeclarationSite = { |
| 23 | + readonly name: string; |
| 24 | + readonly platformExecution?: unknown; |
| 25 | +}; |
| 26 | + |
| 27 | +/** |
| 28 | + * ADR 0019 §6: every descriptor declares its platform-execution mode explicitly. |
| 29 | + * An undeclared discriminator is a registry-load error, so a command cannot |
| 30 | + * acquire platform execution by omission. |
| 31 | + * |
| 32 | + * This gate sees one descriptor at a time. Platform execution delegated to |
| 33 | + * another command is covered by the CLI-route dominance gate in |
| 34 | + * `__tests__/platform-execution-cli-route.test.ts`. |
| 35 | + */ |
| 36 | +export function readDeclaredPlatformExecution( |
| 37 | + descriptor: PlatformExecutionDeclarationSite, |
| 38 | +): CommandPlatformExecution { |
| 39 | + const declared = descriptor.platformExecution; |
| 40 | + if (declared === undefined) { |
| 41 | + throw new TypeError( |
| 42 | + `Command descriptor "${descriptor.name}" must declare platformExecution (none, host, inventory, or device-runtime); there is no registry-entry default`, |
| 43 | + ); |
| 44 | + } |
| 45 | + assertCommandPlatformExecution(declared); |
| 46 | + return declared; |
| 47 | +} |
| 48 | + |
| 49 | +// #2016: a plain `close` (no app-target positional) has nothing to close via |
| 50 | +// flags, so it's the only close shape eligible for the sessionless |
| 51 | +// no-lease-anywhere admission bypass in request-admission.ts. `close <app>` |
| 52 | +// resolves its device straight from flags when there's no session and must |
| 53 | +// stay behind full lease/tenant admission. |
| 54 | +export const resolvePlainCloseLeaseAdmissionExemption = ( |
| 55 | + req: DispatchedCommand, |
| 56 | +): { kind: 'unconditional' } | undefined => |
| 57 | + (req.positionals?.length ?? 0) === 0 ? { kind: 'unconditional' } : undefined; |
| 58 | + |
| 59 | +export const resolveDeferredProviderAppCatalogLeaseAdmissionExemption: NonNullable< |
| 60 | + DaemonCommandDescriptor['sessionlessLeaseAdmissionExemption'] |
| 61 | +> = (req) => { |
| 62 | + const provider = req.flags?.leaseProvider; |
| 63 | + return req.flags?.leaseId === undefined && |
| 64 | + typeof provider === 'string' && |
| 65 | + (req.flags?.platform === 'android' || req.flags?.platform === 'ios') |
| 66 | + ? { kind: 'provider-app-catalog', provider } |
| 67 | + : undefined; |
| 68 | +}; |
| 69 | + |
| 70 | +// ADR 0014 request-sensitive ref-frame resolvers. The action is the leading |
| 71 | +// positional (see keyboard/alert daemon writers in src/commands/system/index.ts |
| 72 | +// and src/commands/capture/alert.ts). Only the read-only status probes preserve |
| 73 | +// the frame; every mutating subaction crosses a device side effect. |
| 74 | +// |
| 75 | +// keyboard actions are status/get/dismiss/enter/return (src/commands/system/ |
| 76 | +// runtime/system.ts): status/get inspect, while dismiss hides the keyboard and |
| 77 | +// enter/return dispatch a real return key. Anything other than a read is |
| 78 | +// classified may-invalidate (the honest superset for unknown subactions). |
| 79 | +const KEYBOARD_READ_ONLY_ACTIONS = new Set(['status', 'get']); |
| 80 | +export const keyboardRefFrameEffect = (req: DispatchedCommand): RefFrameEffect => |
| 81 | + readOnlySubactionRefFrameEffect(req, KEYBOARD_READ_ONLY_ACTIONS, 'status'); |
| 82 | + |
| 83 | +// alert actions are get/wait/accept/dismiss: get/wait read, accept/dismiss act. |
| 84 | +const ALERT_READ_ONLY_ACTIONS = new Set(['get', 'wait']); |
| 85 | +export const alertRefFrameEffect = (req: DispatchedCommand): RefFrameEffect => |
| 86 | + readOnlySubactionRefFrameEffect(req, ALERT_READ_ONLY_ACTIONS, 'get'); |
| 87 | + |
| 88 | +export const keyboardRecordingEffect = (req: DispatchedCommand): RecordingEffect => |
| 89 | + readOnlySubactionRecordingEffect(req, KEYBOARD_READ_ONLY_ACTIONS, 'status'); |
| 90 | + |
| 91 | +export const alertRecordingEffect = (req: DispatchedCommand): RecordingEffect => |
| 92 | + readOnlySubactionRecordingEffect(req, ALERT_READ_ONLY_ACTIONS, 'get'); |
| 93 | + |
| 94 | +export const findRecordingEffect = (req: DispatchedCommand): RecordingEffect => { |
| 95 | + try { |
| 96 | + return isReadOnlyFindAction(parseFindArgs(req.positionals ?? []).action) |
| 97 | + ? 'observes-app' |
| 98 | + : 'mutates-app'; |
| 99 | + } catch { |
| 100 | + // Invalid requests never record, but classify the unknown shape conservatively. |
| 101 | + return 'mutates-app'; |
| 102 | + } |
| 103 | +}; |
| 104 | + |
| 105 | +export const clipboardRecordingEffect = (req: DispatchedCommand): RecordingEffect => |
| 106 | + readOnlySubactionRecordingEffect(req, new Set(['read']), ''); |
| 107 | + |
| 108 | +// A settings request reads only when it names a readable setting with nothing after it; every other |
| 109 | +// settings request changes device state — including `settings text-size <category>`, which names the |
| 110 | +// same word and performs a mutation. The leg comes from the same resolver the daemon admits with, so |
| 111 | +// the classification and the operation it selects are one declaration rather than two that a test |
| 112 | +// holds together. |
| 113 | +const settingsRequestReads = (req: DispatchedCommand): boolean => |
| 114 | + resolveSettingsRuntimePlan(req.positionals).kind === 'read'; |
| 115 | + |
| 116 | +export const settingsRecordingEffect = (req: DispatchedCommand): RecordingEffect => |
| 117 | + settingsRequestReads(req) ? 'observes-app' : 'mutates-app'; |
| 118 | + |
| 119 | +export const settingsRefFrameEffect = (req: DispatchedCommand): RefFrameEffect => |
| 120 | + settingsRequestReads(req) ? 'preserve' : 'may-invalidate'; |
| 121 | + |
| 122 | +function readOnlySubactionRefFrameEffect( |
| 123 | + req: DispatchedCommand, |
| 124 | + readOnlyActions: ReadonlySet<string>, |
| 125 | + defaultAction: string, |
| 126 | +): RefFrameEffect { |
| 127 | + return readOnlyActions.has((req.positionals?.[0] ?? defaultAction).toLowerCase()) |
| 128 | + ? 'preserve' |
| 129 | + : 'may-invalidate'; |
| 130 | +} |
| 131 | + |
| 132 | +function readOnlySubactionRecordingEffect( |
| 133 | + req: DispatchedCommand, |
| 134 | + readOnlyActions: ReadonlySet<string>, |
| 135 | + defaultAction: string, |
| 136 | +): RecordingEffect { |
| 137 | + return readOnlyActions.has((req.positionals?.[0] ?? defaultAction).toLowerCase()) |
| 138 | + ? 'observes-app' |
| 139 | + : 'mutates-app'; |
| 140 | +} |
0 commit comments