@xenosystem/agent-interface-host 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,834 @@
+import { type AgentEngineeringHostMethod, type AgentHostEvent, type AgentHostEventListener, type AgentHostInput, type AgentHostMethod, type AgentHostOutput, type AgentHostTransport, type AgentHostUnsubscribe, type AgentRuntimeProviderDescriptor, type AgentRuntimeEventDraft, type AgentRuntimeEventEnvelope, type AgentRuntimeEventListResult, type AgentWorkspaceStateLoadResult, type AgentWorkspaceStateSaveRequest, type AgentWorkspaceStateSaveResult, type AgentConversationStateLoadResult, type AgentConversationStateSaveRequest, type AgentConversationStateSaveResult, type AgentConversationStateDeleteRequest, type AgentConversationStateDeleteResult, type AgentRuntimeSelection, type AgentTurnCancelRequest, type AgentTurnSteerRequest, type AgentAcpProviderApprovalResult, type AgentTurnStartRequest } from '@xenosystem/agent-interface-contract';
+import { type InterruptedTurnStore } from './turns/interruptedTurns.js';
+import { type TurnAdmissionPolicy } from './turns/turnAdmission.js';
+import { type SubagentRunPort } from './subagents/subagentRunPort.js';
+import { CoordinationService } from './coordination/CoordinationService.js';
+import type { RunActivitySignal } from './coordination/query.js';
+import { RunObservationService } from './observation/RunObservationService.js';
+import { RunIsolationService } from './isolation/RunIsolationService.js';
+import { IntakeService } from './intake/IntakeService.js';
+import { WorkspaceKnowledgeService } from './knowledge/WorkspaceKnowledgeService.js';
+import { AgentSessionService } from './session/AgentSessionService.js';
+/**
+ * Performs ACP provider approval — a PORT, not a direct call.
+ *
+ * `AcpProviderApprovalService` imports `@xenosystem/acp-core`, and pulling that
+ * into this module would make the whole coordinator unloadable wherever ACP is
+ * not installed. The composition supplies the implementation, exactly as it does
+ * for observation and sessions.
+ *
+ * It resolves the agent id to a config itself, because that mapping lives in the
+ * ACP registry and the coordinator has no business duplicating it.
+ */
+export interface AgentAcpApprovalService {
+    approveProvider(input: {
+        agentId: string;
+        providerId?: string;
+        action: 'approve' | 'revoke';
+    }): Promise<AgentAcpProviderApprovalResult>;
+}
+export interface AgentRuntimeEventRepository {
+    appendGenerated(event: AgentRuntimeEventDraft): Promise<{
+        inserted: boolean;
+        event: AgentRuntimeEventEnvelope;
+    }>;
+    append(event: AgentRuntimeEventEnvelope): Promise<{
+        inserted: boolean;
+        event: AgentRuntimeEventEnvelope;
+    }>;
+    list(input: AgentHostInput<'runtime.events.list'>): Promise<AgentRuntimeEventListResult>;
+}
+export interface AgentStateRepository {
+    loadWorkspaces(): Promise<AgentWorkspaceStateLoadResult>;
+    saveWorkspaces(input: AgentWorkspaceStateSaveRequest): Promise<AgentWorkspaceStateSaveResult>;
+    loadConversations(): Promise<AgentConversationStateLoadResult>;
+    saveConversation(input: AgentConversationStateSaveRequest): Promise<AgentConversationStateSaveResult>;
+    deleteConversation(input: AgentConversationStateDeleteRequest): Promise<AgentConversationStateDeleteResult>;
+    close?(): Promise<void> | void;
+}
+export interface AgentWorkspaceService {
+    setEventSink(sink: (type: AgentHostEvent['type'], payload: Record<string, unknown>) => void): void;
+    grantDirectory(input: AgentHostInput<'workspace.access.grant'>): AgentHostOutput<'workspace.access.grant'> | Promise<AgentHostOutput<'workspace.access.grant'>>;
+    grantApplication(input: AgentHostInput<'workspace.application.grant'>): AgentHostOutput<'workspace.application.grant'> | Promise<AgentHostOutput<'workspace.application.grant'>>;
+    listDirectory(input: AgentHostInput<'workspace.directory.list'>): AgentHostOutput<'workspace.directory.list'> | Promise<AgentHostOutput<'workspace.directory.list'>>;
+    readFile(input: AgentHostInput<'workspace.file.read'>): AgentHostOutput<'workspace.file.read'> | Promise<AgentHostOutput<'workspace.file.read'>>;
+    writeFile(input: AgentHostInput<'workspace.file.write'>): AgentHostOutput<'workspace.file.write'> | Promise<AgentHostOutput<'workspace.file.write'>>;
+    runCommand(input: AgentHostInput<'workspace.command.run'>): AgentHostOutput<'workspace.command.run'> | Promise<AgentHostOutput<'workspace.command.run'>>;
+    startTerminal(input: AgentHostInput<'workspace.terminal.start'>): AgentHostOutput<'workspace.terminal.start'> | Promise<AgentHostOutput<'workspace.terminal.start'>>;
+    stopTerminal(input: AgentHostInput<'workspace.terminal.stop'>): AgentHostOutput<'workspace.terminal.stop'> | Promise<AgentHostOutput<'workspace.terminal.stop'>>;
+    startPty(input: AgentHostInput<'workspace.pty.start'>): AgentHostOutput<'workspace.pty.start'> | Promise<AgentHostOutput<'workspace.pty.start'>>;
+    snapshotPty(input: AgentHostInput<'workspace.pty.snapshot'>): AgentHostOutput<'workspace.pty.snapshot'> | Promise<AgentHostOutput<'workspace.pty.snapshot'>>;
+    inputPty(input: AgentHostInput<'workspace.pty.input'>): AgentHostOutput<'workspace.pty.input'> | Promise<AgentHostOutput<'workspace.pty.input'>>;
+    resizePty(input: AgentHostInput<'workspace.pty.resize'>): AgentHostOutput<'workspace.pty.resize'> | Promise<AgentHostOutput<'workspace.pty.resize'>>;
+    clearPty(input: AgentHostInput<'workspace.pty.clear'>): AgentHostOutput<'workspace.pty.clear'> | Promise<AgentHostOutput<'workspace.pty.clear'>>;
+    stopPty(input: AgentHostInput<'workspace.pty.stop'>): AgentHostOutput<'workspace.pty.stop'> | Promise<AgentHostOutput<'workspace.pty.stop'>>;
+    close?(): Promise<void> | void;
+}
+export interface AgentInteractionService {
+    answerPermission(input: AgentHostInput<'elicitation.permission.answer'>): AgentHostOutput<'elicitation.permission.answer'> | Promise<AgentHostOutput<'elicitation.permission.answer'>>;
+    answerAskUser(input: AgentHostInput<'elicitation.ask-user.answer'>): AgentHostOutput<'elicitation.ask-user.answer'> | Promise<AgentHostOutput<'elicitation.ask-user.answer'>>;
+}
+/**
+ * Host-owned permission POLICY administration (ADE spec §7 "one authority").
+ *
+ * Separate from `AgentInteractionService`, which answers a single live prompt.
+ * This is the standing policy behind those prompts: what a user chose to
+ * remember, and their ability to take it back. Rules persist and accumulate, so
+ * a surface that can create them and not revoke them is a one-way door.
+ */
+export interface AgentPermissionPolicyService {
+    listRules(): AgentHostOutput<'permissions.rules.list'> | Promise<AgentHostOutput<'permissions.rules.list'>>;
+    revokeRule(input: AgentHostInput<'permissions.rules.revoke'>): AgentHostOutput<'permissions.rules.revoke'> | Promise<AgentHostOutput<'permissions.rules.revoke'>>;
+}
+export interface AgentSdkControlService {
+    listSessions(input: AgentHostInput<'sdk.sessions.list'>): AgentHostOutput<'sdk.sessions.list'> | Promise<AgentHostOutput<'sdk.sessions.list'>>;
+    showSession(input: AgentHostInput<'sdk.sessions.show'>): AgentHostOutput<'sdk.sessions.show'> | Promise<AgentHostOutput<'sdk.sessions.show'>>;
+    attachSession(input: AgentHostInput<'sdk.sessions.attach'>): AgentHostOutput<'sdk.sessions.attach'> | Promise<AgentHostOutput<'sdk.sessions.attach'>>;
+    detachSession(input: AgentHostInput<'sdk.sessions.detach'>): AgentHostOutput<'sdk.sessions.detach'> | Promise<AgentHostOutput<'sdk.sessions.detach'>>;
+    deleteSession(input: AgentHostInput<'sdk.sessions.delete'>): AgentHostOutput<'sdk.sessions.delete'> | Promise<AgentHostOutput<'sdk.sessions.delete'>>;
+    cleanSessions(input: AgentHostInput<'sdk.sessions.clean'>): AgentHostOutput<'sdk.sessions.clean'> | Promise<AgentHostOutput<'sdk.sessions.clean'>>;
+    listCheckpoints(input: AgentHostInput<'sdk.checkpoints.list'>): AgentHostOutput<'sdk.checkpoints.list'> | Promise<AgentHostOutput<'sdk.checkpoints.list'>>;
+    restoreCheckpoint(input: AgentHostInput<'sdk.checkpoints.restore'>): AgentHostOutput<'sdk.checkpoints.restore'> | Promise<AgentHostOutput<'sdk.checkpoints.restore'>>;
+    deleteCheckpoint(input: AgentHostInput<'sdk.checkpoints.delete'>): AgentHostOutput<'sdk.checkpoints.delete'> | Promise<AgentHostOutput<'sdk.checkpoints.delete'>>;
+    readTaskOutput(input: AgentHostInput<'sdk.tasks.output'>): AgentHostOutput<'sdk.tasks.output'> | Promise<AgentHostOutput<'sdk.tasks.output'>>;
+    stopTask(input: AgentHostInput<'sdk.tasks.stop'>): AgentHostOutput<'sdk.tasks.stop'> | Promise<AgentHostOutput<'sdk.tasks.stop'>>;
+    close?(): Promise<void> | void;
+}
+export interface AgentEngineeringControlService {
+    request<M extends AgentEngineeringHostMethod>(method: M, input: AgentHostInput<M>): AgentHostOutput<M> | Promise<AgentHostOutput<M>>;
+    close?(): void | Promise<void>;
+}
+export interface AgentTurnExecutionContext {
+    signal: AbortSignal;
+    /**
+     * Announces an event that the adapter has already committed to the host-owned runtime journal.
+     */
+    publishPersistedRuntimeEvent(event: AgentRuntimeEventEnvelope): void;
+}
+export interface AgentTurnExecutionAdapter {
+    id: string;
+    supports(provider: AgentRuntimeProviderDescriptor): boolean;
+    execute(request: AgentTurnStartRequest, provider: AgentRuntimeProviderDescriptor, selection: Readonly<AgentRuntimeSelection>, context: AgentTurnExecutionContext): Promise<void>;
+    cancel?(request: AgentTurnCancelRequest): Promise<void> | void;
+    /**
+     * Deliver a correction to a turn that is already running.
+     *
+     * Optional because it is a tier-3 capability (ADE spec §2.9): it needs a
+     * protocol the agent listens on mid-turn. An adapter that cannot do this must
+     * NOT stub it — the host reports `steer_unsupported` with a named reason,
+     * which §6.3 requires, and the user can move the session to a mode that
+     * supports it. A silent no-op would be the worst outcome: the user believes
+     * they corrected the agent and nothing happened.
+     */
+    steer?(request: AgentTurnSteerRequest): Promise<void> | void;
+    close?(): Promise<void> | void;
+}
+export interface AgentHostCoordinatorOptions {
+    hostVersion: string;
+    hostInstanceId: string;
+    processBoundary: 'in-process' | 'per-user-service';
+    storageSchemaVersion: number;
+    eventSchemaVersion: number;
+    providers?: AgentRuntimeProviderDescriptor[];
+    providerCatalogLoader?: () => AgentRuntimeProviderDescriptor[] | Promise<AgentRuntimeProviderDescriptor[]>;
+    runtimeEvents?: AgentRuntimeEventEnvelope[];
+    runtimeEventRepository?: AgentRuntimeEventRepository;
+    stateRepository?: AgentStateRepository;
+    workspaceService?: AgentWorkspaceService;
+    interactionService?: AgentInteractionService;
+    permissionPolicyService?: AgentPermissionPolicyService;
+    /**
+     * Durable record of in-flight turns, so a turn killed by process exit is
+     * NAMEABLE afterwards instead of silently absent (§5.5). Defaults to
+     * in-memory, which records nothing across a restart — correct as a default,
+     * and the composition supplies a durable one.
+     */
+    interruptedTurnStore?: InterruptedTurnStore;
+    /**
+     * How many turns may run at once, across EVERY surface. Defaults to the environment-resolved
+     * policy. Injectable so a test can drive the host to capacity without mutating process env,
+     * which is global and would race other tests.
+     */
+    turnAdmissionPolicy?: TurnAdmissionPolicy;
+    /**
+     * How long the host waits for an adapter to notice an abort before it STOPS COUNTING the turn.
+     * Defaults to `DEFAULT_TURN_ABANDON_GRACE_MS`. Injectable so a test need not wait seconds.
+     */
+    turnAbandonGraceMs?: number;
+    sdkControlService?: AgentSdkControlService;
+    engineeringControlService?: AgentEngineeringControlService;
+    turnExecutionAdapters?: AgentTurnExecutionAdapter[];
+    /**
+     * Coordination between runs (`XENO_AGENT_COORDINATION_SPEC.md`).
+     *
+     * Optional, and absent means the host runs exactly as it did before: no
+     * coordination events, no claims, `coordination` reports undefined. A fleet
+     * of one does not need the primitives, and a host that silently invented a
+     * coordination surface would make "is this host coordinating?" unanswerable
+     * from its options.
+     */
+    coordinationService?: CoordinationService;
+    /**
+     * Tier-1 run observation (`XENO_AGENT_ADE_SPEC.md` §2.9).
+     *
+     * Optional for the same reason coordination is: a host with no isolation
+     * substrate wired has nothing to observe, and inventing an empty diff would
+     * be the false-clean output §2.9's sensors exist to prevent.
+     */
+    runObservationService?: RunObservationService;
+    /**
+     * Answers whether a run is CONTAINED (ADE §5.3).
+     *
+     * Optional, and its ABSENCE is meaningful rather than merely permitted: with
+     * no service the host still answers, and answers `none`, because nothing
+     * confining a run is a fact the user is entitled to be told.
+     */
+    runIsolationService?: RunIsolationService;
+    /**
+     * Told when a run begins, so something can attach a sandbox to it.
+     *
+     * The service folds a stream it is GIVEN; it never acquires one. Without this
+     * hook the only way a run becomes observed is a caller who already knows the
+     * run id, which is nobody — so the service would be mounted and permanently
+     * empty. That is the "built, tested, unreachable" shape this ecosystem has
+     * shipped four times, and this is the call that closes it.
+     *
+     * Deliberately NOT awaited: attaching means spawning a container, and a turn
+     * must not wait on a review capability. A binder that fails leaves the run
+     * unobserved, which every consumer already reports honestly.
+     */
+    runObservationBinder?: AgentRunObservationBinder;
+    /**
+     * The session substrate (§2.8) — every session's PTY, its optional protocol
+     * channel, and its render mode as one object.
+     *
+     * Optional like its siblings: a host with no substrate mounted has no
+     * sessions, which is honest, rather than sessions that render nothing.
+     */
+    sessionService?: AgentSessionService;
+    /**
+     * Intake (§5.1). Optional like its siblings: a host with no sources wired has
+     * no inbox, which is honest — an empty inbox invented for a host that cannot
+     * read one would say "no work" when the truth is "nobody looked".
+     */
+    intakeService?: IntakeService;
+    /**
+     * Workspace knowledge (§5.8). Optional: a host without it reports knowledge
+     * unavailable, which is honest. Inventing an empty knowledge base would say
+     * "this workspace has learned nothing" when the truth is "nobody is keeping
+     * track".
+     */
+    knowledgeService?: WorkspaceKnowledgeService;
+    /**
+     * ACP provider approval (§10b). Optional: a host without it reports
+     * `unavailable` by name rather than pretending the action succeeded.
+     */
+    acpApprovalService?: AgentAcpApprovalService;
+    /**
+     * Subagent runs — ADE §5.2. Absent means this host declines `subagent.run.*` with a named
+     * reason rather than queueing work nothing will execute.
+     */
+    subagentRuns?: SubagentRunPort;
+    /**
+     * Which run a turn belongs to, for gate-8 cause attribution.
+     *
+     * 🔴 A TURN IS NOT A RUN, and conflating them breaks claims. A run outlives
+     * its turns — the coordination spec §6 has a message to an idle run *begin* a
+     * new turn, so the run demonstrably exists between them — while
+     * `endRun` RELEASES EVERY CLAIM THE RUN HOLDS. Deriving `endRun` from turn
+     * completion would drop another agent's lock the moment a turn finished,
+     * defeating the one primitive that exists to stop two runs colliding.
+     *
+     * So only `endTurn` is wired here (it clears the message cause, which is
+     * genuinely turn-scoped) and `endRun` is deliberately left to whoever created
+     * the run. This resolver only has to answer "which run is this turn part of";
+     * the default reads the request's own identifiers and never guesses.
+     */
+    resolveRunId?: (request: AgentTurnStartRequest) => string | undefined;
+}
+/**
+ * Attaches an isolation substrate to a run as it begins.
+ *
+ * A port, so the host stays free of any knowledge of `xeno-use` — including its
+ * licence. The composition supplies the implementation; the host only knows that
+ * a run started and what workspace it belongs to.
+ */
+export interface AgentRunObservationBinder {
+    begin(context: {
+        runId: string;
+        conversationId: string;
+        /**
+         * The run's working directory, when the request named one.
+         *
+         * This is what an observer actually needs — the sensor watches a directory,
+         * not an id — so it is passed rather than a `workspaceId` the binder would
+         * have to resolve through a service it should not need.
+         */
+        primaryDirectory?: string;
+        workspaceId?: string;
+        agentId?: string;
+    }): void;
+}
+/**
+ * How long the host waits for an adapter to notice an abort before it stops counting the turn.
+ *
+ * 🔴 This exists because the host used to wait FOREVER. `activeTurns` is cleared in the
+ * `.finally()` of the adapter's execute promise, so an adapter that ignores `signal` — or simply
+ * hangs — kept its entry indefinitely. Measured 2026-08-17: `turn.cancel` returned
+ * `success: true` while the turn stayed active and stayed counted, and with turn admission in
+ * place the slot never came back. Sixteen such turns wedge a default host, recoverable only by
+ * restarting it.
+ *
+ * Generous, because a slow-but-honest adapter finishing its cleanup is the common case and
+ * abandoning it early would be worse than waiting. Bounded, because "wait for cooperation that
+ * may never come" is not a policy.
+ */
+export declare const DEFAULT_TURN_ABANDON_GRACE_MS = 5000;
+export declare class AgentHostCoordinator implements AgentHostTransport {
+    private readonly options;
+    private readonly listeners;
+    private readonly providers;
+    private readonly providerCatalogLoader;
+    private readonly runtimeEvents;
+    private readonly runtimeEventRepository;
+    private readonly stateRepository;
+    private readonly workspaceService;
+    private readonly interactionService;
+    private readonly permissionPolicyService;
+    private readonly interruptedTurnStore;
+    private readonly sdkControlService;
+    private readonly engineeringControlService;
+    private readonly coordinationService;
+    /**
+     * Run id -> the conversation that run belongs to.
+     *
+     * Gate 8 needs coordination on the RUN TIMELINE, and a timeline entry is
+     * addressed by conversation and request. Only the host knows that mapping;
+     * the coordination service deals in run ids alone, which is what keeps it
+     * testable without a store.
+     */
+    private readonly runContexts;
+    private coordinationEventSequence;
+    /** Collisions seen since this host started — see the sink above for why this
+     *  is the only place they exist. */
+    private readonly fleetCollisions;
+    private readonly runObservationService;
+    private readonly runIsolationService;
+    private readonly runObservationBinder;
+    private readonly sessionService;
+    private readonly intakeService;
+    private readonly knowledgeService;
+    private readonly acpApprovalService;
+    /**
+     * Subagent runs — ADE §5.2. A PORT spanning `SubagentRunService` (create/list) and
+     * `SubagentScheduler` (cancel), because cancelling a launched run must reach the adapter.
+     */
+    private readonly subagentRuns;
+    private readonly resolveRunId;
+    private readonly connectedClients;
+    /** What each connected client declared it can do, keyed the same way. */
+    private readonly clientCapabilities;
+    private readonly turnExecutionAdapters;
+    private readonly turnAdmissionPolicy;
+    private readonly turnAbandonGraceMs;
+    /**
+     * Timers owned by a live turn: its deadline, and any abandonment grace already started.
+     * Cleared when the turn settles, so a completed turn cannot be abandoned retroactively.
+     */
+    private readonly turnTimers;
+    private readonly activeTurns;
+    private readonly commandResults;
+    /**
+     * Instructions stacked while a turn is running, per conversation.
+     *
+     * Held by the HOST, not by an adapter: that is what makes queueing work at
+     * every structure tier (ADE spec §2.9), including a third-party agent running
+     * its own TUI where there is no protocol to hand a steer to.
+     *
+     * The host does NOT auto-start the queued turn. It holds the instruction and
+     * signals when the active turn ends; the client starts the next turn, because
+     * the client is where the user's permission context lives. Auto-drain would
+     * convert a queue into unattended execution, which is a different decision.
+     */
+    private readonly queuedInstructions;
+    private queuedInstructionSequence;
+    private sequence;
+    private catalogRevision;
+    private providerCatalogFingerprint;
+    private providerCatalogRefresh;
+    constructor(options: AgentHostCoordinatorOptions);
+    /**
+     * The mounted coordination service, or `undefined` when the host has none.
+     *
+     * Deliberately NOT reachable through `request()`. A run coordinates with
+     * another run; a client surface watches. Exposing send/claim as host methods
+     * would let whatever is holding a transport act *as* a run, which is exactly
+     * the boundary coordination spec §4 draws — and `AgentHostTransport` is a
+     * protected cross-repo interface whose consumers (Hub, Shell) would all need
+     * coordinating for a capability neither of them is asking for.
+     */
+    get coordination(): CoordinationService | undefined;
+    /**
+     * Puts what the workspace knows into the turn — ADE §5.8's gate.
+     *
+     * 🔴 **In the coordinator, before the adapter is invoked, so it cannot be
+     * per-provider.** The gate is that a fact learned by one provider reaches a
+     * later run on a DIFFERENT one; injecting inside an adapter would make that a
+     * property each lane had to remember, and the lane that forgot would fail
+     * silently — the prompt would simply be missing knowledge, which looks exactly
+     * like an agent that never learned anything.
+     *
+     * 🔴 **Prepended to `systemPrompt`, never replacing it.** Standing context
+     * about the codebase is what a system prompt is for, and every lane already
+     * carries one — so this reaches all of them without touching three adapters.
+     * A caller's own system prompt is preserved below it.
+     *
+     * A failure here does NOT fail the turn. Knowledge is an enrichment; the run
+     * is the user's actual work, and a broken store must not be able to stop it.
+     * The turn simply proceeds without the block, which is the same behaviour as a
+     * workspace that has learned nothing yet.
+     */
+    private injectWorkspaceKnowledge;
+    /** Workspace knowledge — ADE §5.8. Thin: the rules live in `core`. */
+    private listKnowledge;
+    private recordKnowledge;
+    private forgetKnowledge;
+    private knowledgeContext;
+    /** Intake — ADE §5.1. Thin: every rule lives in `core/intakeClaim`. */
+    private listIntakeSources;
+    private listIntakeItems;
+    private claimIntakeItem;
+    private releaseIntakeItem;
+    private dispatchIntakeItem;
+    /**
+     * Sessions over the protocol — ADE §5.5, build-order step 4.
+     *
+     * The substrate has had attach, takeover and input routing all along; none of
+     * it was reachable from a surface, which is the same "built, tested,
+     * unreachable" shape this repo has shipped repeatedly. These methods are thin
+     * on purpose: every rule worth trusting lives in `AgentSessionService` and
+     * `writeLease`, where it is tested without a host.
+     */
+    private listSessions;
+    private attachSession;
+    private detachSession;
+    private snapshotSession;
+    /**
+     * Hands a run what its peers said — ADE §5.2b's `message` primitive.
+     *
+     * 🔴 Nothing called `deliverTo`. Messages were sent, journalled, reported
+     * `delivered` to the sender — and sat in the bus forever, because the only
+     * thing that empties an inbox had no caller anywhere in the repo. The
+     * primitive was half a pipe: every agent could send and no agent could
+     * receive, while the sender was told it had been delivered.
+     *
+     * At TURN START and in the coordinator, for the same reason §5.8's knowledge
+     * injection is: a push that each lane had to remember would fail silently in
+     * the lane that forgot, and a prompt merely missing its messages looks exactly
+     * like a run nobody wrote to.
+     *
+     * Prepended to `systemPrompt` alongside knowledge rather than appended to the
+     * user's prompt — what a peer said is standing context for this turn, not
+     * something the user typed, and putting it in their words would misattribute
+     * it.
+     *
+     * ⚠️ Draining also sets the run's CAUSE, which is what makes gate 8
+     * attribution and §8 loop detection work at all: a message this run sends
+     * while handling another inherits the chain. Both were inert for the same
+     * reason.
+     */
+    private deliverCoordinationMessages;
+    /**
+     * A run's activity changed — §7's run state and last decision.
+     *
+     * 🔴 `awaiting-approval` had no producer at all, and the gap is not
+     * cosmetic: a peer deciding whether to wait for a run or take the work itself
+     * needs "blocked on a human" to look different from "busy". A run reported
+     * `running` while it sits on a permission prompt is the one case where
+     * waiting is guaranteed to be wrong.
+     *
+     * Public because the signal originates in a turn adapter, which the
+     * composition builds BEFORE this host exists — the same ordering
+     * `setEventSink` already solves for coordination events.
+     */
+    reportRunActivity(signal: RunActivitySignal): void;
+    /**
+     * Puts a run on the coordination roster — ADE §5.2b.
+     *
+     * 🔴 Nothing called `registerRun`. The primitives were reachable from both
+     * lanes and INERT: `peers()` returns an empty list for a caller it has never
+     * heard of, so every agent asking who else was working got the same answer as
+     * an agent genuinely alone. The build was complete and the feature did
+     * nothing — the shape this repo keeps finding one level further in.
+     *
+     * An UPSERT, called at both ends of a turn, because a run spans many turns and
+     * its state changes: `running` while a turn is in flight, `idle` between them.
+     * A run is never removed here; `endRun` belongs to whoever created the run,
+     * and claims have lease expiry as the backstop for a host that never got the
+     * news.
+     *
+     * ⚠️ `complete: false`, always, and honestly. This host observes FILES — the
+     * process sensor lives behind `xeno-use` and only the file-change port is
+     * consumed here — so `commandsRun` is empty because commands are UNOBSERVED,
+     * not because none ran. A peer must be able to tell those apart.
+     */
+    private registerCoordinationRun;
+    /**
+     * Gives a run a session — ADE §2.8, and the step §9 has been stuck on.
+     *
+     * Opened at TURN START rather than on demand, because a session is where a
+     * person looks to see what the agent is doing, and one that only exists after
+     * someone asks for it is not there during the minute they most want it.
+     *
+     * 🔴 Every ingredient is derived, none is asserted:
+     *
+     * - the render support comes from the ADAPTERS (`renderSupportFor`), so a
+     *   provider nothing can execute is refused by name instead of opening a
+     *   session that would render nothing;
+     * - the protocol channel is the run's OWN runtime-event stream, already
+     *   redacted and already durable, so the terminal is a rendering of the run
+     *   rather than a second opinion about it;
+     * - the PTY has no process behind it, because in `acp` there is nothing to
+     *   attach to — and `createBufferedSessionPty` throws rather than silently
+     *   swallowing a write, so a broken mode rule surfaces instead of losing
+     *   what someone typed.
+     *
+     * Failures are contained for the same reason the observation binder's are: a
+     * turn is the user's actual work, and a session is an observability surface
+     * over it. A run without a session is honest — `session.list` simply will not
+     * show it — whereas a turn that failed to start because a terminal could not
+     * be opened would be absurd.
+     *
+     * ⚠️ One session per RUN, not per turn. A second turn on the same run finds
+     * the session already open and leaves it alone; re-opening would discard the
+     * output a viewer is reading mid-conversation.
+     */
+    private openSessionForRun;
+    private routeSessionInput;
+    /**
+     * The turn a run is executing right now, if any.
+     *
+     * §2.8's routing needs two facts — is a turn in flight, and can this agent
+     * take a correction mid-turn — and both live here. `activeTurns` is keyed by
+     * conversation and request, so finding a RUN's turn means asking
+     * `resolveRunId` about each one, the same derivation everything else uses.
+     */
+    private activeTurnForRun;
+    /**
+     * Delivers what the substrate could not, through the ONE path that can.
+     *
+     * §2.8 promises typing never falls into a void, and `AgentSessionService`
+     * keeps its half by refusing to write into a PTY with no process behind it. It
+     * deliberately stops there: an `acp` steer travels `turn.steer`, where
+     * acknowledgement, idempotency and the named refusal already live, and a
+     * second delivery path from inside the substrate would be the unacknowledged
+     * one §5.5 measured to be wrong.
+     *
+     * So the host — which owns execution — closes the loop here, for BOTH input
+     * doors. Splitting it would leave the promise held at one entrance again.
+     *
+     * A failure is REPORTED, never swallowed: `turn_not_active` in particular is
+     * an ordinary outcome (someone typed between turns) and its message already
+     * tells the reader to queue instead. Reporting `delivered: true` there would
+     * be the precise lie this whole chain exists to prevent.
+     */
+    private deliverOwedSessionInput;
+    private takeOverSession;
+    private releaseSession;
+    /**
+     * Every run this host knows about — ADE §9 step 6.
+     *
+     * Composed from three subsystems rather than a fourth record, because a
+     * separate fleet ledger would be a second copy of facts that already exist and
+     * would disagree with them the first time one was updated and the other was
+     * not.
+     *
+     * 🔴 The completeness flags are the load-bearing part. A fleet view showing
+     * three collisions when five happened, or four changed files when a drain was
+     * dropped, is worse than no fleet view: it is the shape a person uses to
+     * decide the work is safe to land.
+     */
+    /**
+     * Plans a fan-out WITHOUT starting anything — ADE §5.2's scheduler.
+     *
+     * Deliberately separate from dispatch. A plan is the reviewable artifact: it
+     * shows which agent gets which task, which tasks nothing can run and why, and
+     * how the load actually spread — all before a single agent touches a
+     * repository. Fusing plan and execute would remove the only moment at which
+     * any of that can be checked.
+     */
+    private planFleetFanOut;
+    /**
+     * Which agents could run a task requiring these capabilities — ADE §5.2.
+     *
+     * A pure QUERY over the live provider catalog: it starts nothing, so a
+     * surface or a scheduler can ask before committing to anything.
+     *
+     * 🔴 The refusal REASON is the deliverable, not the boolean. §5.2's gate is
+     * that a task requiring an undeclared capability is "refused with a named
+     * reason" — so this reports which capability nobody declares, and
+     * distinguishes that from every capable agent merely being down. Those two
+     * send a user to completely different places.
+     *
+     * The matching rules live in `routeByCapability` (provider-neutral, in
+     * `core`) rather than here: this method's job is to supply the catalog and
+     * shape the answer for the wire.
+     */
+    private routeByCapabilities;
+    private readFleetView;
+    /**
+     * A run's observed diff, for review.
+     *
+     * 🔴 Unavailable is reported as `available: false` with a reason, never as an
+     * empty change list. They are different facts — "this run changed nothing" and
+     * "nobody was watching" — and a surface that cannot tell them apart will show
+     * a clean review for an unobserved run.
+     */
+    /**
+     * What a run is not being told yet — coordination §6 `hold`.
+     *
+     * 🔴 `available: false` when this host has no coordination service, so a
+     * surface can tell "this host does not coordinate" from "nothing is
+     * held". Reporting an empty list for both would make an unmounted service
+     * look like a quiet one.
+     */
+    private listHeldMessages;
+    /** A human approves one held message. §6's approval step, made reachable. */
+    private releaseHeldMessage;
+    /**
+     * A human pins or releases a run's inbound policy — §6's override, made
+     * reachable.
+     *
+     * 🔴 Deliberately a HOST method and not a lane call. `CoordinationLanePort`
+     * exposes exactly four calls and this is not one of them, because an agent
+     * that could set its receiver's policy could accept its own messages past the
+     * rule that a message never moves trust upward.
+     */
+    private setCoordinationInboundPolicy;
+    private readRunObservation;
+    /**
+     * Content for one changed path — §2.9 hunk-level review.
+     *
+     * The service refuses a path the run did not change, so this cannot be used to
+     * browse the sandbox: that is a different capability with a different consent
+     * story, and a review pane is not a licence to read arbitrary files.
+     */
+    private readRunObservationChange;
+    /** Where the observed runs collide — §5.7, while both are still alive. */
+    private readRunObservationOverlaps;
+    /**
+     * How many turns are executing right now.
+     *
+     * Exposed so a composition can answer "would quitting destroy work?" — which
+     * it cannot ask any other way, and which is the difference between an app that
+     * closes cleanly and one that silently ends a run the user is waiting on.
+     *
+     * A COUNT, not the turns themselves: a caller deciding whether to quit has no
+     * business with the requests, and handing them out would make an internal map
+     * part of the surface.
+     */
+    get activeTurnCount(): number;
+    /**
+     * The mounted run-observation service, or `undefined` when unmounted.
+     *
+     * The full change set is pulled through here rather than pushed on the feed:
+     * a diff is large and mostly unchanged between polls, while the notification
+     * that it moved is small. Same reason it is not on `AgentHostTransport` —
+     * that is a protected cross-repo interface (root ABSOLUTE RULE §4).
+     */
+    get runObservation(): RunObservationService | undefined;
+    /**
+     * The mounted session substrate, or `undefined` when unmounted.
+     *
+     * Reached by composition, not through `request()`: attaching to a session
+     * means subscribing to a byte stream, which is not a request/response shape —
+     * and `AgentHostTransport` is protected (root ABSOLUTE RULE §4).
+     */
+    get sessions(): AgentSessionService | undefined;
+    request<M extends AgentHostMethod>(method: M, input: AgentHostInput<M>): Promise<AgentHostOutput<M>>;
+    subscribe(listener: AgentHostEventListener): AgentHostUnsubscribe;
+    /**
+     * Forget a client whose connection is gone.
+     *
+     * 🔴 Before this there was no `connectedClients.delete` anywhere except a wholesale clear, so
+     * the set only ever grew within a session. That is invisible until something asks a question of
+     * it — and `canPresentElicitations` is exactly such a question, asked immediately before the
+     * host puts a prompt to a person and waits with no timeout.
+     */
+    releaseClient(instanceId: string): void;
+    /**
+     * Is there a connected client that can put a question to a person and answer it?
+     *
+     * ⚠️ Subscribers are NOT the signal, and that is the trap this method exists to avoid: the RPC
+     * server subscribes exactly ONE listener and fans out to whatever sockets it has, so a listener
+     * count of 1 is equally consistent with ten attached clients and none. Only a completed
+     * handshake says someone is there, and only a declared capability says they can answer.
+     */
+    hasElicitationCapableClient(): boolean;
+    registerProvider(provider: AgentRuntimeProviderDescriptor): void;
+    registerTurnExecutionAdapter(adapter: AgentTurnExecutionAdapter): void;
+    close(): Promise<void>;
+    removeProvider(providerId: string): boolean;
+    recordRuntimeEvent(event: AgentRuntimeEventEnvelope): Promise<boolean>;
+    publishPersistedRuntimeEvent(event: AgentRuntimeEventEnvelope): void;
+    createElicitationSurfaceMessenger(): {
+        send(channel: string, payload: Record<string, unknown>): void;
+    };
+    /**
+     * Enqueue a subagent run — ADE §5.2, the join between `fleet.plan` and `SubagentScheduler`.
+     *
+     * ⚠️ Reached through a PORT spanning two objects on purpose. `createRun`/`listRuns` live on
+     * `SubagentRunService` and `cancelRun` on `SubagentScheduler` — and cancel must go through the
+     * SCHEDULER, because cancelling a run whose adapter has already launched it has to tell the
+     * adapter. Handing the host either object alone would push that distinction onto every caller.
+     *
+     * 🔴 Refuses with a NAMED reason when no scheduler is mounted, rather than pretending. A host
+     * with no scheduler is a normal composition (the standalone app had none until this landed),
+     * and a create that silently succeeded against nothing would queue work no one will ever run.
+     */
+    private createSubagentRun;
+    /**
+     * What the turn that spawned this run is allowed to reach.
+     *
+     * Resolved from `runContexts`, which the host populates at `turn.start` and keeps for the life
+     * of the run. Absent means the host genuinely does not know — a run created outside a turn, or
+     * by a surface that declared no workspace — and `boundSubagentWorkspace` treats that as
+     * authorising nothing rather than as permission.
+     */
+    private parentTurnWorkspace;
+    private listSubagentRuns;
+    private cancelSubagentRun;
+    /** Remember a timer owned by this turn, so settling can cancel it. */
+    private trackTurnTimer;
+    /**
+     * Drop every timer for a turn. Called when it settles, so a turn that finished normally can
+     * never be abandoned afterwards by a timer that was already in flight.
+     */
+    private clearTurnTimers;
+    /**
+     * Abort a turn, then STOP COUNTING IT if the adapter does not settle in time.
+     *
+     * 🔴 The honesty this preserves is the whole point. The host cannot make a third-party adapter
+     * stop — it can only ask, and then decide what to believe. Waiting forever means one
+     * uncooperative adapter permanently consumes an admission slot; pretending the abort worked
+     * means reporting a success we do not have, which this repo's own rules forbid. So the host
+     * abandons ITS OWN record and says so: `turn.execution.abandoned` states that the host gave up
+     * tracking, NOT that the work stopped.
+     */
+    private abortAndAbandon;
+    private startTurn;
+    private recordContextCompaction;
+    private cancelTurn;
+    private steerTurn;
+    /** True while any turn is running for this conversation. */
+    private hasActiveTurn;
+    private queueSnapshot;
+    private queueTurnInstruction;
+    private listQueuedInstructions;
+    private dropQueuedInstruction;
+    private rememberTurnStartFailure;
+    private commandKey;
+    private isConnectedClient;
+    private handshake;
+    private listProviders;
+    private refreshProviderCatalog;
+    private listRuntimeEvents;
+    private requireStateRepository;
+    private requireWorkspaceService;
+    private requireInteractionService;
+    /**
+     * Re-issues a turn that process death interrupted (§5.5).
+     *
+     * ⚠️ It RESTARTS rather than resumes, and says so in the result. A turn killed
+     * with the process left no continuation point inside the agent — only the
+     * request that produced it. Work already done is done again, and side effects
+     * already performed have already happened. Where the request carries a
+     * provider continuation the session is picked up, which narrows the gap
+     * without closing it.
+     *
+     * Everything after the lookup goes through `startTurn`, deliberately: a
+     * second execution path would be free to drift from the first on provider
+     * validation, catalog revision, adapter selection and idempotency — and the
+     * one that runs rarely is the one that would rot.
+     */
+    /**
+     * Approve or revoke an ACP provider's binary.
+     *
+     * Fails CLOSED and by name in every branch. The shipping app previously
+     * rendered an enabled Approve button whose bridge answered "not available on
+     * this host yet" — a message that was true of the bridge and false of the
+     * host, which implements this. `unavailable` here means the host genuinely
+     * has no approval service mounted, and says so.
+     */
+    private approveAcpProvider;
+    private resumeTurn;
+    /**
+     * Reports turns that were running when the previous process ended (§5.5).
+     *
+     * Called by the composition after construction. Each surviving record is
+     * journalled as a durable `turn.interrupted` runtime event, so the surface
+     * shows "this turn was interrupted" instead of a turn that simply stops
+     * mid-sentence and never says why. An absence indistinguishable from an
+     * outcome is the failure this whole mechanism exists to remove.
+     *
+     * Records are NOT cleared: `turn.resume` needs them. They clear when the turn
+     * reaches a terminal state, which a resumed turn eventually does.
+     */
+    reportInterruptedTurns(): Promise<number>;
+    private requirePermissionPolicyService;
+    private requireSdkControlService;
+    private requireEngineeringControlService;
+    private assertWorkspaceClient;
+    private assertSdkControlClient;
+    private assertEngineeringControlClient;
+    private setProvider;
+    private publishCatalogChange;
+    private appendRuntimeEvent;
+    /**
+     * Writes one coordination event to the run timeline.
+     *
+     * Silent when the run has no known conversation — a coordination event
+     * addressed to a run this host never started a turn for has no timeline to
+     * join, and inventing a conversation id would put the entry somewhere a
+     * reviewer would never look. It stays on the live feed either way.
+     */
+    private recordCoordinationEvent;
+    private publish;
+}
+/**
+ * Coordination — the team-agent primitives (`XENO_AGENT_COORDINATION_SPEC.md`).
+ *
+ * Exported from the PORTABLE entry rather than `./node`: these are
+ * provider-neutral rules with no Node dependency, and the host is the only party
+ * that can arbitrate them because it is the only party that sees every run.
+ */
+export * from './coordination/claims.js';
+export * from './coordination/messages.js';
+export * from './coordination/query.js';
+export * from './coordination/CoordinationService.js';
+export * from './coordination/laneBridge.js';
+export * from './coordination/coordinationTools.js';
+export * from './coordination/permissionWaitRegistry.js';
+export * from './coordination/renderInbox.js';
+export * from './coordination/runtimeEvents.js';
+export * from './knowledge/WorkspaceKnowledgeService.js';
+export * from './intake/IntakeService.js';
+export * from './observation/RunObservationService.js';
+export * from './isolation/RunIsolationService.js';
+/**
+ * The confining implementation — browser-safe, and that is not an accident.
+ *
+ * It reaches the substrate over `fetch` and imports nothing from `node:`, so it
+ * belongs in THIS barrel while `RunExecutionEnvironment` does not: the
+ * environment constructs a `LocalCommandExecutor`, which spawns processes.
+ * Exporting the environment here made the browser barrel transitively reach
+ * `node:child_process` — caught by `browserBarrelPurity.test.ts` rather than by
+ * review, which is the whole reason that gate exists.
+ */
+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';
+//# sourceMappingURL=index.d.ts.map