@anureo/adapter-acp 0.2.0 → 0.3.0

package/src/diagnostics.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Prepare one stderr line for StderrTail.push. Truncate to 8,192 UTF-16 code units plus an
+ * ellipsis when needed, then redact recognized credential patterns.
+ */
+export declare function redactLine(line: string): string;
+/**
+ * Buffer decoded stderr for captureStderr. The tail keeps at most 32,768 UTF-16 code units
+ * of redacted text, counting each retained line's length plus one for its separator.
+ */
+export declare class StderrTail {
+    private readonly maxLines;
+    private readonly onLine?;
+    /**
+     * Set the retained line limit. A nonpositive limit disables capture and the optional synchronous
+     * onLine callback. Callback throws are ignored so captureStderr can keep draining.
+     */
+    constructor(maxLines: number, onLine?: ((line: string) => void) | undefined);
+    /** Redact one line and notify onLine before updating the tail. Evict oldest entries to enforce both bounds. */
+    push(line: string): void;
+    /**
+     * Buffer decoded stderr across chunks and publish each LF-delimited line.
+     * Publish an unterminated fragment once it exceeds 8,192 code units to bound retained partial text.
+     */
+    write(chunk: string): void;
+    /** Publish and clear any buffered fragment. captureStderr calls this when draining ends. */
+    flush(): void;
+    /** Rendered tail, oldest first. Empty when capture is disabled or nothing arrived. */
+    text(): string;
+    /** Number of retained lines, excluding a buffered partial line. */
+    get size(): number;
+    private readonly lines;
+    private retainedCodeUnits;
+    private partial;
+    /** Treat a fragment emitted by write or flush as one entry so both paths use the same redaction and bounds. */
+    private publishPartial;
+}

package/src/diagnostics.js

