@sdods/agents 0.2.0

package/dist/adapter/claude.d.ts

@@ -0,0 +1,42 @@
+import { type AgentEvent, type CompleteRequest, type CompleteResult, type LlmAdapter, type RunAgentOptions, type RunAgentResult, type TokenUsage } from './types.js';
+/**
+ * Claude adapter: `runAgent` uses the Claude Agent SDK (query + in-process MCP tools + the
+ * bundled Playwright MCP); `complete`/`stream` use the Anthropic Messages API.
+ * The SDK modules are imported lazily so the package loads without them (FakeAdapter, tests).
+ */
+export interface ClaudeAdapterOptions {
+    apiKey?: string;
+    model?: string;
+    /** injected for tests */
+    sdk?: {
+        query: (params: {
+            prompt: string;
+            options?: Record<string, unknown>;
+        }) => AsyncIterable<Record<string, any>>;
+        tool: (...a: any[]) => any;
+        createSdkMcpServer: (o: any) => any;
+    };
+    anthropic?: {
+        messages: {
+            create: (p: any) => Promise<any>;
+            stream?: (p: any) => AsyncIterable<any>;
+        };
+    };
+    withPlaywrightMcp?: boolean;
+}
+export declare class ClaudeAdapter implements LlmAdapter {
+    private readonly opts;
+    readonly provider: "claude";
+    readonly defaultModel: string;
+    constructor(opts?: ClaudeAdapterOptions);
+    private ensureKey;
+    private sdk;
+    private anthropic;
+    complete(req: CompleteRequest): Promise<CompleteResult>;
+    stream(req: CompleteRequest): AsyncIterable<string>;
+    runAgent(o: RunAgentOptions): Promise<RunAgentResult>;
+}
+/** Convert Claude Agent SDK messages into SDODS agent events. */
+export declare function normalize(msg: Record<string, any>): AgentEvent[];
+export declare function usageOf(u: Record<string, unknown> | undefined): TokenUsage | undefined;
+//# sourceMappingURL=claude.d.ts.map

package/dist/adapter/claude.js

