@anureo/adapter-acp 0.2.0 → 0.3.0

package/src/stdio.js

@@ -0,0 +1,108 @@
+// Adapts a subprocess to ACP's framed message streams and drains startup diagnostics.
+import * as acp from '@agentclientprotocol/sdk';
+import { HarnessSdkError, spawnHarnessProcess } from '@anureo/sdk';
+import { StderrTail } from "./diagnostics.js";
+/**
+ * Start the owned stdio channel used by AcpAdapter.initialize when connect is omitted.
+ * Reject with HARNESS_UNAVAILABLE for a missing command or failed spawn. Resolve after spawning
+ * so initialize can negotiate ACP over the returned stream and await channel disposal on teardown.
+ * AcpAdapter.withDiagnostics reads the tail captured so far when annotating handshake or
+ * connection-closure failures.
+ */
+export async function processStream(options) {
+    if (!options.command)
+        throw new HarnessSdkError('HARNESS_UNAVAILABLE', 'An ACP executable or stream factory is required');
+    const child = await spawnHarnessProcess({
+        command: options.command,
+        args: options.args,
+        cwd: options.cwd,
+        env: options.env,
+    });
+    const incoming = framedStdout(child.stdout, options);
+    const outgoing = framedStdin(child, options);
+    const tail = captureStderr(child, options);
+    return {
+        stream: acp.ndJsonStream(outgoing, incoming),
+        dispose: () => child.dispose(),
+        diagnostics: () => tail.text(),
+    };
+}
+/**
+ * Supply ACP's ndJSON decoder with guarded stdout chunks. EOF closes the stream, and read or
+ * limit failures error it. Cancelling calls the stdout iterator's return method when present.
+ * Channel disposal owns child teardown.
+ */
+function framedStdout(stdout, options) {
+    const iterator = stdout[Symbol.asyncIterator]();
+    const checkIncoming = frameGuard(options, 'ACP frame exceeds its limit');
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const value = await iterator.next();
+                if (value.done) {
+                    controller.close();
+                    return;
+                }
+                checkIncoming(value.value);
+                controller.enqueue(value.value);
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        async cancel() { await iterator.return?.(); },
+    });
+}
+/**
+ * Guard bytes from ACP's ndJSON encoder before forwarding them to child stdin. Writes await the
+ * process write callback and propagate limit or pipe failures. Closing ends stdin.
+ */
+function framedStdin(child, options) {
+    const checkOutgoing = frameGuard(options, 'ACP outgoing frame exceeds its limit');
+    return new WritableStream({
+        write(chunk) {
+            checkOutgoing(chunk);
+            return child.write(chunk);
+        },
+        close: () => child.closeInput(),
+    });
+}
+/**
+ * Keep one direction's frame length across chunks, resetting on LF. Throw BACKPRESSURE_EXCEEDED
+ * before the caller forwards a chunk that takes a frame over the limit (8 MiB by default).
+ */
+function frameGuard(options, message) {
+    let lineBytes = 0;
+    return (chunk) => {
+        for (const byte of chunk) {
+            if (byte === 10) {
+                lineBytes = 0;
+            }
+            else if (++lineBytes > (options.maxFrameBytes ?? 8 * 1024 * 1024)) {
+                throw new HarnessSdkError('BACKPRESSURE_EXCEEDED', message);
+            }
+        }
+    };
+}
+/**
+ * Start draining immediately so startup stderr is available even when no ACP frame arrives.
+ * processStream exposes the live tail as channel diagnostics. A pipe read failure ends capture
+ * and flushes buffered text without failing the protocol. Channel disposal does not await the drain.
+ */
+function captureStderr(child, options) {
+    const tail = new StderrTail(options.stderrTailLines ?? 200, options.onStderr);
+    const decoder = new TextDecoder();
+    void (async () => {
+        try {
+            for await (const chunk of child.stderr)
+                tail.write(decoder.decode(chunk, { stream: true }));
+        }
+        catch {
+            // Pipe teardown can race the drain.
+        }
+        finally {
+            tail.flush();
+        }
+    })();
+    return tail;
+}

package/src/stop.d.ts

