@wix/pathgrade 0.29.0

package/dist/utils/llm-mocks.js

@@ -0,0 +1,108 @@
+function isToolResponse(r) {
+    return typeof r === 'object' && 'kind' in r;
+}
+function isThrowResponse(r) {
+    return typeof r === 'object' && 'throws' in r;
+}
+export function createMockLLM(opts = {}) {
+    const queue = [...(opts.responses ?? [])];
+    const calls = [];
+    const toolCalls = [];
+    const defaultResponse = opts.defaultResponse;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let costUsd = 0;
+    let callCount = 0;
+    const take = () => {
+        callCount++;
+        const r = queue.shift();
+        if (r !== undefined)
+            return r;
+        if (defaultResponse !== undefined)
+            return defaultResponse;
+        throw new Error(`createMockLLM: out of responses (call #${callCount})`);
+    };
+    const port = {
+        get tokenUsage() {
+            return { inputTokens, outputTokens };
+        },
+        get costUsd() {
+            return costUsd;
+        },
+        get supportsToolUse() {
+            return true;
+        },
+        get lastProvider() {
+            return 'mock';
+        },
+        addTokens(input, output) {
+            inputTokens += input;
+            outputTokens += output;
+        },
+        addCost(usd) {
+            if (!Number.isFinite(usd) || usd < 0)
+                return;
+            costUsd += usd;
+        },
+        async measure(fn) {
+            const inBefore = inputTokens;
+            const outBefore = outputTokens;
+            const costBefore = costUsd;
+            const result = await fn();
+            return {
+                result,
+                tokens: {
+                    inputTokens: inputTokens - inBefore,
+                    outputTokens: outputTokens - outBefore,
+                },
+                costUsd: costUsd - costBefore,
+            };
+        },
+        async call(prompt, callOpts) {
+            calls.push({ prompt, opts: callOpts });
+            const r = opts.respond ? await opts.respond(prompt, callOpts) : take();
+            if (isThrowResponse(r))
+                throw r.throws;
+            if (isToolResponse(r)) {
+                throw new Error(`createMockLLM: call() got a tool-use response (kind='${r.kind}') — expected a plain call response`);
+            }
+            const body = typeof r === 'string' ? { text: r } : r;
+            inputTokens += body.inputTokens ?? 0;
+            outputTokens += body.outputTokens ?? 0;
+            return {
+                text: body.text,
+                inputTokens: body.inputTokens,
+                outputTokens: body.outputTokens,
+                provider: body.provider ?? 'anthropic',
+                model: body.model ?? 'mock',
+            };
+        },
+        async callWithTools(messages, callOpts) {
+            toolCalls.push({ messages, opts: callOpts });
+            const r = take();
+            if (isThrowResponse(r))
+                throw r.throws;
+            if (!isToolResponse(r)) {
+                throw new Error('createMockLLM: callWithTools() expected a response with kind=\'tool_use\' or kind=\'final\'');
+            }
+            inputTokens += r.inputTokens ?? 0;
+            outputTokens += r.outputTokens ?? 0;
+            return r;
+        },
+        queueResponse(r) {
+            queue.push(r);
+        },
+        clearCalls() {
+            calls.length = 0;
+            toolCalls.length = 0;
+            callCount = 0;
+        },
+        get calls() {
+            return calls;
+        },
+        get toolCalls() {
+            return toolCalls;
+        },
+    };
+    return port;
+}

package/dist/utils/llm-providers/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { LLMProvider } from '../llm-types.js';
+export declare const anthropicProvider: LLMProvider;

package/dist/utils/llm-providers/anthropic.js