@@ -0,0 +1,91 @@
+// Bounds the stderr tail included in ACP failure diagnostics and filters recognized credentials.
+/**
+ * Prepare one stderr line for StderrTail.push. Truncate to 8,192 UTF-16 code units plus an
+ * ellipsis when needed, then redact recognized credential patterns.
+ */
+export function redactLine(line) {
+    let value = line.length > LINE_CODE_UNIT_LIMIT ? `${line.slice(0, LINE_CODE_UNIT_LIMIT)}…` : line;
+    for (const [pattern, replacement] of REDACTIONS)
+        value = value.replace(pattern, replacement);
+    return value;
+}
+/**
+ * Buffer decoded stderr for captureStderr. The tail keeps at most 32,768 UTF-16 code units
+ * of redacted text, counting each retained line's length plus one for its separator.
+ */
+export class StderrTail {
+    maxLines;
+    onLine;
+    /**
+     * Set the retained line limit. A nonpositive limit disables capture and the optional synchronous
+     * onLine callback. Callback throws are ignored so captureStderr can keep draining.
+     */
+    constructor(maxLines, onLine) {
+        this.maxLines = maxLines;
+        this.onLine = onLine;
+    }
+    /** Redact one line and notify onLine before updating the tail. Evict oldest entries to enforce both bounds. */
+    push(line) {
+        if (this.maxLines <= 0)
+            return;
+        const redacted = redactLine(line);
+        try {
+            this.onLine?.(redacted);
+        }
+        catch { /* a consumer callback must not break draining */ }
+        this.retainedCodeUnits += redacted.length + 1;
+        this.lines.push(redacted);
+        while (this.lines.length > this.maxLines || this.retainedCodeUnits > TOTAL_CODE_UNIT_LIMIT) {
+            const dropped = this.lines.shift();
+            if (dropped === undefined)
+                break;
+            this.retainedCodeUnits -= dropped.length + 1;
+        }
+    }
+    /**
+     * Buffer decoded stderr across chunks and publish each LF-delimited line.
+     * Publish an unterminated fragment once it exceeds 8,192 code units to bound retained partial text.
+     */
+    write(chunk) {
+        if (this.maxLines <= 0)
+            return;
+        this.partial += chunk;
+        for (let index = this.partial.indexOf('\n'); index >= 0; index = this.partial.indexOf('\n')) {
+            this.push(this.partial.slice(0, index));
+            this.partial = this.partial.slice(index + 1);
+        }
+        // A child that never emits a newline must not grow the buffer without bound.
+        if (this.partial.length > LINE_CODE_UNIT_LIMIT)
+            this.publishPartial();
+    }
+    /** Publish and clear any buffered fragment. captureStderr calls this when draining ends. */
+    flush() {
+        if (!this.partial)
+            return;
+        this.publishPartial();
+    }
+    /** Rendered tail, oldest first. Empty when capture is disabled or nothing arrived. */
+    text() {
+        return this.lines.join('\n');
+    }
+    /** Number of retained lines, excluding a buffered partial line. */
+    get size() {
+        return this.lines.length;
+    }
+    lines = [];
+    retainedCodeUnits = 0;
+    partial = '';
+    /** Treat a fragment emitted by write or flush as one entry so both paths use the same redaction and bounds. */
+    publishPartial() {
+        this.push(this.partial);
+        this.partial = '';
+    }
+}
+const LINE_CODE_UNIT_LIMIT = 8 * 1024;
+const TOTAL_CODE_UNIT_LIMIT = 32 * 1024;
+const REDACTIONS = [
+    [/\b(sk-[A-Za-z0-9_-]{8,})/g, 'sk-[redacted]'],
+    [/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, '$1[redacted]'],
+    [/\b((?:api[_-]?key|token|secret|password|authorization)\s*[:=]\s*)\S+/gi, '$1[redacted]'],
+    [/\b(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[redacted]@'],
+];

package/src/dsh.d.ts

@@ -0,0 +1,32 @@
+import { type AcpAdapter } from "./adapter.js";
+import type { AcpAdapterOptions } from "./options.js";
+/** Configure the DSH command and approval policy alongside ACP's host ports and transport options. */
+export interface DshAcpOptions extends Omit<AcpAdapterOptions, 'command' | 'args'> {
+    /** `dsh` executable; defaults to `dsh` on PATH. */
+    command?: string;
+    /** Value passed to `--profile`; defaults to `acp`. */
+    profile?: string;
+    /**
+     * Set the child's DSH home. An explicit env.DSH_HOME entry takes precedence, including undefined.
+     * Otherwise the preset uses this value, the host's DSH_HOME, or `~/.dsh`, in that order.
+     */
+    dshHome?: string;
+    /**
+     * Opt into the allow-once policy for unattended hosts, overriding autoRespondPermission.
+     * Requests without a matching option still fall back to interactive handling. Defaults to false.
+     */
+    autoApprove?: boolean;
+}
+/**
+ * Create an ACP adapter for DeepSeek Harness, launching `dsh --profile acp` by default.
+ * Pass it to createClient to start the transport and negotiate ACP, then await client disposal
+ * when finished. Construction only configures the adapter. A supplied connect factory takes
+ * precedence over the command during initialization.
+ *
+ * DSH needs Node.js >= 24.9 and provider credentials in DSH_HOME. Startup failures during the
+ * handshake include the redacted stderr tail when available. The preset sets a 120,000 ms
+ * native request wait (excluding session/prompt) when requestTimeoutMs is omitted. Passing it
+ * explicitly as undefined uses ACP's 30,000 ms fallback. Stdio retains up to 200 stderr lines by default.
+ * Child environment overrides are merged over the host environment and preset DSH_HOME.
+ */
+export declare function createDshAcpAdapter(options?: DshAcpOptions): AcpAdapter;

package/src/dsh.js

@@ -0,0 +1,31 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createAcpAdapter } from "./adapter.js";
+/**
+ * Create an ACP adapter for DeepSeek Harness, launching `dsh --profile acp` by default.
+ * Pass it to createClient to start the transport and negotiate ACP, then await client disposal
+ * when finished. Construction only configures the adapter. A supplied connect factory takes
+ * precedence over the command during initialization.
+ *
+ * DSH needs Node.js >= 24.9 and provider credentials in DSH_HOME. Startup failures during the
+ * handshake include the redacted stderr tail when available. The preset sets a 120,000 ms
+ * native request wait (excluding session/prompt) when requestTimeoutMs is omitted. Passing it
+ * explicitly as undefined uses ACP's 30,000 ms fallback. Stdio retains up to 200 stderr lines by default.
+ * Child environment overrides are merged over the host environment and preset DSH_HOME.
+ */
+export function createDshAcpAdapter(options = {}) {
+    const { dshHome, profile = 'acp', autoApprove = false, ...rest } = options;
+    return createAcpAdapter({
+        stderrTailLines: 200,
+        requestTimeoutMs: 120_000,
+        ...rest,
+        command: rest.command ?? 'dsh',
+        args: ['--profile', profile],
+        env: {
+            ...process.env,
+            DSH_HOME: dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh'),
+            ...rest.env,
+        },
+        ...(autoApprove ? { autoRespondPermission: 'allow-once' } : {}),
+    });
+}

package/src/extensions.d.ts

@@ -0,0 +1,25 @@
+/** Operations that can be advertised as private ACP methods. */
+export type ExtensionKey = 'fork' | 'revert' | 'steer' | 'history' | 'goalSet' | 'goalClear' | 'compact' | 'review';
+/** Negotiated features shared by AcpAdapter and its backend sessions. */
+export interface Extensions {
+    /** Accepted private method names, which the adapter can withdraw after a native rejection. */
+    methods: Partial<Record<ExtensionKey, string>>;
+    /** Supported fork boundaries when a private fork method is present. */
+    fork: Array<'before' | 'through'>;
+    /** Supported revert scopes when a private revert method is present. */
+    revert: Array<'conversation' | 'files' | 'both'>;
+    /** Whether peer updates can describe nested subagent activity. */
+    subagents: boolean;
+    /** Whether session open can send custom instructions in AHP metadata. */
+    instructions: boolean;
+    /** Whether the adapter accepts the negotiated _ahp/user_input request. */
+    userInput: boolean;
+    /** Whether the adapter accepts the negotiated _ahp/dynamic_tool request. */
+    dynamicTool: boolean;
+    /** Whether v2 turn-correlation notifications and prompt receipts govern execution. */
+    nativeLifecycle?: boolean;
+}
+/** Read AHP v1 metadata or v2 metadata with explicit turn correlation. AcpAdapter.configureCapabilities
+ * stores the parsed methods and flags and uses them to advertise supported operations.
+ * Missing or incompatible metadata yields no capabilities from this extension. */
+export declare function extensions(response: unknown): Extensions;

package/src/extensions.js

@@ -0,0 +1,30 @@
+// Parses optional AHP capabilities advertised in native ACP metadata.
+import { record } from "./mapping.js";
+/** Read AHP v1 metadata or v2 metadata with explicit turn correlation. AcpAdapter.configureCapabilities
+ * stores the parsed methods and flags and uses them to advertise supported operations.
+ * Missing or incompatible metadata yields no capabilities from this extension. */
+export function extensions(response) {
+    const extension = record(record(record(response)._meta).ahp);
+    const methods = {};
+    const result = { methods, fork: [], revert: [], subagents: false, instructions: false, userInput: false, dynamicTool: false };
+    if (extension.version !== 1 && !(extension.version === 2 && extension.turnCorrelation === true))
+        return result;
+    result.nativeLifecycle = extension.version === 2 && extension.turnCorrelation === true;
+    const names = record(extension.methods);
+    for (const key of extensionKeys) {
+        const name = names[key];
+        if (typeof name === 'string' && /^_[a-zA-Z0-9/_.-]+$/.test(name))
+            methods[key] = name;
+    }
+    if (methods.fork && Array.isArray(extension.fork))
+        result.fork = extension.fork.filter((value) => value === 'before' || value === 'through');
+    if (methods.revert && Array.isArray(extension.revert))
+        result.revert = extension.revert.filter((value) => ['conversation', 'files', 'both'].includes(String(value)));
+    result.subagents = extension.subagents === true;
+    result.instructions = extension.instructions === true;
+    const requests = record(extension.clientRequests);
+    result.userInput = requests.userInput === '_ahp/user_input';
+    result.dynamicTool = requests.dynamicTool === '_ahp/dynamic_tool';
+    return result;
+}
+const extensionKeys = ['fork', 'revert', 'steer', 'history', 'goalSet', 'goalClear', 'compact', 'review'];

package/src/file-changes.d.ts

@@ -0,0 +1,9 @@
+import type { FileChange } from '@anureo/protocol';
+/**
+ * Convert valid ACP diff blocks to complete file-text materials without reading or writing files.
+ * The mapper includes them in live tool snapshots. AcpBackendSession.extension uses them
+ * to fill absent fileChanges in history before validating the page. Retain valid diff blocks
+ * in input order and ignore other content, including text that resembles a patch.
+ * Missing or null oldText means a new file. Empty strings are valid file contents.
+ */
+export declare function acpFileChanges(content: unknown): FileChange[];

package/src/file-changes.js

@@ -0,0 +1,29 @@
+/**
+ * Convert valid ACP diff blocks to complete file-text materials without reading or writing files.
+ * The mapper includes them in live tool snapshots. AcpBackendSession.extension uses them
+ * to fill absent fileChanges in history before validating the page. Retain valid diff blocks
+ * in input order and ignore other content, including text that resembles a patch.
+ * Missing or null oldText means a new file. Empty strings are valid file contents.
+ */
+export function acpFileChanges(content) {
+    if (!Array.isArray(content))
+        return [];
+    return content.flatMap(value => {
+        if (!value || typeof value !== 'object')
+            return [];
+        const part = value;
+        if (part.type !== 'diff' || typeof part.path !== 'string')
+            return [];
+        if (part.oldText !== undefined && part.oldText !== null && typeof part.oldText !== 'string')
+            return [];
+        if (typeof part.newText !== 'string')
+            return [];
+        const oldText = part.oldText ?? null;
+        return [{
+                path: part.path,
+                operation: oldText === null ? 'add' : 'modify',
+                materials: [{ format: 'text', scope: 'file', oldText, newText: part.newText }],
+                completeness: 'complete',
+            }];
+    });
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export { AcpAdapter, AcpBackendSession, createAcpAdapter } from "./adapter.js";
+export { createDshAcpAdapter, type DshAcpOptions } from "./dsh.js";
+export type { AcpAdapterOptions, AcpChannel, AcpFileSystemPort, AcpPermissionContext, AcpPermissionDecision, AcpPermissionPolicy, AcpTerminalPort, } from "./options.js";

package/src/index.js

@@ -0,0 +1,3 @@
+// Publishes the ACP adapter, host integration contracts and DeepSeek Harness preset.
+export { AcpAdapter, AcpBackendSession, createAcpAdapter } from "./adapter.js";
+export { createDshAcpAdapter } from "./dsh.js";

package/src/mapping.d.ts

@@ -0,0 +1,119 @@
+import type { Capabilities, ConfigOption, InputBlock, JsonObject, JsonValue, McpServer as SessionMcpServer, SessionState } from '@anureo/protocol';
+import { type SessionEventSink } from '@anureo/sdk';
+import type { ContentBlock, McpServer } from '@agentclientprotocol/sdk';
+/** Read a native object by reference. Arrays, null and primitives become a fresh empty record. */
+export declare function record(value: unknown): Record<string, unknown>;
+/**
+ * Make a detached JSON copy and apply publicValue redaction before retaining native payloads.
+ * Nullish values become null. JSON serialization and parsing errors propagate synchronously.
+ * Callers still own removal of secrets embedded in arbitrary text.
+ */
+export declare function safe(value: unknown): JsonValue;
+/**
+ * Flatten native content for message, plan and compaction text. Arrays join block text with
+ * newlines, diffs join old and new text with a newline, and unrecognized blocks yield empty text.
+ */
+export declare function text(value: unknown): string;
+/**
+ * Translate prompt blocks in order for AcpBackendSession.submitStandardInput and
+ * submitCorrelatedInput to send in session/prompt. File links use the URI as the name when
+ * omitted. Throws INVALID_PARAMS before dispatch if an image's data or MIME type is empty or missing.
+ */
+export declare function input(blocks: InputBlock[]): ContentBlock[];
+/**
+ * Build native MCP server entries in input order for the session request sent by AcpAdapter.openSession.
+ * Omitted servers, stdio arguments, HTTP headers and environment variables become empty arrays.
+ */
+export declare function mcp(servers?: SessionMcpServer[]): McpServer[];
+/**
+ * Project native booleans, select lists and modes for AcpBackendSession.configure to advertise in
+ * capabilities and merge into current state. Missing current values supply no patch.
+ * setConfiguration uses keys to address the native option or mode, so the model alias points
+ * to its original native descriptor.
+ */
+export declare function configuration(data: Record<string, unknown>): {
+    options: ConfigOption[];
+    values: JsonObject;
+    keys: Map<string, Record<string, unknown>>;
+};
+/**
+ * Project one execution's native updates into ordered item events and session patches.
+ * AcpBackendSession keeps a standard mapper and creates a separate mapper for each correlated
+ * turn that receives an update. The session controls reset, completion and resource cleanup.
+ * Await each update in source order. Sink and callback failures reject after any prior mutations.
+ */
+export declare class AcpUpdateMapper {
+    private readonly sink;
+    private readonly getTurn;
+    private readonly state;
+    private readonly setState;
+    private readonly subagents;
+    /**
+     * AcpBackendSession supplies the event sink, a turn ID reader that can return undefined while
+     * idle, and callbacks backed by snapshot and configure. The mapper applies state patches
+     * synchronously before reading or publishing state. Enable subagents only after negotiation.
+     */
+    constructor(sink: SessionEventSink, getTurn: () => string | undefined, state: () => SessionState, setState: (data: Record<string, unknown>) => void, subagents: boolean);
+    /**
+     * Forget cached items, completions, summaries and generated plan IDs without publishing.
+     * AcpBackendSession.beginStandardSubmission calls this before reusing the standard mapper.
+     */
+    reset(): void;
+    /**
+     * Flush unended cached items in insertion order, promoting running status to completed.
+     * AcpBackendSession.submitStandardInput and nativeEvent await this before publishing
+     * turn/completed. Publication failures reject and leave prior mutations and events in place.
+     * With no current turn, no items are published.
+     */
+    complete(): Promise<void>;
+    /**
+     * Await projection/publication of one native update forwarded by AcpBackendSession.update.
+     * Configuration, metadata and usage can be published while idle. Other idle updates and unmapped
+     * turn updates produce notices. A failed publication leaves state and cache mutations in place.
+     * AcpAdapter's notification routing observes rejection and ends the stream.
+     */
+    update(update: Record<string, unknown>): Promise<void>;
+    private readonly items;
+    private readonly ended;
+    private serial;
+    private readonly compaction;
+    /**
+     * Cache a turn's item before publishing it. An unseen ID starts even in completion mode.
+     * Later snapshots emit full patches until the ID is marked ended. Mark it ended before
+     * awaiting completion publication so subsequent writes stay silent even if the sink rejects.
+     * With no current turn, discard the snapshot without touching the cache.
+     */
+    private upsert;
+    /**
+     * Apply a changed title before publishing session/metadata, including while idle.
+     * Omitted, invalid and unchanged titles leave state and publication alone. Null clears the title.
+     */
+    private updateMetadata;
+    /**
+     * Accumulate message chunks by kind and message ID, falling back to one item per kind.
+     * Publish a start before the first delta. User items emit full patches and agent/reasoning
+     * items emit text deltas. Unsupported content is retained in notices. complete flushes the items.
+     */
+    private updateMessage;
+    /** Publish the merged tool snapshot, closing the item when its mapped status is terminal. */
+    private updateToolCall;
+    /**
+     * Publish standard steps under one stable ID and extension plans under their supplied or
+     * generated IDs. Extension removal publishes an empty terminal plan.
+     */
+    private updatePlan;
+    /** Accumulate summary chunks, replace explicit summaries, and close only on native terminal status. */
+    private updateCompaction;
+    /** Merge negotiated subagent fields and publish a terminal snapshot when its native state ends. */
+    private updateSubagent;
+}
+/**
+ * Resolve a host value against the agent's advertised session configuration.
+ * AcpAdapter.openSession passes the model override here before calling setConfiguration.
+ * Returns the requested value when no nonempty string enum constrains it, otherwise accepts
+ * an exact match or a unique provider-qualified suffix. Throws CAPABILITY_UNSUPPORTED for
+ * a missing session option and INVALID_PARAMS for an unknown or ambiguous enum value.
+ *
+ * This lets hosts use a bare model name when a peer advertises `provider/model`.
+ */
+export declare function resolveConfigValue(capabilities: Capabilities, key: string, wanted: string): string;