@sweny-ai/core 0.1.148 → 0.1.150

package/dist/harness/acp.d.ts

@@ -0,0 +1,189 @@
+/**
+ * ACP harness (#416): runs a node on any Agent Client Protocol agent
+ * (`--agent acp:<command>`, for example `acp:opencode acp`,
+ * `acp:hermes acp`, `acp:goose acp`, `acp:gemini --experimental-acp`).
+ *
+ * ACP is the long-tail adapter. It is JSON-RPC 2.0 over the agent's stdio and
+ * carries a prompt and a stream of updates; it does not carry sweny's
+ * opinions. Read from agentclientprotocol/agent-client-protocol at tag
+ * schema-v1.24.1 (`schema/v1/schema.json`, `docs/protocol/v1/*.mdx`):
+ * - transports: newline-delimited JSON over stdio (`transports.mdx`).
+ * - `initialize` negotiates `protocolVersion` (1) and capabilities
+ *   (`initialization.mdx`); `InitializeRequest` / `InitializeResponse`.
+ * - `session/new {cwd, mcpServers}` returns `{sessionId}`; every agent MUST
+ *   support stdio MCP servers, http and sse are optional
+ *   (`session-setup.mdx`, `McpServerStdio`, `McpServerHttp`).
+ * - `session/prompt {sessionId, prompt: ContentBlock[]}` streams
+ *   `session/update` notifications (`agent_message_chunk`, `tool_call`,
+ *   `tool_call_update`, `usage_update`, ...) and ends with
+ *   `{stopReason}`; `PromptResponse` has no other field (`prompt-turn.mdx`).
+ * - `session/cancel` (notification) ends a turn with stopReason `cancelled`
+ *   (`prompt-turn.mdx`, Cancellation); pending permission requests get the
+ *   `cancelled` outcome.
+ * - `session/request_permission {toolCall, options}` is how an agent MAY ask
+ *   before a tool runs; the client picks an option or answers `cancelled`
+ *   (`tool-calls.mdx`, `RequestPermissionResponse`).
+ * - `fs/read_text_file` and `fs/write_text_file` are client methods an agent
+ *   may use only when the client advertised them (`file-system.mdx`).
+ *
+ * Every sweny opinion is enforced by sweny here, refused or reported as
+ * `degraded` by `policyGate` (see ACP_CAPABILITIES for the honest list):
+ * - Structured output: the schema rides in the prompt; sweny parses the last
+ *   JSON object, checks it and asks once more before giving up.
+ * - Tool deny and read-only: best effort through `session/request_permission`
+ *   (denied classes and every non-read tool under `readOnly` are rejected),
+ *   plus a refusal of every `fs/write_text_file`. The protocol has no deny list
+ *   and an agent that does not ask is not stopped, so `policyGate` still
+ *   reports deny and read-only as unenforced; strict refuses the node unless
+ *   the process wrapper provides the read-only mount.
+ * - Sandbox and egress: none in the protocol. The whole agent process runs
+ *   inside the sandbox wrapper (sandbox-wrapper.ts); strict refuses without it.
+ * - Env: sweny spawns the agent with the scoped env (agent-env.ts).
+ * - Skill tools: passed in `session/new` as the stdio MCP server of the tool
+ *   bridge (#414), so the executor still observes every call.
+ * - Turn limit: a watchdog counts tool calls and cancels past the budget.
+ * - Timeout: `session/cancel`, a grace period, then the process is killed.
+ */
+import type { Logger, McpServerConfig, ToolContext } from "../types.js";
+import { type SandboxMode } from "../agent-env.js";
+import type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessId, HarnessInfo, HarnessRunRequest, HarnessRunResult, ToolClass } from "./types.js";
+import { ACP_CAPABILITIES } from "./capabilities.js";
+import { type HarnessPolicyMode } from "./policy.js";
+import { type SandboxWrapper } from "./sandbox-wrapper.js";
+export { ACP_CAPABILITIES };
+/** The ACP major version sweny speaks (`InitializeRequest.protocolVersion`). */
+export declare const ACP_PROTOCOL_VERSION = 1;
+export interface AcpHarnessOptions {
+    /**
+     * The agent to run: a command line (`"opencode acp"`, the part after `acp:`)
+     * or an explicit `{command, args}`. Never run through a shell.
+     */
+    acpCommand?: string | {
+        command: string;
+        args: string[];
+    };
+    /** Tool-call budget the watchdog enforces when a node sets no `max_turns` (default: 20). */
+    maxTurns?: number;
+    /** Working directory (default: process.cwd()). */
+    cwd?: string;
+    logger?: Logger;
+    /** Default tool context for standalone usage (not via the executor). */
+    defaultContext?: ToolContext;
+    /** Catalog defaults, overridden by per-run skill servers and explicit mcpServers. */
+    defaultMcpServers?: Record<string, McpServerConfig>;
+    /** Explicit external MCP servers, overriding defaults and per-run skill servers. */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** Extra env var names passed through (see agent-env.ts). Default: `SWENY_ENV_PASSTHROUGH`. */
+    envPassthrough?: string[];
+    /** The agent's own auth env var names, always passed through when scoping (none are assumed). */
+    authVars?: string[];
+    /** Scope the agent env to the allowlist. Default: `SWENY_ENV_SCOPE`, else on in CI. */
+    envScope?: boolean;
+    /** Process sandbox mode. Default: `SWENY_SANDBOX`, else `auto` in CI and `off` locally. */
+    sandbox?: SandboxMode;
+    /** The host's process sandbox wrapper (#360 step 2). `undefined` = detect srt once per process; `null` = none (test seam). */
+    sandboxWrapper?: SandboxWrapper | null;
+    /** `strict` refuses a node with unenforceable opinions. Default: {@link resolveHarnessPolicy}. */
+    policy?: HarnessPolicyMode;
+    /** Hosts the agent itself needs (its model API), allowed through the sandbox wrapper. */
+    egress?: string[];
+    /** Shim command override for the tool bridge (test seam). */
+    toolBridgeShim?: {
+        command: string;
+        args: string[];
+    };
+    /** Grace period between SIGTERM and SIGKILL, and for the agent to exit on its own (default: 2000 ms). */
+    killGraceMs?: number;
+    /** How long the agent gets to answer `session/cancel` before it is killed (default: 5000 ms). */
+    cancelGraceMs?: number;
+    /** How long `initialize` and `session/new` may take (default: 60000 ms). */
+    startupTimeoutMs?: number;
+}
+/** Portable tool classes an ACP tool call can be, from its `kind` (schema `ToolKind`) and name. */
+export declare function classifyAcpTool(kind: string | null | undefined, name: string | null | undefined): {
+    classes: ToolClass[];
+    readOnlySafe: boolean;
+};
+/** Does this tool call name one of sweny's skill tools (they reach the agent as MCP tools of the tool bridge)? */
+export declare function isSkillToolCall(names: readonly (string | null | undefined)[], skillTools: readonly string[]): boolean;
+interface PermissionOption {
+    optionId: string;
+    kind: string;
+}
+/** The permission outcome for an option list: the first option of a wanted kind, else `cancelled`. */
+export declare function pickPermissionOutcome(options: readonly PermissionOption[], allow: boolean): {
+    outcome: "selected";
+    optionId: string;
+} | {
+    outcome: "cancelled";
+};
+/** A loosely typed JSON object, for reading what the agent sends. */
+type Obj = Record<string, any>;
+/** `McpServerConfig` map to the ACP `mcpServers` array (schema `McpServer`). Returns what the agent cannot load too. */
+export declare function toAcpMcpServers(servers: Record<string, McpServerConfig>, agentHttp: boolean): {
+    list: Obj[];
+    unsupported: string[];
+};
+export declare class AcpHarness implements AgentHarness {
+    readonly id: HarnessId;
+    readonly capabilities: HarnessCapabilities;
+    /** Empty on purpose: judges use the agent's own default model. */
+    readonly defaultJudgeModel = "";
+    readonly logger: Logger;
+    private agent;
+    private maxTurns;
+    private cwd;
+    private defaultContext;
+    private mcpServers;
+    private defaultMcpServers;
+    private envPassthrough;
+    private authVars;
+    private envScope;
+    private sandboxMode;
+    private sandboxWrapper;
+    private policyMode;
+    private egress;
+    private toolBridgeShim;
+    private killGraceMs;
+    private cancelGraceMs;
+    private startupTimeoutMs;
+    private agentVersion;
+    constructor(opts?: AcpHarnessOptions);
+    info(): HarnessInfo;
+    /**
+     * Is the agent command there? Deliberately does not start it: it would run
+     * outside the sandbox wrapper. The version comes from `initialize` on the
+     * first run (`agentInfo.version`).
+     */
+    preflight(): Promise<{
+        ok: true;
+        version: string;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Env for the agent process: scoped like Claude Code's, with only the auth vars the operator named. */
+    private buildEnv;
+    /** The node policy, with the harness policy mode and the watchdog budget applied. */
+    private compilePolicy;
+    /**
+     * Talk to one agent process from `initialize` to the last `session/prompt`
+     * response, then stop it. Never throws: every failure is on the result.
+     */
+    private converse;
+    /**
+     * Run a node. The gate runs first: in strict mode a node whose opinions an
+     * ACP agent cannot honor is refused before the agent starts. The agent
+     * process runs inside the host's sandbox wrapper (#360 step 2) when the
+     * sandbox mode asks for one and the host has one.
+     */
+    run(req: HarnessRunRequest): Promise<HarnessRunResult>;
+    /** Map one conversation onto a NodeResult with Claude Code's semantics. */
+    private toResult;
+    /**
+     * One completion: a fresh session with no MCP servers, every permission
+     * request rejected, and any tool call over budget. null when it failed
+     * (callers fail closed).
+     */
+    complete(req: HarnessCompleteRequest): Promise<string | null>;
+}