@@ -0,0 +1,18 @@
+import type { TurnCompletedEvent } from '@anureo/protocol';
+/** Status published in the AHP turn/completed payload. */
+export type TurnStatus = TurnCompletedEvent['payload']['status'];
+/** Internal prompt outcome with the terminal turn status and any preceding warning. */
+export interface StopOutcome {
+    status: TurnStatus;
+    notice?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Classify a prompt stop reason for AcpBackendSession.submitStandardInput, which publishes any
+ * warning before turn/completed. A lookup miss or non-string value yields a failed outcome
+ * with ACP_STOP_UNKNOWN.
+ * Treat returned table entries as read-only because later prompts reuse them.
+ */
+export declare function stopOutcome(stopReason: unknown): StopOutcome;

package/src/stop.js

@@ -0,0 +1,30 @@
+/**
+ * Classify a prompt stop reason for AcpBackendSession.submitStandardInput, which publishes any
+ * warning before turn/completed. A lookup miss or non-string value yields a failed outcome
+ * with ACP_STOP_UNKNOWN.
+ * Treat returned table entries as read-only because later prompts reuse them.
+ */
+export function stopOutcome(stopReason) {
+    const key = typeof stopReason === 'string' ? stopReason : '';
+    return STOP_REASONS[key] ?? {
+        status: 'failed',
+        notice: { code: 'ACP_STOP_UNKNOWN', message: 'Backend stopped for an unclassified reason' },
+    };
+}
+/**
+ * AHP has no truncated status. Limits complete the turn with a warning so observers
+ * can distinguish a response that hit a limit from an ordinary end_turn.
+ */
+const STOP_REASONS = {
+    end_turn: { status: 'completed' },
+    max_tokens: {
+        status: 'completed',
+        notice: { code: 'ACP_STOP_MAX_TOKENS', message: 'Turn ended at the model output limit; the reply may be truncated' },
+    },
+    max_turn_requests: {
+        status: 'completed',
+        notice: { code: 'ACP_STOP_MAX_TURN_REQUESTS', message: 'Turn ended at the agent turn limit' },
+    },
+    cancelled: { status: 'interrupted' },
+    refusal: { status: 'failed' },
+};

package/dist/file-changes.d.ts

@@ -1,3 +0,0 @@
-import type { FileChange } from '@anureo/protocol';
-/** Only ACP's typed diff blocks are source material. Text output is execution output. */
-export declare function acpFileChanges(content: unknown): FileChange[];

package/dist/index.d.ts

@@ -1,98 +0,0 @@
-import * as acp from '@agentclientprotocol/sdk';
-import { type HarnessAdapter, type BackendSession, type SessionEventSink, type SessionMethod } from '@anureo/sdk';
-import { type Capabilities, type SessionBinding, type SessionOpenParams, type SessionState, type InitializeParams, type InitializeResult, type AhpRequestMap, type AhpResultMap, type JsonObject } from '@anureo/protocol';
-export interface AcpFileSystemPort {
-    readTextFile?: (params: acp.ReadTextFileRequest) => Promise<acp.ReadTextFileResponse>;
-    writeTextFile?: (params: acp.WriteTextFileRequest) => Promise<acp.WriteTextFileResponse | void>;
-}
-export interface AcpTerminalPort {
-    createTerminal(params: acp.CreateTerminalRequest): Promise<acp.CreateTerminalResponse>;
-    terminalOutput(params: acp.TerminalOutputRequest): Promise<acp.TerminalOutputResponse>;
-    releaseTerminal(params: acp.ReleaseTerminalRequest): Promise<acp.ReleaseTerminalResponse | void>;
-    waitForTerminalExit(params: acp.WaitForTerminalExitRequest): Promise<acp.WaitForTerminalExitResponse>;
-    killTerminal(params: acp.KillTerminalRequest): Promise<acp.KillTerminalResponse | void>;
-}
-export interface AcpAdapterOptions {
-    command?: string;
-    args?: readonly string[];
-    cwd?: string;
-    env?: Record<string, string | undefined>;
-    fs?: AcpFileSystemPort;
-    terminal?: AcpTerminalPort;
-    /** Inject an official v1 message stream for remote transports or deterministic wire tests. */
-    connect?: () => Promise<{
-        stream: acp.Stream;
-        dispose(): Promise<void>;
-    }>;
-    requestTimeoutMs?: number;
-    maxFrameBytes?: number;
-    /** session/load snapshots have no turn boundaries; expose them separately from AHP realtime events. */
-    onLoadSnapshot?: (binding: SessionBinding, updates: readonly JsonObject[]) => void;
-}
-type ExtensionKey = 'fork' | 'revert' | 'steer' | 'history' | 'goalSet' | 'goalClear' | 'compact' | 'review';
-interface Extensions {
-    methods: Partial<Record<ExtensionKey, string>>;
-    fork: Array<'before' | 'through'>;
-    revert: Array<'conversation' | 'files' | 'both'>;
-    subagents: boolean;
-    instructions: boolean;
-    userInput: boolean;
-    dynamicTool: boolean;
-}
-export declare class AcpAdapter implements HarnessAdapter {
-    readonly options: AcpAdapterOptions;
-    private connection;
-    private channel;
-    private info;
-    readonly sessions: Map<string, AcpBackendSession>;
-    private nativeSessions;
-    private opening;
-    private openTail;
-    private readonly deliveries;
-    private closing;
-    extension: Extensions;
-    capabilities: Capabilities;
-    constructor(options: AcpAdapterOptions);
-    get nativeCapabilities(): acp.AgentCapabilities;
-    get agent(): acp.ClientContext;
-    private backend;
-    private interaction;
-    initialize(params: InitializeParams): Promise<InitializeResult>;
-    private runtime;
-    call<M extends acp.AgentRequestMethod>(method: M, params: acp.AgentRequestParamsByMethod[M]): Promise<acp.AgentRequestResponsesByMethod[M]>;
-    call(method: string, params: unknown): Promise<unknown>;
-    private extensionInteraction;
-    openSession(params: SessionOpenParams, sink: SessionEventSink): Promise<BackendSession>;
-    dispose(): Promise<void>;
-}
-export declare class AcpBackendSession implements BackendSession {
-    readonly adapter: AcpAdapter;
-    private readonly params;
-    readonly sink: SessionEventSink;
-    nativeId: string;
-    activeTurn: string | undefined;
-    hydrating: boolean;
-    readonly loadedSnapshot: JsonObject[];
-    readonly terminals: Set<string>;
-    readonly capabilities: Capabilities;
-    private config;
-    private configKeys;
-    private configurationData;
-    private capabilityRevision;
-    private sessionTitle?;
-    private closed;
-    private readonly mapper;
-    private snapshotBytes;
-    constructor(adapter: AcpAdapter, params: SessionOpenParams, sink: SessionEventSink);
-    get binding(): SessionBinding;
-    state(): SessionState;
-    configure(data: Record<string, unknown>): void;
-    update(data: Record<string, unknown>): Promise<void>;
-    requireTerminal(id: string): void;
-    setConfiguration(patch: JsonObject): Promise<SessionState>;
-    private extension;
-    execute<M extends SessionMethod>(method: M, params: AhpRequestMap[M]): Promise<AhpResultMap[M]>;
-    dispose(): Promise<void>;
-}
-export declare function createAcpAdapter(options: AcpAdapterOptions): AcpAdapter;
-export {};