@sweny-ai/core 0.1.132 → 0.1.134

package/dist/harness/claude-code.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Claude Client - Headless Claude Code backend
+ *
+ * Uses the @anthropic-ai/claude-agent-sdk to run headless Claude Code
+ * as the LLM backend. Tools are exposed via an in-process MCP server
+ * that Claude Code calls during execution.
+ *
+ * This is the ONLY supported LLM backend. The whole point of sweny
+ * is to use headless Claude Code - never the raw Anthropic API.
+ */
+import type { Claude, ToolContext, Logger, McpServerConfig } from "../types.js";
+import { type SandboxMode } from "../agent-env.js";
+import type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessInfo, HarnessRunRequest, HarnessRunResult } from "./types.js";
+import { CLAUDE_CODE_CAPABILITIES } from "./capabilities.js";
+import { buildEvaluatePrompt } from "./prompts.js";
+export { buildEvaluatePrompt, CLAUDE_CODE_CAPABILITIES };
+/**
+ * Built-in tools disallowed for the route-evaluation (`evaluate`) and
+ * reflection/judge (`ask`) calls.
+ *
+ * These are pure classification calls over prior-node data that can be
+ * attacker-influenceable (a prior node summarizes an untrusted issue body,
+ * PR diff, log line, etc.). They must never be able to mutate the workspace
+ * or shell out, regardless of any node's own `disallowed_tools` policy.
+ * `maxTurns: 1` already bounds them; this removes the powerful built-ins
+ * from the model's context entirely as structural defense-in-depth.
+ */
+export declare const CLASSIFICATION_DISALLOWED_TOOLS: readonly ["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit", "WebFetch", "WebSearch"];
+/**
+ * Built-in tools disallowed for a node run with `readOnly: true` (dry run,
+ * #380): everything that can edit the workspace, shell out (and so reach
+ * `gh`, `curl`, `git push`), spawn a subagent that could, or fetch an
+ * arbitrary URL (a GET can still trigger a webhook or exfiltrate data).
+ * Read, Grep, Glob and WebSearch stay available for analysis.
+ */
+export declare const READ_ONLY_DISALLOWED_TOOLS: readonly ["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit", "Task", "Agent", "WebFetch"];
+/** How sweny resolves which credentials reach the Claude Code subprocess. */
+export type SwenyAuthMode = "auto" | "api-key" | "oauth";
+export interface ResolveAuthEnvOpts {
+    /** Explicit override; when absent, read from `env.SWENY_AUTH`. Test seam. */
+    mode?: SwenyAuthMode;
+    /** Logger for the debug line + invalid-value warning. */
+    logger?: Pick<Logger, "debug" | "warn">;
+}
+/**
+ * Decide which auth credentials survive into the Claude Code subprocess env.
+ *
+ * sweny does not select the winning credential (the spawned agent and any
+ * on-disk `~/.claude/.credentials.json` do that). This function only controls
+ * what is *present* in the env we hand the agent.
+ *
+ * Modes (`SWENY_AUTH`, default `auto`):
+ *  - `auto`    - today's protective behavior: when an OAuth token is present,
+ *                strip `ANTHROPIC_API_KEY` so a stray `.env` key cannot
+ *                silently bill a metered API account. `ANTHROPIC_AUTH_TOKEN`
+ *                (a bearer token, not a console key) is never touched.
+ *  - `api-key` - user explicitly authenticates a gateway with a key/bearer:
+ *                preserve both even when an OAuth token is also present.
+ *  - `oauth`   - user explicitly wants subscription/OAuth: strip both
+ *                `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` so a leftover
+ *                credential cannot win at the agent. Fails closed.
+ *
+ * Base-URL presence is deliberately NOT a signal here: pass-through proxies
+ * (corporate egress, observability) set `ANTHROPIC_BASE_URL` while still
+ * billing the real key, so inferring "use the key" from a base URL would
+ * re-introduce a surprise-billing path. Intent must be explicit.
+ *
+ * An unrecognized `SWENY_AUTH` value falls back to `auto` with a warning
+ * (never throws - an env typo must not crash a CI run).
+ *
+ * Pure: returns a copy, never mutates the input.
+ */
+export declare function resolveAuthEnv(env: Record<string, string>, opts?: ResolveAuthEnvOpts): Record<string, string>;
+export interface ClaudeCodeHarnessOptions {
+    /** Model override */
+    model?: string;
+    /** Max turns for tool use loop (default: 20) */
+    maxTurns?: number;
+    /** Working directory for Claude Code (default: process.cwd()) */
+    cwd?: string;
+    /** Logger */
+    logger?: Logger;
+    /** Default tool context for standalone usage (not via 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 to the agent subprocess on top of the
+     * allowlist (see agent-env.ts). `"*"` inherits the full environment.
+     * Default: `SWENY_ENV_PASSTHROUGH` (comma-separated).
+     */
+    envPassthrough?: string[];
+    /**
+     * Scope the agent env to the allowlist. Default: `SWENY_ENV_SCOPE`, else on
+     * when CI is truthy and off locally (full env).
+     */
+    envScope?: boolean;
+    /**
+     * SDK sandbox for agent commands: `auto` (sandbox when the host supports
+     * it, else warn and run unsandboxed), `strict` (sandbox or fail), `off`.
+     * Default: `SWENY_SANDBOX`, else `auto` when CI is truthy, `off` otherwise.
+     */
+    sandbox?: SandboxMode;
+    /** Extra hosts sandboxed commands may reach. Default: `SWENY_SANDBOX_ALLOWED_DOMAINS`. */
+    sandboxAllowedDomains?: string[];
+    /** Sandbox preflight probe (test seam). Returns a reason when the sandbox cannot run. */
+    sandboxProbe?: () => string | undefined;
+}
+/**
+ * Wire an optional timeout + caller signal onto a single AbortController.
+ *
+ * Returns undefined when neither a timeout nor a signal is supplied so the
+ * default code path (no abortController, no timer) is byte-for-byte unchanged.
+ *
+ * `reason()` reports whether the abort came from the timeout timer or an
+ * external signal, so callers can log a distinct timeout message.
+ */
+export declare function makeAbort(timeoutMs?: number, signal?: AbortSignal): {
+    controller: AbortController;
+    clear: () => void;
+    reason: () => "timeout" | "signal" | undefined;
+} | undefined;
+export declare class ClaudeCodeHarness implements Claude, AgentHarness {
+    readonly id: "claude-code";
+    readonly capabilities: HarnessCapabilities;
+    readonly defaultJudgeModel = "claude-haiku-4-5";
+    private model;
+    private maxTurns;
+    private cwd;
+    readonly logger: Logger;
+    private defaultContext;
+    private mcpServers;
+    private defaultMcpServers;
+    private envPassthrough;
+    private sandboxMode;
+    private sandboxAllowedDomains;
+    private sandboxProbe;
+    private sandboxWarned;
+    private envScope;
+    constructor(opts?: ClaudeCodeHarnessOptions);
+    /**
+     * Build env for the Claude Code subprocess (#360). Applies auth precedence
+     * via {@link resolveAuthEnv} on the full process env (it reads
+     * `SWENY_AUTH`). When env scoping is on (default in CI, see
+     * {@link resolveEnvScope}) the result is narrowed to the allowlist plus
+     * `extraVars` (the node's declared skill env vars) and the operator
+     * passthrough list, and the withheld names (never values) are reported once
+     * per process ({@link reportWithheldEnv}). When off, the full env passes through as before.
+     */
+    private buildEnv;
+    /** Which harness (and SDK version) produced a result. */
+    info(): HarnessInfo;
+    preflight(): Promise<{
+        ok: true;
+        version: string;
+    }>;
+    /**
+     * Run a node. The query itself is unchanged by the harness seam; this only
+     * runs {@link policyGate} (always `degraded: []` for Claude Code) and tags
+     * the result with the harness id and version.
+     */
+    run(req: HarnessRunRequest): Promise<HarnessRunResult>;
+    private runQuery;
+    /**
+     * Single completion: no tools, no MCP, one turn. Shared by core `ask()`
+     * (retry reflection, judge scoring) and `evaluate()` (route choice); the
+     * query options are the ones `ask` and `evaluate` used before the seam.
+     * Returns null when the query failed (SDK error, timeout, non-success
+     * subtype); callers fail closed.
+     */
+    complete(req: HarnessCompleteRequest): Promise<string | null>;
+    /** Route evaluation. Delegates to core {@link coreEvaluate} over {@link complete}. */
+    evaluate(opts: {
+        question: string;
+        context: Record<string, unknown>;
+        choices: {
+            id: string;
+            description: string;
+        }[];
+        /** Abort the query after this many ms. Default: no timeout (back-compat). */
+        timeoutMs?: number;
+        /** Caller-supplied abort signal. Aborting it interrupts the query. */
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    /** Free-text completion. Delegates to core {@link coreAsk} over {@link complete}. */
+    ask(opts: {
+        instruction: string;
+        context: Record<string, unknown>;
+        model?: string;
+        /** Abort the query after this many ms. Default: no timeout (back-compat). */
+        timeoutMs?: number;
+        /** Caller-supplied abort signal. Aborting it interrupts the query. */
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+/** @deprecated Use {@link ClaudeCodeHarnessOptions}. */
+export type ClaudeClientOptions = ClaudeCodeHarnessOptions;
+/** @deprecated Use {@link ClaudeCodeHarness} (or `createHarness("claude-code")`). */
+export declare const ClaudeClient: typeof ClaudeCodeHarness;
+/** @deprecated Use {@link ClaudeCodeHarness}. */
+export type ClaudeClient = ClaudeCodeHarness;
+/**
+ * Best-effort recovery of typed output from a tool_result's `content`.
+ *
+ * The MCP protocol sends tool results as string content. Our in-process
+ * wrapper JSON-stringifies structured output before returning; external
+ * MCP servers generally do the same for JSON payloads. If the string
+ * looks like a JSON object or array and parses, return the parsed value
+ * so verify's output-path walks work against typed data.
+ *
+ * Raw strings are preserved verbatim. JSON-primitive strings (e.g. the
+ * literal four characters `"42"`) are intentionally NOT parsed - we
+ * cannot distinguish a tool that returned the number 42 (wrapper sends
+ * `"42"`) from a tool that returned the string "42" (wrapper also sends
+ * `"42"`). Preserving the string is safer than guessing.
+ */
+export declare function parseToolResultContent(content: unknown): unknown;
+/**
+ * Produce a short, single-line description of a tool-error payload suitable
+ * for the CI log stream. The full parsed value stays on the ToolCall for
+ * verify and downstream tooling - this is only for inline observability.
+ *
+ * Collapses newlines, trims whitespace, and caps to 300 chars so a huge
+ * API response body doesn't flood the log.
+ */
+export declare function summarizeToolError(parsed: unknown): string;