@xenosystem/agent-interface-host 0.1.3

package/dist/subagents/HostTurnSubagentExecutionAdapter.d.ts

@@ -0,0 +1,78 @@
+import type { AgentHostClientIdentity, AgentTurnStartRequest } from '@xenosystem/agent-interface-contract';
+import type { SubagentExecutionAdapter } from './SubagentScheduler.js';
+import type { SubagentRun } from './subagentTypes.js';
+/**
+ * Run a subagent by starting a TURN on this host — ADE §5.2, step 6's execution half.
+ *
+ * 🔴 A subagent run IS a turn, and the evidence is in the shapes rather than in an argument:
+ * `AgentTurnStartRequest` already carries `subagentRunId`, and `AgentRuntimeEventEnvelope` already
+ * carries `subagentRunId` and `parentRunId`. The turn machinery was built expecting this adapter
+ * to exist. Nothing here invents a second execution path, which matters because a second one
+ * would need its own admission, its own deadlines and its own abandonment — and would drift from
+ * the ones the host already enforces.
+ *
+ * What that inherits, for free and on purpose:
+ *   - **admission** — a subagent turn counts against the same one-per-user budget as every other
+ *     surface's, so a fan-out cannot starve the human's own work;
+ *   - **deadlines** — `timeoutMs` is enforced by the host rather than by each adapter;
+ *   - **abandonment** — a runtime that ignores cancellation stops consuming capacity.
+ *
+ * 🔴 It reports terminal state from the HOST'S OWN terminal events, and that is only possible
+ * because `turn.execution.completed` exists. Before it, the protocol could say a turn FAILED and
+ * could say nothing about one that succeeded, so an adapter had to infer success by
+ * string-matching provider-specific runtime types — the exact hand-maintained-list shape that has
+ * broken this codebase repeatedly. A subagent whose success was inferred that way would silently
+ * hang the parent fan-out the day a provider named its completion event differently.
+ */
+export interface HostTurnSubagentExecutionAdapterOptions {
+    /** The host, as the narrow slice this adapter needs. Not the coordinator — see below. */
+    host: SubagentTurnHost;
+    /** Identity this adapter presents when starting turns. */
+    identity: AgentHostClientIdentity;
+    /**
+     * Chooses the runtime for a run. Injected rather than read from the run, because capability
+     * matching is `fleet.plan`'s job and duplicating it here would give the fleet two answers.
+     */
+    /**
+     * ⚠️ May return a PROMISE. Selection asks `fleet.plan`, which is a host round-trip, and the
+     * synchronous signature this once had could not express that — the composition satisfied it by
+     * casting the Promise to a plain object, so selection returned `undefined` on every run and every
+     * subagent failed with "No runtime could be selected".
+     */
+    selectProvider: (run: SubagentRun) => TurnSelection | undefined | Promise<TurnSelection | undefined>;
+    /** Optional per-run deadline. Absent means the host's own default governs. */
+    timeoutMsFor?: (run: SubagentRun) => number | undefined;
+}
+export interface TurnSelection {
+    providerId: string;
+    catalogRevision: string;
+    modelId: string;
+    reasoningOptionId?: string;
+}
+/**
+ * The slice of the host this adapter uses.
+ *
+ * 🔴 A PORT, not `AgentHostCoordinator`. Handed the whole coordinator, an execution adapter could
+ * cancel other surfaces' turns, mutate workspace state or answer elicitations — none of which are
+ * its business. The same reasoning the ACP lane's `coordinationPort` records: what a lane may do
+ * should be visible in the type it is given.
+ */
+export interface SubagentTurnHost {
+    request<M extends 'turn.start' | 'turn.cancel'>(method: M, input: M extends 'turn.start' ? AgentTurnStartRequest : TurnCancelInput): Promise<unknown>;
+    subscribe(listener: (event: {
+        type: string;
+        payload: unknown;
+    }) => void): () => void;
+}
+interface TurnCancelInput {
+    command: AgentTurnStartRequest['command'];
+    conversationId: string;
+    requestId: string;
+    reason?: string;
+}
+export declare const HOST_TURN_SUBAGENT_ADAPTER_ID = "host-turn-subagent-v1";
+export declare function createHostTurnSubagentExecutionAdapter(options: HostTurnSubagentExecutionAdapterOptions): SubagentExecutionAdapter & {
+    dispose: () => void;
+};
+export {};
+//# sourceMappingURL=HostTurnSubagentExecutionAdapter.d.ts.map