@@ -0,0 +1,216 @@
+import { DEFAULT_MODELS, AgentsConfigError, } from './types.js';
+export class ClaudeAdapter {
+    opts;
+    provider = 'claude';
+    defaultModel;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.defaultModel = opts.model ?? process.env.SDODS_CLAUDE_MODEL ?? DEFAULT_MODELS.claude;
+    }
+    ensureKey() {
+        const key = this.opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+        if (!key) {
+            throw new AgentsConfigError('ANTHROPIC_API_KEY is not set.', 'Export ANTHROPIC_API_KEY (your own key, billed by Anthropic) or use --adapter fake / --dry-run.');
+        }
+        return key;
+    }
+    async sdk() {
+        if (this.opts.sdk)
+            return this.opts.sdk;
+        const mod = (await import('@anthropic-ai/claude-agent-sdk'));
+        return mod;
+    }
+    async anthropic() {
+        if (this.opts.anthropic)
+            return this.opts.anthropic;
+        const { default: Anthropic } = await import('@anthropic-ai/sdk');
+        return new Anthropic({ apiKey: this.ensureKey() });
+    }
+    async complete(req) {
+        this.ensureKey();
+        const client = await this.anthropic();
+        const res = await client.messages.create({
+            model: req.model ?? this.defaultModel,
+            max_tokens: req.maxTokens ?? 16_000,
+            system: req.system,
+            messages: [{ role: 'user', content: req.prompt }],
+            thinking: { type: 'adaptive' },
+            ...(req.effort ? { output_config: { effort: req.effort } } : {}),
+        });
+        const text = res.content
+            .filter((c) => c.type === 'text')
+            .map((c) => c.text ?? '')
+            .join('');
+        return { text, usage: usageOf(res.usage), model: res.model };
+    }
+    async *stream(req) {
+        this.ensureKey();
+        const client = await this.anthropic();
+        if (!client.messages.stream) {
+            const r = await this.complete(req);
+            yield r.text;
+            return;
+        }
+        const s = client.messages.stream({
+            model: req.model ?? this.defaultModel,
+            max_tokens: req.maxTokens ?? 64_000,
+            system: req.system,
+            messages: [{ role: 'user', content: req.prompt }],
+        });
+        for await (const ev of s) {
+            if (ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta')
+                yield ev.delta.text;
+        }
+    }
+    async runAgent(o) {
+        this.ensureKey();
+        const sdk = await this.sdk();
+        const tools = o.tools.map((t) => sdk.tool(t.name, t.description, t.inputSchema, async (args) => t.handler(args), { annotations: t.annotations }));
+        const mcpServers = {
+            sdods: sdk.createSdkMcpServer({ name: 'sdods', version: '0.1.0', tools }),
+        };
+        if (this.opts.withPlaywrightMcp !== false)
+            mcpServers.playwright = {
+                type: 'stdio',
+                command: 'npx',
+                args: ['playwright', 'mcp', '--headless'],
+            };
+        for (const [name, cfg] of Object.entries(o.mcpServers ?? {})) {
+            if (cfg.transport === 'http' && cfg.url)
+                mcpServers[name] = { type: 'http', url: cfg.url, headers: cfg.headers };
+            else if (cfg.command)
+                mcpServers[name] = {
+                    type: 'stdio',
+                    command: cfg.command,
+                    args: cfg.args ?? [],
+                    env: cfg.env,
+                };
+        }
+        const abort = new AbortController();
+        o.signal?.addEventListener('abort', () => abort.abort(), { once: true });
+        const q = sdk.query({
+            prompt: o.prompt,
+            options: {
+                systemPrompt: o.system,
+                model: o.model ?? this.defaultModel,
+                maxTurns: o.maxTurns ?? 40,
+                maxBudgetUsd: o.maxBudgetUsd,
+                cwd: o.cwd,
+                abortController: abort,
+                permissionMode: 'default',
+                allowedTools: [
+                    'Read',
+                    'Glob',
+                    'Grep',
+                    'mcp__sdods__*',
+                    'mcp__playwright__*',
+                    ...Object.keys(o.mcpServers ?? {}).map((n) => `mcp__${n}__*`),
+                ],
+                disallowedTools: [
+                    'Bash',
+                    'Write',
+                    'Edit',
+                    'MultiEdit',
+                    'NotebookEdit',
+                    'WebFetch',
+                    'WebSearch',
+                ],
+                mcpServers,
+                canUseTool: async () => ({
+                    behavior: 'deny',
+                    message: 'SDODS agents may only use MCP tools and read-only file tools.',
+                }),
+            },
+        });
+        let text = '';
+        let turns = 0;
+        let toolCalls = 0;
+        let result;
+        for await (const msg of q) {
+            const ev = normalize(msg);
+            for (const e of ev) {
+                o.onEvent?.(e);
+                if (e.type === 'text')
+                    text += e.text;
+                if (e.type === 'tool_call')
+                    toolCalls++;
+                if (e.type === 'result') {
+                    turns = e.turns;
+                    result = {
+                        text,
+                        costUsd: e.costUsd,
+                        usage: e.usage,
+                        turns,
+                        stopReason: e.stopReason,
+                        isError: e.isError,
+                        toolCalls,
+                    };
+                }
+            }
+        }
+        return result ?? { text, turns, stopReason: 'end', toolCalls };
+    }
+}
+/** Convert Claude Agent SDK messages into SDODS agent events. */
+export function normalize(msg) {
+    const out = [];
+    switch (msg?.type) {
+        case 'assistant': {
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === 'text' && block.text)
+                    out.push({ type: 'text', text: block.text });
+                if (block.type === 'tool_use')
+                    out.push({ type: 'tool_call', id: block.id, name: block.name, input: block.input });
+            }
+            break;
+        }
+        case 'user': {
+            for (const block of msg.message?.content ?? []) {
+                if (block?.type === 'tool_result')
+                    out.push({
+                        type: 'tool_result',
+                        id: block.tool_use_id,
+                        output: block.content,
+                        isError: block.is_error,
+                    });
+            }
+            break;
+        }
+        case 'result': {
+            const usage = msg.usage ? usageOf(msg.usage) : undefined;
+            out.push({
+                type: 'result',
+                costUsd: msg.total_cost_usd,
+                usage,
+                turns: msg.num_turns ?? 0,
+                stopReason: msg.subtype ?? msg.stop_reason ?? 'end',
+                isError: Boolean(msg.is_error),
+            });
+            if (typeof msg.result === 'string' && msg.result)
+                out.push({ type: 'text', text: msg.result });
+            break;
+        }
+        case 'system':
+        case 'status':
+            if (msg.subtype || msg.message)
+                out.push({ type: 'status', message: String(msg.subtype ?? msg.message) });
+            break;
+        default:
+            break;
+    }
+    return out;
+}
+export function usageOf(u) {
+    if (!u)
+        return undefined;
+    return {
+        inputTokens: num(u.input_tokens),
+        outputTokens: num(u.output_tokens),
+        cacheReadTokens: num(u.cache_read_input_tokens),
+        cacheWriteTokens: num(u.cache_creation_input_tokens),
+    };
+}
+function num(v) {
+    return typeof v === 'number' ? v : undefined;
+}
+//# sourceMappingURL=claude.js.map