@@ -0,0 +1,132 @@
+function getApiKey(env) {
+    return env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY;
+}
+function resolveBaseUrl(env) {
+    return env?.ANTHROPIC_BASE_URL || process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com';
+}
+function buildHeaders(apiKey, useCache) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+    };
+    if (useCache) {
+        headers['anthropic-beta'] = 'prompt-caching-2024-07-31';
+    }
+    return headers;
+}
+function sumInputTokens(usage) {
+    return (usage?.input_tokens ?? 0)
+        + (usage?.cache_creation_input_tokens ?? 0)
+        + (usage?.cache_read_input_tokens ?? 0);
+}
+async function postAnthropic(apiKey, useCache, body, env) {
+    const response = await fetch(`${resolveBaseUrl(env)}/v1/messages`, {
+        method: 'POST',
+        headers: buildHeaders(apiKey, useCache),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const errBody = await response.text().catch(() => '');
+        throw new Error(`Anthropic API error (${response.status}): ${errBody.slice(0, 300)}`);
+    }
+    return await response.json();
+}
+export const anthropicProvider = {
+    name: 'anthropic',
+    async isAvailable(env) {
+        return !!getApiKey(env);
+    },
+    supportsModel(model) {
+        return model.trim().toLowerCase().startsWith('claude');
+    },
+    async call(prompt, opts) {
+        const apiKey = getApiKey(opts.env);
+        if (!apiKey) {
+            throw new Error('No ANTHROPIC_API_KEY available');
+        }
+        const model = opts.model || 'claude-sonnet-4-20250514';
+        const temperature = opts.temperature ?? 0;
+        const useCache = opts.cacheControl ?? false;
+        const content = useCache
+            ? [{ type: 'text', text: prompt, cache_control: { type: 'ephemeral' } }]
+            : prompt;
+        try {
+            const data = await postAnthropic(apiKey, useCache, {
+                model,
+                max_tokens: 4096,
+                temperature,
+                messages: [{ role: 'user', content }],
+            }, opts.env);
+            const inputTokens = sumInputTokens(data?.usage);
+            const firstText = data?.content?.find((b) => b.type === 'text');
+            return {
+                text: firstText?.text || '',
+                inputTokens: inputTokens || undefined,
+                outputTokens: data?.usage?.output_tokens,
+                provider: 'anthropic',
+                model,
+            };
+        }
+        catch (error) {
+            throw new Error(`Anthropic API call failed`, { cause: error });
+        }
+    },
+    async callWithTools(messages, opts) {
+        const apiKey = getApiKey(opts.env);
+        if (!apiKey) {
+            throw new Error('No ANTHROPIC_API_KEY available');
+        }
+        const model = opts.model || 'claude-sonnet-4-20250514';
+        const temperature = opts.temperature ?? 0;
+        const maxTokens = opts.maxTokens ?? 4096;
+        const useCache = opts.cacheControl === true;
+        // Tool schemas: only the last gets cache_control, serving as a cache
+        // breakpoint covering the entire (stable) schema block.
+        const tools = useCache && opts.tools.length > 0
+            ? opts.tools.map((t, i) => i === opts.tools.length - 1 ? { ...t, cache_control: { type: 'ephemeral' } } : t)
+            : opts.tools;
+        const body = {
+            model,
+            max_tokens: maxTokens,
+            temperature,
+            messages,
+            tools,
+        };
+        if (opts.system) {
+            body.system = useCache
+                ? [{ type: 'text', text: opts.system, cache_control: { type: 'ephemeral' } }]
+                : opts.system;
+        }
+        const data = await postAnthropic(apiKey, useCache, body, opts.env);
+        const inputTokens = sumInputTokens(data?.usage);
+        const blocks = [];
+        let text = '';
+        for (const block of data?.content ?? []) {
+            if (block.type === 'tool_use') {
+                const b = block;
+                if (b.id && b.name) {
+                    blocks.push({ type: 'tool_use', id: b.id, name: b.name, input: b.input ?? {} });
+                }
+            }
+            else if (block.type === 'text') {
+                text += block.text ?? '';
+            }
+        }
+        if (blocks.length > 0) {
+            return {
+                kind: 'tool_use',
+                blocks,
+                text: text || undefined,
+                inputTokens: inputTokens || undefined,
+                outputTokens: data?.usage?.output_tokens,
+            };
+        }
+        return {
+            kind: 'final',
+            text,
+            inputTokens: inputTokens || undefined,
+            outputTokens: data?.usage?.output_tokens,
+        };
+    },
+};

package/dist/utils/llm-providers/cli.d.ts

@@ -0,0 +1,20 @@
+import type { LLMProvider } from '../llm-types.js';
+/** Reset the availability cache (for testing). */
+export declare function resetCliCache(): void;
+/** Check if claude CLI is installed and authenticated. */
+export declare function isClaudeCliAvailable(): Promise<boolean>;
+export declare function isCodexCliAvailable(): Promise<boolean>;
+interface CliEnvelope {
+    result?: string;
+    structured_output?: unknown;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cache_creation_input_tokens?: number;
+        cache_read_input_tokens?: number;
+    };
+}
+export declare function parseCliEnvelope(raw: string): CliEnvelope;
+export declare function extractStructuredOutput(raw: string): string;
+export declare const cliProvider: LLMProvider;
+export {};