package/dist/subagents/HostTurnSubagentExecutionAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HostTurnSubagentExecutionAdapter.d.ts","sourceRoot":"","sources":["../../src/subagents/HostTurnSubagentExecutionAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,sCAAsC,CAAA;AAC7C,OAAO,KAAK,EACV,wBAAwB,EAEzB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,uCAAuC;IACtD,yFAAyF;IACzF,IAAI,EAAE,gBAAgB,CAAA;IACtB,0DAA0D;IAC1D,QAAQ,EAAE,uBAAuB,CAAA;IACjC;;;OAGG;IACH;;;;;OAKG;IACH,cAAc,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAA;IACpG,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAA;CACxD;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,CAAC,SAAS,YAAY,GAAG,aAAa,EAC5C,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,CAAC,SAAS,YAAY,GAAG,qBAAqB,GAAG,eAAe,GACtE,OAAO,CAAC,OAAO,CAAC,CAAA;IACnB,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACrF;AAED,UAAU,eAAe;IACvB,OAAO,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAA;IACzC,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,eAAO,MAAM,6BAA6B,0BAA0B,CAAA;AAEpE,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,wBAAwB,GAAG;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA2IpD"}

package/dist/subagents/HostTurnSubagentExecutionAdapter.js

@@ -0,0 +1,160 @@
+export const HOST_TURN_SUBAGENT_ADAPTER_ID = 'host-turn-subagent-v1';
+export function createHostTurnSubagentExecutionAdapter(options) {
+    /** requestId -> the run it belongs to, so a terminal event can be attributed. */
+    const launched = new Map();
+    let sequence = 0;
+    const unsubscribe = options.host.subscribe((event) => {
+        const outcome = terminalOutcomeOf(event.type);
+        if (!outcome)
+            return;
+        const payload = event.payload;
+        const requestId = typeof payload?.requestId === 'string' ? payload.requestId : undefined;
+        if (!requestId)
+            return;
+        const entry = launched.get(requestId);
+        if (!entry)
+            return;
+        // Removed BEFORE reporting: the scheduler may act on the terminal event synchronously, and a
+        // duplicate report would try to settle a run that is already settled.
+        launched.delete(requestId);
+        entry.context.terminal({
+            adapterId: HOST_TURN_SUBAGENT_ADAPTER_ID,
+            childRequestId: requestId,
+            status: outcome.status,
+            ...(outcome.error ? { error: outcome.error } : {}),
+        });
+    });
+    return {
+        id: HOST_TURN_SUBAGENT_ADAPTER_ID,
+        version: '1.0.0',
+        capabilities: ['turn.execution'],
+        async launch(run, context) {
+            const selection = await options.selectProvider(run);
+            if (!selection) {
+                // 🔴 Reported as a terminal FAILURE, never swallowed. A run that is launched and then
+                // silently not started sits in `running` until its lease expires, and the parent fan-out
+                // waits for a child that was never going to exist.
+                context.terminal({
+                    adapterId: HOST_TURN_SUBAGENT_ADAPTER_ID,
+                    status: 'failed',
+                    error: 'No runtime could be selected for this subagent run.',
+                });
+                return;
+            }
+            const requestId = run.childRequestId ?? `subagent-${run.id}-${++sequence}`;
+            const timeoutMs = options.timeoutMsFor?.(run);
+            launched.set(requestId, { run, context });
+            try {
+                const started = await options.host.request('turn.start', {
+                    command: {
+                        schemaVersion: 1,
+                        commandId: `subagent-launch-${run.id}-${sequence}`,
+                        // Keyed by the RUN, so a scheduler retry of the same run is a replay rather than a
+                        // second child doing the same work twice.
+                        idempotencyKey: `subagent-launch-${run.id}`,
+                        client: { ...options.identity },
+                    },
+                    conversationId: run.childConversationId,
+                    requestId,
+                    mode: 'development',
+                    selection: {
+                        providerId: selection.providerId,
+                        catalogRevision: selection.catalogRevision,
+                        modelId: selection.modelId,
+                        ...(selection.reasoningOptionId ? { reasoningOptionId: selection.reasoningOptionId } : {}),
+                    },
+                    prompt: run.objective,
+                    // Bounded by the parent at create time (`boundSubagentWorkspace`), so passing it here
+                    // cannot widen anything. Without it every child ran with no workspace at all, which
+                    // every lane resolves to read-only with no directory access — safe, and useless for
+                    // the editing work delegation exists to do.
+                    ...(run.workspace === undefined ? {} : { workspace: run.workspace }),
+                    subagentRunId: run.id,
+                    workspaceId: run.workspaceId,
+                    teamId: run.teamId,
+                    agentId: run.childAgentId,
+                    ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                });
+                // 🔴 A REFUSAL IS A RESULT, NOT AN EXCEPTION. `turn.start` resolves to
+                // `{ success: false, code, safeError }` when the host declines — no provider, no adapter,
+                // at capacity, a capability the lane cannot honour. Only catching `throw` meant a refused
+                // turn fell through to the heartbeat below and the run sat in `running` until its lease
+                // expired, with zero runtime events because no turn ever began.
+                //
+                // ⚠️ The comment fifteen lines above already described this exact outcome as the thing to
+                // avoid. It was checked for one of the two ways it can happen.
+                if (started && started.success === false) {
+                    launched.delete(requestId);
+                    context.terminal({
+                        adapterId: HOST_TURN_SUBAGENT_ADAPTER_ID,
+                        childRequestId: requestId,
+                        status: 'failed',
+                        error: started.safeError
+                            || `The host refused this subagent turn (${started.code || 'unknown reason'}).`,
+                    });
+                    return;
+                }
+            }
+            catch (error) {
+                launched.delete(requestId);
+                context.terminal({
+                    adapterId: HOST_TURN_SUBAGENT_ADAPTER_ID,
+                    childRequestId: requestId,
+                    status: 'failed',
+                    error: error instanceof Error ? error.message : 'The host refused this subagent turn.',
+                });
+                return;
+            }
+            // Only after the host accepted it. Heartbeating a turn that was refused would hold a lease
+            // for work nobody is doing.
+            context.heartbeat({
+                adapterId: HOST_TURN_SUBAGENT_ADAPTER_ID,
+                childRequestId: requestId,
+            });
+        },
+        async cancel(run) {
+            const requestId = run.childRequestId;
+            if (!requestId)
+                return;
+            // The entry stays until the host reports terminal: `turn.cancel` asks, and the honest
+            // record of what happened is the terminal event that follows.
+            await options.host.request('turn.cancel', {
+                command: {
+                    schemaVersion: 1,
+                    commandId: `subagent-cancel-${run.id}-${++sequence}`,
+                    idempotencyKey: `subagent-cancel-${run.id}-${sequence}`,
+                    client: { ...options.identity },
+                },
+                conversationId: run.childConversationId,
+                requestId,
+                reason: 'Subagent run cancelled.',
+            }).catch(() => undefined);
+        },
+        dispose() {
+            unsubscribe();
+            launched.clear();
+        },
+    };
+}
+/**
+ * Map a host turn's terminal event onto a run outcome.
+ *
+ * ⚠️ `abandoned` is reported as FAILED, not cancelled, and the distinction is the honest one: the
+ * host stopped tracking that turn and released its capacity, but it never claimed the work
+ * stopped. Recording it as `cancelled` would tell the parent the child was called off; `failed`
+ * says it did not deliver, which is what is actually known.
+ */
+function terminalOutcomeOf(type) {
+    if (type === 'turn.execution.completed')
+        return { status: 'completed' };
+    if (type === 'turn.execution.failed')
+        return { status: 'failed', error: 'The subagent turn failed.' };
+    if (type === 'turn.execution.abandoned') {
+        return {
+            status: 'failed',
+            error: 'The host stopped tracking this subagent turn; its runtime may still be running.',
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=HostTurnSubagentExecutionAdapter.js.map

package/dist/subagents/HostTurnSubagentExecutionAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HostTurnSubagentExecutionAdapter.js","sourceRoot":"","sources":["../../src/subagents/HostTurnSubagentExecutionAdapter.ts"],"names":[],"mappings":"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"}

package/dist/subagents/SubagentRunService.d.ts

@@ -0,0 +1,103 @@
+import type { CapabilityMatchRequest, CancelSubagentRunRequest, ClaimSubagentRunRequest, CreateSubagentRunRequest, HeartbeatSubagentRunRequest, ListSubagentRunsRequest, RecoverExpiredSubagentRunsRequest, SubagentAgentStatus, SubagentCapabilityMatch, SubagentRun, SubagentSchedulerRecoverySnapshot, UpdateSubagentRunRequest } from './subagentTypes.js';
+export declare class SubagentRunService {
+    readonly storePath: string;
+    /**
+     * ⚠️ The default is the REAL user's home, and a host that runs isolated must not use it.
+     * `readonly` and public so `getSubagentRunService` can refuse a second, conflicting store.
+     */
+    constructor(storePath?: string);
+    createRun(request: CreateSubagentRunRequest): {
+        success: boolean;
+        run?: SubagentRun;
+        error?: string;
+    };
+    updateRun(request: UpdateSubagentRunRequest): {
+        success: boolean;
+        run?: SubagentRun;
+        error?: string;
+    };
+    claimNextRun(request: ClaimSubagentRunRequest): {
+        success: boolean;
+        run?: SubagentRun;
+        error?: string;
+    };
+    heartbeatRun(request: HeartbeatSubagentRunRequest): {
+        success: boolean;
+        run?: SubagentRun;
+        error?: string;
+    };
+    cancelRun(request: CancelSubagentRunRequest): {
+        success: boolean;
+        run?: SubagentRun;
+        error?: string;
+    };
+    recoverExpiredRuns(request?: RecoverExpiredSubagentRunsRequest): {
+        success: boolean;
+        recovered: number;
+        failed: number;
+        timedOut: number;
+        stale: number;
+        runs: SubagentRun[];
+        error?: string;
+    };
+    getRun(id: string): {
+        success: boolean;
+        run?: SubagentRun;
+        error?: string;
+    };
+    listRuns(request?: ListSubagentRunsRequest): {
+        success: boolean;
+        runs: SubagentRun[];
+        error?: string;
+    };
+    getDurableRecoverySnapshot(request?: RecoverExpiredSubagentRunsRequest): {
+        success: boolean;
+        snapshot?: SubagentSchedulerRecoverySnapshot;
+        error?: string;
+    };
+    getAgentStatus(agentId: string): {
+        success: boolean;
+        status?: SubagentAgentStatus;
+        error?: string;
+    };
+    matchCapabilities(request: CapabilityMatchRequest): {
+        success: boolean;
+        capabilityMatch?: SubagentCapabilityMatch;
+        error?: string;
+    };
+    private load;
+    private save;
+    private readStoreFile;
+    private backupPath;
+    private preserveCorruptStore;
+    private atomicWrite;
+}
+/**
+ * The ONE subagent run store for this process.
+ *
+ * 🔴 A SINGLETON ON PURPOSE, and that is why the path is configured here rather than by
+ * constructing a private instance. `SubagentScheduler` and `TeamAgentRouter` both default their
+ * service parameter to this function, so a composition holding its own instance while they hold
+ * the singleton would create runs in one store and launch them from another.
+ *
+ * ⚠️ The default path is the real user's home. A host running with its own home — a dev
+ * profile, a test, CI — must pass `storePath` on the FIRST call, before anything else resolves
+ * the singleton. Until 2026-08-18 nothing did, so an isolated host wrote its subagent runs into
+ * the operator's actual `~/.xeno`, and two hosts shared one roster.
+ */
+/**
+ * Drop the process-wide instance so the next `getSubagentRunService` can open a different home.
+ *
+ * 🔴 FOR TESTS ONLY, and the guard above is why it must exist rather than why it should not.
+ * That guard is correct — two homes in one process is a real misconfiguration and silently serving
+ * the wrong one would present as runs that vanish. But it left a suite that composes several hosts,
+ * each with its own `mkdtemp` home, unable to run at all: `composeHostHeadless.test.ts` was RED from
+ * the day the guard landed (2026-08-18), failing 9 of 11 cases with the guard's own error.
+ *
+ * ⚠️ Calling this from production code is the bug the guard exists to catch, not a way around
+ * it — a running host has exactly one home for its whole life. It is exported separately, named
+ * unmistakably, and touches nothing but the singleton reference.
+ */
+export declare function resetSubagentRunServiceForTests(): void;
+export declare function getSubagentRunService(storePath?: string): SubagentRunService;
+//# sourceMappingURL=SubagentRunService.d.ts.map

package/dist/subagents/SubagentRunService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubagentRunService.d.ts","sourceRoot":"","sources":["../../src/subagents/SubagentRunService.ts"],"names":[],"mappings":"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"}