package/dist/adapter/cli-common.d.ts

@@ -0,0 +1,46 @@
+import { type ExternalMcpServerConfig } from './types.js';
+/** Where the sdods MCP server for a project comes from (same resolution as packages/mcp). */
+export interface McpStdioSpec {
+    command: string;
+    args: string[];
+}
+export interface CliAdapterContext {
+    rootDir?: string;
+    project?: string;
+    env?: string;
+    /** injected for tests: binary name/path override */
+    bin?: string;
+    /** include the bundled Playwright MCP server (default true) */
+    withPlaywrightMcp?: boolean;
+}
+/** Locate a binary on PATH (or an explicit path). Returns null when missing. */
+export declare function findOnPath(bin: string): string | null;
+export declare function sdodsMcpServerSpec(ctx: CliAdapterContext): McpStdioSpec;
+export declare function playwrightMcpSpec(): McpStdioSpec;
+/** Full MCP server map for a run: sdods + playwright + the project's external servers. */
+export declare function mcpServerMap(ctx: CliAdapterContext, external?: Record<string, ExternalMcpServerConfig>): Record<string, Record<string, unknown>>;
+export declare function writeTempJson(prefix: string, value: unknown): string;
+export interface JsonlRunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    /** called for every non-empty stdout line; JSON lines are parsed, others passed as strings */
+    onLine: (line: unknown, raw: string) => void;
+    /** feed this to stdin then close it (default: stdin ignored) */
+    stdin?: string;
+    timeoutMs?: number;
+}
+export interface JsonlRunResult {
+    exitCode: number;
+    stderr: string;
+    signal?: NodeJS.Signals | null;
+}
+/** Spawn a CLI that emits one JSON object per stdout line and stream the lines back. */
+export declare function runJsonl(command: string, args: string[], o: JsonlRunOptions): Promise<JsonlRunResult>;
+/** Resolve the binary or throw a clear configuration error with install/login hints. */
+export declare function requireCli(bin: string, install: string): string;
+export declare function runQuiet(command: string, args: string[], timeoutMs?: number): {
+    ok: boolean;
+    stdout: string;
+};
+//# sourceMappingURL=cli-common.d.ts.map

package/dist/adapter/cli-common.js

