@tangle-network/braid 0.1.2 → 0.2.0

package/dist/adapters/runtime/tangle-retained-interactive-contract.js

@@ -0,0 +1,135 @@
+import { canonicalDigest } from '../../domain/canonical.js';
+import { publicMaterializationReceipt } from '../../domain/materialization-receipt.js';
+import { stableProviderId } from './production-backend-common.js';
+export function assertInteractiveProvider(prepared) {
+    const interactive = prepared.capabilities.interactiveAgent;
+    if (interactive?.start !== true ||
+        interactive.control !== true ||
+        interactive.status !== true ||
+        interactive.attach !== true ||
+        interactive.reattach !== true ||
+        interactive.sendPrompt !== true ||
+        interactive.input !== true ||
+        interactive.resize !== true ||
+        interactive.stop !== true) {
+        throw new Error('Tangle retained connection does not support exact interactive agents');
+    }
+}
+export function interactiveRunCapabilities(prepared) {
+    const { interactions: _interactions, ...environment } = prepared.capabilities;
+    return Object.freeze({
+        streaming: { live: true, replay: true, detach: true, turnIdempotency: true },
+        sessions: { continue: true, messages: false },
+        controls: { cancel: true, steer: false, queue: false, status: true, recreate: true },
+        events: { stableIdentity: true, sequence: true, cursor: true },
+        usage: false,
+        environment,
+    });
+}
+export function interactiveMaterializationReceipt(prepared) {
+    return publicMaterializationReceipt({
+        provider: prepared.provider.name,
+        backend: 'environment-provider',
+        surface: 'interactive-agent',
+        lifecycle: 'retained',
+        execution: 'agent-runtime-retained-interactive',
+        cleanup: 'explicit',
+        continuity: 'session',
+        idleTtlSeconds: prepared.idleTtlSeconds,
+        model: prepared.model,
+        runner: prepared.runner,
+    });
+}
+export function interactiveEnvironment(prepared, runId, idempotencyKey = interactiveEnvironmentIdempotencyKey(runId), profile = prepared.profile) {
+    return {
+        profile,
+        backend: prepared.runner,
+        name: stableProviderId('braid-interactive-', runId),
+        metadata: {
+            owner: 'braid',
+            lifecycle: 'retained',
+            surface: 'interactive-agent',
+        },
+        idempotencyKey,
+    };
+}
+export function interactiveIdempotencyKey(runId) {
+    return stableProviderId('interactive-braid-', runId);
+}
+function interactiveEnvironmentIdempotencyKey(runId) {
+    return stableProviderId('env-braid-interactive-', runId);
+}
+export function requireAdmissionRecorder(recorder) {
+    if (recorder === undefined) {
+        throw new Error('Retained Tangle interactive execution requires a durable admission recorder');
+    }
+    return (admission) => recorder(admission);
+}
+export function requireRecoveryReceipt(input) {
+    if (input === undefined) {
+        throw new Error('Interactive intent recovery requires the original run receipt');
+    }
+    return input;
+}
+export function requireInteractiveAdmission(value) {
+    switch (value?.phase) {
+        case 'interactive_intent':
+        case 'interactive_environment':
+        case 'interactive_started':
+            return value;
+        default:
+            throw new Error('Interactive recovery requires a canonical interactive admission');
+    }
+}
+export function interactiveAdmissionOrUndefined(value) {
+    if (value === undefined)
+        return undefined;
+    return requireInteractiveAdmission(value);
+}
+export function interactiveSessionId(admission) {
+    if (admission.phase === 'interactive_intent')
+        return admission.sessionId;
+    return admission.phase === 'interactive_environment'
+        ? admission.request.run.sessionId
+        : admission.ref.run.sessionId;
+}
+export function assertInteractiveAdmissionMatchesInput(admission, input) {
+    if (admission.phase === 'interactive_started') {
+        assertStartedAdmissionMatchesInput(admission, input);
+        return;
+    }
+    const sessionId = interactiveSessionId(admission);
+    if (input.providerSessionId !== undefined && input.providerSessionId !== sessionId) {
+        throw new Error('Interactive provider session conflicts with the saved admission');
+    }
+    if (input.controlRef !== undefined) {
+        throw new Error('Interactive control reference conflicts with the saved admission');
+    }
+}
+export function assertStartedAdmissionMatchesInput(admission, input) {
+    if (input.providerSessionId !== undefined &&
+        input.providerSessionId !== admission.ref.run.sessionId) {
+        throw new Error('Interactive provider session conflicts with the saved process reference');
+    }
+    if (input.controlRef !== undefined &&
+        canonicalDigest(input.controlRef) !== canonicalDigest(admission.ref.run)) {
+        throw new Error('Interactive control reference conflicts with the saved process reference');
+    }
+}
+export function assertExactControl(input, actual) {
+    if ((input.providerSessionId !== undefined || input.controlRef !== undefined) &&
+        actual === undefined) {
+        throw new Error('Interactive exact control reference is unavailable');
+    }
+    if (input.providerSessionId !== undefined &&
+        actual !== undefined &&
+        input.providerSessionId !== actual.sessionId) {
+        throw new Error('Interactive provider session conflicts with the saved run');
+    }
+    if (input.controlRef !== undefined &&
+        actual !== undefined &&
+        canonicalDigest(input.controlRef) !== canonicalDigest(actual)) {
+        throw new Error('Interactive control reference conflicts with the saved run');
+    }
+}
+//# sourceMappingURL=tangle-retained-interactive-contract.js.map

