@osdlc/agent-call 0.0.1-stage → 0.4.0

package/dist/adapters/shared.d.ts

@@ -0,0 +1,40 @@
+import type { CapabilityNote, Support } from '../plan.js';
+import type { AgentCallSpec, PermissionMode } from '../spec.js';
+/** `--model <model>`: the flag claude, codex, antigravity and pi all take. */
+export declare function modelFlag(model: string): string[];
+export interface PermissionModeEntry {
+    argv: string[];
+    support: Extract<Support, 'native' | 'approximated'>;
+    detail: string;
+}
+export type PermissionModeTable = Partial<Record<Exclude<PermissionMode, 'default'>, PermissionModeEntry>>;
+/** permissions.mode → argv tokens, shared by adapters that express modes as CLI flags. */
+export declare function applyPermissionMode(argv: string[], notes: CapabilityNote[], mode: PermissionMode | undefined, table: PermissionModeTable): void;
+/** Which spec fields the target CLI handles natively (everything else gets emulated in the prompt). */
+export interface PromptEmulation {
+    /** CLI attaches context files natively; skip the file preamble. */
+    filesNative?: boolean | undefined;
+    /** Prefix file entries with `@` for agents with @-inclusion syntax. */
+    filesAtSyntax?: boolean | undefined;
+    /** CLI enforces an output schema natively; skip the JSON instruction. */
+    schemaNative?: boolean | undefined;
+    /** CLI takes system prompts natively; skip the system preamble. */
+    systemNative?: boolean;
+    /** CLI takes appended system prompts natively; skip the instructions preamble. */
+    appendSystemNative?: boolean;
+}
+/**
+ * Build the prompt actually sent, folding in every spec field the target CLI
+ * cannot express natively. Each fold is recorded as an `emulated` note.
+ */
+export declare function buildEffectivePrompt(spec: AgentCallSpec, emulation: PromptEmulation, notes: CapabilityNote[]): string;
+/** Strip one surrounding markdown code fence, if present. */
+export declare function stripCodeFence(text: string): string;
+/** Parse JSON, tolerating a surrounding code fence. Returns undefined on failure. */
+export declare function tryParseJson(text: string): unknown;
+/** Parse line-delimited JSON, skipping lines that aren't JSON objects. */
+export declare function parseJsonLines(stdout: string): unknown[];
+/** Type-tolerant object field access for parsing loosely specified payloads. */
+export declare function get(value: unknown, ...path: string[]): unknown;
+export declare function asString(value: unknown): string | undefined;
+export declare function asNumber(value: unknown): number | undefined;

package/dist/adapters/shared.js