package/dist/utils/llm-providers/cli.js

@@ -0,0 +1,162 @@
+import { spawn } from 'child_process';
+// --- Availability check with promise-based dedup ---
+const availabilityPromises = new Map();
+function getCliAvailability(command, args, timeoutSec) {
+    const cacheKey = `${command} ${args.join(' ')}`;
+    const existing = availabilityPromises.get(cacheKey);
+    if (existing)
+        return existing;
+    const promise = checkCliAvailability(command, args, timeoutSec);
+    availabilityPromises.set(cacheKey, promise);
+    return promise;
+}
+async function checkCliAvailability(command, args, timeoutSec) {
+    try {
+        const result = await runCli(command, args, {}, timeoutSec);
+        return result.exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Reset the availability cache (for testing). */
+export function resetCliCache() {
+    availabilityPromises.clear();
+}
+/** Check if claude CLI is installed and authenticated. */
+export async function isClaudeCliAvailable() {
+    return getCliAvailability('claude', ['auth', 'status'], 5);
+}
+export async function isCodexCliAvailable() {
+    return getCliAvailability('codex', ['login', 'status'], 5);
+}
+export function parseCliEnvelope(raw) {
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    if (!jsonMatch)
+        return {};
+    try {
+        return JSON.parse(jsonMatch[0]);
+    }
+    catch {
+        return {};
+    }
+}
+export function extractStructuredOutput(raw) {
+    const envelope = parseCliEnvelope(raw);
+    if (!envelope || (!envelope.structured_output && !envelope.result)) {
+        const jsonMatch = raw.match(/\{[\s\S]*\}/);
+        return jsonMatch ? jsonMatch[0] : raw.trim();
+    }
+    if (envelope.structured_output && typeof envelope.structured_output === 'object') {
+        return JSON.stringify(envelope.structured_output);
+    }
+    if (typeof envelope.result === 'string' && envelope.result) {
+        return envelope.result;
+    }
+    return raw.trim();
+}
+// --- CLI adapter ---
+export const cliProvider = {
+    name: 'cli',
+    async isAvailable() {
+        return isClaudeCliAvailable();
+    },
+    supportsModel(model) {
+        const normalized = model.trim().toLowerCase();
+        // CLI supports Claude models and unknown models (defaults to claude-cli)
+        if (normalized.startsWith('claude'))
+            return true;
+        // CLI does NOT support non-Claude models like gpt-*, o1, o3, o4
+        if (normalized.startsWith('gpt-')
+            || normalized.startsWith('chatgpt-')
+            || normalized.startsWith('o1')
+            || normalized.startsWith('o3')
+            || normalized.startsWith('o4')) {
+            return false;
+        }
+        // Unknown models — let CLI try (it will fail gracefully)
+        return true;
+    },
+    async call(prompt, opts) {
+        const args = ['-p', '--no-session-persistence'];
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        // Always use JSON output to get token usage from the envelope
+        args.push('--output-format', 'json');
+        if (opts.jsonSchema) {
+            args.push('--json-schema', opts.jsonSchema);
+        }
+        const result = await runCli('claude', args, opts.env ?? {}, 120, prompt);
+        if (result.exitCode !== 0) {
+            throw new Error(`Claude CLI exited with code ${result.exitCode}: ${result.stderr.slice(0, 300)}`);
+        }
+        const envelope = parseCliEnvelope(result.stdout);
+        let text;
+        if (opts.jsonSchema) {
+            // For structured output, extract structured_output or result
+            if (envelope.structured_output && typeof envelope.structured_output === 'object') {
+                text = JSON.stringify(envelope.structured_output);
+            }
+            else if (typeof envelope.result === 'string' && envelope.result) {
+                text = envelope.result;
+            }
+            else {
+                text = extractStructuredOutput(result.stdout);
+            }
+        }
+        else {
+            // For plain text, extract result from the JSON envelope
+            text = typeof envelope.result === 'string' ? envelope.result : result.stdout.trim();
+        }
+        const usage = envelope.usage;
+        const inputTokens = usage
+            ? (usage.input_tokens ?? 0)
+                + (usage.cache_creation_input_tokens ?? 0)
+                + (usage.cache_read_input_tokens ?? 0)
+            : undefined;
+        return {
+            text,
+            inputTokens: inputTokens || undefined,
+            outputTokens: usage?.output_tokens,
+            provider: 'cli',
+            model: opts.model || 'claude-cli',
+        };
+    },
+};
+function runCli(command, args, env, timeoutSec, stdin) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            env: { ...process.env, ...env },
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                child.kill('SIGTERM');
+                setTimeout(() => { if (!child.killed)
+                    child.kill('SIGKILL'); }, 500);
+            }
+        }, timeoutSec * 1000);
+        if (stdin) {
+            child.stdin.write(stdin, () => child.stdin.end());
+        }
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.stderr.on('data', (d) => { stderr += d.toString(); });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr, exitCode: code ?? 1 });
+        });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr: stderr + '\n' + err.message, exitCode: 1 });
+        });
+    });
+}