package/dist/adapters/runtime/tangle-retained-interactive-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tangle-retained-interactive-contract.js","sourceRoot":"","sources":["../../../src/adapters/runtime/tangle-retained-interactive-contract.ts"],"names":[],"mappings":"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"}

package/dist/adapters/runtime/tangle-retained-interactive-execution.d.ts

@@ -0,0 +1,35 @@
+import type { AgentExactRunControlRef } from '@tangle-network/agent-interface';
+import type { RuntimeEventEnvelope } from '../../domain/runtime-events.js';
+import type { CancelRunInput, ControlAcknowledgement, ExecuteTurnInput, ExecutionAdmission, ExecutionPort, ProviderRunSnapshot, RunCapabilities } from '../../ports/execution.js';
+import type { NativeInteractiveRunBroker } from './native-interactive-run-broker.js';
+import type { PreparedTangleRetainedConnection } from './production-tangle-sandbox-backend.js';
+import { type TangleInteractiveRecoveryInput } from './tangle-retained-interactive-contract.js';
+export interface TangleRetainedInteractiveExecutionOptions {
+    readonly resolve: (input: ExecuteTurnInput) => Promise<PreparedTangleRetainedConnection>;
+    readonly recover?: (input: ExecuteTurnInput) => Promise<PreparedTangleRetainedConnection>;
+    readonly broker: Pick<NativeInteractiveRunBroker, 'open' | 'settle'>;
+    readonly holderId?: string;
+}
+/** Runs one exact Tangle coding-agent TUI through Runtime's durable APIs. */
+export declare class TangleRetainedInteractiveExecutionPort implements ExecutionPort {
+    #private;
+    readonly admissionMode: 'async';
+    constructor(options: TangleRetainedInteractiveExecutionOptions);
+    capabilities: (input: ExecuteTurnInput) => RunCapabilities | Promise<RunCapabilities>;
+    admit(input: ExecuteTurnInput): Promise<ExecutionAdmission>;
+    streamTurn(input: ExecuteTurnInput): AsyncIterable<RuntimeEventEnvelope>;
+    reconnect(input: TangleInteractiveRecoveryInput): AsyncIterable<RuntimeEventEnvelope>;
+    status(input: TangleInteractiveRecoveryInput): Promise<ProviderRunSnapshot | null>;
+    detachRun(input: {
+        readonly runId: string;
+        readonly operationId: string;
+        readonly providerSessionId?: string;
+        readonly controlRef?: AgentExactRunControlRef;
+        readonly cursor?: string;
+        readonly signal?: AbortSignal;
+    } & TangleInteractiveRecoveryInput): Promise<ControlAcknowledgement>;
+    cancelRun(input: CancelRunInput & {
+        readonly signal?: AbortSignal;
+    }): Promise<ControlAcknowledgement>;
+}
+//# sourceMappingURL=tangle-retained-interactive-execution.d.ts.map

