@xenosystem/agent-interface-contract 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2019 @@
+export * from './cloudRuns.js';
+import type * as Engineering from './engineering.js';
+export declare const XENO_AGENT_HOST_PROTOCOL_VERSION: 1;
+export declare const XENO_AGENT_HOST_MIN_PROTOCOL_VERSION: 1;
+export declare const AGENT_SURFACE_KINDS: readonly ["standalone-desktop", "hub-embed", "shell-embed", "embed-preview", "headless-client"];
+export type AgentSurfaceKind = (typeof AGENT_SURFACE_KINDS)[number];
+export declare const AGENT_RUNTIME_PROVIDER_KINDS: readonly ["sdk-native", "xeno-cloud", "cli-app-server", "cli-remote", "acp"];
+export type AgentRuntimeProviderKind = (typeof AGENT_RUNTIME_PROVIDER_KINDS)[number];
+export declare const AGENT_HARNESS_CAPABILITIES: readonly ["development.execution", "turn.streaming", "turn.reasoning", "turn.cancel", "turn.resume", "acp.provider.approve", "turn.queue", "turn.steer", "tools.file.read", "tools.file.write", "tools.patch", "tools.terminal", "tools.background-process", "git.operations", "review.selective-hunks", "checkpoints.create", "checkpoints.restore", "workspace.multi-root", "code.lsp", "browser.automation", "browser.devtools", "context.semantic-retrieval", "context.compaction", "mcp", "plugins", "skills", "hooks", "subagents", "background-runs", "remote-runs", "usage.reporting", "support.diagnostics", "coordination.messages", "coordination.claims", "coordination.query"];
+export type AgentHarnessCapability = (typeof AGENT_HARNESS_CAPABILITIES)[number];
+export type AgentAvailability = 'available' | 'degraded' | 'blocked' | 'unavailable';
+export type AgentCapabilityStatus = 'available' | 'degraded' | 'blocked' | 'unsupported';
+export interface AgentCapabilityDescriptor {
+    status: AgentCapabilityStatus;
+    source: 'provider' | 'host' | 'policy';
+    reason?: string;
+    version?: string;
+}
+export type AgentCapabilityMatrix = Partial<Record<AgentHarnessCapability, AgentCapabilityDescriptor>>;
+export interface AgentReasoningOption {
+    id: string;
+    label: string;
+    description?: string;
+    runtimeModelId?: string;
+    isDefault?: boolean;
+}
+export interface AgentModelDescriptor {
+    id: string;
+    displayName: string;
+    availability: AgentAvailability;
+    isDefault?: boolean;
+    contextWindowTokens?: number;
+    maxOutputTokens?: number;
+    reasoningOptions?: AgentReasoningOption[];
+    safeUnavailableReason?: string;
+}
+export interface AgentRuntimeProviderDescriptor {
+    id: string;
+    kind: AgentRuntimeProviderKind;
+    displayName: string;
+    availability: AgentAvailability;
+    safeUnavailableReason?: string;
+    capabilities: AgentCapabilityMatrix;
+    models: AgentModelDescriptor[];
+    defaultModelId?: string;
+    allowsProviderDefaultModel?: boolean;
+    catalogRevision: string;
+}
+export interface AgentRuntimeSelection {
+    providerId: string;
+    catalogRevision: string;
+    modelId?: string;
+    reasoningOptionId?: string;
+    runtimeModelId?: string;
+}
+export interface AgentHostProtocolRange {
+    min: number;
+    max: number;
+}
+export interface AgentHostClientIdentity {
+    clientId: string;
+    clientVersion: string;
+    instanceId: string;
+    surface: AgentSurfaceKind;
+}
+export type AgentEngineeringRequest<T extends Engineering.EngineeringRequestBase> = T & {
+    client: AgentHostClientIdentity;
+};
+export interface AgentHostHandshakeRequest {
+    identity: AgentHostClientIdentity;
+    supportedProtocol: AgentHostProtocolRange;
+}
+export interface AgentHostHandshake {
+    protocol: {
+        current: number;
+        supported: AgentHostProtocolRange;
+    };
+    host: {
+        instanceId: string;
+        version: string;
+        authority: 'primary' | 'diagnostic-read-only';
+        processBoundary: 'in-process' | 'per-user-service';
+    };
+    storage: {
+        owner: 'xeno-agent-host';
+        schemaVersion: number;
+        eventSchemaVersion: number;
+    };
+    surface: AgentHostClientIdentity;
+}
+/**
+ * 🔴 THE HANDSHAKE HAS NO `capabilities`, and its absence is deliberate.
+ *
+ * It used to carry an `AgentCapabilityMatrix`. No composition ever passed one,
+ * so every real host sent `{}`, and nothing anywhere read it — but "unused" is
+ * the weaker half of the reason.
+ *
+ * The strong half: a host-level matrix is at the WRONG GRANULARITY to ever be
+ * correct. Capabilities in this system belong to a PROVIDER
+ * (`AgentRuntimeProviderDescriptor.capabilities`), because what an agent can do
+ * depends on which lane is executing it — and the host lowers them further at
+ * registration when it, not the provider, owns the answer
+ * (`withHostBackedCapabilities`, `source: 'host'`). One matrix for the whole
+ * host could only ever be a summary that is wrong for some provider.
+ *
+ * Left in place it would eventually be "fixed" by populating it, and surfaces
+ * would start reading a claim no host can honestly make. Ask a provider.
+ */
+export interface AgentProviderListRequest {
+    includeUnavailable?: boolean;
+}
+export type AgentProviderRefreshRequest = AgentProviderListRequest;
+export interface AgentProviderListResult {
+    revision: string;
+    providers: AgentRuntimeProviderDescriptor[];
+}
+export interface AgentRuntimeEventEnvelope {
+    id: string;
+    sequence: number;
+    timestamp: string;
+    conversationId: string;
+    requestId: string;
+    workspaceId?: string;
+    teamId?: string;
+    agentId?: string;
+    parentRunId?: string;
+    subagentRunId?: string;
+    providerKind?: string;
+    providerId?: string;
+    type: string;
+    source: string;
+    schemaVersion?: string;
+    redactionState?: string;
+    event: Record<string, unknown>;
+}
+export interface AgentRuntimeEventDraft {
+    conversationId: string;
+    requestId: string;
+    workspaceId?: string;
+    teamId?: string;
+    agentId?: string;
+    parentRunId?: string;
+    subagentRunId?: string;
+    providerKind?: string;
+    providerId?: string;
+    source?: string;
+    schemaVersion?: string;
+    redactionState?: string;
+    event: Record<string, unknown> & {
+        id: string;
+        type: string;
+        timestamp: string;
+    };
+}
+export interface AgentRuntimeEventListRequest {
+    conversationId: string;
+    requestId?: string;
+    subagentRunId?: string;
+    type?: string;
+    afterSequence?: number;
+    limit?: number;
+}
+export interface AgentRuntimeEventListResult {
+    events: AgentRuntimeEventEnvelope[];
+    nextSequence: number | null;
+}
+/**
+ * Transitional host-owned snapshot persistence used while the legacy JSON
+ * stores are migrated into the final transactional state database. The host
+ * validates and sanitizes these opaque renderer projections before writing.
+ */
+export interface AgentWorkspaceStateLoadResult {
+    success: boolean;
+    workspaces: unknown[];
+    error?: string;
+}
+export interface AgentWorkspaceStateSaveRequest {
+    workspaces: unknown[];
+}
+export interface AgentWorkspaceStateSaveResult {
+    success: boolean;
+    error?: string;
+}
+export interface AgentConversationStateLoadResult {
+    success: boolean;
+    conversations: unknown[];
+    recoveredConversationIds?: string[];
+    corruptConversationFiles?: string[];
+    error?: string;
+}
+export interface AgentConversationStateSaveRequest {
+    conversation: unknown;
+}
+export interface AgentConversationStateSaveResult {
+    success: boolean;
+    error?: string;
+}
+export interface AgentConversationStateDeleteRequest {
+    conversationId: string;
+}
+export interface AgentConversationStateDeleteResult {
+    success: boolean;
+    deleted?: boolean;
+    error?: string;
+}
+export interface AgentWorkspaceAccessContext {
+    client: AgentHostClientIdentity;
+    allowedDirectories: string[];
+    conversationId?: string;
+    workspaceId?: string;
+    teamId?: string;
+    agentId?: string;
+}
+export interface AgentWorkspaceGrantRequest {
+    path: string;
+    source: 'user-picker' | 'legacy-migration' | 'host-managed';
+}
+export interface AgentWorkspaceGrantResult {
+    success: boolean;
+    path: string | null;
+    error: string | null;
+}
+/**
+ * Authorising an APPLICATION the agent may launch a file with.
+ *
+ * 🔴 A host method rather than a local call, because the grant is mutable Agent
+ * state and §7 gives that exactly one owner. It had no method: the desktop
+ * composition called `WorkspaceHostService.grantApplication` directly on a
+ * service it built itself. In-process that happened to be the authority; under
+ * §9 step 3, where a DETACHED host owns the lease, it was a second process
+ * writing the authority's store behind its back — and the owner holds its
+ * grants in memory, so it never saw the write, while the user was told
+ * `success: true`.
+ */
+/**
+ * Messages withheld from a run, awaiting a human — coordination §6 `hold`.
+ *
+ * 🔴 The human half of coordination had NO protocol surface at all. The
+ * message bus implements the whole lifecycle — set an inbound policy, list
+ * what it withheld, release one — and nothing above it exposed the last two,
+ * so `hold` was a state a message could enter and never leave. §6 requires a
+ * held message to be "surfaced to the human for approval"; without these a
+ * hold is a silent drop with extra steps.
+ */
+export interface AgentCoordinationHeldListRequest {
+    runId: string;
+}
+export interface AgentCoordinationHeldMessage {
+    id: string;
+    fromRunId: string;
+    text: string;
+    sentAt: number;
+}
+export interface AgentCoordinationHeldListResult {
+    /** False when this host has no coordination service — distinct from a run
+     *  that simply has nothing held. */
+    available: boolean;
+    runId: string;
+    held: AgentCoordinationHeldMessage[];
+    reason?: string;
+}
+export interface AgentCoordinationHeldReleaseRequest {
+    command: AgentHostCommandContext;
+    runId: string;
+    messageId: string;
+}
+export interface AgentCoordinationHeldReleaseResult {
+    /** The message's OUTCOME, not a boolean: §6 requires the sender to learn
+     *  what became of every message, and a release can legitimately find
+     *  nothing, which is `expired` rather than failure. */
+    status: 'delivered' | 'expired' | 'refused' | 'held';
+    messageId: string;
+    reason?: string;
+}
+/**
+ * Sets or clears a run's inbound-message policy — §6.
+ *
+ * 🔴 A HUMAN method, deliberately absent from the turn-execution lane port. An
+ * agent choosing its own receiver's policy could accept its way past the rule
+ * that a message never moves trust upward, which is the one thing §6 exists to
+ * prevent.
+ */
+export interface AgentCoordinationPolicySetRequest {
+    command: AgentHostCommandContext;
+    runId: string;
+    /**
+     * `null` CLEARS the override and returns the run to the derived default.
+     *
+     * Distinct from `'accept'`: one hands the decision back to §6, the other pins
+     * the permissive answer permanently. Without a clear, setting a policy is a
+     * one-way door.
+     */
+    policy: 'accept' | 'hold' | 'refuse' | null;
+}
+export interface AgentCoordinationPolicySetResult {
+    ok: boolean;
+    /** What a human has pinned, absent when the derivation decides. */
+    explicit?: 'accept' | 'hold' | 'refuse';
+    /** Why not, when not — never a bare false. */
+    reason?: string;
+}
+export interface AgentWorkspaceApplicationGrantRequest {
+    path: string;
+    source: 'user-picker' | 'legacy-migration' | 'host-managed';
+}
+export interface AgentWorkspaceApplicationGrantResult {
+    success: boolean;
+    appPath: string | null;
+    error: string | null;
+}
+export interface AgentWorkspaceDirectoryEntry {
+    name: string;
+    path: string;
+    size: number;
+    modified: string;
+    type: 'file' | 'directory';
+    extension: string;
+}
+export interface AgentWorkspaceDirectoryListRequest extends AgentWorkspaceAccessContext {
+    dirPath: string;
+}
+export interface AgentWorkspaceDirectoryListResult {
+    success: boolean;
+    entries: AgentWorkspaceDirectoryEntry[];
+    error: string | null;
+}
+export interface AgentWorkspaceFileReadRequest extends AgentWorkspaceAccessContext {
+    path: string;
+}
+export interface AgentWorkspaceFileReadResult {
+    success: boolean;
+    path: string | null;
+    content: string;
+    bytes: number;
+    error: string | null;
+}
+export interface AgentWorkspaceFileWriteRequest extends AgentWorkspaceAccessContext {
+    path: string;
+    content: string;
+}
+export interface AgentWorkspaceFileWriteResult {
+    success: boolean;
+    path: string | null;
+    bytes: number;
+    error: string | null;
+}
+export interface AgentWorkspaceCommandRunRequest extends AgentWorkspaceAccessContext {
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+}
+export interface AgentWorkspaceCommandRunResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    cwd: string | null;
+    error: string | null;
+    /**
+     * Output hit the ceiling and was trimmed.
+     *
+     * 🔴 REQUIRED, and it was missing. This result trimmed at 200 KB and said
+     * nothing, so a caller could not tell a short output from a truncated one —
+     * and the shorter one is the dangerous reading, because a reader concludes
+     * "that's all it printed". The host always knows whether it trimmed, so there
+     * is no case for making this optional: an absent field would mean "cannot
+     * answer", and it can.
+     */
+    truncated: boolean;
+}
+export interface AgentWorkspaceTerminalStartRequest extends AgentWorkspaceAccessContext {
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+}
+export interface AgentWorkspaceTerminalStartResult {
+    success: boolean;
+    terminalId: string | null;
+    cwd: string | null;
+    error: string | null;
+}
+export interface AgentWorkspaceTerminalControlRequest extends AgentWorkspaceAccessContext {
+    terminalId: string;
+}
+export interface AgentWorkspaceTerminalControlResult {
+    success: boolean;
+    error: string | null;
+}
+export interface AgentWorkspacePtyStartRequest extends AgentWorkspaceAccessContext {
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+}
+export interface AgentWorkspacePtyStartResult {
+    success: boolean;
+    terminalId: string | null;
+    cwd: string | null;
+    error: string | null;
+}
+export interface AgentWorkspacePtySnapshotRequest extends AgentWorkspaceTerminalControlRequest {
+}
+export interface AgentWorkspacePtySnapshotResult {
+    success: boolean;
+    exists: boolean;
+    terminalId: string;
+    cwd: string | null;
+    output: string;
+    error: string | null;
+}
+export interface AgentWorkspacePtyInputRequest extends AgentWorkspaceTerminalControlRequest {
+    data: string;
+}
+export interface AgentWorkspacePtyResizeRequest extends AgentWorkspaceTerminalControlRequest {
+    cols: number;
+    rows: number;
+}
+export interface AgentHostCommandContext {
+    schemaVersion: 1;
+    commandId: string;
+    idempotencyKey: string;
+    client: AgentHostClientIdentity;
+}
+export type AgentTurnMode = 'development' | 'chat';
+export interface AgentTurnMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface AgentTurnWorkspace {
+    primaryDirectory?: string;
+    additionalDirectories?: string[];
+    permissionProfile?: string;
+    filesystem?: 'read-only' | 'workspace-write';
+}
+export interface AgentTurnExecutionOptions {
+    maxIterations?: number;
+    enableThinking?: boolean;
+    capabilities?: {
+        terminal?: boolean;
+        browser?: boolean;
+        fileRead?: boolean;
+        fileWrite?: boolean;
+        appLaunch?: boolean;
+        webSearch?: boolean;
+    };
+    approvalRules?: Array<Record<string, unknown>>;
+}
+export interface AgentTurnContinuation {
+    providerId: string;
+    providerSessionId: string;
+    state?: Record<string, unknown>;
+    providerConfigFingerprint?: string;
+    workspaceFingerprint?: string;
+}
+export interface AgentTurnContextCompaction {
+    strategyVersion: number;
+    rawMessageCount: number;
+    sentMessageCount: number;
+    compactedMessageCount: number;
+    estimatedRawTokens: number;
+    estimatedSentTokens: number;
+    retainedAnchorCount: number;
+    retainedArtifactCount: number;
+    retainedGrantedDirectoryCount: number;
+    contextDigest: string;
+}
+export interface AgentTurnStartRequest {
+    command: AgentHostCommandContext;
+    conversationId: string;
+    requestId: string;
+    workspaceId?: string;
+    teamId?: string;
+    agentId?: string;
+    subagentRunId?: string;
+    mode: AgentTurnMode;
+    selection: AgentRuntimeSelection;
+    prompt: string;
+    history?: AgentTurnMessage[];
+    systemPrompt?: string;
+    workspace?: AgentTurnWorkspace;
+    execution?: AgentTurnExecutionOptions;
+    continuation?: AgentTurnContinuation;
+    contextCompaction?: AgentTurnContextCompaction;
+    timeoutMs?: number;
+}
+export type AgentTurnStartFailureCode = 'invalid_request' | 'client_not_connected' | 'idempotency_conflict' | 'provider_not_found' | 'provider_unavailable' | 'catalog_revision_mismatch' | 'model_not_found' | 'model_unavailable' | 'model_required' | 'reasoning_option_not_found' | 'development_capability_missing' | 'adapter_unavailable' | 'request_already_active';
+export type AgentTurnStartResult = {
+    success: true;
+    status: 'accepted' | 'replayed';
+    conversationId: string;
+    requestId: string;
+    adapterId: string;
+    selection: AgentRuntimeSelection;
+} | {
+    success: false;
+    code: AgentTurnStartFailureCode;
+    safeError: string;
+    conversationId?: string;
+    requestId?: string;
+};
+export interface AgentTurnCancelRequest {
+    command: AgentHostCommandContext;
+    conversationId: string;
+    requestId: string;
+    reason?: string;
+}
+export type AgentTurnCancelResult = {
+    success: true;
+    status: 'cancel_requested' | 'replayed';
+    conversationId: string;
+    requestId: string;
+} | {
+    success: false;
+    code: 'invalid_request' | 'client_not_connected' | 'idempotency_conflict' | 'turn_not_active';
+    safeError: string;
+    conversationId?: string;
+    requestId?: string;
+};
+/**
+ * How a steer reached the agent. Reported so the surface can show the user
+ * which structure tier a session is running at (ADE spec §6.3 requires the tier
+ * to be visible, not inferred).
+ *
+ * - `adapter` — delivered over the protocol; the agent acknowledged receipt.
+ * - `pty`     — written into the terminal we own, indistinguishable from the
+ *               user typing. Real steering, but WITHOUT acknowledgement: we do
+ *               not learn whether the agent accepted or integrated it (§10b).
+ *               Not yet available; arrives with the session substrate.
+ *
+ * 🔴 NEITHER delivery is instantaneous, and no surface may imply that it is.
+ * Measured against real Claude Code on 2026-08-11: a correction injected into a
+ * running turn was honoured at the agent's NEXT DECISION POINT, not inside the
+ * tool call already in flight — one further file was written after the steer
+ * landed. So `delivered` means "the agent has it", never "the agent has
+ * stopped". That distance is about one tool call, which is exactly the window
+ * in which a destructive command completes. `turn.cancel` is the mechanism for
+ * STOP; steering is for REDIRECT, and the two do not share a latency.
+ * Evidence: docs/evidence/PTY_STEERING_2026-08-11.md
+ */
+export type AgentTurnSteerDelivery = 'adapter' | 'pty';
+export interface AgentTurnSteerRequest {
+    command: AgentHostCommandContext;
+    conversationId: string;
+    requestId: string;
+    instruction: string;
+}
+export type AgentTurnSteerResult = {
+    success: true;
+    status: 'delivered' | 'replayed';
+    /** Whether the agent confirmed receipt. False for `pty` delivery. */
+    acknowledged: boolean;
+    deliveredVia: AgentTurnSteerDelivery;
+    conversationId: string;
+    requestId: string;
+} | {
+    success: false;
+    code: 'invalid_request' | 'client_not_connected' | 'idempotency_conflict' | 'turn_not_active' | 'steer_unsupported';
+    safeError: string;
+    conversationId?: string;
+    requestId?: string;
+};
+/**
+ * A instruction the user stacked while a turn was still running.
+ *
+ * Queueing is deliberately a HOST concern rather than an adapter one: the host
+ * holds the instruction and signals when the active turn ends, so it works at
+ * every structure tier (ADE spec §2.9) — including a third-party agent running
+ * its own TUI, where no protocol exists to hand a steer to. This is why §10b
+ * lists `turn.queue` as available rather than degraded.
+ */
+export interface AgentTurnQueuedInstruction {
+    id: string;
+    instruction: string;
+    queuedAt: string;
+    /** Surface instance that queued it, for provenance in the timeline. */
+    queuedByInstanceId: string;
+}
+export interface AgentTurnQueueRequest {
+    command: AgentHostCommandContext;
+    conversationId: string;
+    /** Discard anything already queued for this conversation first. */
+    replace?: boolean;
+    instruction: string;
+}
+export type AgentTurnQueueResult = {
+    success: true;
+    status: 'queued' | 'replayed';
+    conversationId: string;
+    queue: AgentTurnQueuedInstruction[];
+} | {
+    success: false;
+    code: 'invalid_request' | 'client_not_connected' | 'idempotency_conflict' | 'queue_full';
+    safeError: string;
+    conversationId?: string;
+};
+export interface AgentTurnQueueListRequest {
+    conversationId: string;
+}
+export interface AgentTurnQueueListResult {
+    conversationId: string;
+    queue: AgentTurnQueuedInstruction[];
+    /** True while a turn is running, i.e. the queue is not drainable yet. */
+    turnActive: boolean;
+}
+export interface AgentTurnQueueDropRequest {
+    command: AgentHostCommandContext;
+    conversationId: string;
+    /** Omit to clear the whole queue. */
+    instructionId?: string;
+}
+export type AgentTurnQueueDropResult = {
+    success: true;
+    conversationId: string;
+    queue: AgentTurnQueuedInstruction[];
+} | {
+    success: false;
+    code: 'invalid_request' | 'client_not_connected' | 'not_found';
+    safeError: string;
+    conversationId?: string;
+};
+export interface AgentChooseDirectoryAnswerRequest {
+    requestId?: string;
+    chooseDirectoryId: string;
+    path?: string;
+    cancelled?: boolean;
+    error?: string;
+}
+export interface AgentChooseDirectoryAnswerResult {
+    success: boolean;
+    error?: string;
+    chooseDirectoryId?: string;
+    requestId?: string;
+    path?: string;
+    cancelled?: boolean;
+    responseError?: string;
+}
+export type AgentWorkspacePlacementChoice = 'inbox' | 'reuse' | 'create';
+export interface AgentWorkspacePlacementAnswerRequest {
+    requestId?: string;
+    workspacePlacementId: string;
+    directory?: string;
+    choice?: AgentWorkspacePlacementChoice;
+    workspaceName?: string;
+    result?: string;
+    cancelled?: boolean;
+    error?: string;
+}
+export interface AgentWorkspacePlacementResponse {
+    choice?: AgentWorkspacePlacementChoice;
+    directory?: string;
+    workspaceName?: string;
+    result?: string;
+    cancelled?: boolean;
+    error?: string;
+    timedOut?: boolean;
+}
+export interface AgentWorkspacePlacementAnswerResult {
+    success: boolean;
+    error?: string;
+    workspacePlacementId?: string;
+    requestId?: string;
+    response?: AgentWorkspacePlacementResponse;
+}
+export interface AgentPermissionAnswerRequest {
+    permissionId: string;
+    granted: boolean;
+    directory?: string;
+    /**
+     * An explicit choice among the options the agent offered (ACP lane). This is
+     * how a surface says "allow ALWAYS" rather than "allow once" — the boolean
+     * alone cannot express it, so without this a user can never create a
+     * host-owned policy rule.
+     *
+     * Advisory, never authoritative: the host validates it against the options
+     * actually offered and ignores anything else. The renderer is untrusted (§7).
+     */
+    selectedOptionId?: string;
+}
+/**
+ * A stored, host-owned permission rule (ACP lane).
+ *
+ * Surfaced so a user can SEE and REVOKE what they approved. A rule that can be
+ * created but not removed is a one-way door, and these both persist and
+ * accumulate.
+ */
+export interface AgentTurnResumeRequest {
+    command: AgentHostCommandContext;
+    conversationId: string;
+    requestId: string;
+}
+/**
+ * ⚠️ `status: 'restarted'` is deliberate and is NOT a synonym for "resumed".
+ *
+ * A turn killed by process death left no continuation point inside the agent —
+ * only the request that produced it. So the host RE-ISSUES that request: any
+ * work the agent had already done is done again, and side effects it already
+ * performed have already happened. Where the request carries a provider
+ * continuation the provider session is picked up, which narrows the gap but
+ * does not close it.
+ *
+ * Reporting this as `resumed` would promise a continuation the host cannot
+ * deliver, and the user would discover the difference by watching an agent redo
+ * something destructive.
+ */
+export type AgentTurnResumeResult = {
+    success: true;
+    status: 'restarted';
+    conversationId: string;
+    requestId: string;
+    adapterId: string;
+} | {
+    success: false;
+    code: 'invalid_request' | 'client_not_connected' | 'not_interrupted' | 'turn_already_active' | 'resume_failed';
+    safeError: string;
+    conversationId?: string;
+    requestId?: string;
+};
+export interface AgentPermissionRuleView {
+    id: string;
+    decision: 'allow' | 'deny';
+    toolKind?: string;
+    pathPrefix?: string;
+    createdAt?: number;
+}
+export interface AgentPermissionRuleListResult {
+    success: boolean;
+    rules: AgentPermissionRuleView[];
+    error?: string;
+}
+export interface AgentPermissionRuleRevokeRequest {
+    ruleId: string;
+}
+export interface AgentPermissionRuleRevokeResult {
+    success: boolean;
+    revoked: boolean;
+    error?: string;
+}
+export interface AgentPermissionAnswerResult {
+    success: boolean;
+    error?: string;
+}
+export interface AgentAskUserAnswerRequest {
+    askUserId: string;
+    answer: string;
+    selectedOption?: string;
+    cancelled?: boolean;
+}
+export interface AgentAskUserAnswerResult {
+    success: boolean;
+    error?: string;
+}
+export interface AgentSdkControlContext {
+    client: AgentHostClientIdentity;
+}
+export interface AgentSdkSessionListRequest extends AgentSdkControlContext {
+    role?: string;
+    workingDirectory?: string;
+    limit?: number;
+}
+export interface AgentSdkSessionListResult {
+    success: boolean;
+    sessions?: unknown[];
+    error?: string;
+}
+export interface AgentSdkSessionShowRequest extends AgentSdkControlContext {
+    sessionId: string;
+}
+export interface AgentSdkSessionShowResult {
+    success: boolean;
+    session?: unknown;
+    sessionDir?: string;
+    checkpoints?: unknown[];
+    error?: string;
+}
+export interface AgentSdkSessionAttachRequest extends AgentSdkControlContext {
+    conversationId: string;
+    sessionId: string;
+}
+export interface AgentSdkSessionAttachResult extends AgentSdkSessionShowResult {
+    sessionHistoryPath?: string;
+}
+export interface AgentSdkSessionDetachRequest extends AgentSdkControlContext {
+    conversationId: string;
+}
+export interface AgentSdkSessionDeleteRequest extends AgentSdkControlContext {
+    sessionId: string;
+}
+export interface AgentSdkSessionCleanRequest extends AgentSdkControlContext {
+    workingDirectory: string;
+    excludeSessionIds?: string[];
+}
+export interface AgentSdkSessionCleanResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface AgentSdkMutationResult {
+    success: boolean;
+    error?: string;
+}
+export interface AgentSdkCheckpointListRequest extends AgentSdkControlContext {
+    sessionId: string;
+}
+export interface AgentSdkCheckpointListResult {
+    success: boolean;
+    checkpoints?: unknown[];
+    error?: string;
+}
+export interface AgentSdkCheckpointRestoreRequest extends AgentSdkControlContext {
+    sessionId: string;
+    checkpointId: string;
+    conversationId?: string;
+}
+export interface AgentSdkCheckpointRestoreResult {
+    success: boolean;
+    restored?: unknown;
+    pendingRuntimeRestore?: boolean;
+    error?: string;
+}
+export interface AgentSdkCheckpointDeleteRequest extends AgentSdkControlContext {
+    sessionId: string;
+    checkpointId: string;
+}
+export interface AgentSdkTaskOutputRequest extends AgentSdkControlContext {
+    taskId: string;
+    offset?: number;
+}
+export type AgentSdkTaskStatus = 'running' | 'completed' | 'failed' | 'stopped' | 'unknown';
+export interface AgentSdkTaskResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+    command?: string;
+    status?: AgentSdkTaskStatus;
+    exitCode?: number | null;
+    totalSize?: number;
+}
+export interface AgentSdkTaskStopRequest extends AgentSdkControlContext {
+    taskId: string;
+}
+export interface AgentHostRequestMap {
+    'host.handshake': {
+        input: AgentHostHandshakeRequest;
+        output: AgentHostHandshake;
+    };
+    'providers.list': {
+        input: AgentProviderListRequest;
+        output: AgentProviderListResult;
+    };
+    'providers.refresh': {
+        input: AgentProviderRefreshRequest;
+        output: AgentProviderListResult;
+    };
+    'runtime.events.list': {
+        input: AgentRuntimeEventListRequest;
+        output: AgentRuntimeEventListResult;
+    };
+    'state.workspaces.load': {
+        input: Record<string, never>;
+        output: AgentWorkspaceStateLoadResult;
+    };
+    'state.workspaces.save': {
+        input: AgentWorkspaceStateSaveRequest;
+        output: AgentWorkspaceStateSaveResult;
+    };
+    'state.conversations.load': {
+        input: Record<string, never>;
+        output: AgentConversationStateLoadResult;
+    };
+    'state.conversations.save': {
+        input: AgentConversationStateSaveRequest;
+        output: AgentConversationStateSaveResult;
+    };
+    'state.conversations.delete': {
+        input: AgentConversationStateDeleteRequest;
+        output: AgentConversationStateDeleteResult;
+    };
+    'workspace.access.grant': {
+        input: AgentWorkspaceGrantRequest;
+        output: AgentWorkspaceGrantResult;
+    };
+    'coordination.held.list': {
+        input: AgentCoordinationHeldListRequest;
+        output: AgentCoordinationHeldListResult;
+    };
+    'coordination.held.release': {
+        input: AgentCoordinationHeldReleaseRequest;
+        output: AgentCoordinationHeldReleaseResult;
+    };
+    'coordination.policy.set': {
+        input: AgentCoordinationPolicySetRequest;
+        output: AgentCoordinationPolicySetResult;
+    };
+    'workspace.application.grant': {
+        input: AgentWorkspaceApplicationGrantRequest;
+        output: AgentWorkspaceApplicationGrantResult;
+    };
+    'workspace.directory.list': {
+        input: AgentWorkspaceDirectoryListRequest;
+        output: AgentWorkspaceDirectoryListResult;
+    };
+    'workspace.file.read': {
+        input: AgentWorkspaceFileReadRequest;
+        output: AgentWorkspaceFileReadResult;
+    };
+    'workspace.file.write': {
+        input: AgentWorkspaceFileWriteRequest;
+        output: AgentWorkspaceFileWriteResult;
+    };
+    'workspace.command.run': {
+        input: AgentWorkspaceCommandRunRequest;
+        output: AgentWorkspaceCommandRunResult;
+    };
+    'workspace.terminal.start': {
+        input: AgentWorkspaceTerminalStartRequest;
+        output: AgentWorkspaceTerminalStartResult;
+    };
+    'workspace.terminal.stop': {
+        input: AgentWorkspaceTerminalControlRequest;
+        output: AgentWorkspaceTerminalControlResult;
+    };
+    'workspace.pty.start': {
+        input: AgentWorkspacePtyStartRequest;
+        output: AgentWorkspacePtyStartResult;
+    };
+    'workspace.pty.snapshot': {
+        input: AgentWorkspacePtySnapshotRequest;
+        output: AgentWorkspacePtySnapshotResult;
+    };
+    'workspace.pty.input': {
+        input: AgentWorkspacePtyInputRequest;
+        output: AgentWorkspaceTerminalControlResult;
+    };
+    'workspace.pty.resize': {
+        input: AgentWorkspacePtyResizeRequest;
+        output: AgentWorkspaceTerminalControlResult;
+    };
+    'workspace.pty.clear': {
+        input: AgentWorkspaceTerminalControlRequest;
+        output: AgentWorkspaceTerminalControlResult;
+    };
+    'workspace.pty.stop': {
+        input: AgentWorkspaceTerminalControlRequest;
+        output: AgentWorkspaceTerminalControlResult;
+    };
+    'turn.start': {
+        input: AgentTurnStartRequest;
+        output: AgentTurnStartResult;
+    };
+    'turn.cancel': {
+        input: AgentTurnCancelRequest;
+        output: AgentTurnCancelResult;
+    };
+    'turn.steer': {
+        input: AgentTurnSteerRequest;
+        output: AgentTurnSteerResult;
+    };
+    'turn.queue': {
+        input: AgentTurnQueueRequest;
+        output: AgentTurnQueueResult;
+    };
+    'turn.queue.list': {
+        input: AgentTurnQueueListRequest;
+        output: AgentTurnQueueListResult;
+    };
+    'run.observation.snapshot': {
+        input: AgentRunObservationSnapshotRequest;
+        output: AgentRunObservationSnapshotResult;
+    };
+    'run.observation.change': {
+        input: AgentRunObservationChangeRequest;
+        output: AgentRunObservationChangeResult;
+    };
+    'run.observation.overlaps': {
+        input: AgentRunObservationOverlapsRequest;
+        output: AgentRunObservationOverlapsResult;
+    };
+    'fleet.view': {
+        input: AgentFleetViewRequest;
+        output: AgentFleetViewResult;
+    };
+    'fleet.route': {
+        input: AgentFleetRouteRequest;
+        output: AgentFleetRouteResult;
+    };
+    'fleet.plan': {
+        input: AgentFleetPlanRequest;
+        output: AgentFleetPlanResult;
+    };
+    'session.list': {
+        input: AgentSessionListRequest;
+        output: AgentSessionListResult;
+    };
+    'session.attach': {
+        input: AgentSessionViewerRequest;
+        output: AgentSessionViewerResult;
+    };
+    'session.detach': {
+        input: AgentSessionViewerRequest;
+        output: AgentSessionViewerResult;
+    };
+    'session.snapshot': {
+        input: AgentSessionSnapshotRequest;
+        output: AgentSessionSnapshotResult;
+    };
+    'session.input': {
+        input: AgentSessionInputRequest;
+        output: AgentSessionInputResult;
+    };
+    'session.takeover': {
+        input: AgentSessionTakeoverRequest;
+        output: AgentSessionTakeoverResult;
+    };
+    'session.release': {
+        input: AgentSessionViewerRequest;
+        output: AgentSessionViewerResult;
+    };
+    'intake.sources.list': {
+        input: AgentIntakeSourcesRequest;
+        output: AgentIntakeSourcesResult;
+    };
+    'intake.items.list': {
+        input: AgentIntakeItemsRequest;
+        output: AgentIntakeItemsResult;
+    };
+    'intake.item.claim': {
+        input: AgentIntakeClaimRequest;
+        output: AgentIntakeClaimResult;
+    };
+    'intake.item.release': {
+        input: AgentIntakeClaimRequest;
+        output: AgentIntakeClaimResult;
+    };
+    'intake.item.dispatch': {
+        input: AgentIntakeDispatchRequest;
+        output: AgentIntakeClaimResult;
+    };
+    'knowledge.list': {
+        input: AgentKnowledgeListRequest;
+        output: AgentKnowledgeListResult;
+    };
+    'knowledge.record': {
+        input: AgentKnowledgeRecordRequest;
+        output: AgentKnowledgeRecordResult;
+    };
+    'knowledge.forget': {
+        input: AgentKnowledgeForgetRequest;
+        output: AgentKnowledgeRecordResult;
+    };
+    'knowledge.context': {
+        input: AgentKnowledgeContextRequest;
+        output: AgentKnowledgeContextResult;
+    };
+    'turn.queue.drop': {
+        input: AgentTurnQueueDropRequest;
+        output: AgentTurnQueueDropResult;
+    };
+    'elicitation.choose-directory.answer': {
+        input: AgentChooseDirectoryAnswerRequest;
+        output: AgentChooseDirectoryAnswerResult;
+    };
+    'elicitation.workspace-placement.answer': {
+        input: AgentWorkspacePlacementAnswerRequest;
+        output: AgentWorkspacePlacementAnswerResult;
+    };
+    'elicitation.permission.answer': {
+        input: AgentPermissionAnswerRequest;
+        output: AgentPermissionAnswerResult;
+    };
+    'turn.resume': {
+        input: AgentTurnResumeRequest;
+        output: AgentTurnResumeResult;
+    };
+    'acp.provider.approve': {
+        input: AgentAcpProviderApprovalRequest;
+        output: AgentAcpProviderApprovalResult;
+    };
+    'permissions.rules.list': {
+        input: Record<string, never>;
+        output: AgentPermissionRuleListResult;
+    };
+    'permissions.rules.revoke': {
+        input: AgentPermissionRuleRevokeRequest;
+        output: AgentPermissionRuleRevokeResult;
+    };
+    'elicitation.ask-user.answer': {
+        input: AgentAskUserAnswerRequest;
+        output: AgentAskUserAnswerResult;
+    };
+    'sdk.sessions.list': {
+        input: AgentSdkSessionListRequest;
+        output: AgentSdkSessionListResult;
+    };
+    'sdk.sessions.show': {
+        input: AgentSdkSessionShowRequest;
+        output: AgentSdkSessionShowResult;
+    };
+    'sdk.sessions.attach': {
+        input: AgentSdkSessionAttachRequest;
+        output: AgentSdkSessionAttachResult;
+    };
+    'sdk.sessions.detach': {
+        input: AgentSdkSessionDetachRequest;
+        output: AgentSdkMutationResult;
+    };
+    'sdk.sessions.delete': {
+        input: AgentSdkSessionDeleteRequest;
+        output: AgentSdkMutationResult;
+    };
+    'sdk.sessions.clean': {
+        input: AgentSdkSessionCleanRequest;
+        output: AgentSdkSessionCleanResult;
+    };
+    'sdk.checkpoints.list': {
+        input: AgentSdkCheckpointListRequest;
+        output: AgentSdkCheckpointListResult;
+    };
+    'sdk.checkpoints.restore': {
+        input: AgentSdkCheckpointRestoreRequest;
+        output: AgentSdkCheckpointRestoreResult;
+    };
+    'sdk.checkpoints.delete': {
+        input: AgentSdkCheckpointDeleteRequest;
+        output: AgentSdkMutationResult;
+    };
+    'sdk.tasks.output': {
+        input: AgentSdkTaskOutputRequest;
+        output: AgentSdkTaskResult;
+    };
+    'sdk.tasks.stop': {
+        input: AgentSdkTaskStopRequest;
+        output: AgentSdkTaskResult;
+    };
+    'engineering.git.status': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.GitStatusResponse;
+    };
+    'engineering.git.diff': {
+        input: AgentEngineeringRequest<Engineering.GitDiffRequest>;
+        output: Engineering.GitDiffResponse;
+    };
+    'engineering.git.stage': {
+        input: AgentEngineeringRequest<Engineering.GitStageRequest>;
+        output: Engineering.GitStatusResponse;
+    };
+    'engineering.git.unstage': {
+        input: AgentEngineeringRequest<Engineering.GitStageRequest>;
+        output: Engineering.GitStatusResponse;
+    };
+    'engineering.git.commit': {
+        input: AgentEngineeringRequest<Engineering.GitCommitRequest>;
+        output: Engineering.GitStatusResponse;
+    };
+    'engineering.git.branch': {
+        input: AgentEngineeringRequest<Engineering.GitBranchRequest>;
+        output: Engineering.GitStatusResponse;
+    };
+    'engineering.git.push': {
+        input: AgentEngineeringRequest<Engineering.GitPushRequest>;
+        output: Engineering.GitPushResponse;
+    };
+    'engineering.git.pr.create': {
+        input: AgentEngineeringRequest<Engineering.GitPullRequestCreateRequest>;
+        output: Engineering.GitPullRequestCreateResponse;
+    };
+    'engineering.landing.enqueue': {
+        input: AgentEngineeringRequest<Engineering.LandingEnqueueRequest>;
+        output: Engineering.LandingQueueResponse;
+    };
+    'engineering.landing.remove': {
+        input: AgentEngineeringRequest<Engineering.LandingRemoveRequest>;
+        output: Engineering.LandingQueueResponse;
+    };
+    'engineering.landing.status': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.LandingQueueResponse;
+    };
+    'engineering.landing.land': {
+        input: AgentEngineeringRequest<Engineering.LandingLandRequest>;
+        output: Engineering.LandingLandResponse;
+    };
+    'engineering.landing.verify': {
+        input: AgentEngineeringRequest<Engineering.LandingVerifyRequest>;
+        output: Engineering.LandingVerifyResponse;
+    };
+    'engineering.checks.discover': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.EngineeringCheckDiscoveryResponse;
+    };
+    'engineering.checks.run': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRunRequest>;
+        output: Engineering.EngineeringRunResponse;
+    };
+    'engineering.background.start': {
+        input: AgentEngineeringRequest<Engineering.EngineeringBackgroundRunRequest>;
+        output: Engineering.EngineeringBackgroundRunResponse;
+    };
+    'engineering.background.list': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.EngineeringBackgroundRunListResponse;
+    };
+    'engineering.background.output': {
+        input: AgentEngineeringRequest<Engineering.EngineeringBackgroundRunLookupRequest>;
+        output: Engineering.EngineeringBackgroundRunResponse;
+    };
+    'engineering.background.stop': {
+        input: AgentEngineeringRequest<Engineering.EngineeringBackgroundRunLookupRequest>;
+        output: Engineering.EngineeringBackgroundRunResponse;
+    };
+    'engineering.runs.list': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.EngineeringRunListResponse;
+    };
+    'engineering.diagnostics': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.EngineeringDiagnosticsResponse;
+    };
+    'engineering.patches.list': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.PatchReviewListResponse;
+    };
+    'engineering.patches.enqueue': {
+        input: AgentEngineeringRequest<Engineering.PatchReviewUpsertRequest>;
+        output: Engineering.PatchReviewMutationResponse;
+    };
+    'engineering.patches.update': {
+        input: AgentEngineeringRequest<Engineering.PatchReviewUpdateRequest>;
+        output: Engineering.PatchReviewMutationResponse;
+    };
+    'engineering.patches.review': {
+        input: AgentEngineeringRequest<Engineering.PatchReviewSelectionRequest>;
+        output: Engineering.PatchReviewSelectionResponse;
+    };
+    'engineering.checkpoints.list': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.EngineeringCheckpointListResponse;
+    };
+    'engineering.checkpoints.compare': {
+        input: AgentEngineeringRequest<Engineering.EngineeringCheckpointCompareRequest>;
+        output: Engineering.EngineeringCheckpointCompareResponse;
+    };
+    'engineering.checkpoints.restore': {
+        input: AgentEngineeringRequest<Engineering.EngineeringCheckpointRestoreRequest>;
+        output: Engineering.EngineeringCheckpointRestoreResponse;
+    };
+    'engineering.sessions.list': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRequestBase>;
+        output: Engineering.EngineeringSessionListResponse;
+    };
+    'engineering.runtime.timeline': {
+        input: AgentEngineeringRequest<Engineering.EngineeringRuntimeTimelineRequest>;
+        output: Engineering.EngineeringRuntimeTimelineResponse;
+    };
+}
+export type AgentHostMethod = keyof AgentHostRequestMap;
+export type AgentEngineeringHostMethod = Extract<AgentHostMethod, `engineering.${string}`>;
+/** Derived from the prefix, like its siblings, so a new `run.observation.*`
+ *  method needs no edit here to become callable. */
+export type AgentRunObservationHostMethod = Extract<AgentHostMethod, `run.observation.${string}`>;
+/** Derived from the prefix like its siblings. */
+export type AgentFleetHostMethod = Extract<AgentHostMethod, `fleet.${string}`>;
+/** Derived from the prefix like its siblings. */
+export type AgentSessionHostMethod = Extract<AgentHostMethod, `session.${string}`>;
+/** Derived from the prefix like its siblings. */
+export type AgentIntakeHostMethod = Extract<AgentHostMethod, `intake.${string}`>;
+/** Derived from the prefix like its siblings. */
+export type AgentKnowledgeHostMethod = Extract<AgentHostMethod, `knowledge.${string}`>;
+/**
+ * ACP registry operations that must run under the host's authority.
+ *
+ * A template-literal group like `engineering.*`, so a future ACP method joins
+ * without another client helper.
+ */
+export type AgentAcpHostMethod = Extract<AgentHostMethod, `acp.${string}`>;
+export type AgentHostInput<M extends AgentHostMethod> = AgentHostRequestMap[M]['input'];
+export type AgentHostOutput<M extends AgentHostMethod> = AgentHostRequestMap[M]['output'];
+export declare const AGENT_HOST_METHODS: readonly ["host.handshake", "providers.list", "providers.refresh", "runtime.events.list", "state.workspaces.load", "state.workspaces.save", "state.conversations.load", "state.conversations.save", "state.conversations.delete", "workspace.access.grant", "coordination.held.list", "coordination.held.release", "coordination.policy.set", "workspace.application.grant", "workspace.directory.list", "workspace.file.read", "workspace.file.write", "workspace.command.run", "workspace.terminal.start", "workspace.terminal.stop", "workspace.pty.start", "workspace.pty.snapshot", "workspace.pty.input", "workspace.pty.resize", "workspace.pty.clear", "workspace.pty.stop", "turn.start", "turn.cancel", "turn.steer", "turn.queue", "turn.queue.list", "run.observation.snapshot", "run.observation.change", "run.observation.overlaps", "fleet.view", "fleet.route", "fleet.plan", "session.list", "session.attach", "session.detach", "session.snapshot", "session.input", "session.takeover", "session.release", "intake.sources.list", "intake.items.list", "intake.item.claim", "intake.item.release", "intake.item.dispatch", "knowledge.list", "knowledge.record", "knowledge.forget", "knowledge.context", "turn.queue.drop", "elicitation.choose-directory.answer", "elicitation.workspace-placement.answer", "elicitation.permission.answer", "turn.resume", "acp.provider.approve", "permissions.rules.list", "permissions.rules.revoke", "elicitation.ask-user.answer", "sdk.sessions.list", "sdk.sessions.show", "sdk.sessions.attach", "sdk.sessions.detach", "sdk.sessions.delete", "sdk.sessions.clean", "sdk.checkpoints.list", "sdk.checkpoints.restore", "sdk.checkpoints.delete", "sdk.tasks.output", "sdk.tasks.stop", "engineering.git.status", "engineering.git.diff", "engineering.git.stage", "engineering.git.unstage", "engineering.git.commit", "engineering.git.branch", "engineering.git.push", "engineering.git.pr.create", "engineering.landing.enqueue", "engineering.landing.remove", "engineering.landing.status", "engineering.landing.land", "engineering.landing.verify", "engineering.checks.discover", "engineering.checks.run", "engineering.background.start", "engineering.background.list", "engineering.background.output", "engineering.background.stop", "engineering.runs.list", "engineering.diagnostics", "engineering.patches.list", "engineering.patches.enqueue", "engineering.patches.update", "engineering.patches.review", "engineering.checkpoints.list", "engineering.checkpoints.compare", "engineering.checkpoints.restore", "engineering.sessions.list", "engineering.runtime.timeline"];
+export declare function isAgentHostMethod(value: unknown): value is AgentHostMethod;
+/**
+ * Approve or revoke which BINARY may run as an ACP provider.
+ *
+ * A trust decision, which is why it is a host method rather than something a
+ * surface performs for itself: the ACP lane's equivalent of the plugin
+ * `preflightTrust` gate, and §2.6 moves everything onto ACP. One authority
+ * decides it and both surfaces get the same answer.
+ */
+export interface AgentAcpProviderApprovalRequest {
+    /**
+     * Carries `client` directly rather than a full `AgentHostCommandContext`,
+     * matching the `engineering.*` registry methods rather than the idempotent
+     * turn commands. Approval is not idempotent-by-key: approving twice is
+     * approving, and revoking after approving must not be deduplicated away.
+     */
+    client: AgentHostClientIdentity;
+    /** The configured ACP agent whose provider policy is being approved. */
+    agentId: string;
+    /** Optional narrowing; must match the agent config's own `--provider`. */
+    providerId?: string;
+    action: 'approve' | 'revoke';
+}
+export interface AgentAcpProviderApprovalResult {
+    success: boolean;
+    status: 'approved' | 'revoked' | 'failed' | 'unavailable';
+    agentId: string;
+    /** Basename only — a full binary path is host layout, not a surface's business. */
+    commandBasename?: string;
+    /** Redacted tails, so a failure is diagnosable without leaking a policy file. */
+    stdoutTail?: string[];
+    stderrTail?: string[];
+    /** Present on failure. Never a raw exception string. */
+    safeError?: string;
+}
+/**
+ * Every event the host may publish, as a VALUE.
+ *
+ * 🔴 **This array is the type AND the runtime guard.** It used to be a
+ * hand-written union beside a hand-written `isAgentHostEvent` predicate, and
+ * they diverged: `coordination.event`, `run.observation` and `session.event`
+ * were legal in the type and REJECTED by the guard.
+ *
+ * That is not a dropped event. `LocalAgentHostRpcClientTransport.receive` treats
+ * an unrecognised frame as a protocol violation and **disconnects**, so a single
+ * `session.attached` tore down every connected surface's transport. The three
+ * missing types were the three newest pillars — coordination (§5.2b),
+ * tier-1 observation (§2.9) and the session substrate (§2.8) — which is to
+ * say the whole ADE was unusable over the real transport while every in-process
+ * test passed, because `publish` never crosses the frame guard in one heap.
+ *
+ * Deriving both from one array makes the divergence unrepresentable.
+ */
+export declare const AGENT_HOST_EVENT_TYPES: readonly ["host.ready", "provider.catalog.changed", "runtime.event.appended", "turn.execution.failed", "elicitation.choose-directory.requested", "elicitation.workspace-placement.requested", "elicitation.permission.requested", "elicitation.ask-user.requested", "task.changed", "workspace.terminal.data", "workspace.terminal.exit", "workspace.pty.data", "workspace.pty.exit", "coordination.event", "run.observation", "session.event"];
+export type AgentHostEventType = (typeof AGENT_HOST_EVENT_TYPES)[number];
+/**
+ * Reading a run's observed diff — the READ half of §2.9.
+ *
+ * The `run.observation` EVENT carries counts and completeness only, deliberately:
+ * it is broadcast to every connected client and a diff is content. So a surface
+ * that wants to show a review has to ask, and these are the questions it asks.
+ *
+ * 🔴 `available` is a first-class answer, not an error. A host with no isolation
+ * substrate wired observes nothing, and a surface must be able to tell "this run
+ * changed nothing" from "nobody was watching". Reporting the second as the first
+ * is the false-clean diff the whole observation path exists to prevent.
+ */
+export interface AgentRunObservationSnapshotRequest {
+    runId: string;
+    /** Drain pending events first. Default is to read what has already been folded,
+     *  so opening a review pane cannot consume a batch another reader is waiting on. */
+    poll?: boolean;
+}
+export interface AgentRunObservationChangeSummary {
+    path: string;
+    kind: 'added' | 'modified' | 'deleted';
+}
+export interface AgentRunObservationSnapshotResult {
+    available: boolean;
+    runId: string;
+    changes: AgentRunObservationChangeSummary[];
+    /**
+     * False when anything is known to have been missed.
+     *
+     * A surface must NOT present an incomplete diff as a review. §2.9's claim is
+     * that tier 1 yields a real diff, and one that quietly omits changes is worse
+     * than none, because a reviewer acts on it.
+     */
+    complete: boolean;
+    droppedEvents: number;
+    problems: string[];
+    /** Why observation is unavailable, when it is. */
+    reason?: string;
+}
+export interface AgentRunObservationChangeRequest {
+    runId: string;
+    path: string;
+}
+/**
+ * Content for one changed path.
+ *
+ * ⚠️ A SNAPSHOT, not the state at the moment of the change: the agent may have
+ * written again since. A surface must never label this "what the agent did at
+ * 10:04:03".
+ */
+export interface AgentRunObservationChangeResult {
+    available: boolean;
+    path: string;
+    before?: string;
+    after?: string;
+    /** Never partially rendered as a hunk — decoding binary to UTF-8 produces a
+     *  plausible-looking diff of something that was never text. */
+    binary: boolean;
+    truncated: boolean;
+    /** Present when a side could not be produced, so an empty pane is legible. */
+    refusal?: string;
+}
+export interface AgentRunObservationOverlapsRequest {
+    /** Paths each run has CLAIMED, if the caller knows them. Complementary to the
+     *  observed sets, never a substitute: nothing forces an agent to claim before
+     *  writing, so the run that surprises us is the one whose overlap matters. */
+    claimedPathsByRun?: Record<string, string[]>;
+}
+export interface AgentRunObservationOverlapSummary {
+    path: string;
+    runIds: string[];
+    kind: 'edit-vs-edit' | 'delete-vs-edit' | 'add-vs-add';
+    /** True when no run had claimed the path — invisible to the registry. */
+    unclaimed?: boolean;
+}
+export interface AgentRunObservationOverlapsResult {
+    available: boolean;
+    overlaps: AgentRunObservationOverlapSummary[];
+    /**
+     * Runs whose changes were NOT fully compared. An overlap cannot be ruled out
+     * for these.
+     *
+     * TWO kinds, in one list because the reader'''s next action is the same — go
+     * look at that run: a run whose diff has a hole, and a run the observer never
+     * saw at all. The second used to be invisible, so a landing gate could be told
+     * "no overlaps, and the answer is complete" while an unobserved run was
+     * editing the same files.
+     */
+    incompleteRuns: string[];
+    complete: boolean;
+    reason?: string;
+}
+/**
+ * The fleet — every run this host knows about, in one answer.
+ *
+ * ADE §9 step 6. The point of the step is that the workspace stops being an
+ * agent WINDOW and becomes a view over many runs at once, so this deliberately
+ * composes what three separate subsystems know rather than adding a fourth
+ * record: coordination (who claimed what, and where two runs collided),
+ * observation (what each run actually changed, and whether that diff is whole),
+ * and the host itself (which runs are working right now).
+ *
+ * 🔴 **Scope is stated, not implied.** `coordinationComplete` is false when the
+ * claim history is only what this host has seen since it started — a restarted
+ * host has a shorter record than the durable timeline, and a fleet view that
+ * quietly showed fewer collisions than actually happened would be read as
+ * "nobody collided". That is the same false-clean failure as an incomplete diff.
+ */
+export interface AgentFleetViewRequest {
+    /** Claimed paths per run, if the caller knows them. Advisory: overlaps are
+     *  computed from OBSERVED diffs, because nothing forces a claim before a write. */
+    claimedPathsByRun?: Record<string, string[]>;
+}
+/**
+ * A fan-out PLAN — ADE §5.2's scheduler, asked without being run.
+ *
+ * Returned by `fleet.plan`, which starts nothing. A plan you can inspect before
+ * anything begins is the reviewable artifact: it is what a person wants to see
+ * before N agents start editing their repository.
+ */
+export interface AgentFleetPlanRequest {
+    tasks: AgentFleetPlanTask[];
+}
+export interface AgentFleetPlanTask {
+    taskId: string;
+    requiredCapabilities?: AgentHarnessCapability[];
+}
+export interface AgentFleetPlanAssignment {
+    taskId: string;
+    providerId: string;
+    /** Capabilities served DEGRADED for this task — carried so a worse-but-
+     *  possible run does not look like a clean one in the plan. */
+    degraded: AgentHarnessCapability[];
+}
+export interface AgentFleetPlanRefusal {
+    taskId: string;
+    reason: string;
+}
+export interface AgentFleetPlanResult {
+    assignments: AgentFleetPlanAssignment[];
+    /** Refused INDIVIDUALLY — one unroutable task does not fail the batch. */
+    refusals: AgentFleetPlanRefusal[];
+    /** Tasks per provider, INCLUDING idle ones at 0, so a caller can see the
+     *  spread rather than trust it. */
+    loadByProvider: Record<string, number>;
+}
+/**
+ * "Which agents could run a task requiring these capabilities?" — ADE §5.2.
+ *
+ * A QUERY, deliberately: it starts nothing, so a surface or a scheduler can ask
+ * before committing. §5.2's gate requires a task needing an undeclared
+ * capability to be "refused with a named reason", and a refusal nothing can
+ * observe is not a refusal anyone can act on — which is what this method exists
+ * to make visible.
+ */
+export interface AgentFleetRouteRequest {
+    /** Capabilities the task requires. Empty means "any runnable agent". */
+    requiredCapabilities: AgentHarnessCapability[];
+}
+export interface AgentFleetRouteCandidate {
+    providerId: string;
+    /** Capabilities this provider serves DEGRADED. Non-empty means it can run the
+     *  task and will run it worse — reported rather than hidden, so the choice is
+     *  informed rather than silently downgraded. */
+    degraded: AgentHarnessCapability[];
+}
+export interface AgentFleetRouteRejection {
+    providerId: string;
+    /** Absent when the PROVIDER is unavailable rather than a capability missing. */
+    capability?: AgentHarnessCapability;
+    reason: string;
+}
+export interface AgentFleetRouteResult {
+    /** False means NOTHING can run this task. `reason` is then required. */
+    routable: boolean;
+    candidates: AgentFleetRouteCandidate[];
+    /** Every provider ruled out, and why — a partial fan-out has to be explicable. */
+    rejected: AgentFleetRouteRejection[];
+    /**
+     * Why nothing can run it. REQUIRED when `routable` is false — the §5.2 gate is
+     * "refused with a named reason", so a bare `false` would not satisfy it.
+     */
+    reason?: string;
+}
+export interface AgentFleetRun {
+    runId: string;
+    conversationId?: string;
+    workspaceId?: string;
+    agentId?: string;
+    /** True while a turn is executing for this run. */
+    working: boolean;
+    /** Scopes this run currently holds. */
+    claims: string[];
+    /** Present only when the run is being observed. */
+    changes?: {
+        added: number;
+        modified: number;
+        deleted: number;
+    };
+    /**
+     * Whether this run's diff is the whole story. ABSENT when unobserved —
+     * which is deliberately different from `false`: "not watched" and "watched
+     * with a hole" call for different actions.
+     */
+    diffComplete?: boolean;
+    /**
+     * The intake item this run was dispatched from, when it was — §5.1's
+     * provenance, on the RUN side.
+     *
+     * The intake board already answers "who is working on this item". This is the
+     * opposite question, and the one a reviewer asks: "where did this run's work
+     * come from?" ABSENT means the run was not dispatched from intake (someone
+     * typed a prompt), which is different from an unknown origin.
+     */
+    intakeItemId?: string;
+    /** Paths another live run also changed. */
+    contestedPaths: string[];
+    /**
+     * The run is stopped on a permission prompt — §7's `awaiting-approval`.
+     *
+     * 🔴 Distinct from `working`, which stays TRUE throughout: a turn blocked on
+     * a human is still in flight. Reporting only `working` told the person
+     * reading this board that the run was busy, when the run was waiting for
+     * THEM — the one reader who could clear it instantly.
+     *
+     * ABSENT means unknown, because a host with no coordination service has no
+     * roster to ask. Not `false`, which would assert the run is not waiting.
+     */
+    awaitingApproval?: boolean;
+    /**
+     * Messages withheld from this run, awaiting a human (coordination §6 `hold`).
+     *
+     * 🔴 ABSENT when the host has no coordination service — no roster means
+     * no answer, and `0` would assert that nothing is waiting. Deliberately
+     * SEPARATE from `awaitingApproval`, which is the run itself stopped on a
+     * permission prompt: that blocks the RUN, this blocks a message TO it, and
+     * a reader clears them by different actions.
+     *
+     * A COUNT, never the text. Coordination facts that reach a surface this way
+     * carry ids and counts and never message bytes; the text is fetched
+     * deliberately through `coordination.held.list`.
+     */
+    heldMessages?: number;
+    /**
+     * §6's EXPLICIT inbound-policy override, absent when the derivation decides.
+     *
+     * Not the effective policy: the derivation is comparative, so what happens to
+     * a message depends on who sent it. This is the part a human pinned, and
+     * therefore the only part they can clear.
+     */
+    inboundPolicy?: 'accept' | 'hold' | 'refuse';
+    /**
+     * Whether this run is CONTAINED — ADE §5.3.
+     *
+     * REQUIRED, deliberately. Every other risk-shaped field here is optional so an
+     * absent one reads as "the host cannot answer", but §5.3 says the user always
+     * knows whether the thing running is contained — so the host must answer, and
+     * `'none'` is a real answer rather than a missing one.
+     */
+    isolation: 'none' | 'sandboxed' | 'unknown';
+    /** What confines it, present only alongside `sandboxed`. */
+    isolationMechanism?: string;
+    /** Why the answer is `unknown`, present only alongside it. */
+    isolationReason?: string;
+}
+export interface AgentFleetCollision {
+    scope: string;
+    wantedByRunId: string;
+    heldByRunId: string;
+    at: string;
+    /** True while the holder still holds an overlapping claim. */
+    stillHeld: boolean;
+}
+export interface AgentFleetViewResult {
+    runs: AgentFleetRun[];
+    collisions: AgentFleetCollision[];
+    /** False when the claim/collision record is known to be partial. */
+    coordinationComplete: boolean;
+    /**
+     * True only when every listed run's diff can be trusted as the whole story.
+     *
+     * 🔴 False in THREE cases, and the last two were reported as `true`:
+     * an observed run with a hole; a run nobody observed; and a host with no
+     * observation substrate at all. "Nothing was watched" is not "nothing
+     * changed" — reporting completeness for an unwatched fleet is the
+     * false-clean output §2.9's sensors exist to prevent, and it is the same
+     * defect already found and fixed once in `coordinationComplete`.
+     */
+    observationComplete: boolean;
+    /** Why either completeness flag is false, for a human. */
+    problems: string[];
+}
+/**
+ * Sessions over the protocol — ADE §5.5 attach and takeover, build-order step 4.
+ *
+ * The substrate (§2.8) has had `attach`, `takeOver` and input routing since the
+ * session work landed; none of it was reachable from a surface. These are that
+ * surface.
+ *
+ * 🔴 **Terminal bytes are NEVER on the event feed.** `session.event` is a
+ * broadcast to every connected client, and output is per-viewer and large. So
+ * output is READ, by an explicit `session.snapshot` call from the surface that
+ * wants it — the same shape `workspace.pty.snapshot` already uses here.
+ */
+export interface AgentSessionListRequest {
+    /** Limit to one run's sessions. Absent lists every open session. */
+    runId?: string;
+}
+export interface AgentSessionSummary {
+    sessionId: string;
+    runId: string;
+    mode: string;
+    switchable: boolean;
+    hasProtocolChannel: boolean;
+    openedAt: number;
+    viewers: string[];
+    /** Who may write into the session right now, and since when. */
+    lease: {
+        holder: string | null;
+        heldSince: number | null;
+        interventions: number;
+    };
+}
+export interface AgentSessionListResult {
+    available: boolean;
+    sessions: AgentSessionSummary[];
+    /** Present when this host has no session substrate mounted. */
+    reason?: string;
+}
+export interface AgentSessionViewerRequest {
+    sessionId: string;
+    /** Identifies the watching surface. Attach is plural: two surfaces may hold
+     *  the same session and both see it move. */
+    viewerId: string;
+}
+export interface AgentSessionViewerResult {
+    ok: boolean;
+    /** Why not, when not — never a bare false. */
+    reason?: string;
+    session?: AgentSessionSummary;
+}
+export interface AgentSessionSnapshotRequest {
+    sessionId: string;
+}
+export interface AgentSessionSnapshotResult {
+    available: boolean;
+    output: string;
+    /**
+     * True when older output has already been dropped from the retained window.
+     * A surface must say so rather than presenting a terminal that appears to
+     * begin mid-sentence for no reason.
+     */
+    truncated: boolean;
+    reason?: string;
+}
+export interface AgentSessionInputRequest {
+    sessionId: string;
+    /**
+     * 🔴 REQUIRED, because typing into a session MUTATES the run.
+     *
+     * For an `acp` session the host delivers these keystrokes through the one
+     * `turn.steer` path, which is idempotent by command id. Without one, a
+     * retried input is either delivered twice or refused as a duplicate of a
+     * different instruction — and two identical keystrokes are legitimately two
+     * inputs, so nothing derivable from the DATA can stand in for it.
+     *
+     * Optional would not have helped, for the same reason `viewerId` is not: a
+     * caller that omits it is indistinguishable from one entitled to skip
+     * idempotency.
+     */
+    command: AgentHostCommandContext;
+    /**
+     * 🔴 Which surface is typing. REQUIRED, and the reason is the lease.
+     *
+     * `session.takeover` refuses a second human because *"interleaving two humans
+     * produces a command neither typed"*. This method writes to the same PTY, so
+     * without a viewer id the host cannot apply that rule here — and the exact
+     * interleaving the lease exists to prevent was reachable through this door
+     * while being refused at the other one.
+     *
+     * Optional would not have fixed it: a caller that omits the field is
+     * indistinguishable from one entitled to write, which is the ambiguity, not
+     * a mitigation of it.
+     */
+    viewerId: string;
+    data: string;
+}
+/**
+ * 🔴 `turnInFlight` and `acceptsMidTurnSteering` USED TO BE FIELDS HERE, and
+ * removing them is the point.
+ *
+ * Both decide whether a keystroke steers the agent now or waits for its next
+ * turn — §2.8's routing — and both are facts the HOST owns: it holds the active
+ * turns, and it knows whether the run's adapter can steer at all, because it
+ * already refuses with `steer_unsupported` when the adapter cannot.
+ *
+ * Taking them from the caller let a surface decide how its own input would be
+ * treated, which is the shape invariant 12 exists for: a caller CLAIMING
+ * authority never grants it. It also made the method unusable — a panel has no
+ * way to know either fact, so binding it would have meant guessing, and a guess
+ * here silently changes what happens to what someone typed.
+ */
+export interface AgentSessionInputResult {
+    ok: boolean;
+    /**
+     * The instruction this input became, when the disposition was `queue`.
+     *
+     * 🔴 Positive evidence that the queue actually took it. `disposition`
+     * states the INTENT and cannot say whether it happened — and for a long time
+     * it did not: the `turn.queue` sink was derived, announced, and serviced by
+     * nobody, so typing during a turn the agent could not take mid-flight fell
+     * into exactly the void the comment below says never happens.
+     *
+     * 🔴 ONE object, not two optional fields. An id a surface cannot
+     * address is evidence it can render and not act on — `turn.queue.drop` is
+     * keyed by CONVERSATION, and a session knows only its run. Shipping the id
+     * alone (as this first did) left "you have something queued" with no way to
+     * take it back. The two facts are true together or not at all, so they are
+     * one field and the useless half is unrepresentable.
+     *
+     * ABSENT rather than a pair of nulls when queuing did not happen.
+     */
+    queued?: {
+        instructionId: string;
+        conversationId: string;
+    };
+    /** Named, so a surface can say WHY rather than showing keystrokes vanishing. */
+    code?: 'no_such_session' | 'lease_held';
+    /** `steer` is for the agent now; `queue` is for its next decision point. There
+     *  is deliberately no `drop`: typing never falls into a void. */
+    disposition?: 'steer' | 'queue';
+    /**
+     * True when the session ALREADY put the keystrokes in front of the agent.
+     *
+     * 🔴 The disposition alone does not say this, and reading it as if it did
+     * is how typing gets lost. In `native-tui` the PTY is the agent's terminal, so
+     * a steer is delivered by the time this returns. In `acp` nothing sits behind
+     * the PTY — it renders the structured stream — so delivery is still owed, via
+     * `sink`. A caller that ignores this either double-delivers or drops.
+     */
+    delivered?: boolean;
+    /** Where the keystrokes went, or must still go. */
+    sink?: 'pty' | 'turn.steer' | 'turn.queue';
+    reason?: string;
+}
+export interface AgentSessionTakeoverRequest {
+    sessionId: string;
+    /**
+     * 🔴 REQUIRED, because typing into a session MUTATES the run.
+     *
+     * For an `acp` session the host delivers these keystrokes through the one
+     * `turn.steer` path, which is idempotent by command id. Without one, a
+     * retried input is either delivered twice or refused as a duplicate of a
+     * different instruction — and two identical keystrokes are legitimately two
+     * inputs, so nothing derivable from the DATA can stand in for it.
+     *
+     * Optional would not have helped, for the same reason `viewerId` is not: a
+     * caller that omits it is indistinguishable from one entitled to skip
+     * idempotency.
+     */
+    command: AgentHostCommandContext;
+    viewerId: string;
+    /** The keystrokes. §5.5 has no request-and-wait step — typing IS the takeover,
+     *  because the case it exists for is an agent going wrong now. */
+    data: string;
+}
+export interface AgentSessionTakeoverResult {
+    ok: boolean;
+    /** False when another human holds the lease. Their keystrokes are NOT
+     *  written: interleaving two humans produces a command neither typed. */
+    lease?: {
+        holder: string | null;
+        heldSince: number | null;
+        interventions: number;
+    };
+    /** Whether the keystrokes reached the agent. Taking the lease and delivering
+     *  what was typed are separate outcomes, and a takeover with no text at all is
+     *  ordinary — §5.5 has no request-and-wait step, so the first keystroke IS the
+     *  takeover, and there may not be one yet. */
+    delivered?: boolean;
+    sink?: 'pty' | 'turn.steer' | 'turn.queue';
+    reason?: string;
+}
+/**
+ * Intake — ADE §5.1, work arriving from wherever a developer's work arrives.
+ *
+ * 🔴 **Claimed exactly once under concurrent clients** is the gate, so a losing
+ * claim is a NAMED refusal rather than a silent no-op: the loser's next action
+ * (pick something else) depends on knowing it lost.
+ *
+ * 🔴 **A source that failed is not a source with no work.** `complete: false`
+ * says the inbox could not be fully read — an empty inbox and an unreadable one
+ * are the same zero items and opposite meanings.
+ *
+ * **Boundary (§5.1):** this renders and dispatches intake. It is not a ticket
+ * system, and it does not own scheduling — recurring triggers are `xeno-workflow`.
+ */
+export interface AgentIntakeSourcesRequest {
+    [key: string]: never;
+}
+export interface AgentIntakeSourceSummary {
+    sourceId: string;
+    label: string;
+    /** False when the last read failed. */
+    healthy: boolean;
+    problem?: string;
+}
+export interface AgentIntakeSourcesResult {
+    available: boolean;
+    sources: AgentIntakeSourceSummary[];
+    reason?: string;
+}
+export interface AgentIntakeItemsRequest {
+    /** Limit to one source. Absent reads them all. */
+    sourceId?: string;
+}
+export interface AgentIntakeItemSummary {
+    id: string;
+    sourceId: string;
+    externalId: string;
+    title: string;
+    detail?: string;
+    createdAt?: number;
+    url?: string;
+    /** `unclaimed` | `claimed` | `dispatched`, plus who and which run. */
+    claimState: string;
+    claimedBy?: string;
+    runId?: string;
+}
+export interface AgentIntakeItemsResult {
+    available: boolean;
+    items: AgentIntakeItemSummary[];
+    /** False when any source failed — the inbox may be missing work. */
+    complete: boolean;
+    failedSources: Array<{
+        sourceId: string;
+        problem: string;
+    }>;
+    reason?: string;
+}
+export interface AgentIntakeClaimRequest {
+    itemId: string;
+    /** Who is claiming. Distinct clients must not share this, or exactly-once
+     *  degrades to first-surface-wins-forever. */
+    clientId: string;
+}
+export interface AgentIntakeDispatchRequest extends AgentIntakeClaimRequest {
+    /** The run that will do the work. Recorded so provenance answers "where did
+     *  this come from?" after the fact. */
+    runId: string;
+}
+export interface AgentIntakeClaimResult {
+    ok: boolean;
+    /** Present on refusal, naming who holds it and why. */
+    reason?: string;
+    heldBy?: string;
+    runId?: string;
+    claimState?: string;
+}
+/**
+ * Workspace knowledge — ADE §5.8 LEARN.
+ *
+ * 🔴 The gate is CROSS-PROVIDER: *"a fact established in one run is available to
+ * a different provider in a later run without the user restating it."* Provider
+ * is recorded as provenance and never consulted when selecting — `context` takes
+ * no provider argument at all, which is the simplest way to keep the mistake
+ * unrepresentable.
+ *
+ * **Boundary:** this is WORKSPACE knowledge — conventions, architecture, prior
+ * decisions. Agent-owned earned memory (the Soul model) belongs to `xeno-anima`.
+ */
+export interface AgentKnowledgeListRequest {
+    workspaceId: string;
+}
+export interface AgentKnowledgeEntrySummary {
+    id: string;
+    subject: string;
+    fact: string;
+    pinned?: boolean;
+    runId: string;
+    /** Recorded for provenance only. Never decides what a later run sees. */
+    providerId?: string;
+    at: number;
+}
+export interface AgentKnowledgeListResult {
+    available: boolean;
+    entries: AgentKnowledgeEntrySummary[];
+    /** False when the store does not survive a restart. Reported rather than
+     *  assumed — a surface promising durable memory over an in-memory store lies. */
+    durable: boolean;
+    reason?: string;
+}
+export interface AgentKnowledgeRecordRequest {
+    workspaceId: string;
+    subject: string;
+    fact: string;
+    pinned?: boolean;
+    runId: string;
+    providerId?: string;
+}
+export interface AgentKnowledgeForgetRequest {
+    workspaceId: string;
+    entryId: string;
+}
+export interface AgentKnowledgeRecordResult {
+    ok: boolean;
+    entry?: AgentKnowledgeEntrySummary;
+    reason?: string;
+}
+export interface AgentKnowledgeContextRequest {
+    workspaceId: string;
+    /** Rough character budget. Characters rather than tokens: a token count needs
+     *  a tokenizer per provider, and this must not vary by provider. */
+    maxChars?: number;
+}
+export interface AgentKnowledgeContextResult {
+    available: boolean;
+    /** The block to inject, already rendered. */
+    text: string;
+    entries: AgentKnowledgeEntrySummary[];
+    /** Facts left out for space. Named, never silently dropped — a prompt missing
+     *  knowledge makes an agent look like it forgot, with nothing explaining why. */
+    omitted: Array<{
+        subject: string;
+        reason: string;
+    }>;
+    complete: boolean;
+    reason?: string;
+}
+export interface AgentHostEvent<TPayload = unknown> {
+    id: string;
+    sequence: number;
+    timestamp: number;
+    type: AgentHostEventType;
+    source: 'host';
+    schemaVersion: 1;
+    redactionState: 'safe';
+    payload: TPayload;
+}
+export type AgentHostEventListener = (event: AgentHostEvent) => void;
+export type AgentHostUnsubscribe = () => void;
+export interface AgentHostTransport {
+    request<M extends AgentHostMethod>(method: M, input: AgentHostInput<M>): Promise<AgentHostOutput<M>>;
+    subscribe(listener: AgentHostEventListener): AgentHostUnsubscribe;
+}
+export type AgentHostProtocolErrorCode = 'invalid_handshake' | 'protocol_mismatch' | 'surface_mismatch' | 'not_connected' | 'invalid_response';
+export declare class AgentHostProtocolError extends Error {
+    readonly code: AgentHostProtocolErrorCode;
+    constructor(code: AgentHostProtocolErrorCode, message: string);
+}
+export declare function isAgentSurfaceKind(value: unknown): value is AgentSurfaceKind;
+export declare function isAgentHostClientIdentity(value: unknown): value is AgentHostClientIdentity;
+export declare function isAgentHostHandshake(value: unknown): value is AgentHostHandshake;
+export declare function isAgentProviderListResult(value: unknown): value is AgentProviderListResult;
+/**
+ * Which run something belongs to, from the two identifiers that answer it.
+ *
+ * 🔴 ONE callee, deliberately, because two things need this answer and they
+ * must never disagree: the host resolving a run from a turn REQUEST, and a
+ * session deciding whether a runtime EVENT belongs in its terminal. Both types
+ * carry the same pair of fields; if the derivations drifted, a session would
+ * render another run's output — in a fleet that is both confusing and a
+ * disclosure, and it would look like a rendering bug rather than a routing one.
+ *
+ * A subagent run is its own run. That is why `subagentRunId` wins: a subagent's
+ * events belong to the subagent's session, not to the conversation that spawned
+ * it.
+ */
+export declare function defaultRunIdOf(ids: {
+    conversationId: string;
+    subagentRunId?: string | undefined;
+}): string;
+export declare function isAgentRuntimeEventEnvelope(value: unknown): value is AgentRuntimeEventEnvelope;
+export declare function isAgentRuntimeEventListResult(value: unknown): value is AgentRuntimeEventListResult;
+export declare function isAgentTurnStartResult(value: unknown): value is AgentTurnStartResult;
+export declare function isAgentTurnCancelResult(value: unknown): value is AgentTurnCancelResult;
+export declare function isAgentHostEvent(value: unknown): value is AgentHostEvent;
+/**
+ * 🔴 Reads AGENT_HOST_EVENT_TYPES rather than restating it.
+ *
+ * Restating it is what shipped a guard three types short of the contract. A
+ * frame the guard does not recognise is not ignored — it DISCONNECTS the
+ * client — so an omission here is an outage, not a gap.
+ */
+export declare function isAgentHostEventType(value: unknown): value is AgentHostEventType;
+export declare function assertCompatibleHandshake(handshake: AgentHostHandshake, identity: AgentHostClientIdentity, supportedProtocol: AgentHostProtocolRange): void;
+export * from './engineering.js';
+//# sourceMappingURL=index.d.ts.map