@airterm/protocol 0.4.0 → 0.6.0

package/README.md

@@ -21,6 +21,25 @@ the public APIs from the package root.
 import { deriveCapabilityKeys, NoiseTransport } from '@airterm/protocol';
 ```
 
+## ACP middleware
+
+The additive `acp-middleware-v4` feature carries a bounded canonical ACP model
+between the CLI and browser. `AcpCommand` frames contain only validated user
+actions; `AcpEvent` frames contain reducer mutations, snapshots, and bounded
+catalog results. Raw provider JSON-RPC, request identifiers, extension fields,
+and tool payloads are intentionally outside this browser-facing contract.
+Snapshots are committed atomically after their declared SHA-256 digest
+(computed over canonical key-sorted JSON serialization via `canonicalJsonStringify`)
+and mutation counts validate. Terminal framing remains protocol version 1. The
+reserved raw ACP frame (28) is rejected; there is no raw browser fallback.
+
+Version 4 adds identified plans: `plan-upsert` and `plan-remove` mutations over a
+canonical plan that is an item checklist, bounded markdown, or an opaque file
+reference. Each part is bounded in bytes and in count, and a plan that exceeds a
+bound is truncated by its producer with an explicit marker, because the codec
+refuses an oversized plan rather than trimming it. There is no v3 compatibility
+path: the browser and the CLI are released together.
+
 Requires Node.js 22.12 or newer for Node-based consumers. Browser consumers need
 Web Crypto and WebAssembly support.
 
@@ -48,10 +67,11 @@ Output acknowledgements refer to contiguous PTY byte offsets consumed by the
 terminal renderer, not merely received by the socket. Never acknowledge across
 a gap, reuse a cipher after failure, or replay uncertain terminal input.
 
-## Account encryption envelopes (0.4 prerelease)
+## Account encryption envelopes
 
 The vault and pairing exports are additive application envelopes; terminal protocol v1 framing is unchanged. Vaults use RSA-OAEP-3072/SHA-256, AES-256-GCM, and context-bound HKDF. Version 1 fixes passphrase Argon2id parameters at 64 MiB, three iterations, one lane, 16-byte salt, and 32-byte output; browser derivation lives in the application worker. Unknown fields, algorithms, versions, sizes, or substituted account/session context must fail closed.
 
 Exactly one primary vault wrapper and one user-held recovery wrapper are supported. The pairing encryption secret is distinct from the polling credential and never reaches the server. These primitives do not authenticate a downloaded browser application or provide an independent cryptographic audit.
 
-The backend pins a reproducible prerelease tarball until separately authorized registry publication. Publish the protocol before any CLI release that depends on it; do not relabel a prerelease artifact as an already published version.
+Publish `@airterm/protocol` before any CLI release that depends on it; the CLI
+package pins an exact protocol version.

package/dist/acp-agents.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Agent identity and capability normalisation.
+ *
+ * ACP capability payloads are shaped by each agent, and they differ in practice:
+ * opencode, Codex, and pi each advertise a different subset, and some add keys
+ * of their own. Clients should not read those payloads feature by feature, so
+ * everything an agent says is reduced here to one shape that both the CLI and
+ * the browser agree on. Unknown keys are ignored, never rejected, because an
+ * agent adding one is not an error.
+ */
+export interface AcpAgentCapabilities {
+    /** Can enumerate its own chats (`session/list`). */
+    listChats?: boolean;
+    loadSession?: boolean;
+    resume?: boolean;
+    fork?: boolean;
+    close?: boolean;
+    delete?: boolean;
+    images?: boolean;
+    audio?: boolean;
+    embeddedContext?: boolean;
+}
+/**
+ * An ACP agent a CLI can start.
+ *
+ * Browsers choose an agent by id and never by command: ids resolve against the
+ * CLI's own registry, so a request can never name a program to run.
+ */
+export interface AcpAgentDescription {
+    id: string;
+    label: string;
+    available: boolean;
+    /** Starting it may fetch an adapter, so the first launch can be slow. */
+    slowStart?: boolean;
+    /** Preview support: the agent is usable but not yet a settled integration. */
+    beta?: boolean;
+    /** Absent until the agent has been asked what it supports. */
+    capabilities?: AcpAgentCapabilities;
+}
+export declare const ACP_AGENT_LIMIT = 32;
+export declare const ACP_AGENT_LABEL_LIMIT = 96;
+/**
+ * Reduces an `initialize` response's `agentCapabilities` to what this client
+ * understands.
+ *
+ * A session capability is advertised by the presence of an entry (an empty
+ * object means supported, `null` means not), while `loadSession` is a plain
+ * boolean - so each is read the way the protocol defines it rather than by
+ * truthiness of the whole object.
+ */
+export declare function readAgentCapabilities(value: unknown): AcpAgentCapabilities;
+/** Whether an agent id is one this protocol allows on the wire. */
+export declare function isAcpAgentId(value: unknown): value is string;
+/** A display label an agent may have chosen, bounded and free of control characters. */
+export declare function readAgentLabel(value: unknown): string | undefined;
+export declare function encodeAgentCapabilities(capabilities: AcpAgentCapabilities): Record<string, boolean>;
+export declare function decodeAgentCapabilities(value: unknown): AcpAgentCapabilities | undefined;
+/**
+ * Reads the agent list from a session description.
+ *
+ * An unusable entry is dropped rather than thrown: one bad agent must not cost
+ * the browser the whole description. `undefined` means the CLI predates the
+ * field, which is different from an empty list.
+ */
+export declare function decodeAcpAgents(value: unknown): AcpAgentDescription[] | undefined;
+//# sourceMappingURL=acp-agents.d.ts.map

package/dist/acp-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-agents.d.ts","sourceRoot":"","sources":["../src/acp-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,oBAAoB;IACjC,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8DAA8D;IAC9D,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAKxC;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAuB1E;AAOD,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE5D;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAgBjE;AAED,wBAAgB,uBAAuB,CACnC,YAAY,EAAE,oBAAoB,GACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB;AAED,wBAAgB,uBAAuB,CACnC,KAAK,EAAE,OAAO,GACf,oBAAoB,GAAG,SAAS,CAkBlC;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,EAAE,GAAG,SAAS,CAqCjF"}

package/dist/acp-agents.js

@@ -0,0 +1,141 @@
+/**
+ * Agent identity and capability normalisation.
+ *
+ * ACP capability payloads are shaped by each agent, and they differ in practice:
+ * opencode, Codex, and pi each advertise a different subset, and some add keys
+ * of their own. Clients should not read those payloads feature by feature, so
+ * everything an agent says is reduced here to one shape that both the CLI and
+ * the browser agree on. Unknown keys are ignored, never rejected, because an
+ * agent adding one is not an error.
+ */
+export const ACP_AGENT_LIMIT = 32;
+export const ACP_AGENT_LABEL_LIMIT = 96;
+const AGENT_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const CONTROL_CHARACTERS = /[\p{Cc}\p{Cf}]/u;
+/**
+ * Reduces an `initialize` response's `agentCapabilities` to what this client
+ * understands.
+ *
+ * A session capability is advertised by the presence of an entry (an empty
+ * object means supported, `null` means not), while `loadSession` is a plain
+ * boolean - so each is read the way the protocol defines it rather than by
+ * truthiness of the whole object.
+ */
+export function readAgentCapabilities(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const session = isRecord(value.sessionCapabilities)
+        ? value.sessionCapabilities
+        : {};
+    const prompt = isRecord(value.promptCapabilities)
+        ? value.promptCapabilities
+        : {};
+    return {
+        ...(value.loadSession === true ? { loadSession: true } : {}),
+        ...(isAdvertised(session.list) ? { listChats: true } : {}),
+        ...(isAdvertised(session.resume) ? { resume: true } : {}),
+        ...(isAdvertised(session.fork) ? { fork: true } : {}),
+        ...(isAdvertised(session.close) ? { close: true } : {}),
+        ...(isAdvertised(session.delete) ? { delete: true } : {}),
+        ...(prompt.image === true ? { images: true } : {}),
+        ...(prompt.audio === true ? { audio: true } : {}),
+        ...(prompt.embeddedContext === true ? { embeddedContext: true } : {}),
+    };
+}
+/** An advertised session capability is a capability object, or absent/null. */
+function isAdvertised(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether an agent id is one this protocol allows on the wire. */
+export function isAcpAgentId(value) {
+    return typeof value === 'string' && AGENT_ID.test(value);
+}
+/** A display label an agent may have chosen, bounded and free of control characters. */
+export function readAgentLabel(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const label = value.trim();
+    if (label.length === 0 ||
+        label.length > ACP_AGENT_LABEL_LIMIT ||
+        CONTROL_CHARACTERS.test(label)) {
+        return undefined;
+    }
+    return label;
+}
+export function encodeAgentCapabilities(capabilities) {
+    return {
+        ...(capabilities.listChats === true ? { list_chats: true } : {}),
+        ...(capabilities.loadSession === true ? { load_session: true } : {}),
+        ...(capabilities.resume === true ? { resume: true } : {}),
+        ...(capabilities.fork === true ? { fork: true } : {}),
+        ...(capabilities.close === true ? { close: true } : {}),
+        ...(capabilities.delete === true ? { delete: true } : {}),
+        ...(capabilities.images === true ? { images: true } : {}),
+        ...(capabilities.audio === true ? { audio: true } : {}),
+        ...(capabilities.embeddedContext === true ? { embedded_context: true } : {}),
+    };
+}
+export function decodeAgentCapabilities(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return {
+        ...(hasCapability(value.list_chats) || hasCapability(value.listChats) ? { listChats: true } : {}),
+        ...(hasCapability(value.load_session) || hasCapability(value.loadSession) ? { loadSession: true } : {}),
+        ...(hasCapability(value.resume) ? { resume: true } : {}),
+        ...(hasCapability(value.fork) ? { fork: true } : {}),
+        ...(hasCapability(value.close) ? { close: true } : {}),
+        ...(hasCapability(value.delete) ? { delete: true } : {}),
+        ...(hasCapability(value.images) ? { images: true } : {}),
+        ...(hasCapability(value.audio) ? { audio: true } : {}),
+        ...(hasCapability(value.embedded_context) || hasCapability(value.embeddedContext)
+            ? { embeddedContext: true }
+            : {}),
+    };
+}
+function hasCapability(value) {
+    return value === true || (typeof value === 'object' && value !== null && !Array.isArray(value));
+}
+/**
+ * Reads the agent list from a session description.
+ *
+ * An unusable entry is dropped rather than thrown: one bad agent must not cost
+ * the browser the whole description. `undefined` means the CLI predates the
+ * field, which is different from an empty list.
+ */
+export function decodeAcpAgents(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error('Invalid agent list payload.');
+    }
+    const agents = [];
+    for (const entry of value.slice(0, ACP_AGENT_LIMIT)) {
+        if (!isRecord(entry) || !isAcpAgentId(entry.id)) {
+            continue;
+        }
+        const label = readAgentLabel(entry.label);
+        if (label === undefined) {
+            continue;
+        }
+        const capabilities = entry.capabilities === undefined
+            ? undefined
+            : decodeAgentCapabilities(entry.capabilities);
+        agents.push({
+            id: entry.id,
+            label,
+            available: entry.available === true,
+            ...(entry.slow_start === true ? { slowStart: true } : {}),
+            ...(entry.beta === true ? { beta: true } : {}),
+            ...(capabilities === undefined ? {} : { capabilities }),
+        });
+    }
+    return agents;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=acp-agents.js.map

package/dist/acp-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-agents.js","sourceRoot":"","sources":["../src/acp-agents.ts"],"names":[],"mappings":"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"}

package/dist/acp-middleware.d.ts

@@ -0,0 +1,426 @@
+/** Provider-neutral ACP messages exchanged across AirTerm's encrypted transport. */
+export declare const ACP_MIDDLEWARE_VERSION: 4;
+export declare const ACP_MIDDLEWARE_FEATURE: "acp-middleware-v4";
+export declare const ACP_MIDDLEWARE_MAX_COMMAND_BYTES: number;
+export declare const ACP_MIDDLEWARE_MAX_EVENT_BYTES: number;
+export declare const ACP_MIDDLEWARE_MAX_MUTATIONS = 64;
+export declare const ACP_MIDDLEWARE_MAX_SNAPSHOT_BYTES: number;
+export declare const ACP_MIDDLEWARE_MAX_SNAPSHOT_CHUNKS = 128;
+export declare const ACP_MIDDLEWARE_MAX_SNAPSHOT_MUTATIONS = 4096;
+export declare const ACP_MIDDLEWARE_MAX_TEXT_BYTES: number;
+/** How many attachment paths one prompt may carry. */
+export declare const ACP_MIDDLEWARE_MAX_PROMPT_FILES: 10;
+/** A path is a host path, bounded the same way every other one is. */
+export declare const ACP_MIDDLEWARE_MAX_PATH_BYTES = 4096;
+export declare const ACP_MIDDLEWARE_MAX_TURNS = 50;
+export declare const ACP_MIDDLEWARE_MAX_HISTORY_BYTES: number;
+export declare const ACP_MIDDLEWARE_MAX_ACTIVE_TURN_BYTES: number;
+export declare const ACP_MIDDLEWARE_MAX_PENDING_REQUESTS = 16;
+export declare const ACP_MIDDLEWARE_MAX_PENDING_BYTES: number;
+export declare const ACP_MIDDLEWARE_MAX_REASONING_BYTES: number;
+export declare const ACP_MIDDLEWARE_MAX_CONFIG_OPTIONS: 64;
+export declare const ACP_MIDDLEWARE_MAX_CONFIG_CHOICES: 255;
+export declare const ACP_MIDDLEWARE_MAX_COMMANDS: 128;
+export declare const ACP_MIDDLEWARE_MAX_COMMAND_NAME_BYTES = 128;
+export declare const ACP_MIDDLEWARE_MAX_COMMAND_DESCRIPTION_BYTES = 256;
+export declare const ACP_MIDDLEWARE_MAX_COMMAND_HINT_BYTES = 128;
+/**
+ * Bounds on an agent's plan.
+ *
+ * A plan is display-only content an agent may rewrite as often as it likes, so
+ * every part of it is bounded here rather than at the point a pane happens to
+ * render it: the identifier an update is correlated by, how many entries an item
+ * plan may show, how long each entry may be, and how much markdown a markdown
+ * plan may carry. A plan that exceeds a bound is truncated by its producer with a
+ * marker saying so, never silently cut.
+ */
+export declare const ACP_MIDDLEWARE_MAX_PLAN_ID_BYTES = 128;
+export declare const ACP_MIDDLEWARE_MAX_PLAN_ITEMS = 32;
+export declare const ACP_MIDDLEWARE_MAX_PLAN_ITEM_BYTES = 512;
+export declare const ACP_MIDDLEWARE_MAX_PLAN_MARKDOWN_BYTES: number;
+/** How many plans one turn may carry at once, newest kept. */
+export declare const ACP_MIDDLEWARE_MAX_PLANS_PER_TURN = 8;
+export type AcpCanonicalPhase = 'starting' | 'loading' | 'ready' | 'error' | 'closed';
+export interface AcpCanonicalCapabilities {
+    resume: boolean;
+    load: boolean;
+    cancel: boolean;
+    configuration: boolean;
+    permissions: boolean;
+    elicitation: boolean;
+}
+export interface AcpCanonicalConfigOption {
+    id: string;
+    category?: string;
+    type?: string;
+    currentValue?: string;
+    options?: Array<{
+        value: string;
+        label?: string;
+    }>;
+}
+/**
+ * A command a provider advertises for its slash picker.
+ *
+ * ACP requires every command to carry a description, so the provider's
+ * `input.hint` becomes the only optional field and an entry without a
+ * description is malformed rather than a blank row.
+ */
+export interface AcpCanonicalCommand {
+    name: string;
+    description: string;
+    inputHint?: string;
+}
+export interface AcpCanonicalTool {
+    id: string;
+    title: string;
+    kind?: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+    detail?: string;
+    failureReason?: string;
+    locations?: string[];
+}
+export interface AcpCanonicalMessage {
+    id: string;
+    role: 'assistant' | 'thought';
+    text: string;
+}
+export type AcpCanonicalTurnItem = {
+    kind: 'message';
+    id: string;
+    role: 'assistant' | 'thought';
+    text: string;
+} | {
+    kind: 'tool';
+    tool: AcpCanonicalTool;
+} | {
+    kind: 'omission';
+    id: string;
+    reason: string;
+};
+/**
+ * A plan an agent published, in one of the formats ACP defines.
+ *
+ * The three variants are deliberately different shapes rather than one shape with
+ * optional fields: an item plan is a checklist a pane can summarise progress
+ * from, a markdown plan is prose it renders, and a file plan is only a promise
+ * that a plan exists somewhere this client cannot reach.
+ */
+export type AcpPlan = {
+    id: string;
+    type: 'items';
+    /** The entries a pane shows, newest state of the plan. */
+    entries: AcpPlanItem[];
+    /** The count before truncation, present only when entries were cut. */
+    totalEntries?: number;
+} | {
+    id: string;
+    type: 'markdown';
+    content: string;
+    /** Set when the agent's markdown was longer than this contract allows. */
+    truncated?: boolean;
+} | {
+    id: string;
+    /**
+     * Identity only. The host URI an agent sends is deliberately discarded:
+     * it names a path on the agent's machine, which this client cannot read
+     * and must not pretend to.
+     */
+    type: 'file';
+};
+export interface AcpPlanItem {
+    content: string;
+    /** ACP's own statuses; an unknown one is shown as-is rather than refused. */
+    status: string;
+    priority?: string;
+}
+export interface AcpCanonicalTurn {
+    id: string;
+    origin: 'user' | 'agent';
+    userText?: string;
+    items: AcpCanonicalTurnItem[];
+    status: 'active' | 'complete' | 'interrupted';
+    stopReason?: string;
+    /**
+     * Plans this turn published, in the order they were first seen.
+     *
+     * Held beside `items` rather than in it because a plan is not a step of the
+     * transcript: it is replaced in place as the agent revises it, so it has no
+     * position in the narration it must keep.
+     */
+    plans?: AcpPlan[];
+}
+export interface AcpCanonicalInteraction {
+    id: string;
+    kind: 'permission' | 'elicitation';
+    message: string;
+    options?: Array<{
+        id: string;
+        label: string;
+        kind?: string;
+    }>;
+    schema?: Record<string, unknown>;
+}
+export interface AcpCanonicalNotice {
+    id: string;
+    level: 'info' | 'warning' | 'error';
+    message: string;
+}
+export interface AcpCanonicalState {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    phase: AcpCanonicalPhase;
+    agent: string;
+    sessionId?: string;
+    title?: string;
+    error?: string;
+    capabilities: AcpCanonicalCapabilities;
+    configOptions: AcpCanonicalConfigOption[];
+    currentModel?: string;
+    mode?: string;
+    commands: AcpCanonicalCommand[];
+    usage?: {
+        used: number;
+        size: number;
+        cost?: number;
+        currency?: string;
+    };
+    historyBoundary?: 'complete' | 'omitted';
+    turns: AcpCanonicalTurn[];
+    activeTurnId?: string;
+    interactions: AcpCanonicalInteraction[];
+    notices: AcpCanonicalNotice[];
+}
+export type AcpMutation = {
+    type: 'session';
+    phase: AcpCanonicalPhase;
+    sessionId?: string;
+    title?: string;
+    error?: string;
+} | {
+    type: 'history-boundary';
+    boundary: 'complete' | 'omitted';
+} | {
+    type: 'turn-start';
+    turnId: string;
+    origin: 'user' | 'agent';
+    userText?: string;
+} | {
+    type: 'turn-user-append';
+    turnId: string;
+    text: string;
+} | {
+    type: 'message-append';
+    turnId: string;
+    messageId: string;
+    role: 'assistant' | 'thought';
+    text: string;
+} | {
+    type: 'tool-upsert';
+    turnId: string;
+    tool: AcpCanonicalTool;
+} | {
+    type: 'omission-append';
+    turnId: string;
+    omissionId: string;
+    reason: string;
+} | {
+    type: 'plan-upsert';
+    turnId: string;
+    plan: AcpPlan;
+} | {
+    type: 'plan-remove';
+    turnId: string;
+    planId: string;
+} | {
+    type: 'turn-finish';
+    turnId: string;
+    status: 'complete' | 'interrupted';
+    stopReason?: string;
+} | {
+    type: 'config';
+    options: AcpCanonicalConfigOption[];
+    model?: string;
+} | {
+    type: 'mode';
+    mode?: string;
+} | {
+    type: 'commands';
+    commands: AcpCanonicalCommand[];
+} | {
+    type: 'usage';
+    used: number;
+    size: number;
+    cost?: number;
+    currency?: string;
+} | {
+    type: 'interaction-upsert';
+    interaction: AcpCanonicalInteraction;
+} | {
+    type: 'interaction-remove';
+    interactionId: string;
+} | {
+    type: 'notice';
+    notice: AcpCanonicalNotice;
+} | {
+    type: 'notice-remove';
+    noticeId: string;
+};
+/**
+ * A file's contents, as the CLI read them.
+ *
+ * The browser has no filesystem access, so a file reaches it the same way the
+ * workspace and session catalogs do - as the answer to a typed command. The
+ * count is of the whole file rather than of `content`, which is what lets a
+ * truncated read say how much was left behind.
+ */
+export interface AcpFileContent {
+    /** The path as resolved on the CLI's machine, for the viewer's header. */
+    path: string;
+    /** The file's text, empty when the file is binary. */
+    content: string;
+    /** The file's size in bytes, whether or not all of it was sent. */
+    totalBytes: number;
+    /** Set when `content` is a prefix of the file. */
+    truncated?: boolean;
+    /** Set when the file is not text; `content` is then empty. */
+    isBinary?: boolean;
+}
+/**
+ * A file's uncommitted changes, as `git diff` reported them.
+ *
+ * `isGit` separates "no changes" from "cannot tell": a workspace outside any
+ * repository is a different statement from a clean one, and the viewer says so
+ * rather than showing an empty diff the reader would read as "up to date".
+ */
+export interface AcpFileDiff {
+    path: string;
+    /** Unified diff text, empty when there are no changes. */
+    diff: string;
+    /** False when the file is outside a git work tree. */
+    isGit: boolean;
+    /** True when the file matches HEAD (or is not in git). */
+    clean: boolean;
+    /** Count of added lines, counted from the diff itself. */
+    additions?: number;
+    /** Count of removed lines. */
+    deletions?: number;
+    /** Set when `diff` is a prefix of the whole change. */
+    truncated?: boolean;
+}
+export type AcpCommand = {
+    kind: 'sync';
+    epoch?: string;
+    afterSequence?: number;
+} | {
+    kind: 'prompt';
+    text: string;
+    files?: string[];
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'set-config';
+    id: string;
+    value: string;
+} | {
+    kind: 'respond-interaction';
+    interactionId: string;
+    action: 'accept' | 'decline' | 'cancel';
+    values?: Record<string, unknown>;
+} | {
+    kind: 'history';
+    action: 'retry' | 'continue';
+} | {
+    kind: 'catalog-workspaces';
+    agent: string;
+} | {
+    kind: 'catalog-sessions';
+    agent: string;
+    cwd: string;
+} | {
+    kind: 'catalog-directories';
+    path?: string;
+} | {
+    kind: 'read-file';
+    path: string;
+    cwd?: string;
+} | {
+    kind: 'file-diff';
+    path: string;
+    cwd?: string;
+};
+export interface AcpCommandEnvelope {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    type: 'command';
+    commandId: string;
+    command: AcpCommand;
+}
+export type AcpEventEnvelope = {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    type: 'delta';
+    epoch: string;
+    firstSequence: number;
+    mutations: AcpMutation[];
+} | {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    type: 'snapshot-start';
+    snapshotId: string;
+    epoch: string;
+    throughSequence: number;
+    chunkCount: number;
+    mutationCount: number;
+    digest: string;
+} | {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    type: 'snapshot-chunk';
+    snapshotId: string;
+    index: number;
+    mutations: AcpMutation[];
+} | {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    type: 'snapshot-complete';
+    snapshotId: string;
+    chunkCount: number;
+    mutationCount: number;
+} | {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    type: 'command-result';
+    commandId: string;
+    accepted: boolean;
+    error?: string;
+} | {
+    version: typeof ACP_MIDDLEWARE_VERSION;
+    type: 'catalog-result';
+    commandId: string;
+    value: unknown;
+};
+export declare function createAcpCanonicalState(agent?: string, capabilities?: Partial<AcpCanonicalCapabilities>): AcpCanonicalState;
+export declare function isAcpGenerating(state: AcpCanonicalState): boolean;
+/** Pure reducer used by the CLI authority and the browser projection. */
+export declare function reduceAcpCanonicalState(state: AcpCanonicalState, mutation: AcpMutation): AcpCanonicalState;
+/**
+ * Cuts text to a byte budget without splitting a character.
+ *
+ * Every bound in this file is a UTF-8 byte count, but a JavaScript `slice`
+ * counts UTF-16 code units - so a producer that truncated by character count
+ * could emit a title or a message whose bytes exceed the bound the decoder
+ * enforces. The decoder would then reject the whole mutation, and because a
+ * mutation is validated as a unit, one over-long field would take the entire
+ * state restore with it. Truncating by bytes is what keeps a producer's own
+ * bound and the decoder's bound the same number.
+ */
+export declare function truncateUtf8(text: string, maximum: number): string;
+/** Reads text a byte-bounded field can hold, or nothing when it holds none. */
+export declare function boundedUtf8Text(value: unknown, maximum: number): string | undefined;
+export declare function encodeAcpCommand(commandIdValue: string, command: AcpCommand): Uint8Array;
+export declare function decodeAcpCommand(payload: Uint8Array): AcpCommandEnvelope;
+export declare function encodeAcpEvent(event: AcpEventEnvelope): Uint8Array;
+export declare function decodeAcpEvent(payload: Uint8Array): AcpEventEnvelope;
+/**
+ * Deterministic JSON serialization where object keys are recursively sorted.
+ *
+ * Arrays preserve their order; primitive values, null, and booleans match
+ * standard JSON.stringify; object keys whose values are undefined, functions,
+ * or symbols are omitted, matching standard JSON object serialization.
+ */
+export declare function canonicalJsonStringify(value: unknown): string;
+//# sourceMappingURL=acp-middleware.d.ts.map