package/dist/adapters/runtime/tangle-retained-interactive-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tangle-retained-interactive-execution.d.ts","sourceRoot":"","sources":["../../../src/adapters/runtime/tangle-retained-interactive-execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAgB,MAAM,iCAAiC,CAAA;AAgB5F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAA;AAC1E,OAAO,KAAK,EACV,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,eAAe,EAChB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAA;AAEpF,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,wCAAwC,CAAA;AAE9F,OAAO,EAaL,KAAK,8BAA8B,EACpC,MAAM,2CAA2C,CAAA;AAWlD,MAAM,WAAW,yCAAyC;IACxD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,gCAAgC,CAAC,CAAA;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,gCAAgC,CAAC,CAAA;IACzF,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAA;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAOD,6EAA6E;AAC7E,qBAAa,sCAAuC,YAAW,aAAa;;IAC1E,QAAQ,CAAC,aAAa,EAAG,OAAO,CAAS;IAYzC,YAAY,OAAO,EAAE,yCAAyC,EAK7D;IAED,YAAY,UAAW,gBAAgB,KAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CACL;IAEzE,KAAK,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAYhE;IAEM,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CAAC,oBAAoB,CAAC,CA+C9E;IAEM,SAAS,CAAC,KAAK,EAAE,8BAA8B,GAAG,aAAa,CAAC,oBAAoB,CAAC,CAwD3F;IAEK,MAAM,CAAC,KAAK,EAAE,8BAA8B,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAwBvF;IAEK,SAAS,CACb,KAAK,EAAE;QACL,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;QACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAA;QAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAC9B,GAAG,8BAA8B,GACjC,OAAO,CAAC,sBAAsB,CAAC,CA0BjC;IAEK,SAAS,CACb,KAAK,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACxD,OAAO,CAAC,sBAAsB,CAAC,CAsHjC;CAkNF"}

package/dist/adapters/runtime/tangle-retained-interactive-execution.js

