@xenosystem/agent-interface-host 0.1.4 → 0.1.6

package/dist/index.js

@@ -8,7 +8,7 @@ import { AgentHostProtocolError, XENO_AGENT_HOST_MIN_PROTOCOL_VERSION, XENO_AGEN
 const MAX_FLEET_COLLISIONS = 500;
 const MAX_QUEUED_INSTRUCTIONS = 50;
 const MAX_QUEUED_INSTRUCTION_LENGTH = 20_000;
-import { cloneProvider, isDevelopmentProviderReady, missingDevelopmentCapabilities, resolveAgentRuntimeSelection, renderWorkspaceKnowledge, selectAvailableProviders, withHostBackedCapabilities, planFanOut, routeByCapability, } from '@xenosystem/agent-interface-core';
+import { cloneProvider, isDevelopmentProviderReady, missingDevelopmentCapabilities, resolveAgentRuntimeSelection, renderWorkspaceKnowledge, selectAvailableProviders, selectSessionRenderMode, withHostBackedCapabilities, planFanOut, routeByCapability, } from '@xenosystem/agent-interface-core';
 import { InMemoryInterruptedTurnStore, } from './turns/interruptedTurns.js';
 import { evaluateTurnAdmission, resolveTurnAdmissionPolicy, } from './turns/turnAdmission.js';
 import { boundSubagentWorkspace } from './subagents/subagentWorkspaceAuthority.js';
@@ -23,6 +23,7 @@ import { IntakeService } from './intake/IntakeService.js';
 import { WorkspaceKnowledgeService } from './knowledge/WorkspaceKnowledgeService.js';
 import { AgentSessionService } from './session/AgentSessionService.js';
 import { createBufferedSessionPty } from './session/bufferedSessionPty.js';
+import { createNativeTuiSessionPty } from './session/nativeTuiSessionPty.js';
 import { renderSupportFor } from './session/renderSupport.js';
 import { createRuntimeEventSessionChannel } from './session/runtimeEventChannel.js';
 import { answerChooseDirectoryRequest } from './agent/chooseDirectoryBridge.js';
@@ -74,6 +75,8 @@ export class AgentHostCoordinator {
     runIsolationService;
     runObservationBinder;
     sessionService;
+    nativeTuiLane;
+    acpAgentRegistry;
     intakeService;
     knowledgeService;
     acpApprovalService;
@@ -95,6 +98,18 @@ export class AgentHostCoordinator {
      */
     turnTimers = new Map();
     activeTurns = new Map();
+    /**
+     * The lane a conversation last ran on, kept AFTER the turn ends.
+     *
+     * 🔴 `activeTurns` cannot answer this and that is not an oversight — it is keyed by
+     * `(conversationId, requestId)` because everything it serves is turn-scoped. Pin-forward
+     * (§2.2) is normally a BETWEEN-turns act, so resolving its target from `activeTurns` would make
+     * the feature work only during the one window where the user is least likely to want it.
+     *
+     * ⚠️ Deliberately never cleared on turn end. "Which agent is this conversation running on" stays
+     * true between turns; clearing it would reintroduce the turn scope this map exists to escape.
+     */
+    conversationAdapters = new Map();
     commandResults = new Map();
     /**
      * Instructions stacked while a turn is running, per conversation.
@@ -115,7 +130,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, intakeService, knowledgeService, acpApprovalService, subagentRuns, resolveRunId, ...hostOptions } = 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;
         if (runtimeEventRepository && runtimeEvents && runtimeEvents.length > 0) {
             throw new Error('Seeded runtimeEvents cannot be combined with a durable runtimeEventRepository.');
         }
@@ -187,6 +202,8 @@ export class AgentHostCoordinator {
         // Counts and completeness only — see the contract's `run.observation`.
         this.runObservationService?.setEventSink((summary) => this.publish('run.observation', summary));
         this.sessionService = sessionService;
+        this.nativeTuiLane = nativeTuiLane;
+        this.acpAgentRegistry = acpAgentRegistry;
         this.intakeService = intakeService;
         this.knowledgeService = knowledgeService;
         // Session lifecycle on the feed: ids, modes and viewer counts — never PTY
@@ -651,8 +668,38 @@ export class AgentHostCoordinator {
         if (!service)
             return;
         try {
-            const support = renderSupportFor(provider, { adapters: [...this.turnExecutionAdapters.values()] });
-            const protocol = createRuntimeEventSessionChannel({
+            const support = renderSupportFor(provider, {
+                adapters: [...this.turnExecutionAdapters.values()],
+                // The seam `renderSupport.ts` declares. Undefined falls back to
+                // `noNativeTuiLane`, so the default is unchanged.
+                // The predicate is DERIVED from the command, so support cannot be
+                // claimed for a provider we could not actually launch.
+                ...(this.nativeTuiLane
+                    ? { nativeTuiLane: (candidate) => Boolean(this.nativeTuiLane?.(candidate)) }
+                    : {}),
+            });
+            /**
+             * 🔴 Ask which mode before building the channel, because the two modes
+             * are EXCLUSIVE and this call site used to build both.
+             *
+             * `open()` refuses `native-tui` when a protocol channel is present — a
+             * CLI in interactive TUI mode is not also serving ACP. Passing `protocol`
+             * unconditionally was harmless only while `nativeTuiLane` was hardcoded
+             * false: the moment a lane said true, `selectSessionRenderMode` would
+             * pick `native-tui` and this site would hand it the one thing that makes
+             * it illegal, so EVERY session on that provider would be refused with
+             * `protocol_channel_forbidden`.
+             *
+             * That is the exact failure `renderSupport.ts` promised could not happen
+             * — "the mode becomes available by construction". Construction reached as
+             * far as `renderSupportFor` and stopped one caller short.
+             *
+             * ⚠️ This calls the SAME exported selector `open()` calls, rather than
+             * restating its rule. Two callers of one function cannot drift; two
+             * copies of a rule can.
+             */
+            const selection = selectSessionRenderMode(support);
+            const createProtocol = () => createRuntimeEventSessionChannel({
                 runId,
                 subscribe: (listener) => this.subscribe((event) => {
                     if (event.type !== 'runtime.event.appended')
@@ -662,23 +709,94 @@ export class AgentHostCoordinator {
                         listener(payload.event);
                 }),
             });
+            const protocol = selection.ok && selection.mode === 'acp' ? createProtocol() : undefined;
+            /**
+             * 🔴 The PTY is chosen by MODE, and the two are not interchangeable.
+             *
+             * `acp` gets a render target — our drawing of the structured stream, with
+             * a `write` that THROWS because a keystroke reaching it means a mode rule
+             * broke. `native-tui` gets a real terminal with the vendor's own binary
+             * inside it, where a write is a keystroke and must land.
+             *
+             * Handing the wrong one over is the single most likely way this mode goes
+             * wrong, which is why the buffered pty was built to fail loudly rather
+             * than no-op.
+             */
+            const spawnRequest = selection.ok && selection.mode === 'native-tui'
+                ? this.nativeTuiLane?.(provider)
+                : undefined;
             const opened = service.open({
                 sessionId: runId,
                 runId,
                 support,
-                pty: createBufferedSessionPty(),
-                protocol,
+                pty: spawnRequest ? createNativeTuiSessionPty(spawnRequest) : createBufferedSessionPty(),
+                ...(protocol ? { protocol } : {}),
+                /**
+                 * Passed even when a channel was built above, because `session.setMode`
+                 * CLOSES the channel on the way to `native-tui` and a closed one cannot
+                 * be revived. Without the factory the switch would be one-way, and a
+                 * user who tried the agent's own TUI could never get the structured
+                 * view back.
+                 */
+                createProtocol,
             });
             // A refusal is the substrate doing its job — an unexecutable provider has
             // nothing to render. Close the channel we built for it rather than leaving
             // a subscription attached to a session that never existed.
             if (!opened.ok)
-                protocol.close();
+                protocol?.close();
         }
         catch {
             // Contained: see above. The run proceeds without a session.
         }
     }
+    /**
+     * ADE §2.8's switch. The substrate has always accepted a preference; until
+     * `session.setMode` existed, no client could express one.
+     */
+    /**
+     * The slice of the ACP registry this host needs — a PORT, not the service.
+     *
+     * Declared structurally so `packages/host`'s public surface does not drag the
+     * registry's own types across the protocol boundary, and so a composition can
+     * supply something else entirely.
+     */
+    listAcpAgents() {
+        const registry = this.acpAgentRegistry;
+        // "No agents" and "this host cannot manage agents" are different facts, and
+        // a client that conflates them shows an empty picker with no way forward.
+        if (!registry)
+            return { ok: false, agents: [], reason: 'This host has no ACP agent registry mounted.' };
+        return { ok: true, agents: registry.listSummaries() };
+    }
+    addAcpPreset(request) {
+        const registry = this.acpAgentRegistry;
+        if (!registry)
+            return { ok: false, reason: 'This host has no ACP agent registry mounted.' };
+        // 🔴 Validated against the registry's OWN list, not a copy of it here. A
+        // second list of preset ids would be free to drift from the one that
+        // decides — which is exactly how the previous guard came to name three
+        // presets while six existed.
+        if (!registry.isPresetId(request.presetId)) {
+            return {
+                ok: false,
+                reason: `Unknown agent preset '${request.presetId}'. Available: ${registry.presetIds().join(', ')}.`,
+            };
+        }
+        return registry.addPreset(request.presetId);
+    }
+    removeAcpAgent(request) {
+        const registry = this.acpAgentRegistry;
+        if (!registry)
+            return { ok: false, removed: false, reason: 'This host has no ACP agent registry mounted.' };
+        return registry.remove(request.agentId);
+    }
+    setSessionMode(request) {
+        const service = this.sessionService;
+        if (!service)
+            return { ok: false, reason: 'This host has no session substrate mounted.' };
+        return service.setMode(request.sessionId, request.mode);
+    }
     async routeSessionInput(input) {
         const service = this.sessionService;
         if (!service)
@@ -1072,7 +1190,7 @@ export class AgentHostCoordinator {
                 // 🔴 ALWAYS present, unlike every other optional field on this row.
                 // §5.3 requires the user to always know whether the thing running is
                 // contained, and "always" is the word that forbids omitting it when the
-                // answer is unflattering. `none` IS the answer today.
+                // answer is unflattering. `none` is a real answer, not a missing field.
                 isolation: isolation.isolation,
                 ...(isolation.mechanism === undefined ? {} : { isolationMechanism: isolation.mechanism }),
                 ...(isolation.reason === undefined ? {} : { isolationReason: isolation.reason }),
@@ -1413,6 +1531,9 @@ export class AgentHostCoordinator {
         if (method === 'turn.cancel') {
             return await this.cancelTurn(input);
         }
+        if (method === 'context.inject') {
+            return await this.injectContext(input);
+        }
         if (method === 'turn.steer') {
             return await this.steerTurn(input);
         }
@@ -1470,6 +1591,18 @@ export class AgentHostCoordinator {
         if (method === 'session.release') {
             return this.releaseSession(input);
         }
+        if (method === 'acp.agents.list') {
+            return this.listAcpAgents();
+        }
+        if (method === 'acp.agents.addPreset') {
+            return this.addAcpPreset(input);
+        }
+        if (method === 'acp.agents.remove') {
+            return this.removeAcpAgent(input);
+        }
+        if (method === 'session.setMode') {
+            return this.setSessionMode(input);
+        }
         if (method === 'intake.sources.list') {
             return this.listIntakeSources();
         }
@@ -2025,6 +2158,7 @@ export class AgentHostCoordinator {
         }
         const controller = new AbortController();
         this.activeTurns.set(activeKey, { adapter, controller, request });
+        this.conversationAdapters.set(request.conversationId, adapter);
         // 🔴 The host ENFORCES the deadline it already validates. `timeoutMs` was checked on the way
         // in (1..3_600_000) and forwarded to the adapter, but nothing here ever acted on it: the
         // controller was aborted only for shutdown or an explicit cancel. A turn whose adapter
@@ -2342,9 +2476,21 @@ export class AgentHostCoordinator {
             const failure = {
                 success: false,
                 code: 'steer_unsupported',
+                /**
+                 * 🔴 NAME THE LANE, exactly as the no-steer branch above does (§7.1 capability
+                 * honesty). This said “The provider rejected the correction”, which names nothing an
+                 * operator can act on — with several lanes on a host, “the provider” is the one fact
+                 * they need and the one this withheld.
+                 *
+                 * ⚠️ IT ONLY BECAME REACHABLE WHEN THE ACP LANE LEARNED TO STEER. Until then no ACP
+                 * adapter implemented `steer`, so every ACP refusal took the branch above, which does
+                 * name itself. Implementing the capability moved the refusal onto a path whose message
+                 * was weaker — an improvement that quietly regressed the diagnostics beside it.
+                 * `scripts/session-attach-probe.mjs` caught it; nothing in this repo did.
+                 */
                 safeError: error instanceof Error && error.message
-                    ? `The provider rejected the correction: ${error.message.slice(0, 300)}`
-                    : 'The provider rejected the correction.',
+                    ? `The '${active.adapter.id}' lane rejected the correction: ${error.message.slice(0, 300)}`
+                    : `The '${active.adapter.id}' lane rejected the correction.`,
                 conversationId: input.conversationId,
                 requestId: input.requestId,
             };
@@ -2362,6 +2508,86 @@ export class AgentHostCoordinator {
         this.commandResults.set(commandKey, { method: 'turn.steer', fingerprint, result: structuredClone(result) });
         return result;
     }
+    /**
+     * `context.inject` — push a pinned canvas node back into an agent's context (XENO SPAWN §2.2).
+     *
+     * 🔴 THE COMMAND THAT DID NOT EXIST. Both lanes could already inject — `AgentLoop.injectContext()`
+     * on the SDK side, `AgentProcess.injectContext()` on the ACP side — the `context.injected` event
+     * was defined, forwarded and PROJECTED, and nothing in this host could trigger any of it. Every
+     * layer was built and tested; the one that lets a surface act was missing, which is the shape
+     * this ecosystem keeps re-finding.
+     *
+     * ⚠️ NOT gated on an active turn, unlike `steerTurn`. Pin-forward is normally a between-turns
+     * act, so the lane is resolved from `conversationAdapters` rather than `activeTurns`.
+     */
+    async injectContext(input) {
+        if (!this.isConnectedClient(input.command.client)) {
+            return {
+                success: false,
+                code: 'client_not_connected',
+                safeError: 'Complete the handshake before injecting context.',
+                conversationId: input.conversationId,
+            };
+        }
+        if (typeof input.content !== 'string' || !input.content.trim()) {
+            return {
+                success: false,
+                code: 'invalid_request',
+                safeError: 'Injected content must be a non-empty string.',
+                conversationId: input.conversationId,
+            };
+        }
+        const adapter = this.conversationAdapters.get(input.conversationId);
+        if (!adapter) {
+            // Nothing has run on this conversation yet, so there is no agent to hold the node. Said
+            // plainly rather than as a generic failure: the remedy is to start a turn first.
+            return {
+                success: false,
+                code: 'no_active_session',
+                safeError: 'This conversation has no agent session yet. Start a turn before pinning a node into it.',
+                conversationId: input.conversationId,
+            };
+        }
+        if (!adapter.injectContext) {
+            /**
+             * 🔴 The remedy is DERIVED from what the other lanes can do, not written by hand — the same
+             * rule `steerTurn` follows, so a lane gaining the capability changes this message for free.
+             */
+            const capable = [...this.turnExecutionAdapters.values()]
+                .filter((entry) => entry.injectContext)
+                .map((entry) => entry.id);
+            return {
+                success: false,
+                code: 'inject_unsupported',
+                safeError: capable.length > 0
+                    ? `The '${adapter.id}' lane cannot take injected context. Lanes that can: ${capable.join(', ')}.`
+                    : `The '${adapter.id}' lane cannot take injected context, and no lane on this host can.`,
+                conversationId: input.conversationId,
+            };
+        }
+        try {
+            const outcome = await adapter.injectContext(structuredClone(input));
+            return {
+                success: true,
+                ...(outcome?.messageId ? { messageId: outcome.messageId } : {}),
+                ...(outcome?.status ? { status: outcome.status } : {}),
+                deliveredVia: 'adapter',
+                conversationId: input.conversationId,
+            };
+        }
+        catch (error) {
+            // Reported, never swallowed. A caller that believes a node was pinned when it was not will
+            // reason about what the agent knows using an edge that does not exist.
+            return {
+                success: false,
+                code: 'inject_unsupported',
+                safeError: error instanceof Error && error.message
+                    ? `The provider rejected the injection: ${error.message.slice(0, 300)}`
+                    : 'The provider rejected the injection.',
+                conversationId: input.conversationId,
+            };
+        }
+    }
     /** True while any turn is running for this conversation. */
     hasActiveTurn(conversationId) {
         for (const active of this.activeTurns.values()) {
@@ -3156,7 +3382,6 @@ export * from './isolation/RunIsolationService.js';
  */
 export * from './isolation/SandboxCommandExecutor.js';
 export * from './observation/XenoUseObservationSource.js';
-export * from './observation/XenoUseRunObserver.js';
 export * from './session/AgentSessionService.js';
 export * from './session/runtimeEventChannel.js';
 export * from './session/renderSupport.js';