@womp/spark-agent 3.0.3 → 4.0.1

package/README.md

@@ -1,7 +1,7 @@
 # @womp/spark-agent
 
-Portable AI agent for Womp applications and Kakapo scenes with model-authored JavaScript.
-
+Portable AI agent for Womp applications and Kakapo scenes with model-authored JavaScript.
+
 Spark Agent uses AI SDK 7 `UIMessage` and `UIMessageChunk` as its public chat protocol. Generated
 JavaScript uses the host's executor and capabilities. Native browser execution and isolated QuickJS
 execution use the same model loop. The host owns conversations, artifacts, authorization, and connections.
@@ -16,7 +16,47 @@ execution use the same model loop. The host owns conversations, artifacts, autho
 npm install @womp/spark-agent
 ```
 
-## Package entry points
+## Run a prompt from the command line
+
+With the Spark server already running:
+
+```sh
+yarn agent-run --prompt "Make a cube" --model gpt-5.6-luna --reasoning max
+```
+
+Use `--conversation <id>` to continue a thread and `--output <new-directory>` to save
+`result.json`, `transcript.json` and original run artifacts under `artifacts/`.
+For local runs, use the git-ignored `.spark/` directory, with a fresh subdirectory per run:
+
+```sh
+yarn agent-run --prompt "Make rainbow-colored boxes" --output .spark/agent-runs/rainbow-boxes
+yarn agent-run --prompt "Model this object using both views" --image front.png --image side.jpg --output .spark/agent-runs/reference-model
+```
+
+Repeat `--image <path>` for local PNG, JPEG, WebP or GIF references, in argument order.
+The required prompt and all images are sent in one user message. Files, format signatures,
+and the full JSON request size (including base64 overhead) are checked before contacting the server.
+The CLI uses the server's default 25 MiB request limit; a custom server or provider may impose
+stricter limits. Images are never resized, and remote URLs are not accepted.
+With `--output`, original bytes are saved under `inputs/`; `input.json` and the result's `input`
+field list ordered original filenames, MIME types and relative paths. The submitted message in
+`transcript.json` uses those paths instead of inline data. Generated artifacts stay in `artifacts/`.
+
+Without output, artifacts remain server references. The CLI never clears the scene or
+takes extra screenshots. Defaults are `gpt-6-astra`, `high`, and
+`--api http://127.0.0.1:8787/agent`; unsupported settings are rejected.
+
+Progress goes to stderr; one JSON result goes to stdout. Use `yarn --silent agent-run`
+or the installed `agent-run` executable when parsing stdout (Yarn otherwise adds banners).
+Usage comes from the provider, with per-step USD estimates; missing usage is not estimated.
+Exit codes: 0 completed, 1 run/transport/export failure, 2 invalid arguments,
+3 requires user action (continue in the UI), 130 interrupted. Interrupts attempt to cancel
+only this invocation's run; a failed cancellation is reported and the run may still be active.
+Output directories must not already exist. Artifact manifests include IDs, media types,
+server URLs and relative paths; failed downloads retain their references and report errors.
+Legacy inline base64 uploads in transcripts are replaced with `[inline data omitted]`.
+
+## Package entry points
 
 - `@womp/spark-agent` — browser-safe model loop, two tools, persistence hooks, and shared contracts
 - `@womp/spark-agent/browser` — native JavaScript executor and local chat transport
@@ -60,26 +100,9 @@ the terminal checkpoint. A host run owner must keep consuming when a view detach
 A failed barrier aborts the loop. The default model-step limit is 100; a limit returns
 `status: "incomplete"`. A host must not automatically restart to bypass that limit.
 
