Skip to content

Commit 9ebc58a

Browse files
authored
Merge 1dd596a into d24fb18
2 parents d24fb18 + 1dd596a commit 9ebc58a

17 files changed

Lines changed: 1132 additions & 60 deletions

‎packages/contracts/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -376,6 +376,10 @@
376376
"types": "./src/platform-runtime-host.ts",
377377
"default": "./src/platform-runtime-host.ts"
378378
},
379+
"./platform-runtime-shutdown": {
380+
"types": "./src/platform-runtime-shutdown.ts",
381+
"default": "./src/platform-runtime-shutdown.ts"
382+
},
379383
"./platform-runtime-operations": {
380384
"types": "./src/platform-runtime-operations.ts",
381385
"default": "./src/platform-runtime-operations.ts"
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import { AppError, normalizeError, type NormalizedError } from '@agent-device/kernel/errors';
2+
import type { RuntimeOwnerRef } from './platform-runtime.ts';
3+
4+
export type PlatformRuntimeShutdownFailure = Readonly<{
5+
owner: RuntimeOwnerRef;
6+
error: NormalizedError;
7+
}>;
8+
9+
export type PlatformRuntimeShutdownErrorDetails = Readonly<{
10+
reason: 'platform-owner-shutdown-failed';
11+
failures: readonly PlatformRuntimeShutdownFailure[];
12+
}>;
13+
14+
type OwnerShutdownFailure = Readonly<{ owner: RuntimeOwnerRef; error: unknown }>;
15+
16+
/** Preserves every owner failure without granting authority to retry cleanup or release a claim. */
17+
export function createPlatformRuntimeShutdownError(
18+
failures: readonly [OwnerShutdownFailure, ...OwnerShutdownFailure[]],
19+
): AppError {
20+
const details: PlatformRuntimeShutdownErrorDetails = {
21+
reason: 'platform-owner-shutdown-failed',
22+
failures: failures.map(({ owner, error }) => ({ owner, error: normalizeError(error) })),
23+
};
24+
const message = `Platform runtime owner shutdown failed: ${details.failures
25+
.map(
26+
({ owner, error }) =>
27+
`${owner.kind === 'local-family' ? owner.family : `${owner.provider} (${owner.instance})`}: ${error.message}`,
28+
)
29+
.join('; ')}`;
30+
return new AppError(
31+
'COMMAND_FAILED',
32+
message,
33+
{
34+
...details,
35+
hint: 'Cleanup is unconfirmed. Inspect the owner failures and verify claim ownership before attempting recovery.',
36+
retriable: false,
37+
},
38+
failures.length === 1
39+
? failures[0].error
40+
: new AggregateError(
41+
failures.map(({ error }) => error),
42+
'Original platform runtime owner shutdown failures',
43+
),
44+
);
45+
}

‎packages/contracts/src/platform-runtime.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,12 @@ export type DeviceBindingRequest = Readonly<{
204204
export type DeviceRuntimeGateway<Operations extends object> = Readonly<{
205205
inspectFacts(device: DeviceInfo): Promise<RuntimeFacts<Operations>>;
206206
bind(request: DeviceBindingRequest): Promise<DeviceBinding<Operations>>;
207+
/**
208+
* Attempts each owner once; repeated calls share the attempt and the same rejection.
209+
* Owner failures reject with COMMAND_FAILED and details.reason platform-owner-shutdown-failed;
210+
* details.failures preserves each owner and error. After shutdown starts, bind and inspectFacts
211+
* reject with COMMAND_FAILED and details.reason runtime-gateway-shut-down.
212+
*/
207213
shutdown(): Promise<void>;
208214
/** Package-coordinated durable lifecycle phases used for startup recovery and daemon shutdown. */
209215
applicationLifecycle?: ApplicationLifecycleResourceLifecycle;

0 commit comments

Comments
 (0)