@xenosystem/agent-interface-host 0.1.7 → 0.1.8

package/dist/index.js

@@ -86,6 +86,7 @@ export class AgentHostCoordinator {
      */
     subagentRuns;
     resolveRunId;
+    providerLaneService;
     connectedClients = new Map();
     /** What each connected client declared it can do, keyed the same way. */
     clientCapabilities = new Map();
@@ -130,7 +131,7 @@ export class AgentHostCoordinator {
     providerCatalogFingerprint = '';
     providerCatalogRefresh = null;
     constructor(options) {
-        const { providers, providerCatalogLoader, runtimeEvents, runtimeEventRepository, stateRepository, workspaceService, interactionService, permissionPolicyService, interruptedTurnStore, turnAdmissionPolicy, turnAbandonGraceMs, sdkControlService, engineeringControlService, turnExecutionAdapters, coordinationService, runObservationService, runIsolationService, runObservationBinder, sessionService, nativeTuiLane, acpAgentRegistry, intakeService, knowledgeService, acpApprovalService, subagentRuns, resolveRunId, ...hostOptions } = options;
+        const { providers, providerCatalogLoader, runtimeEvents, runtimeEventRepository, stateRepository, workspaceService, interactionService, permissionPolicyService, interruptedTurnStore, turnAdmissionPolicy, turnAbandonGraceMs, sdkControlService, engineeringControlService, providerLaneService, turnExecutionAdapters, coordinationService, runObservationService, runIsolationService, runObservationBinder, sessionService, nativeTuiLane, acpAgentRegistry, intakeService, knowledgeService, acpApprovalService, subagentRuns, resolveRunId, ...hostOptions } = options;
         if (runtimeEventRepository && runtimeEvents && runtimeEvents.length > 0) {
             throw new Error('Seeded runtimeEvents cannot be combined with a durable runtimeEventRepository.');
         }
@@ -146,6 +147,9 @@ export class AgentHostCoordinator {
         this.turnAbandonGraceMs = turnAbandonGraceMs ?? DEFAULT_TURN_ABANDON_GRACE_MS;
         this.sdkControlService = sdkControlService;
         this.engineeringControlService = engineeringControlService;
+        this.providerLaneService = providerLaneService;
+        this.providerLaneService?.setEventSink?.((type, payload) => this.publish(type, payload));
+        this.providerLaneService?.start?.();
         this.coordinationService = coordinationService;
         // A turn's run identity, if the request carries one. `subagentRunId` first:
         // a subagent IS a distinct run with its own claims, so folding it into its
@@ -153,7 +157,11 @@ export class AgentHostCoordinator {
         // 🔴 `defaultRunIdOf`, not a hand-written `??` — a session filters runtime
         // EVENTS by the same rule, and the two must not drift. See its doc.
         this.resolveRunId = resolveRunId ?? ((request) => defaultRunIdOf(request));
-        this.workspaceService?.setEventSink((type, payload) => this.publish(type, payload));
+        this.workspaceService?.setEventSink((type, payload) => {
+            if (type === 'workspace.pty.exit')
+                this.providerLaneService?.handleWorkspacePtyExit?.(payload);
+            this.publish(type, payload);
+        });
         // Coordination reaches surfaces through the event feed and nothing else.
         // Published as `redactionState: 'safe'` like every host event — which holds
         // because a coordination event carries ids, scopes and outcomes, never
@@ -1519,6 +1527,64 @@ export class AgentHostCoordinator {
             this.assertWorkspaceClient(input);
             return await this.requireWorkspaceService().stopPty(input);
         }
+        if (method === 'conversation.open') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'using provider conversations');
+            return await this.requireProviderLaneService().openConversation(request);
+        }
+        if (method === 'conversation.resume') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'using provider conversations');
+            return await this.requireProviderLaneService().resumeConversation(request);
+        }
+        if (method === 'provider.lanes.list') {
+            const request = input;
+            this.assertConnectedClient(request.client, 'listing provider lanes');
+            return await this.requireProviderLaneService().listLanes(request);
+        }
+        if (method === 'provider.lanes.get') {
+            const request = input;
+            this.assertConnectedClient(request.client, 'reading provider lanes');
+            return await this.requireProviderLaneService().getLane(request);
+        }
+        if (method === 'provider.lanes.select') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'selecting provider lanes');
+            await this.refreshProviderCatalog();
+            return await this.requireProviderLaneService().selectLane(request);
+        }
+        if (method === 'provider.native.attach') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'attaching a native provider TUI');
+            if ([...this.activeTurns.values()].some((active) => active.request.conversationId === request.conversationId)) {
+                return {
+                    success: false,
+                    code: 'LANE_WRITER_ACTIVE',
+                    error: 'A structured provider turn is active for this conversation.',
+                };
+            }
+            return await this.requireProviderLaneService().attachNative(request);
+        }
+        if (method === 'provider.native.detach') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'detaching a native provider TUI');
+            return await this.requireProviderLaneService().detachNative(request);
+        }
+        if (method === 'provider.native.reattach') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'reattaching a native provider TUI');
+            return await this.requireProviderLaneService().reattachNative(request);
+        }
+        if (method === 'provider.native.stop') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'stopping a native provider TUI');
+            return await this.requireProviderLaneService().stopNative(request);
+        }
+        if (method === 'provider.reconcile') {
+            const request = input;
+            this.assertConnectedClient(request.command.client, 'reconciling a provider lane');
+            return await this.requireProviderLaneService().reconcile(request);
+        }
         if (method === 'turn.start') {
             return await this.startTurn(input);
         }