-Before each model request Spark applies an estimated input budget (`maxInputTokens`, default 64,000).
-It first removes duplicate skill bodies and execution observations, then abbreviates older skill reads
-while retaining the latest workflow/reference pair. The agent must read an abbreviated skill again
-before using its API. Older completed scripts can be shortened only when their committed receipts and
-results remain available and their inputs are not tied to provider reasoning/signatures. Requests,
-tool pairs, targets, artifacts, receipts, errors, and unresolved work remain in context; persisted
-history is never shortened. If this cannot fit, the run returns `incomplete` with `context-limit` and
-an actionable explanation, without another model request or automatic replay.
-
-When older successful execution results contain images, their binary content can be omitted from model
-input while preserving artifact references, receipts, and observations. The latest visual result,
-user-provided media, failed/uncertain results, and provider-owned content remain intact. The agent can
-inspect an older artifact again with `emitImage` or `emitFile`; stored history retains the full result.
-Call metadata copied by the SDK onto local tool results is preserved during this trimming; it does not
-prevent compaction of the host-produced image bytes. Original model calls and signatures are unchanged.
-
-Token sizing is approximate (UTF-8 text bytes / 3 plus an 8,192-token allowance per image/file and
-2,048 for tool schemas/framing). This is an application input budget, not provider capacity metadata.
-Hosts should choose it alongside the selected model's output budget and verify their deployed models;
-the estimate cannot guarantee a provider accepts every document or image size.
+Spark does not estimate or limit input tokens or automatically shorten conversation history.
+The provider enforces its context limit; rejections follow the normal provider-error path.
+Provider-reported usage and cost tracking are unchanged.
 
 Screenshot and file APIs return serializable artifact references. `emitImage` and `emitFile` resolve
 them through the host's artifact resolver. Keep references resolvable when reloading history, and
@@ -137,12 +160,23 @@ Closing or reloading the page only detaches the SSE subscriber. It does not canc
 `SparkChatTransport` hides the durable run lifecycle from `useChat`:
 
 ```text
-POST /agent/conversations/:conversationId/messages
+POST /agent/conversations/:conversationId/messages
+PATCH /agent/conversations/:conversationId/settings
 GET  /agent/runs/:runId/stream?after=0
 POST /agent/runs/:runId/cancel
 ```
 
