vally-claudecodecli 0.0.0-stage → 0.1.0

package/dist/config.js

@@ -0,0 +1,287 @@
+export const PERMISSION_MODES = [
+    "acceptEdits",
+    "auto",
+    "bypassPermissions",
+    "dontAsk",
+    "manual",
+    "plan",
+];
+export const SETTING_SOURCES = ["user", "project", "local"];
+export const PROVIDER_TYPES = ["anthropic", "bedrock", "vertex", "foundry"];
+const LABEL = "defaults.executor.config";
+/** Flags the executor sets itself; passing them through `extraArgs` would break the protocol. */
+export const MANAGED_FLAGS = new Set([
+    "-p",
+    "--print",
+    "--output-format",
+    "--input-format",
+    "--verbose",
+    "--replay-user-messages",
+    "--include-partial-messages",
+    "--mcp-config",
+    "--strict-mcp-config",
+    "--permission-mode",
+    "--dangerously-skip-permissions",
+    "--model",
+    "--effort",
+    "--resume",
+    "-r",
+    "--continue",
+    "-c",
+    "--session-id",
+    "--no-session-persistence",
+    "--settings",
+    "--setting-sources",
+    "--add-dir",
+    "--allowedTools",
+    "--allowed-tools",
+    "--disallowedTools",
+    "--disallowed-tools",
+    "--append-system-prompt",
+    "--system-prompt",
+    "--max-budget-usd",
+    "--fallback-model",
+]);
+const CONFIG_KEYS = new Set([
+    "claudePath",
+    "permissionMode",
+    "settingSources",
+    "allowedTools",
+    "disallowedTools",
+    "appendSystemPrompt",
+    "systemPrompt",
+    "maxBudgetUsd",
+    "fallbackModel",
+    "extraArgs",
+    "provider",
+]);
+const PROVIDER_KEYS = new Set([
+    "type",
+    "baseUrl",
+    "apiKeyEnv",
+    "bearerTokenEnv",
+    "headers",
+    "region",
+    "projectId",
+    "resource",
+]);
+const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function assertString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+}
+function assertStringArray(value, field, allowEmpty = true) {
+    if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) {
+        throw new Error(`${field} must be ${allowEmpty ? "an" : "a non-empty"} array of strings`);
+    }
+    for (const item of value)
+        assertString(item, `${field}[]`);
+}
+function assertEnvName(value, field) {
+    if (typeof value !== "string" || !ENV_VAR_NAME.test(value)) {
+        throw new Error(`${field} must be the name of an environment variable`);
+    }
+}
+function assertUrl(value, field) {
+    assertString(value, field);
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${field} must be an absolute http(s) URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`${field} must be an absolute http(s) URL`);
+    }
+}
+function validateProvider(value, label) {
+    if (!isRecord(value))
+        throw new Error(`${label} must be a mapping, got ${describe(value)}`);
+    for (const key of Object.keys(value)) {
+        if (!PROVIDER_KEYS.has(key)) {
+            throw new Error(`${label} has unknown field '${key}' (allowed: ${[...PROVIDER_KEYS].join(", ")})`);
+        }
+    }
+    const type = (value.type ?? "anthropic");
+    if (!PROVIDER_TYPES.includes(type)) {
+        throw new Error(`${label}.type must be one of: ${PROVIDER_TYPES.join(", ")}`);
+    }
+    if (value.baseUrl !== undefined)
+        assertUrl(value.baseUrl, `${label}.baseUrl`);
+    if (value.apiKeyEnv !== undefined)
+        assertEnvName(value.apiKeyEnv, `${label}.apiKeyEnv`);
+    if (value.bearerTokenEnv !== undefined)
+        assertEnvName(value.bearerTokenEnv, `${label}.bearerTokenEnv`);
+    for (const field of ["region", "projectId", "resource"]) {
+        if (value[field] !== undefined)
+            assertString(value[field], `${label}.${field}`);
+    }
+    if (value.headers !== undefined) {
+        if (!isRecord(value.headers))
+            throw new Error(`${label}.headers must be a mapping of header names to values`);
+        for (const [name, header] of Object.entries(value.headers)) {
+            if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name))
+                throw new Error(`${label}.headers has an invalid header name '${name}'`);
+            if (typeof header !== "string" || /[\r\n]/.test(header)) {
+                throw new Error(`${label}.headers.${name} must be a single-line string`);
+            }
+        }
+    }
+    const allowed = {
+        anthropic: ["baseUrl", "apiKeyEnv", "bearerTokenEnv", "headers"],
+        bedrock: ["baseUrl", "apiKeyEnv", "region"],
+        vertex: ["baseUrl", "region", "projectId"],
+        foundry: ["baseUrl", "apiKeyEnv", "resource"],
+    };
+    for (const key of Object.keys(value)) {
+        if (key !== "type" && !allowed[type].includes(key)) {
+            throw new Error(`${label}.${key} is not supported for provider type '${type}'`);
+        }
+    }
+    if (type === "foundry" && value.baseUrl === undefined && value.resource === undefined) {
+        throw new Error(`${label} with type 'foundry' requires either 'resource' or 'baseUrl'`);
+    }
+    return { ...value, type };
+}
+/** Parses and validates `defaults.executor.config`. Throws actionable errors. */
+export function parseConfig(value, label = LABEL) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        throw new Error(`${label} must be a mapping, got ${describe(value)}`);
+    for (const key of Object.keys(value)) {
+        if (!CONFIG_KEYS.has(key)) {
+            throw new Error(`${label} has unknown field '${key}' (allowed: ${[...CONFIG_KEYS].join(", ")})`);
+        }
+    }
+    for (const field of ["claudePath", "appendSystemPrompt", "systemPrompt", "fallbackModel"]) {
+        if (value[field] !== undefined)
+            assertString(value[field], `${label}.${field}`);
+    }
+    if (value.permissionMode !== undefined && !PERMISSION_MODES.includes(value.permissionMode)) {
+        throw new Error(`${label}.permissionMode must be one of: ${PERMISSION_MODES.join(", ")}`);
+    }
+    if (value.settingSources !== undefined) {
+        if (!Array.isArray(value.settingSources))
+            throw new Error(`${label}.settingSources must be an array`);
+        for (const source of value.settingSources) {
+            if (!SETTING_SOURCES.includes(source)) {
+                throw new Error(`${label}.settingSources entries must be one of: ${SETTING_SOURCES.join(", ")}`);
+            }
+        }
+    }
+    for (const field of ["allowedTools", "disallowedTools"]) {
+        if (value[field] !== undefined)
+            assertStringArray(value[field], `${label}.${field}`, false);
+    }
+    if (value.maxBudgetUsd !== undefined &&
+        (typeof value.maxBudgetUsd !== "number" || !Number.isFinite(value.maxBudgetUsd) || value.maxBudgetUsd <= 0)) {
+        throw new Error(`${label}.maxBudgetUsd must be a positive number`);
+    }
+    if (value.extraArgs !== undefined) {
+        if (!Array.isArray(value.extraArgs) || value.extraArgs.some((arg) => typeof arg !== "string")) {
+            throw new Error(`${label}.extraArgs must be an array of strings`);
+        }
+        for (const arg of value.extraArgs) {
+            const flag = arg.split("=", 1)[0];
+            if (MANAGED_FLAGS.has(flag)) {
+                throw new Error(`${label}.extraArgs must not contain '${flag}': the executor manages it`);
+            }
+        }
+    }
+    const provider = value.provider !== undefined ? validateProvider(value.provider, `${label}.provider`) : undefined;
+    return { ...value, ...(provider && { provider }) };
+}
+/** Env vars that select or authenticate a model provider; cleared when a provider is configured. */
+const PROVIDER_ENV_VARS = [
+    "CLAUDE_CODE_USE_BEDROCK",
+    "CLAUDE_CODE_USE_VERTEX",
+    "CLAUDE_CODE_USE_FOUNDRY",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_CUSTOM_HEADERS",
+    "ANTHROPIC_BEDROCK_BASE_URL",
+    "AWS_BEARER_TOKEN_BEDROCK",
+    "ANTHROPIC_VERTEX_BASE_URL",
+    "ANTHROPIC_VERTEX_PROJECT_ID",
+    "ANTHROPIC_FOUNDRY_BASE_URL",
+    "ANTHROPIC_FOUNDRY_RESOURCE",
+    "ANTHROPIC_FOUNDRY_API_KEY",
+];
+function readRequiredEnv(name, field, env) {
+    const value = env[name];
+    if (value === undefined || value.length === 0) {
+        throw new Error(`${field} references environment variable '${name}', which is not set`);
+    }
+    return value;
+}
+/**
+ * Maps a provider config to Claude Code environment variables, resolving the
+ * referenced credentials from `env` (the Vally process environment).
+ */
+export function providerEnv(provider, env = process.env, label = `${LABEL}.provider`) {
+    const set = {};
+    const secrets = [];
+    const secret = (name, field) => {
+        const value = readRequiredEnv(name, `${label}.${field}`, env);
+        secrets.push(value);
+        return value;
+    };
+    switch (provider.type ?? "anthropic") {
+        case "anthropic":
+            if (provider.baseUrl)
+                set.ANTHROPIC_BASE_URL = provider.baseUrl;
+            // Claude Code prefers ANTHROPIC_AUTH_TOKEN over ANTHROPIC_API_KEY, so a bearer token wins.
+            if (provider.bearerTokenEnv)
+                set.ANTHROPIC_AUTH_TOKEN = secret(provider.bearerTokenEnv, "bearerTokenEnv");
+            else if (provider.apiKeyEnv)
+                set.ANTHROPIC_API_KEY = secret(provider.apiKeyEnv, "apiKeyEnv");
+            if (provider.headers && Object.keys(provider.headers).length > 0) {
+                set.ANTHROPIC_CUSTOM_HEADERS = Object.entries(provider.headers)
+                    .map(([name, value]) => `${name}: ${value}`)
+                    .join("\n");
+            }
+            break;
+        case "bedrock":
+            set.CLAUDE_CODE_USE_BEDROCK = "1";
+            if (provider.baseUrl)
+                set.ANTHROPIC_BEDROCK_BASE_URL = provider.baseUrl;
+            if (provider.apiKeyEnv)
+                set.AWS_BEARER_TOKEN_BEDROCK = secret(provider.apiKeyEnv, "apiKeyEnv");
+            if (provider.region)
+                set.AWS_REGION = provider.region;
+            break;
+        case "vertex":
+            set.CLAUDE_CODE_USE_VERTEX = "1";
+            if (provider.baseUrl)
+                set.ANTHROPIC_VERTEX_BASE_URL = provider.baseUrl;
+            if (provider.region)
+                set.CLOUD_ML_REGION = provider.region;
+            if (provider.projectId)
+                set.ANTHROPIC_VERTEX_PROJECT_ID = provider.projectId;
+            break;
+        case "foundry":
+            set.CLAUDE_CODE_USE_FOUNDRY = "1";
+            if (provider.baseUrl)
+                set.ANTHROPIC_FOUNDRY_BASE_URL = provider.baseUrl;
+            if (provider.resource)
+                set.ANTHROPIC_FOUNDRY_RESOURCE = provider.resource;
+            if (provider.apiKeyEnv)
+                set.ANTHROPIC_FOUNDRY_API_KEY = secret(provider.apiKeyEnv, "apiKeyEnv");
+            break;
+    }
+    return { set, unset: PROVIDER_ENV_VARS.filter((name) => !(name in set)), secrets };
+}