@@ -1759,6 +1825,7 @@ export class AgentHostCoordinator {
         }));
         await this.sdkControlService?.close?.();
         await this.engineeringControlService?.close?.();
+        await this.providerLaneService?.close?.();
         await this.workspaceService?.close?.();
         await this.stateRepository?.close?.();
         // Before the listeners go: each session's protocol channel is subscribed to
@@ -2008,13 +2075,26 @@ export class AgentHostCoordinator {
         this.trackTurnTimer(activeKey, timer);
     }
     async startTurn(input) {
-        const invalidReason = validateTurnStartRequest(input);
+        let invalidReason = validateTurnStartRequest(input);
         if (invalidReason) {
             return turnStartFailure('invalid_request', invalidReason, input);
         }
         if (!this.isConnectedClient(input.command.client)) {
             return turnStartFailure('client_not_connected', 'The requesting surface must complete the host handshake before starting a turn.', input);
         }
+        if (this.providerLaneService?.prepareTurn) {
+            try {
+                input = await this.providerLaneService.prepareTurn(structuredClone(input));
+            }
+            catch (error) {
+                return turnStartFailure('invalid_request', error instanceof Error && error.message.trim()
+                    ? error.message.slice(0, 1_000)
+                    : 'The active provider lane rejected this turn.', input);
+            }
+            invalidReason = validateTurnStartRequest(input);
+            if (invalidReason)
+                return turnStartFailure('invalid_request', invalidReason, input);
+        }
         const commandKey = this.commandKey('turn.start', input.command);
         const fingerprint = commandFingerprint(input);
         const prior = this.commandResults.get(commandKey);
@@ -2111,6 +2191,16 @@ export class AgentHostCoordinator {
             return turnStartFailure('concurrency_limit_reached', admission.safeError, input);
         }
         const request = structuredClone(input);
+        if (this.providerLaneService?.beginStructuredTurn) {
+            try {
+                await this.providerLaneService.beginStructuredTurn(request);
+            }
+            catch (error) {
+                return this.rememberTurnStartFailure(commandKey, fingerprint, turnStartFailure('request_already_active', error instanceof Error && error.message.trim()
+                    ? error.message.slice(0, 1_000)
+                    : 'The provider lane writer could not be acquired.', request));
+            }
+        }
         // Recorded BEFORE execution, so a coordination event arriving in the first
         // moments of a turn still finds its conversation.
         const contextRunId = this.resolveRunId(request);
@@ -2202,10 +2292,25 @@ export class AgentHostCoordinator {
             // §5.2b's `message` primitive is a PUSH, and this is the push. Without
             // it a run could send and no run could ever receive.
             .then(() => this.deliverCoordinationMessages(request))
-            .then(() => adapter.execute(request, provider, resolved.selection, {
-            signal: controller.signal,
-            publishPersistedRuntimeEvent: (event) => this.publishPersistedRuntimeEvent(event),
-        }))
+            .then(async () => {
+            const hostBinding = await this.providerLaneService?.getHostBinding?.(request.conversationId);
+            return adapter.execute(request, provider, resolved.selection, {
+                signal: controller.signal,
+                ...(hostBinding ? { hostBinding: structuredClone(hostBinding) } : {}),
+                publishPersistedRuntimeEvent: (event) => this.publishPersistedRuntimeEvent(event),
+                commitProviderContinuation: async (continuation) => {
+                    if (!this.providerLaneService?.commitTurnContinuation)
+                        return;
+                    const result = await this.providerLaneService.commitTurnContinuation({
+                        conversationId: request.conversationId,
+                        requestId: request.requestId,
+                        continuation: structuredClone(continuation),
+                    });
+                    if (!result.success)
+                        throw new Error(result.error || 'Provider continuation could not be committed.');
+                },
+            });
+        })
             .then(() => {
             // The turn ended WELL. Published here rather than inferred by each surface from
             // provider-specific runtime event strings — see the note on the event type itself.
@@ -2217,6 +2322,15 @@ export class AgentHostCoordinator {
             // what the host already told every surface. Late is not the same as successful.
             if (this.activeTurns.get(activeKey)?.controller !== controller)
                 return;
+            if (controller.signal.aborted) {
+                this.publish('turn.execution.abandoned', {
+                    conversationId: request.conversationId,
+                    requestId: request.requestId,
+                    adapterId: adapter.id,
+                    reason: 'The turn was cancelled before completion.',
+                });
+                return;
+            }
             this.publish('turn.execution.completed', {
                 conversationId: request.conversationId,
                 requestId: request.requestId,
@@ -2228,14 +2342,17 @@ export class AgentHostCoordinator {
             // second terminal event either.
             if (this.activeTurns.get(activeKey)?.controller !== controller)
                 return;
-            this.publish('turn.execution.failed', {
+            this.publish(controller.signal.aborted ? 'turn.execution.abandoned' : 'turn.execution.failed', {
                 conversationId: request.conversationId,
                 requestId: request.requestId,
                 adapterId: adapter.id,
-                safeError: 'The selected runtime adapter failed to execute the turn.',
+                ...(controller.signal.aborted
+                    ? { reason: 'The turn was cancelled before completion.' }
+                    : { safeError: 'The selected runtime adapter failed to execute the turn.' }),
             });
         })
-            .finally(() => {
+            .finally(async () => {
+            await this.providerLaneService?.finishStructuredTurn?.(request.conversationId, request.requestId);
             const active = this.activeTurns.get(activeKey);
             if (active?.controller === controller)
                 this.activeTurns.delete(activeKey);
@@ -3034,6 +3151,17 @@ export class AgentHostCoordinator {
         }
         return this.engineeringControlService;
     }
+    requireProviderLaneService() {
+        if (!this.providerLaneService) {
+            throw new AgentHostProtocolError('invalid_response', 'Host-owned provider lane services are unavailable.');
+        }
+        return this.providerLaneService;
+    }
+    assertConnectedClient(identity, operation) {
+        if (!isAgentHostClientIdentity(identity) || !this.isConnectedClient(identity)) {
+            throw new AgentHostProtocolError('invalid_response', `The requesting surface must complete the host handshake before ${operation}.`);
+        }
+    }
     assertWorkspaceClient(input) {
         if (!isRecord(input) || !isAgentHostClientIdentity(input.client) || !this.isConnectedClient(input.client)) {
             throw new AgentHostProtocolError('invalid_response', 'The requesting surface must complete the host handshake before using workspace services.');