@@ -0,0 +1,456 @@
+import { agentInteractiveSessionStopRequestDigest, canonicalCandidateDigest, } from '@tangle-network/agent-interface';
+import { claimRetainedInteractiveControl, reconnectRetainedInteractiveRun, recoverRetainedInteractiveRun, startRetainedInteractiveRun, } from '@tangle-network/agent-runtime/kernel';
+import { canonicalDigest } from '../../domain/canonical.js';
+import { canonicalAgentProfileDigestHex } from '../agent-interface/profile-runtime.js';
+import { safeExecutionId } from './production-backend-common.js';
+import { retainedExecutionKey } from './retained-execution-state.js';
+import { assertExactControl, assertInteractiveAdmissionMatchesInput, assertInteractiveProvider, assertStartedAdmissionMatchesInput, interactiveAdmissionOrUndefined, interactiveEnvironment, interactiveIdempotencyKey, interactiveMaterializationReceipt, interactiveRunCapabilities, requireAdmissionRecorder, requireInteractiveAdmission, requireRecoveryReceipt, } from './tangle-retained-interactive-contract.js';
+import { interactiveStatus, interactiveStatusDetail, observedEnvelope, partialInteractiveStatus, replayBoundary, terminalEnvelope, terminalOutcome, } from './tangle-retained-interactive-projection.js';
+/** Runs one exact Tangle coding-agent TUI through Runtime's durable APIs. */
+export class TangleRetainedInteractiveExecutionPort {
+    admissionMode = 'async';
+    #resolve;
+    #recover;
+    #broker;
+    #holderId;
+    #prepared = new Map();
+    #starting = new Map();
+    #handles = new Map();
+    #activeRuns = new Set();
+    #detachRequested = new Set();
+    #cancelledRuns = new Set();
+    constructor(options) {
+        this.#resolve = options.resolve;
+        this.#recover = options.recover;
+        this.#broker = options.broker;
+        this.#holderId = options.holderId ?? 'braid';
+    }
+    capabilities = (input) => this.#prepare(input).then((prepared) => interactiveRunCapabilities(prepared));
+    async admit(input) {
+        const prepared = await this.#prepare(input);
+        const capabilities = interactiveRunCapabilities(prepared);
+        const materializationReceipt = interactiveMaterializationReceipt(prepared);
+        return {
+            capabilities,
+            provider: prepared.provider.name,
+            materializationReceipt,
+            profileDigest: canonicalAgentProfileDigestHex(input.profile),
+            capabilitiesDigest: canonicalDigest(capabilities),
+            materializationDigest: canonicalDigest(materializationReceipt),
+        };
+    }
+    async *streamTurn(input) {
+        if (this.#cancelledRuns.has(input.runId))
+            return;
+        const prepared = await this.#prepare(input);
+        if (this.#cancelledRuns.has(input.runId))
+            return;
+        const lease = this.#broker.open(input.runId);
+        this.#activeRuns.add(input.runId);
+        let terminal = false;
+        try {
+            const handle = this.#handles.get(input.runId) ?? (await this.#startOnce(prepared, input));
+            this.#rememberHandle(input.runId, handle);
+            lease.publish(handle);
+            if (this.#detachRequested.has(input.runId))
+                this.#settleDetached(input.runId);
+            yield await observedEnvelope(input.runId, handle, prepared, 1);
+            const providerOutcome = await terminalOutcome(handle, input.signal);
+            if (providerOutcome !== undefined) {
+                terminal = true;
+                yield terminalEnvelope(input.runId, handle, prepared, providerOutcome, 2, this.#cancelledRuns.has(input.runId));
+                return;
+            }
+            const outcome = await lease.outcome(input.signal === undefined ? undefined : { signal: input.signal });
+            if (outcome.kind === 'detached')
+                return;
+            terminal = true;
+            yield terminalEnvelope(input.runId, handle, prepared, outcome, 2, this.#cancelledRuns.has(input.runId));
+        }
+        catch (error) {
+            lease.fail(error);
+            throw error;
+        }
+        finally {
+            this.#activeRuns.delete(input.runId);
+            if (terminal)
+                this.#forgetHandle(input.runId);
+            lease.close();
+        }
+    }
+    async *reconnect(input) {
+        const admission = requireInteractiveAdmission(input.retainedAdmission);
+        assertInteractiveAdmissionMatchesInput(admission, input);
+        const prepared = await this.#resolveRecovery(input, admission);
+        assertInteractiveProvider(prepared);
+        const lease = this.#broker.open(input.runId);
+        this.#activeRuns.add(input.runId);
+        let terminal = false;
+        try {
+            const handle = await this.#recoverHandle(prepared, input, admission);
+            if (handle === null)
+                return;
+            this.#rememberHandle(input.runId, handle);
+            this.#detachRequested.delete(input.runId);
+            lease.publish(handle);
+            const replayedSequence = replayBoundary(input, input.runId, handle);
+            if (replayedSequence < 1) {
+                yield await observedEnvelope(input.runId, handle, prepared, 1);
+            }
+            if (replayedSequence >= 2) {
+                terminal = true;
+                return;
+            }
+            const providerOutcome = await terminalOutcome(handle, input.signal);
+            if (providerOutcome !== undefined) {
+                terminal = true;
+                yield terminalEnvelope(input.runId, handle, prepared, providerOutcome, 2, this.#cancelledRuns.has(input.runId));
+                return;
+            }
+            const outcome = await lease.outcome(input.signal === undefined ? undefined : { signal: input.signal });
+            if (outcome.kind === 'detached')
+                return;
+            terminal = true;
+            yield terminalEnvelope(input.runId, handle, prepared, outcome, 2, this.#cancelledRuns.has(input.runId));
+        }
+        catch (error) {
+            lease.fail(error);
+            throw error;
+        }
+        finally {
+            this.#activeRuns.delete(input.runId);
+            if (terminal)
+                this.#forgetHandle(input.runId);
+            lease.close();
+        }
+    }
+    async status(input) {
+        const partial = interactiveAdmissionOrUndefined(input.retainedAdmission);
+        if (partial !== undefined)
+            assertInteractiveAdmissionMatchesInput(partial, input);
+        if (this.#handles.get(input.runId) === undefined &&
+            partial !== undefined &&
+            partial.phase !== 'interactive_started') {
+            return partialInteractiveStatus(input.runId, partial);
+        }
+        const handle = await this.#handleFor(input);
+        if (handle === null)
+            return null;
+        const status = await handle.status({
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        const mapped = interactiveStatus(status, this.#detachRequested.has(input.runId));
+        if (status.state === 'exited')
+            this.#forgetHandle(input.runId);
+        return {
+            runId: input.runId,
+            status: mapped,
+            sessionId: handle.ref.run.sessionId,
+            ...(status.state === 'unknown' ? { error: status.message, detail: status.message } : {}),
+            ...(status.state === 'exited' ? { detail: interactiveStatusDetail(status) } : {}),
+        };
+    }
+    async detachRun(input) {
+        const admission = interactiveAdmissionOrUndefined(input.retainedAdmission);
+        if (admission !== undefined)
+            assertInteractiveAdmissionMatchesInput(admission, input);
+        let handle = this.#handles.get(input.runId);
+        if (handle === undefined &&
+            !this.#prepared.has(input.runId) &&
+            !this.#starting.has(input.runId) &&
+            admission !== undefined &&
+            admission.phase !== 'interactive_started') {
+            this.#detachRequested.add(input.runId);
+            return { operationId: input.operationId, outcome: 'accepted', detail: 'detached' };
+        }
+        if (handle === undefined && !this.#prepared.has(input.runId)) {
+            handle = (await this.#handleFor(input)) ?? undefined;
+        }
+        else if (handle === undefined && this.#starting.has(input.runId)) {
+            handle = (await this.#handleFor(input)) ?? undefined;
+        }
+        this.#assertControl(input.runId, input.providerSessionId, input.controlRef, handle?.ref.run);
+        if (this.#detachRequested.has(input.runId)) {
+            return { operationId: input.operationId, outcome: 'already-applied', detail: 'detached' };
+        }
+        this.#detachRequested.add(input.runId);
+        this.#settleDetached(input.runId);
+        return { operationId: input.operationId, outcome: 'accepted', detail: 'detached' };
+    }
+    async cancelRun(input) {
+        if (this.#cancelledRuns.has(input.runId) && !this.#activeRuns.has(input.runId)) {
+            return { operationId: input.operationId, outcome: 'already-applied', detail: 'cancelled' };
+        }
+        const startInFlight = this.#starting.has(input.runId);
+        const controlSignal = startInFlight || input.signal?.aborted ? undefined : input.signal;
+        const { signal: _foregroundSignal, ...recoveryInputBase } = input;
+        const recoveryInput = {
+            ...recoveryInputBase,
+            ...(controlSignal === undefined ? {} : { signal: controlSignal }),
+        };
+        let handle = this.#handles.get(input.runId);
+        const admissionPhase = input.retainedAdmission?.phase;
+        const interactiveIntent = input.retainedAdmission?.phase === 'interactive_intent' ? input.retainedAdmission : undefined;
+        if (handle === undefined &&
+            !this.#starting.has(input.runId) &&
+            interactiveIntent !== undefined &&
+            input.controlRef === undefined) {
+            if (input.providerSessionId !== undefined &&
+                input.providerSessionId !== interactiveIntent.sessionId) {
+                return {
+                    operationId: input.operationId,
+                    outcome: 'rejected',
+                    detail: 'interactive-intent-provider-session-mismatch',
+                };
+            }
+            this.#cancelledRuns.add(input.runId);
+            this.#prepared.delete(input.runId);
+            this.#settleCancelled(input.runId);
+            return {
+                operationId: input.operationId,
+                outcome: 'accepted',
+                detail: 'cancelled-before-start',
+            };
+        }
+        if (handle === undefined &&
+            this.#prepared.has(input.runId) &&
+            !this.#starting.has(input.runId) &&
+            input.providerSessionId === undefined &&
+            input.controlRef === undefined &&
+            admissionPhase !== 'interactive_started') {
+            this.#cancelledRuns.add(input.runId);
+            this.#prepared.delete(input.runId);
+            this.#settleCancelled(input.runId);
+            return {
+                operationId: input.operationId,
+                outcome: 'accepted',
+                detail: 'cancelled-before-start',
+            };
+        }
+        if (handle === undefined && this.#starting.has(input.runId)) {
+            this.#cancelledRuns.add(input.runId);
+            try {
+                handle = (await this.#handleFor(recoveryInput)) ?? undefined;
+            }
+            catch {
+                return {
+                    operationId: input.operationId,
+                    outcome: 'unknown',
+                    detail: 'interactive-start-could-not-be-cancelled',
+                };
+            }
+        }
+        if (handle === undefined) {
+            try {
+                handle = (await this.#handleFor(recoveryInput)) ?? undefined;
+            }
+            catch {
+                return {
+                    operationId: input.operationId,
+                    outcome: 'unknown',
+                    detail: 'interactive-run-missing',
+                };
+            }
+        }
+        if (handle === undefined) {
+            return {
+                operationId: input.operationId,
+                outcome: 'unknown',
+                detail: 'interactive-run-missing',
+            };
+        }
+        this.#assertControl(input.runId, input.providerSessionId, input.controlRef);
+        const control = await claimRetainedInteractiveControl({
+            handle,
+            holderId: this.#holderId,
+            ...(controlSignal === undefined ? {} : { signal: controlSignal }),
+        });
+        const material = { operationId: input.operationId, ref: handle.ref, control };
+        const acknowledgement = await handle.stop({ ...material, requestDigest: agentInteractiveSessionStopRequestDigest(material) }, controlSignal === undefined ? undefined : { signal: controlSignal });
+        if (acknowledgement.status === 'accepted' || acknowledgement.status === 'replayed') {
+            this.#cancelledRuns.add(input.runId);
+            this.#settleCancelled(input.runId);
+            this.#forgetHandle(input.runId);
+            return {
+                operationId: input.operationId,
+                outcome: acknowledgement.status === 'replayed' ? 'already-applied' : 'accepted',
+                detail: acknowledgement.effect,
+            };
+        }
+        return {
+            operationId: input.operationId,
+            outcome: acknowledgement.status === 'conflict'
+                ? 'rejected'
+                : acknowledgement.status === 'unknown'
+                    ? 'unknown'
+                    : 'rejected',
+            detail: acknowledgement.effect,
+        };
+    }
+    async #start(prepared, input) {
+        const onAdmission = requireAdmissionRecorder(input.onRetainedAdmission);
+        return startRetainedInteractiveRun({
+            provider: prepared.provider,
+            environment: interactiveEnvironment(prepared, input.runId),
+            interactiveIdempotencyKey: interactiveIdempotencyKey(input.runId),
+            ...(input.text.trim() === '' ? {} : { initialPrompt: input.text }),
+            ...(input.workspaceRoot === undefined ? {} : { cwd: input.workspaceRoot }),
+            onAdmission,
+            signal: input.signal,
+        });
+    }
+    async #startOnce(prepared, input) {
+        const current = this.#starting.get(input.runId);
+        if (current !== undefined)
+            return current;
+        const starting = this.#start(prepared, input);
+        this.#starting.set(input.runId, starting);
+        starting.then(() => this.#clearStarting(input.runId, starting), () => this.#clearStarting(input.runId, starting));
+        return starting;
+    }
+    async #prepare(input) {
+        const current = this.#prepared.get(input.runId);
+        if (current !== undefined) {
+            if (current.key !== retainedExecutionKey(input, interactiveRunCapabilities(current.prepared))) {
+                throw new Error('Interactive run admission received a different request');
+            }
+            return current.prepared;
+        }
+        const prepared = await this.#resolve(input);
+        assertInteractiveProvider(prepared);
+        this.#prepared.set(input.runId, {
+            key: retainedExecutionKey(input, interactiveRunCapabilities(prepared)),
+            prepared,
+        });
+        return prepared;
+    }
+    async #recoverHandle(prepared, input, admission) {
+        if (admission.phase === 'interactive_started') {
+            assertStartedAdmissionMatchesInput(admission, input);
+            return reconnectRetainedInteractiveRun({
+                provider: prepared.provider,
+                ref: admission.ref,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+        }
+        const onAdmission = requireAdmissionRecorder(input.onRetainedAdmission);
+        if (admission.phase === 'interactive_environment') {
+            return recoverRetainedInteractiveRun({
+                provider: prepared.provider,
+                admission,
+                onAdmission,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+        }
+        const receipt = requireRecoveryReceipt(input.receipt);
+        const profile = receipt.requested.profile;
+        return recoverRetainedInteractiveRun({
+            provider: prepared.provider,
+            admission,
+            replay: {
+                environment: interactiveEnvironment(prepared, input.runId, admission.idempotencyKey, profile),
+                interactiveIdempotencyKey: admission.interactiveIdempotencyKey,
+                ...(receipt.requested.text.trim() === '' ? {} : { initialPrompt: receipt.requested.text }),
+                ...(input.workspaceRoot === undefined ? {} : { cwd: input.workspaceRoot }),
+            },
+            onAdmission,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+    }
+    async #handleFor(input) {
+        const admissionForInput = interactiveAdmissionOrUndefined(input.retainedAdmission);
+        if (admissionForInput !== undefined) {
+            assertInteractiveAdmissionMatchesInput(admissionForInput, input);
+        }
+        const active = this.#handles.get(input.runId);
+        if (active !== undefined) {
+            this.#assertControl(input.runId, input.providerSessionId, input.controlRef, active.ref.run);
+            return active;
+        }
+        const starting = this.#starting.get(input.runId);
+        if (starting !== undefined) {
+            const handle = await starting;
+            this.#rememberHandle(input.runId, handle);
+            this.#assertControl(input.runId, input.providerSessionId, input.controlRef, handle.ref.run);
+            return handle;
+        }
+        const admission = requireInteractiveAdmission(input.retainedAdmission);
+        const prepared = await this.#resolveRecovery(input, admission);
+        assertInteractiveProvider(prepared);
+        const handle = await this.#recoverHandle(prepared, input, admission);
+        if (handle !== null)
+            this.#rememberHandle(input.runId, handle);
+        return handle;
+    }
+    async #resolveRecovery(input, admission) {
+        const receipt = input.receipt;
+        const profile = (admission.phase === 'interactive_environment'
+            ? admission.request.profile
+            : receipt?.requested.profile);
+        if (profile === undefined) {
+            throw new Error('Interactive recovery requires the original run receipt');
+        }
+        const text = admission.phase === 'interactive_environment'
+            ? (admission.request.initialPrompt ?? '')
+            : (receipt?.requested.text ?? '');
+        const recoveredInput = {
+            operationId: `recover-${safeExecutionId(input.runId)}`,
+            runId: input.runId,
+            text,
+            profile,
+            mode: 'interactive',
+            ...(receipt?.requested.connectionId === undefined
+                ? {}
+                : { connectionId: receipt.requested.connectionId }),
+            ...(input.workspaceRoot === undefined ? {} : { workspaceRoot: input.workspaceRoot }),
+            signal: input.signal ?? new AbortController().signal,
+        };
+        return (this.#recover ?? this.#resolve)(recoveredInput);
+    }
+    #rememberHandle(runId, handle) {
+        const previous = this.#handles.get(runId);
+        if (previous !== undefined &&
+            canonicalCandidateDigest(previous.ref) !== canonicalCandidateDigest(handle.ref)) {
+            throw new Error('Interactive run recovered with a different process reference');
+        }
+        this.#handles.set(runId, handle);
+    }
+    #clearStarting(runId, starting) {
+        if (this.#starting.get(runId) === starting)
+            this.#starting.delete(runId);
+    }
+    #assertControl(runId, providerSessionId, controlRef, expected) {
+        const actual = expected ?? this.#handles.get(runId)?.ref.run;
+        assertExactControl({
+            ...(providerSessionId === undefined ? {} : { providerSessionId }),
+            ...(controlRef === undefined ? {} : { controlRef }),
+        }, actual);
+    }
+    #settleDetached(runId) {
+        if (!this.#activeRuns.has(runId))
+            return;
+        switch (this.#broker.settle(runId, { kind: 'detached' })) {
+            case 'settled':
+            case 'absent':
+            case 'already-settled':
+                return;
+        }
+    }
+    #settleCancelled(runId) {
+        if (!this.#activeRuns.has(runId))
+            return;
+        switch (this.#broker.settle(runId, { kind: 'exited', exitSignal: 'SIGTERM' })) {
+            case 'settled':
+            case 'absent':
+            case 'already-settled':
+                return;
+        }
+    }
+    #forgetHandle(runId) {
+        this.#handles.delete(runId);
+        this.#prepared.delete(runId);
+        if (!this.#activeRuns.has(runId))
+            this.#cancelledRuns.delete(runId);
+    }
+}
+//# sourceMappingURL=tangle-retained-interactive-execution.js.map