Repository navigation
Expand file tree
/
Copy pathruntime-admission.ts
More file actions
168 lines (157 loc) · 6.85 KB
/
Copy pathruntime-admission.ts
File metadata and controls
168 lines (157 loc) · 6.85 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
import type {
BoundDeviceRuntime,
RuntimeOperationKey,
RuntimeOperationUnavailability,
RuntimeUse,
} from '@agent-device/contracts/platform-runtime';
import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
import type { DeviceInfo } from '@agent-device/kernel/device';
import { AppError } from '@agent-device/kernel/errors';
import type {
BindDeviceRuntime,
InspectDeviceRuntimeFacts,
RuntimeAdmissionBindings,
} from './request-runtime-binding.ts';
import { ensureBoundDeviceReady } from './request-runtime-binding.ts';
import type { DeviceReadyOptions } from './device-ready.ts';
import type { DaemonCommandContext } from './context.ts';
import type { DaemonRequest } from './daemon-request.ts';
import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
import type { SessionState } from './session-state.ts';
import { type DaemonFailureResponse, errorResponse } from '@agent-device/kernel/contracts';
/** Builds the failure a command reports when its exact device cell does not admit an operation. */
export type UnavailableRuntimeResponse = (
unavailable: RuntimeOperationUnavailability,
) => DaemonFailureResponse;
export type AdmittedRuntimeGateway =
| Readonly<{ type: 'response'; response: DaemonFailureResponse }>
| Readonly<{ type: 'admitted'; bind: BindDeviceRuntime }>;
export type RuntimeAdmission<Use> =
| Readonly<{ type: 'response'; response: DaemonFailureResponse }>
| Readonly<{ type: 'runtime'; runtime: BoundDeviceRuntime<Use> }>;
export type RuntimeAdmissionRequest = RuntimeAdmissionBindings &
Readonly<{
/** Command wording for the default unsupported message, e.g. `open`, `runtime port-reverse`. */
command: string;
device: DeviceInfo;
required: readonly RuntimeOperationKey<PlatformRuntimeOperations>[];
unavailableResponse?: UnavailableRuntimeResponse;
readiness?: DeviceReadyOptions;
}>;
export type { RuntimeAdmissionBindings };
/**
* The one facts-admission seam every migrated command route shares. It performs exactly one
* side-effect-free inspection and hands back the binding gateway only once the exact device cell
* admits every operation the caller's plan will invoke, so no route can dispatch first and
* discover a missing sibling operation afterwards.
*/
export async function admitRuntimeOperations(
request: RuntimeAdmissionRequest,
): Promise<AdmittedRuntimeGateway> {
const facts = await requireFactsInspection(request.inspectFacts)(request.device);
for (const operation of request.required) {
const fact = facts.operations[operation];
if (fact.available) continue;
const response = request.unavailableResponse
? request.unavailableResponse(fact)
: errorResponse(
'UNSUPPORTED_OPERATION',
`${request.command} is not supported on this device`,
undefined,
fact.hint ? { hint: fact.hint } : undefined,
);
return { type: 'response', response };
}
return { type: 'admitted', bind: requireDeviceBinding(request.bindDevice) };
}
/**
* What the generic dispatcher hands a leaf's execution closure alongside the bound runtime: the
* resolved command context, the live session it runs on, and the request that asked for it. Leaf
* owners that verify their own effect read the session's stored tree as their baseline and read the
* request's flags for the caller's observation opt-out; both reads stay read-only.
*/
export type GenericExecutionDispatch = Readonly<{
dispatchContext: DaemonCommandContext;
session: SessionState;
request: DaemonRequest;
}>;
/**
* Facts admission plus binding for a route whose plan resolves to a single use. Routes that pick
* one of several exactly-typed uses admit with {@link admitRuntimeOperations} and bind their
* selected use themselves.
*/
export async function admitRuntimeUse<
const Required extends readonly RuntimeOperationKey<PlatformRuntimeOperations>[],
const Preferred extends readonly Exclude<
RuntimeOperationKey<PlatformRuntimeOperations>,
Required[number]
>[],
const Conditional extends readonly Exclude<
RuntimeOperationKey<PlatformRuntimeOperations>,
Required[number] | Preferred[number]
>[],
>(
request: Omit<RuntimeAdmissionRequest, 'required'> &
Readonly<{
use: RuntimeUse<PlatformRuntimeOperations, Required, Preferred, Conditional>;
}>,
): Promise<
RuntimeAdmission<RuntimeUse<PlatformRuntimeOperations, Required, Preferred, Conditional>>
> {
const admitted = await admitRuntimeOperations({ ...request, required: request.use.required });
if (admitted.type === 'response') return admitted;
const runtime = await admitted.bind(request.device, request.use);
if (request.readiness !== undefined) {
await ensureBoundDeviceReady(runtime, request.readiness);
}
return { type: 'runtime', runtime };
}
/**
* The generic-route admit-then-bind shape every single-use leaf shares (focus, back, home,
* orientation, tv-remote): admit the exact owner's fact, narrow the binding, and defer execution
* to a closure the dispatcher invokes with its resolved context. One shared shape here is what
* keeps five near-identical leaves from drifting into five copies of the same wiring.
*/
export async function resolveBoundGenericRuntime<
const Required extends readonly RuntimeOperationKey<PlatformRuntimeOperations>[],
const Preferred extends readonly Exclude<
RuntimeOperationKey<PlatformRuntimeOperations>,
Required[number]
>[],
const Conditional extends readonly Exclude<
RuntimeOperationKey<PlatformRuntimeOperations>,
Required[number] | Preferred[number]
>[],
>(
request: Omit<RuntimeAdmissionRequest, 'required'> &
Readonly<{ use: RuntimeUse<PlatformRuntimeOperations, Required, Preferred, Conditional> }>,
execute: (
runtime: BoundDeviceRuntime<
RuntimeUse<PlatformRuntimeOperations, Required, Preferred, Conditional>
>,
dispatch: GenericExecutionDispatch,
) => Promise<Record<string, unknown> | void>,
): Promise<ResolvedGenericExecution> {
const admission = await admitRuntimeUse(request);
if (admission.type === 'response') return { ok: false, response: admission.response };
const runtime = admission.runtime;
return {
ok: true,
execute: async ({ dispatchContext, session, request: dispatchRequest }) =>
await execute(runtime, { dispatchContext, session, request: dispatchRequest }),
};
}
function requireFactsInspection(
inspectFacts: InspectDeviceRuntimeFacts | undefined,
): InspectDeviceRuntimeFacts {
if (inspectFacts) return inspectFacts;
throw new AppError('COMMAND_FAILED', 'Device runtime facts inspection is unavailable.', {
reason: 'runtime-gateway-missing',
});
}
function requireDeviceBinding(bindDevice: BindDeviceRuntime | undefined): BindDeviceRuntime {
if (bindDevice) return bindDevice;
throw new AppError('COMMAND_FAILED', 'Device runtime binding is unavailable.', {
reason: 'runtime-gateway-missing',
});
}