@@ -0,0 +1,145 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { resolveCliInvocation } from '@sdods/mcp';
+import { AgentsConfigError } from './types.js';
+/** Locate a binary on PATH (or an explicit path). Returns null when missing. */
+export function findOnPath(bin) {
+    if (bin.includes('/'))
+        return bin;
+    const path = process.env.PATH ?? '';
+    const exts = process.platform === 'win32' ? ['.cmd', '.exe', ''] : [''];
+    for (const dir of path.split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = join(dir, bin + ext);
+            try {
+                const r = spawnSync('test', ['-x', candidate]);
+                if (r.status === 0)
+                    return candidate;
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    return null;
+}
+export function sdodsMcpServerSpec(ctx) {
+    const rootDir = ctx.rootDir ?? process.cwd();
+    const inv = resolveCliInvocation(rootDir);
+    const args = [...inv.args, 'mcp', '--caps', 'all'];
+    if (ctx.project)
+        args.push('--project', ctx.project);
+    if (ctx.env)
+        args.push('--env', ctx.env);
+    return { command: inv.command, args };
+}
+export function playwrightMcpSpec() {
+    return { command: 'npx', args: ['playwright', 'mcp', '--headless'] };
+}
+/** Full MCP server map for a run: sdods + playwright + the project's external servers. */
+export function mcpServerMap(ctx, external = {}) {
+    const servers = {
+        sdods: { type: 'stdio', ...sdodsMcpServerSpec(ctx) },
+    };
+    if (ctx.withPlaywrightMcp !== false)
+        servers.playwright = { type: 'stdio', ...playwrightMcpSpec() };
+    for (const [name, cfg] of Object.entries(external)) {
+        if (cfg.transport === 'http' && cfg.url)
+            servers[name] = { type: 'http', url: cfg.url, headers: cfg.headers ?? {} };
+        else if (cfg.command)
+            servers[name] = {
+                type: 'stdio',
+                command: cfg.command,
+                args: cfg.args ?? [],
+                env: cfg.env ?? {},
+            };
+    }
+    return servers;
+}
+export function writeTempJson(prefix, value) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    const file = join(dir, 'mcp.json');
+    writeFileSync(file, JSON.stringify(value, null, 2));
+    return file;
+}
+/** Spawn a CLI that emits one JSON object per stdout line and stream the lines back. */
+export function runJsonl(command, args, o) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: o.cwd,
+            env: { ...process.env, ...o.env },
+            stdio: [o.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+        });
+        let stderr = '';
+        let buffer = '';
+        const handleChunk = (chunk) => {
+            buffer += chunk.toString('utf8');
+            let idx;
+            while ((idx = buffer.indexOf('\n')) >= 0) {
+                const raw = buffer.slice(0, idx).replace(/\r$/, '');
+                buffer = buffer.slice(idx + 1);
+                emit(raw);
+            }
+        };
+        const emit = (raw) => {
+            const line = raw.trim();
+            if (!line)
+                return;
+            if (line.startsWith('{') || line.startsWith('[')) {
+                try {
+                    o.onLine(JSON.parse(line), raw);
+                    return;
+                }
+                catch {
+                    /* not JSON */
+                }
+            }
+            o.onLine(raw, raw);
+        };
+        child.stdout?.on('data', handleChunk);
+        child.stderr?.on('data', (c) => {
+            stderr += c.toString('utf8');
+        });
+        const timer = o.timeoutMs ? setTimeout(() => child.kill('SIGTERM'), o.timeoutMs) : undefined;
+        const onAbort = () => child.kill('SIGTERM');
+        o.signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('error', (e) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(e);
+        });
+        child.on('close', (code, signal) => {
+            if (timer)
+                clearTimeout(timer);
+            o.signal?.removeEventListener('abort', onAbort);
+            if (buffer.trim())
+                emit(buffer);
+            resolve({ exitCode: code ?? (signal ? 130 : 1), stderr, signal });
+        });
+        if (o.stdin !== undefined && child.stdin) {
+            child.stdin.end(o.stdin);
+        }
+    });
+}
+/** Resolve the binary or throw a clear configuration error with install/login hints. */
+export function requireCli(bin, install) {
+    const found = findOnPath(bin);
+    if (!found) {
+        throw new AgentsConfigError(`The ${bin} CLI is not installed or not on PATH.`, install);
+    }
+    return found;
+}
+export function runQuiet(command, args, timeoutMs = 15_000) {
+    try {
+        const r = spawnSync(command, args, { encoding: 'utf8', timeout: timeoutMs });
+        return { ok: r.status === 0, stdout: `${r.stdout ?? ''}${r.stderr ?? ''}` };
+    }
+    catch {
+        return { ok: false, stdout: '' };
+    }
+}
+//# sourceMappingURL=cli-common.js.map

package/dist/adapter/codex.d.ts

@@ -0,0 +1,31 @@
+import { type CliAdapterContext } from './cli-common.js';
+import { type AgentEvent, type CompleteRequest, type CompleteResult, type LlmAdapter, type RunAgentOptions, type RunAgentResult, type TokenUsage } from './types.js';
+/** Codex `exec --json` event stream → SDODS events. */
+export declare function normalizeCodexEvent(ev: Record<string, any>): AgentEvent[];
+export declare function codexUsage(u: Record<string, any> | undefined): TokenUsage | undefined;
+/**
+ * Runs SDODS agent roles through the user's logged-in OpenAI Codex CLI (`codex exec --json`).
+ * No OPENAI_API_KEY is needed when Codex is logged in with a ChatGPT account. The sdods MCP
+ * server and the bundled Playwright MCP are injected with `-c mcp_servers.*` overrides; the run
+ * is ephemeral, read-only sandboxed, and the system prompt is prepended to the task.
+ */
+export declare class CodexCliAdapter implements LlmAdapter {
+    private readonly ctx;
+    readonly provider: "codex";
+    readonly defaultModel: string;
+    constructor(ctx?: CliAdapterContext & {
+        model?: string;
+    });
+    bin(): string;
+    static loginStatus(bin?: string): {
+        installed: boolean;
+        loggedIn: boolean | null;
+        detail: string;
+    };
+    private baseArgs;
+    private mcpArgs;
+    complete(req: CompleteRequest): Promise<CompleteResult>;
+    stream(req: CompleteRequest): AsyncIterable<string>;
+    runAgent(o: RunAgentOptions): Promise<RunAgentResult>;
+}
+//# sourceMappingURL=codex.d.ts.map