@@ -0,0 +1,101 @@
+import { note } from '../plan.js';
+/** `--model <model>`: the flag claude, codex, antigravity and pi all take. */
+export function modelFlag(model) {
+    return ['--model', model];
+}
+/** permissions.mode → argv tokens, shared by adapters that express modes as CLI flags. */
+export function applyPermissionMode(argv, notes, mode, table) {
+    if (mode === undefined || mode === 'default')
+        return;
+    const entry = table[mode];
+    if (entry === undefined)
+        return;
+    argv.push(...entry.argv);
+    note(notes, 'permissions.mode', entry.support, entry.detail);
+}
+/**
+ * Build the prompt actually sent, folding in every spec field the target CLI
+ * cannot express natively. Each fold is recorded as an `emulated` note.
+ */
+export function buildEffectivePrompt(spec, emulation, notes) {
+    const sections = [];
+    if (spec.systemPrompt !== undefined && !emulation.systemNative) {
+        sections.push(`<system>\n${spec.systemPrompt}\n</system>`);
+        note(notes, 'systemPrompt', 'emulated', 'no system-prompt flag; prepended to the prompt in a <system> block');
+    }
+    if (spec.appendSystemPrompt !== undefined && !emulation.appendSystemNative) {
+        sections.push(`<instructions>\n${spec.appendSystemPrompt}\n</instructions>`);
+        note(notes, 'appendSystemPrompt', 'emulated', 'no append-system-prompt flag; prepended to the prompt in an <instructions> block');
+    }
+    if (spec.context?.text !== undefined) {
+        sections.push(`<context>\n${spec.context.text}\n</context>`);
+    }
+    const files = spec.context?.files ?? [];
+    if (files.length > 0 && !emulation.filesNative) {
+        const listed = files.map((f) => (emulation.filesAtSyntax ? `@${f}` : `- ${f}`)).join('\n');
+        sections.push(`Relevant files (read them before answering):\n${listed}`);
+        note(notes, 'context.files', 'emulated', emulation.filesAtSyntax
+            ? 'no attach flag; referenced with @path syntax in the prompt'
+            : 'no attach flag; listed in a prompt preamble for the agent to read');
+    }
+    sections.push(spec.prompt);
+    if (spec.output?.schema !== undefined && !emulation.schemaNative) {
+        sections.push('Respond with ONLY a JSON value (no prose, no markdown fences) that ' +
+            `validates against this JSON Schema:\n${JSON.stringify(spec.output.schema)}`);
+        note(notes, 'output.schema', 'emulated', 'no schema flag; appended a respond-only-with-JSON instruction to the prompt');
+    }
+    return sections.join('\n\n');
+}
+/** Strip one surrounding markdown code fence, if present. */
+export function stripCodeFence(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('```'))
+        return trimmed;
+    const lines = trimmed.split('\n');
+    if (lines[0]?.startsWith('```'))
+        lines.shift();
+    if (lines[lines.length - 1]?.trim().startsWith('```'))
+        lines.pop();
+    return lines.join('\n').trim();
+}
+/** Parse JSON, tolerating a surrounding code fence. Returns undefined on failure. */
+export function tryParseJson(text) {
+    try {
+        return JSON.parse(stripCodeFence(text));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse line-delimited JSON, skipping lines that aren't JSON objects. */
+export function parseJsonLines(stdout) {
+    const events = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        try {
+            events.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Interleaved log noise is expected on some CLIs; skip it.
+        }
+    }
+    return events;
+}
+/** Type-tolerant object field access for parsing loosely specified payloads. */
+export function get(value, ...path) {
+    let current = value;
+    for (const key of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+export function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+export function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}

package/dist/adapters/template.d.ts

@@ -0,0 +1,43 @@
+import type { ModelChoice } from '../model-args.js';
+import type { AgentAdapter } from './types.js';
+/**
+ * Options for {@link templateAdapter}.
+ *
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export interface TemplateAdapterOptions {
+    /** Adapter name, reported as `PlannedCall.agent`. */
+    name: string;
+    /** Binary to spawn. */
+    binary: string;
+    /**
+     * Arguments after the binary. `{prompt}`, `{model}` and `{effort}` are
+     * slots: an argument equal to one is replaced whole by its value; any other
+     * argument passes as written, so a value never lands inside a larger one.
+     */
+    args: readonly string[];
+    /** Whether the prompt fills the `{prompt}` slot or goes on stdin. */
+    promptVia: 'argv' | 'stdin';
+}
+/**
+ * Why a template with `args` cannot take `choice`, or `null` when it can: a
+ * model or effort needs its slot, and a slot needs a value.
+ *
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export declare function templateRefusal(args: readonly string[], choice: ModelChoice): string | null;
+/**
+ * A headless call through an argument template for any one-shot CLI: the slots
+ * are filled and the prompt goes in `{prompt}` or on stdin. Context, system
+ * prompt and schema are folded into the prompt; `permissions.mode` is noted
+ * as dropped. Any other field the template cannot express (budget, session,
+ * mcp, plugins, dirs, tool rules) is left out with no note, as
+ * {@link customAdapter} does.
+ *
+ * @throws {Error} From `plan` (so from `planCall` and `callAgent`) when the
+ * spec's model or effort does not fit the slots ({@link templateRefusal}).
+ * @throws {Error} From `templateAdapter` itself when `promptVia` is `'argv'` and
+ * `args` has no `{prompt}` slot, or when it is `'stdin'` and `args` has one.
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export declare function templateAdapter(options: TemplateAdapterOptions): AgentAdapter;

package/dist/adapters/template.js

@@ -0,0 +1,62 @@
+import { customAdapter } from './custom.js';
+/**
+ * Why a template with `args` cannot take `choice`, or `null` when it can: a
+ * model or effort needs its slot, and a slot needs a value.
+ *
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export function templateRefusal(args, choice) {
+    for (const [field, slot] of [
+        ['model', '{model}'],
+        ['effort', '{effort}'],
+    ]) {
+        const value = choice[field];
+        const has = args.includes(slot);
+        if (value !== undefined && !has) {
+            return `its headless template has no ${slot} slot; cannot pass ${field} '${value}'`;
+        }
+        if (value === undefined && has) {
+            return `its headless template's ${slot} slot needs a ${field}, and none was resolved`;
+        }
+    }
+    return null;
+}
+/**
+ * A headless call through an argument template for any one-shot CLI: the slots
+ * are filled and the prompt goes in `{prompt}` or on stdin. Context, system
+ * prompt and schema are folded into the prompt; `permissions.mode` is noted
+ * as dropped. Any other field the template cannot express (budget, session,
+ * mcp, plugins, dirs, tool rules) is left out with no note, as
+ * {@link customAdapter} does.
+ *
+ * @throws {Error} From `plan` (so from `planCall` and `callAgent`) when the
+ * spec's model or effort does not fit the slots ({@link templateRefusal}).
+ * @throws {Error} From `templateAdapter` itself when `promptVia` is `'argv'` and
+ * `args` has no `{prompt}` slot, or when it is `'stdin'` and `args` has one.
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export function templateAdapter(options) {
+    const hasPromptSlot = options.args.includes('{prompt}');
+    if (options.promptVia === 'argv' && !hasPromptSlot) {
+        throw new Error(`${options.name}: promptVia 'argv' needs a {prompt} slot in args`);
+    }
+    if (options.promptVia === 'stdin' && hasPromptSlot) {
+        throw new Error(`${options.name}: promptVia 'stdin' cannot have a {prompt} slot in args`);
+    }
+    return customAdapter({
+        name: options.name,
+        binary: options.binary,
+        promptVia: options.promptVia,
+        args: (spec, prompt) => {
+            const refusal = templateRefusal(options.args, spec);
+            if (refusal !== null)
+                throw new Error(`${options.name}: ${refusal}`);
+            const slots = {
+                '{prompt}': prompt,
+                '{model}': spec.model,
+                '{effort}': spec.effort,
+            };
+            return options.args.map((arg) => (Object.hasOwn(slots, arg) ? slots[arg] : arg));
+        },
+    });
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,55 @@
+import type { Conversation, Usage } from '../conversation.js';
+import type { PlannedCall } from '../plan.js';
+import type { AgentCallSpec } from '../spec.js';
+/** What actually came back from the child process. */
+export interface RawProcessOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    durationMs: number;
+    /** The run was cut short: a timeout elapsed, or the caller aborted. */
+    timedOut: boolean;
+    /** Which came first when the run was cut short: the timeout or a caller abort. */
+    cutShortBy?: 'timeout' | 'abort' | undefined;
+    /** The signal that ended the child, when it died on one (for example `SIGKILL`). */
+    signal?: string | undefined;
+    /**
+     * The prompt could not be fully written to the child's stdin, because the
+     * child exited or closed the pipe first — so the agent answered a truncated
+     * prompt. Absent when the write completed.
+     */
+    stdinError?: string | undefined;
+    /** Contents of `readBack` temp files, keyed by `TempFile.name`. */
+    files?: Record<string, string> | undefined;
+}
+/** Adapter-parsed view of a raw run, before assembly into an AgentResult. */
+export interface ParsedOutput {
+    /** Best-effort final assistant answer as plain text. */
+    text: string;
+    /** Parsed JSON answer when `output.schema` was requested. */
+    structured?: unknown | undefined;
+    sessionId?: string | undefined;
+    usage?: Usage | undefined;
+    costUsd?: number | undefined;
+    model?: string | undefined;
+    stopReason?: string | undefined;
+    /** Parsed JSONL events when a streaming format was used. */
+    events?: unknown[] | undefined;
+    /** The agent itself reported failure (distinct from a nonzero exit). */
+    isError?: boolean | undefined;
+    errorDetail?: string | undefined;
+}
+/**
+ * One agent CLI. `plan` is pure (spec in, invocation out); `parseResult`
+ * is pure (bytes in, structure out). All process handling lives in the
+ * runner, so adapters are trivially unit-testable.
+ */
+export interface AgentAdapter {
+    name: string;
+    /** Binary to spawn; override via each adapter factory's `binary` option. */
+    binary: string;
+    plan(spec: AgentCallSpec): PlannedCall;
+    parseResult(planned: PlannedCall, raw: RawProcessOutput): ParsedOutput;
+    /** Optional supplemental layer: lift the raw transcript into the normalized model. */
+    toConversation?(planned: PlannedCall, raw: RawProcessOutput): Conversation | undefined;
+}