package/dist/utils/llm-providers/openai.d.ts

@@ -0,0 +1,2 @@
+import type { LLMProvider } from '../llm-types.js';
+export declare const openaiProvider: LLMProvider;

package/dist/utils/llm-providers/openai.js

@@ -0,0 +1,56 @@
+function getApiKey(env) {
+    return env?.OPENAI_API_KEY || process.env.OPENAI_API_KEY;
+}
+export const openaiProvider = {
+    name: 'openai',
+    async isAvailable(env) {
+        return !!getApiKey(env);
+    },
+    supportsModel(model) {
+        const normalized = model.trim().toLowerCase();
+        return (normalized.startsWith('gpt-')
+            || normalized.startsWith('chatgpt-')
+            || normalized.startsWith('o1')
+            || normalized.startsWith('o3')
+            || normalized.startsWith('o4'));
+    },
+    async call(prompt, opts) {
+        const apiKey = getApiKey(opts.env);
+        if (!apiKey) {
+            throw new Error('No OPENAI_API_KEY available');
+        }
+        const model = opts.model || 'gpt-4o';
+        const temperature = opts.temperature ?? 0;
+        const baseUrl = (opts.env?.OPENAI_BASE_URL || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1').replace(/\/$/, '');
+        try {
+            const response = await fetch(`${baseUrl}/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    model,
+                    max_tokens: 4096,
+                    temperature,
+                    messages: [{ role: 'user', content: prompt }],
+                }),
+            });
+            if (!response.ok) {
+                const errBody = await response.text().catch(() => '');
+                throw new Error(`OpenAI API error (${response.status}): ${errBody.slice(0, 300)}`);
+            }
+            const data = await response.json();
+            return {
+                text: data?.choices?.[0]?.message?.content || '',
+                inputTokens: data?.usage?.prompt_tokens,
+                outputTokens: data?.usage?.completion_tokens,
+                provider: 'openai',
+                model,
+            };
+        }
+        catch (error) {
+            throw new Error(`OpenAI API error: ${error}`);
+        }
+    },
+};

package/dist/utils/llm-types.d.ts

@@ -0,0 +1,107 @@
+export interface LLMCallOptions {
+    model?: string;
+    env?: Record<string, string>;
+    temperature?: number;
+    /** When set, use --json-schema for structured output via CLI. */
+    jsonSchema?: string;
+    /** When true, enable Anthropic prompt caching via cache_control on content blocks. */
+    cacheControl?: boolean;
+}
+export interface LLMCallResult {
+    text: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    provider: 'anthropic' | 'openai' | 'cli';
+    model: string;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Caller-facing type — just call(). */
+export interface LLMPort {
+    call(prompt: string, opts?: LLMCallOptions): Promise<LLMCallResult>;
+    /** Present only on providers that opt in to multi-turn tool use. */
+    callWithTools?(messages: ToolUseMessage[], opts: CallWithToolsOptions): Promise<CallWithToolsResult>;
+    /** Running total of tokens consumed through this port. Present on clients from createLLMClient. */
+    readonly tokenUsage?: TokenUsage;
+    /**
+     * Running total of USD cost consumed through this port. Present on
+     * clients from `createLLMClient`. Accumulates Claude SDK turn-cost
+     * deltas via `addCost` and judge-LLM cost once judge providers expose
+     * comparable metadata.
+     */
+    readonly costUsd?: number;
+    /** Add externally-observed tokens (e.g. from agent CLI turns). */
+    addTokens?(input: number, output: number): void;
+    /** Add externally-observed cost (e.g. from Claude SDK `total_cost_usd`). */
+    addCost?(usd: number): void;
+    /** Run `fn` and return its token + cost delta. */
+    measure?<T>(fn: () => Promise<T>): Promise<{
+        result: T;
+        tokens: TokenUsage;
+        costUsd: number;
+    }>;
+    /** Name of the adapter that resolved the last call (e.g. 'anthropic'). */
+    readonly lastProvider?: string;
+    /** True when this port can dispatch tool use. Type-guard form preferred at call sites. */
+    readonly supportsToolUse?: boolean;
+}
+/** Narrower interface the tool-use runner accepts. */
+export interface ToolCapableLLMPort extends LLMPort {
+    callWithTools(messages: ToolUseMessage[], opts: CallWithToolsOptions): Promise<CallWithToolsResult>;
+}
+export interface ToolSchema {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export interface CallWithToolsOptions extends LLMCallOptions {
+    system?: string;
+    tools: ToolSchema[];
+    maxTokens?: number;
+}
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+export type AssistantContentBlock = TextBlock | ToolUseBlock;
+export type UserContentBlock = TextBlock | ToolResultBlock;
+export interface ToolUseMessage {
+    role: 'user' | 'assistant';
+    content: string | Array<AssistantContentBlock | UserContentBlock>;
+}
+export type CallWithToolsResult = {
+    kind: 'tool_use';
+    blocks: ToolUseBlock[];
+    text?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+} | {
+    kind: 'final';
+    text: string;
+    inputTokens?: number;
+    outputTokens?: number;
+};
+/** Wide implementor-facing type — each provider adapter implements this. */
+export interface LLMProviderAdapter {
+    name: string;
+    isAvailable(env?: Record<string, string>): Promise<boolean>;
+    call(prompt: string, opts: LLMCallOptions): Promise<LLMCallResult>;
+    callWithTools?(messages: ToolUseMessage[], opts: CallWithToolsOptions): Promise<CallWithToolsResult>;
+    supportsModel?(model: string): boolean;
+}
+/** @deprecated Use `LLMProviderAdapter`. Alias retained only during the RFC 010a migration. */
+export type LLMProvider = LLMProviderAdapter;

package/dist/utils/llm-types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/llm.d.ts

@@ -0,0 +1,36 @@
+import type { LLMProviderAdapter, LLMCallOptions, LLMCallResult, LLMPort } from './llm-types.js';
+export type { LLMCallOptions, LLMCallResult, LLMPort, LLMProviderAdapter, LLMProvider, TokenUsage } from './llm-types.js';
+export interface CreateLLMClientOptions {
+    adapters?: LLMProviderAdapter[];
+    agent?: string;
+    env?: Record<string, string>;
+    silent?: boolean;
+}
+export declare class ProviderNotSupportedError extends Error {
+    readonly name = "ProviderNotSupportedError";
+    readonly adapterName: string;
+    constructor(adapterName: string);
+}
+export { isClaudeCliAvailable, isCodexCliAvailable, resetCliCache, extractStructuredOutput, parseCliEnvelope } from './llm-providers/cli.js';
+/**
+ * Create an LLM client that tries providers in order.
+ *
+ * For each call, the client:
+ * 1. Filters providers by supportsModel() if a model is specified
+ * 2. Checks isAvailable() for each candidate
+ * 3. Calls the first available provider
+ * 4. On failure, falls through to the next provider if one exists
+ */
+export declare function createLLMClient(opts: CreateLLMClientOptions): LLMPort;
+export declare function createLLMClient(providers: LLMProviderAdapter[], agentName?: string): LLMPort;
+export declare function callLLM(prompt: string, opts?: LLMCallOptions): Promise<LLMCallResult>;
+/**
+ * Create an LLM client scoped to the providers that match the given agent.
+ *
+ * - claude → CLI + Anthropic API (no OpenAI fallthrough)
+ * - codex  → OpenAI API
+ *
+ * If `agentEnv` is provided, it is merged into every LLM call so that
+ * the agent's env propagates to persona/judge/summarization calls.
+ */
+export declare function createAgentLLM(agentName: string, agentEnv?: Record<string, string>): LLMPort;