-The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
+Conversation settings contain `modelId` and `reasoningEffort`. The standalone UI saves selector
+changes immediately through `transport.saveConversationSettings(id, settings)` and restores them
+per thread. Older threads fall back to their last recorded model (or the default) and medium effort;
+unsupported choices fall back to supported settings. Assistant footers show the model recorded on
+that turn, independently of the selector.
+
+Custom stores must implement `saveConversationSettings` as a settings-only update, and preserve
+stored settings during `saveConversation` so streaming history saves cannot overwrite preferences.
+The built-in memory and SQLite stores do this without a database migration.
+
+The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
 
 ```ts
 type StoredSparkChunk = {
@@ -330,14 +364,6 @@ Releases use a manual package publication; no separate release service is requir
 - Custom JavaScript executors must honor cancellation and host-owned user waits. Callback-based
   scene edits and artifact references work with both the native and QuickJS executors.
 
-### 0.3.1 context defaults
-
-- The default input context budget is now 128,000 estimated tokens. Hosts can still
-  set `maxInputTokens` explicitly; this budget does not change the provider's context limit.
-- Images, including images in tool results, use a 512-token estimate instead of the
-  general 8,192-token file allowance. Encoded media bytes remain excluded from text
-  estimates. Token accounting is heuristic; no API or storage migration is required.
-
 ### Publishing
 
 1. Choose an unused package version after checking `npm view @womp/spark-agent versions --json`.

package/dist/agent-run-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/agent-run-cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { agentRunJson, parseAgentRunArgs, runAgent } from "./agent-run.js";
+const controller = new AbortController();
+const interrupt = () => controller.abort(new Error("Interrupted; requesting run cancellation."));
+process.once("SIGINT", interrupt);
+process.once("SIGTERM", interrupt);
+try {
+    const options = parseAgentRunArgs(process.argv.slice(2));
+    if (!options) {
+        process.stderr.write("Usage: agent-run --prompt <text> [--image <path>]... [--model <id>] [--reasoning <level>] [--conversation <id>] [--api <url>] [--output <new-directory>]\nImages: local PNG, JPEG, WebP or GIF, in argument order; 25 MiB maximum encoded request.\nDefaults: gpt-6-astra, high, http://127.0.0.1:8787/agent\n");
+    }
+    else {
+        const result = await runAgent({ ...options, signal: controller.signal, progress: (text) => { process.stderr.write(text); } });
+        process.stdout.write(`${agentRunJson(result)}\n`);
+        process.exitCode = result.exitCode;
+    }
+}
+catch (error) {
+    process.stdout.write(`${agentRunJson({
+        conversationId: null, runId: null, status: "failed", finalAnswer: "", durationMs: null,
+        steps: 0, toolCounts: {}, requiredActions: [], usage: { total: null, steps: [] },
+        cost: { currency: "USD", totalUsd: null, status: "unavailable", steps: [] }, artifacts: [],
+        errors: [error instanceof Error ? error.message : String(error)], exitCode: 2,
+    })}\n`);
+    process.exitCode = 2;
+}
+finally {
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", interrupt);
+}

package/dist/agent-run-input.d.ts

@@ -0,0 +1,11 @@
+import type { SparkRunSettings } from "./server/types.js";
+import type { SparkUIMessage } from "./ui.js";
+export declare function prepareAgentInput(prompt: string, images: string[], settings: SparkRunSettings): Promise<{
+    message: SparkUIMessage;
+    files: {
+        filename: string;
+        mediaType: string;
+        path: string;
+        bytes: Buffer;
+    }[];
+}>;

package/dist/agent-run-input.js

@@ -0,0 +1,59 @@
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_JSON_LIMIT_BYTES } from "./request-limits.js";
+const formats = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" };
+function matchesFormat(bytes, mediaType) {
+    switch (mediaType) {
+        case "image/png": return bytes.length >= 45 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) &&
+            bytes.toString("ascii", 12, 16) === "IHDR" && bytes.readUInt32BE(16) > 0 && bytes.readUInt32BE(20) > 0 && bytes.toString("ascii", bytes.length - 8, bytes.length - 4) === "IEND";
+        case "image/jpeg": return bytes.length >= 20 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255 && bytes.at(-2) === 255 && bytes.at(-1) === 217;
+        case "image/gif": return bytes.length >= 14 && ["GIF87a", "GIF89a"].includes(bytes.toString("ascii", 0, 6)) &&
+            bytes.readUInt16LE(6) > 0 && bytes.readUInt16LE(8) > 0 && bytes.at(-1) === 59;
+        case "image/webp": return bytes.length >= 30 && bytes.toString("ascii", 0, 4) === "RIFF" &&
+            bytes.toString("ascii", 8, 12) === "WEBP" && ["VP8 ", "VP8L", "VP8X"].includes(bytes.toString("ascii", 12, 16)) && bytes.readUInt32LE(4) + 8 === bytes.length;
+        default: return false;
+    }
+}
+export async function prepareAgentInput(prompt, images, settings) {
+    if (!prompt.trim())
+        throw new Error("--prompt must contain text.");
+    const message = { id: crypto.randomUUID(), role: "user", parts: [{ type: "text", text: prompt }] };
+    const files = [];
+    // Match SparkChatTransport's submit body, including JSON escaping and UTF-8 text.
+    let requestBytes = Buffer.byteLength(JSON.stringify({ trigger: "submit-message", message, settings }));
+    const checkSize = (size) => {
+        if (size > DEFAULT_JSON_LIMIT_BYTES)
+            throw new Error("Request exceeds 25 MiB including prompt, images, base64 overhead and JSON. Use smaller inputs; images are not resized.");
+    };
+    checkSize(requestBytes);
+    for (const image of images) {
+        if (!image.trim() || /^(?:[a-z][a-z0-9+.-]*:\/\/|data:|file:)/iu.test(image))
+            throw new Error("--image requires a local file path, not a URL.");
+        const extension = path.extname(image).toLowerCase();
+        const mediaType = formats[extension];
+        if (!mediaType)
+            throw new Error(`Unsupported image format for ${image}. Use PNG, JPEG, WebP or GIF.`);
+        const filename = path.basename(image);
+        const part = { type: "file", filename, mediaType, url: `data:${mediaType};base64,` };
+        const overhead = 1 + Buffer.byteLength(JSON.stringify(part)); // Array comma and the file part without base64.
+        const file = await open(image, "r").catch((error) => { throw new Error(`Cannot read image ${image}: ${error.message}`); });
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size === 0)
+                throw new Error(`Image ${image} must be a nonempty regular file.`);
+            checkSize(requestBytes + overhead + 4 * Math.ceil(stat.size / 3));
+            const bytes = await file.readFile();
+            requestBytes += overhead + 4 * Math.ceil(bytes.length / 3);
+            checkSize(requestBytes);
+            if (!matchesFormat(bytes, mediaType))
+                throw new Error(`Invalid or truncated ${mediaType} file: ${image}`);
+            part.url += bytes.toString("base64");
+            message.parts.push(part);
+            files.push({ filename, mediaType, path: `inputs/${files.length + 1}${extension}`, bytes });
+        }
+        finally {
+            await file.close();
+        }
+    }
+    return { message, files };
+}

package/dist/agent-run.d.ts

@@ -0,0 +1,81 @@
+import { type ReasoningEffort } from "./models.js";
+import type { SparkRunSettings } from "./server/types.js";
+import type { SparkArtifact } from "./ui.js";
+export declare function parseAgentRunArgs(args: string[]): {
+    prompt: string;
+    api: string;
+    conversation: string | undefined;
+    output: string | undefined;
+    images: string[];
+    settings: {
+        modelId: "gpt-6-astra" | "gpt-5.6-luna" | "gemini-3.8-flash" | "claude-opus-5" | "claude-fable-5";
+        reasoningEffort: ReasoningEffort;
+    };
+} | null;
+type RunOptions = {
+    prompt: string;
+    api: string;
+    conversation?: string;
+    output?: string;
+    images?: string[];
+    settings: SparkRunSettings;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+    progress?: (text: string) => void;
+};
+type ArtifactReference = SparkArtifact & {
+    path?: string;
+    error?: string;
+};
+export declare function agentRunJson(value: unknown, space?: number): string;
+export declare function runAgent(options: RunOptions): Promise<{
+    artifacts: ArtifactReference[];
+    errors: string[];
+    exitCode: number;
+    input?: {
+        messageId: string;
+        prompt: string;
+        images: {
+            path?: string | undefined;
+            filename: string;
+            mediaType: string;
+        }[];
+    } | undefined;
+    conversationId: string | null;
+    runId: string | null;
+    status: "queued" | "running" | "requires_action" | "completed" | "failed" | "cancelled" | "incomplete";
+    finalAnswer: string;
+    durationMs: number | null;
+    steps: number;
+    toolCounts: Record<string, number>;
+    requiredActions: import("ai").UIMessagePart<import("./ui.js").SparkDataParts, import("./ui.js").SparkUITools>[];
+    usage: {
+        total: unknown;
+        steps: {
+            step: number;
+            usage: {} | null;
+        }[];
+    };
+    cost: {
+        currency: string;
+        totalUsd: number | null;
+        status: "unavailable" | "partial" | "estimated";
+        steps: {
+            step: number;
+            cost: {
+                modelId: string;
+                pricingDate: string;
+                totalUsd: number | null;
+                lines: {
+                    label: string;
+                    tokens: number;
+                    usdPerMillion: number;
+                    usd: number;
+                }[];
+                source?: string | undefined;
+                reason?: string | undefined;
+            } | null;
+        }[];
+    };
+}>;
+export {};

package/dist/agent-run.js

@@ -0,0 +1,234 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { SparkChatTransport } from "./client.js";
+import { DEFAULT_MODEL_ID, SPARK_MODELS } from "./models.js";
+import { createBenchMetrics } from "./run-metrics.js";
+import { prepareAgentInput } from "./agent-run-input.js";
+export function parseAgentRunArgs(args) {
+    const { values } = parseArgs({ args, options: {
+            prompt: { type: "string" }, model: { type: "string", default: DEFAULT_MODEL_ID },
+            reasoning: { type: "string", default: "high" }, conversation: { type: "string" },
+            api: { type: "string", default: "http://127.0.0.1:8787/agent" },
+            output: { type: "string" }, image: { type: "string", multiple: true }, help: { type: "boolean" },
+        } });
+    if (values.help)
+        return null;
+    if (!values.prompt?.trim())
+        throw new Error("--prompt must contain text.");
+    const model = SPARK_MODELS.find((item) => item.id === values.model);
+    if (!model)
+        throw new Error(`Unknown model: ${values.model}`);
+    if (!model.reasoningEfforts.includes(values.reasoning)) {
+        throw new Error(`${model.id} supports reasoning: ${model.reasoningEfforts.join(", ")}`);
+    }
+    if (values.conversation !== undefined && !values.conversation.trim())
+        throw new Error("--conversation must not be empty.");
+    if (values.output !== undefined && !values.output.trim())
+        throw new Error("--output must not be empty.");
+    const api = new URL(values.api);
+    if (!["http:", "https:"].includes(api.protocol) || api.username || api.password || api.search || api.hash) {
+        throw new Error("--api must be an HTTP(S) URL without credentials, query or fragment.");
+    }
+    return {
+        prompt: values.prompt, api: api.href.replace(/\/$/u, ""), conversation: values.conversation,
+        output: values.output, images: values.image ?? [],
+        settings: { modelId: model.id, reasoningEffort: values.reasoning },
+    };
+}
+// Older threads may contain inline uploads; exports keep references, not embedded bytes.
+export function agentRunJson(value, space) {
+    return JSON.stringify(value, (_key, item) => typeof item === "string" && /^data:[^,]*;base64,/iu.test(item) ? "[inline data omitted]" : item, space);
+}
+export async function runAgent(options) {
+    const { message, files } = await prepareAgentInput(options.prompt, options.images ?? [], options.settings);
+    const input = {
+        messageId: message.id, prompt: options.prompt,
+        images: files.map(({ filename, mediaType, path }) => ({ filename, mediaType, ...(options.output ? { path } : {}) })),
+    };
+    const metrics = createBenchMetrics();
+    const artifacts = new Map();
+    const errors = [];
+    let conversation;
+    let run;
+    let status = "failed";
+    let started;
+    let durationMs = null;
+    let answer = "";
+    let usage = null;
+    let requiredActions = [];
+    let outputReady = false;
+    let cleanup = false;
+    const request = (input, init) => (options.fetch ?? fetch)(input, {
+        ...init,
+        signal: AbortSignal.any([
+            ...(!cleanup && options.signal ? [options.signal] : []),
+            ...(init?.signal ? [init.signal] : []),
+            // Streaming requests keep running until a terminal event or interruption.
+            ...(!String(input).includes("/stream?") ? [AbortSignal.timeout(30_000)] : []),
+        ]),
+    });
+    const transport = new SparkChatTransport({
+        api: options.api, fetch: request, getSettings: () => options.settings,
+        onRun: (value) => {
+            run = value;
+            status = value.status;
+            if (value.settings.modelId !== options.settings.modelId || value.settings.reasoningEffort !== options.settings.reasoningEffort) {
+                throw new Error("Server returned different model/reasoning settings; cancelling the run.");
+            }
+        },
+    });
+    const terminal = () => !["queued", "running"].includes(status);
+    try {
+        if (options.output) {
+            await mkdir(path.dirname(path.resolve(options.output)), { recursive: true });
+            await mkdir(options.output);
+            outputReady = true;
+            if (files.length) {
+                await mkdir(path.join(options.output, "inputs"));
+                for (const file of files)
+                    await writeFile(path.join(options.output, file.path), file.bytes);
+                await writeFile(path.join(options.output, "input.json"), agentRunJson(input, 2));
+            }
+        }
+        options.signal?.throwIfAborted();
+        conversation = options.conversation
+            ? await transport.getConversation(options.conversation)
+            : await transport.createConversation({ title: options.prompt.slice(0, 100) });
+        started = performance.now();
+        const stream = await transport.sendMessages({
+            trigger: "submit-message", chatId: conversation.id, messageId: undefined,
+            messages: [message],
+            abortSignal: options.signal,
+        });
+        for await (const value of stream) {
+            const chunk = value;
+            metrics.accept(chunk);
+            if (chunk.type === "text-delta") {
+                answer += chunk.delta;
+                options.progress?.(chunk.delta);
+            }
+            if (chunk.type === "tool-input-available")
+                options.progress?.(`\n[tool: ${chunk.toolName}]\n`);
+            if (chunk.type === "data-artifact")
+                artifacts.set(chunk.data.id, chunk.data);
+            if (chunk.type === "error")
+                errors.push(chunk.errorText);
+            if (chunk.type === "data-run-status") {
+                status = chunk.data.status;
+                options.progress?.(`\n[${status}]\n`);
+                if (chunk.data.error)
+                    errors.push(chunk.data.error);
+                if (terminal())
+                    break;
+            }
+        }
+        if (!terminal())
+            throw new Error("Run stream ended without a terminal status.");
+    }
+    catch (error) {
+        durationMs = started === undefined ? null : Math.round(performance.now() - started);
+        errors.push(error instanceof Error ? error.message : String(error));
+        cleanup = true;
+        if (run && conversation && !terminal()) {
+            try {
+                status = (await transport.getRun(run.id)).status;
+                if (!terminal())
+                    status = (await transport.cancelRun(conversation.id))?.status ?? "incomplete";
+            }
+            catch (error) {
+                status = "incomplete";
+                errors.push(`Cancellation failed: ${String(error)}`);
+            }
+        }
+    }
+    finally {
+        durationMs ??= started === undefined ? null : Math.round(performance.now() - started);
+        cleanup = true;
+    }
+    if (run && conversation) {
+        try {
+            conversation = await transport.getConversation(conversation.id);
+            const reply = conversation.messages.find((message) => message.id === run.assistantMessageId);
+            if (reply) {
+                answer = reply.parts.filter((part) => part.type === "text").map((part) => part.text).join("\n\n");
+                usage = reply.metadata?.usage ?? null;
+                if (reply.metadata?.error)
+                    errors.push(reply.metadata.error);
+                if (status === "requires_action")
+                    requiredActions = reply.parts.filter((part) => "state" in part && (part.state === "input-available" || part.state === "approval-requested"));
+                for (const part of reply.parts) {
+                    if (part.type === "data-artifact")
+                        artifacts.set(part.data.id, part.data);
+                    if (part.type === "tool-execute_javascript" && part.state === "output-available") {
+                        for (const item of part.output.artifacts)
+                            artifacts.set(item.artifact.id, item.artifact);
+                    }
+                }
+            }
+            else if (status === "completed")
+                errors.push("Completed assistant message is missing from the transcript.");
+        }
+        catch (error) {
+            errors.push(`Transcript retrieval failed: ${String(error)}`);
+        }
+    }
+    if (outputReady) {
+        try {
+            const transcript = conversation ? { ...conversation, messages: conversation.messages.map((item) => {
+                    if (item.id !== message.id || !files.length)
+                        return item;
+                    return { ...item, parts: message.parts.map((part, index) => part.type === "file" ? { ...part, url: files[index - 1].path } : part) };
+                }) } : null;
+            await writeFile(path.join(options.output, "transcript.json"), agentRunJson(transcript, 2));
+            await mkdir(path.join(options.output, "artifacts"));
+            let artifactIndex = 0;
+            for (const artifact of artifacts.values()) {
+                artifactIndex++;
+                try {
+                    const url = new URL(artifact.url, `${options.api}/`);
+                    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+                        throw new Error("Artifact must have an HTTP(S) reference without embedded credentials.");
+                    const response = await request(url.href);
+                    if (!response.ok)
+                        throw new Error(`Download returned HTTP ${response.status}`);
+                    const extension = path.extname(artifact.name ?? "").match(/^\.[a-zA-Z0-9]{1,10}$/u)?.[0]
+                        ?? ({ "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp", "application/pdf": ".pdf" }[artifact.mediaType] ?? ".bin");
+                    const relative = `artifacts/${artifactIndex}${extension}`;
+                    await writeFile(path.join(options.output, relative), new Uint8Array(await response.arrayBuffer()));
+                    artifact.path = relative;
+                }
+                catch (error) {
+                    artifact.error = String(error);
+                    errors.push(`Artifact ${artifact.id}: ${String(error)}`);
+                }
+            }
+        }
+        catch (error) {
+            errors.push(`Output failed: ${String(error)}`);
+        }
+    }
+    const summary = metrics.snapshot();
+    const details = metrics.details();
+    const result = {
+        conversationId: conversation?.id ?? null, runId: run?.id ?? null, status,
+        finalAnswer: answer, durationMs, steps: summary.steps, toolCounts: details.toolCounts, requiredActions,
+        usage: { total: usage, steps: details.steps.map(({ step, usage }) => ({ step, usage: usage ?? null })) },
+        cost: { currency: "USD", totalUsd: summary.costUsd,
+            status: summary.costUsd !== null && !["completed", "requires_action"].includes(status) ? "partial" : summary.costStatus,
+            steps: details.steps.map(({ step, cost }) => ({ step, cost: cost ?? null })) },
+        ...(files.length ? { input } : {}),
+        artifacts: Array.from(artifacts.values()), errors: Array.from(new Set(errors)),
+        exitCode: options.signal?.aborted ? 130 : errors.length ? 1 : status === "completed" ? 0 : status === "requires_action" ? 3 : 1,
+    };
+    if (outputReady) {
+        try {
+            await writeFile(path.join(options.output, "result.json"), agentRunJson(result, 2));
+        }
+        catch (error) {
+            result.errors.push(`Result output failed: ${String(error)}`);
+            result.exitCode = 1;
+        }
+    }
+    return result;
+}

package/dist/agent-tools.js

@@ -20,6 +20,7 @@ const artifactRefSchema = z.object({
 });
 export function createSparkTools(options) {
     const { controller, persistence } = options;
+    const executionTimeoutMs = options.executionTimeoutMs ?? 60_000;
     const persist = async (action) => {
         if (action === undefined)
             return;
@@ -58,7 +59,7 @@ export function createSparkTools(options) {
             }),
         }),
         execute_javascript: tool({
-            description: "Run an async JavaScript body against the APIs discovered through skills. Use print, emitImage, and emitFile for output. Each call has a fresh local scope; capabilities own their commit boundaries.",
+            description: `Run an async JavaScript body against the APIs discovered through skills. Use print, emitImage, and emitFile for output. Each call has a fresh local scope; capabilities own their commit boundaries. Execution budget: ${executionTimeoutMs} ms per call, excluding registered user/service waits (not all awaits).`,
             inputSchema: z.object({
                 purpose: z.string().min(1).max(240),
                 code: z.string().min(1).max(60_000),
@@ -160,7 +161,7 @@ export function createSparkTools(options) {
                         },
                         emitImage: (ref) => emit(ref, "image"),
                         emitFile: (ref) => emit(ref, "file"),
-                    }, options.executionTimeoutMs ?? 60_000, signal, executionWait);
+                    }, executionTimeoutMs, signal, executionWait);
                     await Promise.all(pending);
                     signal.throwIfAborted();
                     return {

package/dist/agent.d.ts

@@ -25,8 +25,6 @@ export type SparkAgentOptions = {
     instructions?: string;
     maxSteps?: number;
     maxOutputTokens?: number;
-    /** Estimated input budget, including instructions and tool framing. Defaults to 64,000. */
-    maxInputTokens?: number;
     executionTimeoutMs?: number;
     persistence?: SparkPersistence;
     prepareMessages?(messages: ModelMessage[]): Promise<ModelMessage[]>;