package/dist/adapters/types.js

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

package/dist/conversation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The normalized conversation data model — the optional layer on top of the
+ * caller abstraction. Every adapter can lift its raw transcript into this
+ * shape for post-facto analysis; the raw payload is always preserved in
+ * `Conversation.raw` so normalization never loses information.
+ *
+ * The shape follows the common core of the OpenTelemetry GenAI conventions
+ * and the Vercel AI SDK message model: role-tagged messages made of typed
+ * parts (text, reasoning, tool-call, tool-result), plus run-level usage,
+ * cost, and timing.
+ */
+/** The `Conversation.schema` value of this data model; its version is part of the string. */
+export declare const CONVERSATION_SCHEMA: "agent-conversation/1";
+/** Who produced a message. Tool results travel under `tool`. */
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+/** One typed piece of a message: text, reasoning, a tool call, or a tool result. */
+export type Part = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+} | {
+    type: 'tool-call';
+    callId?: string | undefined;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool-result';
+    callId?: string | undefined;
+    name?: string | undefined;
+    output: unknown;
+    isError?: boolean | undefined;
+};
+/** One message of a conversation: a role and its typed parts. */
+export interface ConversationMessage {
+    role: Role;
+    parts: Part[];
+    /** ISO 8601, when the source transcript carries timestamps. */
+    timestamp?: string | undefined;
+}
+/** Token counts for a run. Each field is present only when the agent reports it. */
+export interface Usage {
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+    cacheReadTokens?: number | undefined;
+    cacheWriteTokens?: number | undefined;
+    totalTokens?: number | undefined;
+}
+/** A run lifted into the normalized model, with the untouched source kept in `raw`. */
+export interface Conversation {
+    schema: typeof CONVERSATION_SCHEMA;
+    /** Adapter name, e.g. "claude". */
+    agent: string;
+    model?: string | undefined;
+    sessionId?: string | undefined;
+    messages: ConversationMessage[];
+    usage?: Usage | undefined;
+    costUsd?: number | undefined;
+    durationMs?: number | undefined;
+    stopReason?: string | undefined;
+    /** The untouched source transcript. `format` names the source encoding. */
+    raw: {
+        format: string;
+        data: unknown;
+    };
+}
+/** Concatenated text of every `text` part from assistant messages. */
+export declare function assistantText(conversation: Conversation): string;
+/** Every tool call across the conversation, in order. */
+export declare function toolCalls(conversation: Conversation): Array<Extract<Part, {
+    type: 'tool-call';
+}>>;