package/dist/executor.d.ts

@@ -0,0 +1,31 @@
+import type { Executor, ExecutorOptions, Stimulus, Trajectory } from "@microsoft/vally";
+import { type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from "node:child_process";
+import { type ProviderEnv } from "./config.js";
+export declare const EXECUTOR_NAME = "claude-code-cli";
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptionsWithoutStdio) => ChildProcessWithoutNullStreams;
+export interface ClaudeCodeExecutorOptions {
+    /** Replaces `child_process.spawn`, e.g. to run a fake Claude Code in tests. */
+    spawn?: SpawnFn;
+    /** Path to the compiled simulation hook script. */
+    hookScript?: string;
+    cleanupTimeoutMs?: number;
+}
+/** Runs prompts through the Claude Code CLI (`claude -p`) and returns Vally trajectories. */
+export declare class ClaudeCodeExecutor implements Executor {
+    readonly name = "claude-code-cli";
+    readonly supportsPreparedWorkspace = true;
+    readonly supportsMultiTurn = true;
+    readonly supportsTurnCompletion = true;
+    readonly supportsSimulation = true;
+    readonly supportsAttachments = true;
+    readonly supportsEnvVars = true;
+    private readonly active;
+    private readonly spawn;
+    private readonly hookScript;
+    private readonly cleanupTimeoutMs;
+    constructor(options?: ClaudeCodeExecutorOptions);
+    validateConfig(config: unknown): void;
+    shutdown(): Promise<void>;
+    execute(stimulus: Stimulus, options: ExecutorOptions): Promise<Trajectory>;
+}
+export declare function buildEnv(options: Pick<ExecutorOptions, "env" | "traceContext">, provider?: ProviderEnv): Record<string, string>;