package/dist/conversation.js

@@ -0,0 +1,37 @@
+/**
+ * The normalized conversation data model — the optional layer on top of the
+ * caller abstraction. Every adapter can lift its raw transcript into this
+ * shape for post-facto analysis; the raw payload is always preserved in
+ * `Conversation.raw` so normalization never loses information.
+ *
+ * The shape follows the common core of the OpenTelemetry GenAI conventions
+ * and the Vercel AI SDK message model: role-tagged messages made of typed
+ * parts (text, reasoning, tool-call, tool-result), plus run-level usage,
+ * cost, and timing.
+ */
+/** The `Conversation.schema` value of this data model; its version is part of the string. */
+export const CONVERSATION_SCHEMA = 'agent-conversation/1';
+/** Concatenated text of every `text` part from assistant messages. */
+export function assistantText(conversation) {
+    const chunks = [];
+    for (const message of conversation.messages) {
+        if (message.role !== 'assistant')
+            continue;
+        for (const part of message.parts) {
+            if (part.type === 'text' && part.text !== '')
+                chunks.push(part.text);
+        }
+    }
+    return chunks.join('\n');
+}
+/** Every tool call across the conversation, in order. */
+export function toolCalls(conversation) {
+    const calls = [];
+    for (const message of conversation.messages) {
+        for (const part of message.parts) {
+            if (part.type === 'tool-call')
+                calls.push(part);
+        }
+    }
+    return calls;
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export { EFFORT_LEVELS } from './models.js';
+export type { EffortLevel } from './models.js';
+export type { AgentCallSpec, AgentName, ContextSpec, McpSpec, OutputFormat, OutputSpec, PermissionMode, PermissionSpec, PluginSpec, SessionSpec, } from './spec.js';
+export { TMP_TOKEN } from './plan.js';
+export type { CapabilityNote, PlannedCall, Support, TempFile } from './plan.js';
+export { modelArgs, modelArgsRefusal } from './model-args.js';
+export type { ModelChoice } from './model-args.js';
+export { callAgent, planCall } from './run.js';
+export type { AgentResult, CallError, CallOptions } from './run.js';
+export { adapterFor, BUILTIN_AGENTS, detectAgents } from './registry.js';
+export type { AgentAvailability } from './registry.js';
+export { claudeAdapter, claudePluginArgv, claudeResumeFlag } from './adapters/claude.js';
+export type { ClaudeAdapterOptions } from './adapters/claude.js';
+export { codexAdapter } from './adapters/codex.js';
+export type { CodexAdapterOptions } from './adapters/codex.js';
+export { antigravityAdapter } from './adapters/antigravity.js';
+export type { AntigravityAdapterOptions } from './adapters/antigravity.js';
+export { opencodeAdapter } from './adapters/opencode.js';
+export type { OpencodeAdapterOptions } from './adapters/opencode.js';
+export { customAdapter } from './adapters/custom.js';
+export type { CustomAdapterOptions } from './adapters/custom.js';
+export { templateAdapter, templateRefusal } from './adapters/template.js';
+export type { TemplateAdapterOptions } from './adapters/template.js';
+export type { AgentAdapter, ParsedOutput, RawProcessOutput } from './adapters/types.js';
+export { assistantText, CONVERSATION_SCHEMA, toolCalls } from './conversation.js';
+export type { Conversation, ConversationMessage, Part, Role, Usage } from './conversation.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+export { EFFORT_LEVELS } from './models.js';
+export { TMP_TOKEN } from './plan.js';
+export { modelArgs, modelArgsRefusal } from './model-args.js';
+export { callAgent, planCall } from './run.js';
+export { adapterFor, BUILTIN_AGENTS, detectAgents } from './registry.js';
+export { claudeAdapter, claudePluginArgv, claudeResumeFlag } from './adapters/claude.js';
+export { codexAdapter } from './adapters/codex.js';
+export { antigravityAdapter } from './adapters/antigravity.js';
+export { opencodeAdapter } from './adapters/opencode.js';
+export { customAdapter } from './adapters/custom.js';
+export { templateAdapter, templateRefusal } from './adapters/template.js';
+export { assistantText, CONVERSATION_SCHEMA, toolCalls } from './conversation.js';

package/dist/model-args.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A resolved model and effort to hand a tool's CLI; all optional, none validated here.
+ *
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export interface ModelChoice {
+    model?: string | undefined;
+    effort?: string | undefined;
+    /**
+     * The launch mode the model's provider needs, as flags (codex reaches a
+     * local Ollama model only as `--oss --local-provider ollama`). Passed
+     * before the model flag.
+     */
+    via?: readonly string[] | undefined;
+}
+/**
+ * Why `tool`'s argv cannot take `choice`, or `null` when it can (a tool with
+ * nothing asked of it always can). Only claude, codex and pi have model and
+ * effort flags wired here; any other tool refuses rather than dropping the
+ * choice silently.
+ *
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export declare function modelArgsRefusal(tool: string, choice: ModelChoice): string | null;
+/**
+ * The CLI flags that select `choice` for `tool`, using the headless adapters'
+ * own flag rules: claude `--model <m> --effort <e>`, codex `--model <m> -c
+ * model_reasoning_effort="<e>"`, pi `--model <m> --thinking <e>` (the model as
+ * given, `provider/id` included, e.g. `ollama/qwen3:4b`). A launch mode
+ * (`choice.via`) goes first: codex `--oss --local-provider ollama --model
+ * gemma3:4b`. Empty when nothing is set.
+ *
+ * @throws {Error} For a tool with no flags wired, naming the tool and what was
+ * asked ({@link modelArgsRefusal} gives the same text without throwing).
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export declare function modelArgs(tool: string, choice: ModelChoice): string[];

package/dist/model-args.js

@@ -0,0 +1,58 @@
+import { claudeEffortArgv } from './adapters/claude.js';
+import { codexEffortArgv } from './adapters/codex.js';
+import { modelFlag } from './adapters/shared.js';
+/**
+ * Each tool's effort flag, keyed by tool name: the tools whose command line a
+ * caller builds itself with a model and an effort. A tool run through an
+ * adapter or a template translates its own. pi's `--thinking <level>` takes
+ * `off` through `max`, so a level passes through as given.
+ */
+const EFFORT_ARGV = {
+    claude: claudeEffortArgv,
+    codex: codexEffortArgv,
+    pi: (effort) => ['--thinking', effort],
+};
+/**
+ * Why `tool`'s argv cannot take `choice`, or `null` when it can (a tool with
+ * nothing asked of it always can). Only claude, codex and pi have model and
+ * effort flags wired here; any other tool refuses rather than dropping the
+ * choice silently.
+ *
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export function modelArgsRefusal(tool, choice) {
+    const via = choice.via ?? [];
+    if (choice.model === undefined && choice.effort === undefined && via.length === 0)
+        return null;
+    if (Object.hasOwn(EFFORT_ARGV, tool))
+        return null;
+    const asked = [
+        ...(via.length > 0 ? [`launch mode '${via.join(' ')}'`] : []),
+        ...(choice.model !== undefined ? [`model '${choice.model}'`] : []),
+        ...(choice.effort !== undefined ? [`effort '${choice.effort}'`] : []),
+    ].join(' and ');
+    return `tool '${tool}' has no model or effort flags wired; cannot pass ${asked}`;
+}
+/**
+ * The CLI flags that select `choice` for `tool`, using the headless adapters'
+ * own flag rules: claude `--model <m> --effort <e>`, codex `--model <m> -c
+ * model_reasoning_effort="<e>"`, pi `--model <m> --thinking <e>` (the model as
+ * given, `provider/id` included, e.g. `ollama/qwen3:4b`). A launch mode
+ * (`choice.via`) goes first: codex `--oss --local-provider ollama --model
+ * gemma3:4b`. Empty when nothing is set.
+ *
+ * @throws {Error} For a tool with no flags wired, naming the tool and what was
+ * asked ({@link modelArgsRefusal} gives the same text without throwing).
+ * @experimental Part of the launch-argv helpers, which may change in a minor release.
+ */
+export function modelArgs(tool, choice) {
+    const refusal = modelArgsRefusal(tool, choice);
+    if (refusal !== null)
+        throw new Error(refusal);
+    // A set field got past the refusal, so `tool` is in EFFORT_ARGV.
+    return [
+        ...(choice.via ?? []),
+        ...(choice.model !== undefined ? modelFlag(choice.model) : []),
+        ...(choice.effort !== undefined ? EFFORT_ARGV[tool](choice.effort) : []),
+    ];
+}

package/dist/models.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reasoning-effort intent, a separate axis from model choice: the closed set
+ * the adapters translate. Maps to claude `--effort`, codex
+ * `model_reasoning_effort`, antigravity `--effort` (clamped to `high`), opencode
+ * `--variant`. Frozen at run time.
+ */
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+/** One of {@link EFFORT_LEVELS}. */
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];

package/dist/models.js

@@ -0,0 +1,12 @@
+// Node-free entry point (the package's `./models` subpath export): the effort vocabulary.
+// Imports nothing, so a browser bundle can take it without pulling in the
+// process runner (`node:child_process`) that the package barrel re-exports.
+// This package takes a resolved model; which levels a model accepts is not
+// decided here.
+/**
+ * Reasoning-effort intent, a separate axis from model choice: the closed set
+ * the adapters translate. Maps to claude `--effort`, codex
+ * `model_reasoning_effort`, antigravity `--effort` (clamped to `high`), opencode
+ * `--variant`. Frozen at run time.
+ */
+export const EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);

package/dist/plan.d.ts

@@ -0,0 +1,56 @@
+import type { AgentCallSpec, OutputFormat } from './spec.js';
+/**
+ * How faithfully a spec field survived translation to a concrete CLI call.
+ *
+ * - `native`       — the CLI has a first-class flag for it.
+ * - `approximated` — mapped to the closest available behavior.
+ * - `emulated`     — reproduced through prompt engineering or env plumbing.
+ * - `dropped`      — the CLI has no way to express it; the field was ignored.
+ */
+export type Support = 'native' | 'approximated' | 'emulated' | 'dropped';
+/** How one spec field was translated for one CLI, and why. */
+export interface CapabilityNote {
+    /** Dotted path into the spec, e.g. `"permissions.mode"`. */
+    field: string;
+    support: Support;
+    detail: string;
+}
+/**
+ * Placeholder that adapters embed in argv/env values wherever a temp-file
+ * path is needed. The runner replaces it with a real per-call temp directory
+ * after materializing `PlannedCall.tempFiles`.
+ */
+export declare const TMP_TOKEN = "__AGENT_CALL_TMP__";
+/** A file the runner writes into the per-call temp directory before the spawn. */
+export interface TempFile {
+    /** File name inside the per-call temp directory. */
+    name: string;
+    /** Content written before spawn. Empty string reserves the path only. */
+    content: string;
+    /** Read the file back after the run (exposed as `RawProcessOutput.files`). */
+    readBack?: boolean | undefined;
+}
+/**
+ * A fully translated call: pure data, no side effects. `planCall()` produces
+ * one without running anything, so you can inspect, log, or golden-test the
+ * exact invocation an adapter would make.
+ */
+export interface PlannedCall {
+    agent: string;
+    /** argv[0] is the binary. */
+    argv: string[];
+    /** Written to the child's stdin when set (how most prompts travel). */
+    stdin?: string | undefined;
+    /** The prompt when it travels in argv rather than stdin, kept so a conversation can report it. */
+    prompt?: string | undefined;
+    /** Environment additions (merged over the parent env by the runner). */
+    env: Record<string, string>;
+    cwd?: string | undefined;
+    /** The output format actually requested from the CLI. */
+    outputFormat: OutputFormat;
+    tempFiles: TempFile[];
+    notes: CapabilityNote[];
+    /** The canonical spec this call was planned from. */
+    spec: AgentCallSpec;
+}
+export declare function note(notes: CapabilityNote[], field: string, support: Support, detail: string): void;

package/dist/plan.js

@@ -0,0 +1,9 @@
+/**
+ * Placeholder that adapters embed in argv/env values wherever a temp-file
+ * path is needed. The runner replaces it with a real per-call temp directory
+ * after materializing `PlannedCall.tempFiles`.
+ */
+export const TMP_TOKEN = '__AGENT_CALL_TMP__';
+export function note(notes, field, support, detail) {
+    notes.push({ field, support, detail });
+}