spl-lang 0.2.0 → 0.3.1

package/dist/interpreter.js

@@ -1,10 +1,11 @@
 import { callMethod, iterate, makeBuiltins } from './builtins.js';
 import { Failure, SuccessSignal } from './errors.js';
-import { LlmError, buildPrompt, parseObjectResponse } from './llm.js';
+import { LlmError, buildPrompt, parseJsonResponse } from './llm.js';
+import { compileSchema } from './schema.js';
 import { Restrictions, makeRestriction } from './restrict.js';
 import { MemoryStore } from './store.js';
 import { ToolHost, TOOL_SPECS } from './tools.js';
-import { compareValues, equals, hasKey, isDict, isFunction, isList, newDict, runtimeError, setKey, str, truthy, typeName, } from './values.js';
+import { compareValues, equals, hasKey, isDict, isFunction, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
 export async function run(program, opts) {
     return new Interpreter(program, opts).run();
 }
@@ -29,10 +30,16 @@ class Interpreter {
         this.maxDepth = opts.maxCallDepth ?? 200;
         this.restrictions = new Restrictions(this.cwd);
         this.builtins = makeBuiltins({ log: (m) => opts.logger.info(`log: ${m}`) });
+        for (const tool of Object.keys(TOOL_SPECS)) {
+            this.builtins.set(tool, { __fn: 'builtin', name: tool, call: (args) => this.callTool(tool, args) });
+        }
     }
     async run() {
         const { logger } = this.opts;
         try {
+            if (this.opts.backend.mode === 'replay' && this.opts.store) {
+                throw new Failure('restriction_violation', 'replay does not allow a persistent variable store');
+            }
             for (const [k, v] of Object.entries(this.store.load()))
                 this.globals.vars.set(k, v);
             const signal = await this.execBlock(this.program.body, this.globals);
@@ -53,11 +60,13 @@ class Interpreter {
         }
         finally {
             try {
-                const snapshot = {};
-                for (const [k, v] of this.globals.vars)
-                    if (!isFunction(v))
-                        snapshot[k] = v;
-                this.store.save(snapshot);
+                if (this.opts.backend.mode !== 'replay') {
+                    const snapshot = {};
+                    for (const [k, v] of this.globals.vars)
+                        if (!isFunction(v))
+                            snapshot[k] = v;
+                    this.store.save(snapshot);
+                }
             }
             catch (e) {
                 logger.error(`could not save variable store: ${e.message}`);
@@ -101,10 +110,13 @@ class Interpreter {
     async execStmtInner(s, env) {
         switch (s.t) {
             case 'let':
-                await this.execLet(s.target, s.op, s.value, env);
+                env.vars.set(s.name, await this.eval(s.value, env));
+                return;
+            case 'assign':
+                await this.execAssign(s.target, s.op, s.value, env);
                 return;
             case 'block':
-                return this.execBlock(s.body, { vars: new Map(), parent: env });
+                return this.execBlock(s.body, env);
             case 'expr':
                 await this.eval(s.e, env);
                 return;
@@ -215,13 +227,14 @@ class Interpreter {
         }
         vars.forEach((v, i) => env.vars.set(v, item[i]));
     }
-    async execLet(target, op, valueExpr, env) {
+    async execAssign(target, op, valueExpr, env) {
         const compute = async (current) => {
             const rhs = await this.eval(valueExpr, env);
             return op === '=' ? rhs : this.binary(op.slice(0, -1), current(), rhs);
         };
         if (target.t === 'name') {
-            // Binds in the current scope, which is what lets a nested block shadow an outer variable.
+            if (!env.vars.has(target.name))
+                throw runtimeError(`cannot assign '${target.name}': declare a local with let first`);
             env.vars.set(target.name, await compute(() => this.lookup(target.name, env)));
             return;
         }
@@ -319,21 +332,10 @@ class Interpreter {
                 const hi = e.hi ? await this.eval(e.hi, env) : undefined;
                 return this.slice(obj, lo, hi);
             }
-            case 'ask': {
-                const prompt = str(await this.eval(e.prompt, env));
-                const text = await this.callLlm({ kind: 'ask', prompt, mods: e.mods });
-                return e.mods.fmt === 'object' ? parseObjectResponse(text) : text;
-            }
-            case 'think': {
-                const prompt = str(await this.eval(e.prompt, env));
-                return this.callLlm({
-                    kind: 'think',
-                    prompt,
-                    effort: e.mods.level ?? 'medium',
-                    show: e.mods.show ?? false,
-                });
-            }
-            case 'tool': return this.evalTool(e.tool, e.params, e.instructions, env);
+            case 'ask':
+            case 'think':
+            case 'agent':
+                return this.evalGeneration(e.t, e.mods, e.prompt, env);
         }
     }
     getKey(d, k) {
@@ -484,29 +486,13 @@ class Interpreter {
         return typeof obj === 'string' ? part.join('') : part;
     }
     // ---- LLM and tools -------------------------------------------------
-    async callLlm(c) {
+    async callLlm(req) {
         const { logger, backend } = this.opts;
-        const req = {
-            kind: c.kind,
-            prompt: buildPrompt({
-                prompt: c.prompt,
-                mods: c.mods,
-                thinking: c.kind === 'think',
-                constraints: this.constraints,
-                restrictions: this.restrictions,
-            }),
-            model: this.model,
-            reasoningEffort: c.effort ?? (c.kind === 'tool' ? 'medium' : undefined),
-            showReasoning: c.show ?? false,
-            restrictions: this.restrictions,
-            tools: new ToolHost(this.restrictions, this.cwd),
-            pinned: c.pinned,
-        };
-        logger.llm(`llm request (${c.kind}):\n${req.prompt}`);
+        logger.llm(`llm request (${req.kind}):\n${req.prompt}`);
         const started = Date.now();
         try {
             const res = await backend.call(req);
-            logger.info(`llm ${c.kind} call: ${JSON.stringify(res.effective)} (${Date.now() - started} ms)`);
+            logger.info(`llm ${req.kind} call: ${JSON.stringify(res.effective)} (${Date.now() - started} ms)`);
             logger.llm(`llm response:\n${res.text}`);
             return res.text.trim();
         }
@@ -518,32 +504,76 @@ class Interpreter {
             throw new Failure('llm_error', e.message ?? String(e));
         }
     }
-    async evalTool(tool, paramExprs, instrExpr, env) {
+    async callTool(tool, args) {
+        const names = TOOL_SPECS[tool].required;
+        if (args.length !== names.length)
+            throw runtimeError(`${tool}() takes ${names.length} argument(s) but ${args.length} were given`);
         const params = {};
-        for (const [k, ex] of Object.entries(paramExprs)) {
-            const v = await this.eval(ex, env);
-            if (k !== 'content' && typeof v !== 'string')
-                throw runtimeError(`${tool}: parameter '${k}' must be a string, got ${typeName(v)}`);
-            params[k] = str(v);
-        }
-        const instructions = str(await this.eval(instrExpr, env));
-        const host = new ToolHost(this.restrictions, this.cwd);
-        // When the script leaves a required parameter out, the LLM calls the tool itself with the fixed ones pinned.
-        if (TOOL_SPECS[tool].required.some((p) => !(p in params))) {
-            if (tool === 'write_file' && params.path !== undefined)
-                this.restrictions.checkPath(params.path, 'write');
-            const fixed = Object.keys(params).length ? ` with these fixed parameters (set by the script): ${JSON.stringify(params)}` : '';
-            return this.callLlm({
-                kind: 'tool',
-                prompt: `Use the ${tool} tool${fixed}. Instructions: ${instructions}`,
-                pinned: { tool, params },
+        names.forEach((name, i) => {
+            if (typeof args[i] !== 'string')
+                throw runtimeError(`${tool}(): ${name} must be a string`);
+            params[name] = args[i];
+        });
+        return new ToolHost(this.restrictions, this.cwd, this.opts.backend.mode === 'replay', true).invoke(tool, params);
+    }
+    async evalGeneration(kind, mods, promptExpr, env) {
+        if (kind === 'agent' && this.opts.backend.mode) {
+            throw new Failure('restriction_violation', 'agents cannot run in record/replay mode; record generation-only workflows');
+        }
+        const options = {};
+        for (const [name, expr] of Object.entries(mods))
+            setKey(options, name, await this.eval(expr, env));
+        const { len, reasoning = kind === 'ask' ? undefined : 'medium', show = false, repairs = 0, model } = options;
+        const fmt = options.fmt ?? ('schema' in options ? 'json' : 'text');
+        if (len !== undefined && len !== 'word' && len !== 'sentence' && len !== 'paragraph' && len !== 'long')
+            throw runtimeError('len must be word, sentence, paragraph, or long');
+        if (fmt !== 'text' && fmt !== 'json' && fmt !== 'object')
+            throw runtimeError('fmt must be text, json, or object');
+        if (reasoning !== undefined && reasoning !== 'low' && reasoning !== 'medium' && reasoning !== 'high')
+            throw runtimeError('reasoning must be low, medium, or high');
+        if (typeof show !== 'boolean')
+            throw runtimeError('show must be True or False');
+        if (model !== undefined && (typeof model !== 'string' || !model.trim()))
+            throw runtimeError('model must be a non-empty string');
+        if (typeof repairs !== 'number' || !Number.isInteger(repairs) || repairs < 0 || repairs > 5)
+            throw runtimeError('repairs must be an integer from 0 to 5');
+        if (kind === 'agent' && repairs !== 0)
+            throw runtimeError('agents cannot use repairs: external actions must not be retried automatically');
+        if (fmt === 'text' && ('schema' in options || repairs !== 0))
+            throw runtimeError('schema and repairs require JSON output');
+        const validate = 'schema' in options ? compileSchema(options.schema) : undefined;
+        let prompt = buildPrompt({
+            prompt: str(await this.eval(promptExpr, env)),
+            mods: { len, fmt: fmt === 'object' ? 'object' : undefined },
+            thinking: reasoning !== undefined,
+            constraints: this.constraints,
+            restrictions: this.restrictions,
+        });
+        if (fmt === 'json')
+            prompt += '\n\nReturn ONLY valid JSON, without prose or code fences.';
+        if (validate)
+            prompt += `\n\nThe result must satisfy this JSON Schema:\n${JSON.stringify(toJson(options.schema))}`;
+        const basePrompt = prompt;
+        for (let attempt = 0;; attempt++) {
+            const text = await this.callLlm({
+                kind, prompt,
+                model: this.opts.model ?? model ?? this.model,
+                reasoningEffort: reasoning,
+                showReasoning: show,
+                restrictions: this.restrictions,
+                tools: new ToolHost(this.restrictions, this.cwd, this.opts.backend.mode === 'replay'),
             });
+            try {
+                const value = fmt === 'text' ? text : parseJsonResponse(text, fmt === 'object');
+                validate?.(value);
+                return value;
+            }
+            catch (e) {
+                if (!(e instanceof Failure) || (e.statusCode !== 'invalid_format' && e.statusCode !== 'validation_failed') || attempt >= repairs)
+                    throw e;
+                this.opts.logger.info(`repair ${attempt + 1}/${repairs}: ${e.reason}`);
+                prompt = `${basePrompt}\n\nPrevious response:\n${text}\n\nValidation failed: ${e.reason}\nReturn a corrected JSON value.`;
+            }
         }
-        const output = await host.invoke(tool, params);
-        this.opts.logger.debug(`tool ${tool} ${JSON.stringify(params)} -> ${output.length} chars`);
-        return this.callLlm({
-            kind: 'tool',
-            prompt: `The tool \`${tool}\` was run with parameters ${JSON.stringify(params)}. Its output is between the markers.\n<tool_output>\n${output}\n</tool_output>\n\nInstructions: ${instructions}`,
-        });
     }
 }

package/dist/llm.d.ts

@@ -1,4 +1,4 @@
-import type { AskMods, ToolName } from './ast.js';
+import type { AskMods } from './ast.js';
 import type { Restrictions } from './restrict.js';
 import type { ToolHost } from './tools.js';
 import { type Value } from './values.js';
@@ -8,7 +8,7 @@ export interface Constraint {
     text: string;
 }
 export interface LlmRequest {
-    kind: 'ask' | 'think' | 'tool';
+    kind: 'ask' | 'think' | 'agent';
     /** The fully assembled query: constraints, restriction guidance and hints are already prepended. */
     prompt: string;
     model?: string;
@@ -16,11 +16,6 @@ export interface LlmRequest {
     showReasoning: boolean;
     restrictions: Restrictions;
     tools: ToolHost;
-    /** For tools the script left parameters out of: the LLM calls the tool itself, these params are fixed by the script. */
-    pinned?: {
-        tool: ToolName;
-        params: Record<string, string>;
-    };
 }
 export interface LlmResponse {
     text: string;
@@ -29,6 +24,7 @@ export interface LlmResponse {
     effective: Record<string, unknown>;
 }
 export interface LlmBackend {
+    readonly mode?: 'record' | 'replay';
     call(req: LlmRequest): Promise<LlmResponse>;
     close(): Promise<void>;
 }
@@ -42,5 +38,4 @@ export declare function buildPrompt(opts: {
     constraints: readonly Constraint[];
     restrictions: Restrictions;
 }): string;
-/** Parses an `fmt='object'` response; anything that is not a JSON object or array is `invalid_format`. */
-export declare function parseObjectResponse(text: string): Value;
+export declare function parseJsonResponse(text: string, objectOnly?: boolean): Value;

package/dist/llm.js

@@ -9,12 +9,12 @@ const LEN_HINTS = {
     paragraph: 'Answer in a single paragraph.',
     long: 'Give a long, detailed answer.',
 };
-const FMT_OBJECT_HINT = 'Respond with ONLY a valid JSON value (an object unless the task clearly asks for a list). No prose, no markdown, no code fences.';
+const JSON_HINT = 'Respond with ONLY valid JSON. No prose, no markdown, no code fences.';
 export function buildPrompt(opts) {
     const sections = [];
     if (opts.constraints.length) {
-        sections.push('Rules you must follow strictly:\n' +
-            opts.constraints.map((c) => `- You ${c.kind === 'enforce' ? 'MUST' : 'MUST NOT'}: ${c.text}`).join('\n'));
+        sections.push('Response guidance (not runtime validation):\n' +
+            opts.constraints.map((c) => `- ${c.kind === 'enforce' ? 'Follow' : 'Avoid'}: ${c.text}`).join('\n'));
     }
     const guidance = opts.restrictions.guidance();
     if (guidance.length)
@@ -24,31 +24,22 @@ export function buildPrompt(opts) {
     if (opts.mods?.len)
         sections.push(LEN_HINTS[opts.mods.len]);
     if (opts.mods?.fmt === 'object')
-        sections.push(FMT_OBJECT_HINT);
+        sections.push(`${JSON_HINT} Return an object or array.`);
     sections.push(opts.prompt);
     return sections.join('\n\n');
 }
-/** Parses an `fmt='object'` response; anything that is not a JSON object or array is `invalid_format`. */
-export function parseObjectResponse(text) {
-    const candidates = [text.trim()];
-    const fenced = /^```[a-zA-Z]*\s*\n([\s\S]*?)\n?```$/.exec(text.trim());
-    if (fenced)
-        candidates.push(fenced[1].trim());
-    const open = text.search(/[{[]/);
-    const close = Math.max(text.lastIndexOf('}'), text.lastIndexOf(']'));
-    if (open >= 0 && close > open)
-        candidates.push(text.slice(open, close + 1));
-    let lastError = 'empty response';
-    for (const c of candidates) {
-        try {
-            const v = fromJson(JSON.parse(c));
-            if (isDict(v) || isList(v))
-                return v;
-            lastError = 'response is JSON but not an object or array';
-        }
-        catch (e) {
-            lastError = e.message;
-        }
+export function parseJsonResponse(text, objectOnly = false) {
+    let value;
+    try {
+        value = fromJson(JSON.parse(text));
     }
-    throw new Failure('invalid_format', `LLM response is not valid JSON: ${lastError}`);
+    catch (e) {
+        if (!(e instanceof SyntaxError))
+            throw e;
+        throw new Failure('invalid_format', `LLM response is not valid JSON: ${e.message}`);
+    }
+    if (objectOnly && !isDict(value) && !isList(value)) {
+        throw new Failure('invalid_format', 'LLM response must be a JSON object or array');
+    }
+    return value;
 }

package/dist/parser.d.ts

@@ -1,13 +1,3 @@
-import type { Program, ToolName } from './ast.js';
-export declare const TOOL_NAMES: readonly ToolName[];
-/** Fixed modifier schema per command; anything else is a syntax error. */
-export declare const MODIFIER_SCHEMA: Record<'?' | 'think', Record<string, readonly (string | boolean)[]>>;
-/**
- * Tool parameter schema: the allowed names, and the `required` ones that let the runtime run the tool itself.
- * Every parameter is optional in a script; the LLM supplies the missing required ones when it calls the tool.
- */
-export declare const TOOL_SCHEMA: Record<ToolName, {
-    params: string[];
-    required: string[];
-}>;
+import type { Program } from './ast.js';
+export declare const MODIFIER_NAMES: readonly ['len', 'fmt', 'reasoning', 'show', 'schema', 'repairs', 'model'];
 export declare function parse(source: string): Program;

package/dist/parser.js

@@ -1,33 +1,11 @@
 import { SplSyntaxError } from './errors.js';
 import { tokenize } from './lexer.js';
-export const TOOL_NAMES = ['read_file', 'write_file', 'web_fetch', 'web_search', 'shell'];
 const KEYWORDS = new Set([
     'let', 'if', 'elif', 'else', 'for', 'in', 'while', 'def', 'return', 'try', 'except', 'assert', 'fail',
-    'success', 'enforce', 'forbid', 'restrict', 'think', 'break', 'continue', 'pass', 'and', 'or', 'not',
-    'True', 'False', 'None', ...TOOL_NAMES,
+    'success', 'enforce', 'forbid', 'restrict', 'think', 'agent', 'break', 'continue', 'pass', 'and', 'or', 'not',
+    'True', 'False', 'None',
 ]);
-/** Fixed modifier schema per command; anything else is a syntax error. */
-export const MODIFIER_SCHEMA = {
-    '?': {
-        len: ['word', 'sentence', 'paragraph', 'long'],
-        fmt: ['text', 'object'],
-    },
-    think: {
-        level: ['low', 'medium', 'high'],
-        show: [true, false],
-    },
-};
-/**
- * Tool parameter schema: the allowed names, and the `required` ones that let the runtime run the tool itself.
- * Every parameter is optional in a script; the LLM supplies the missing required ones when it calls the tool.
- */
-export const TOOL_SCHEMA = {
-    read_file: { params: ['path'], required: ['path'] },
-    write_file: { params: ['path', 'content'], required: ['path', 'content'] },
-    web_fetch: { params: ['url'], required: ['url'] },
-    web_search: { params: ['query'], required: ['query'] },
-    shell: { params: ['command'], required: ['command'] },
-};
+export const MODIFIER_NAMES = ['len', 'fmt', 'reasoning', 'show', 'schema', 'repairs', 'model'];
 const DIRECTIVE_SCHEMA = { model: 'string' };
 const ASSIGN_OPS = new Set(['=', '+=', '-=', '*=', '/=', '//=', '%=']);
 export function parse(source) {
@@ -272,6 +250,9 @@ class Parser {
                     return { t: 'constraint', line, kind, text, body: this.parseBlock() };
                 }
                 case 'restrict': return this.parseRestrict();
+                case 'instruct':
+                case 'avoid':
+                    this.fail(`use '${t.value === 'instruct' ? 'enforce' : 'forbid'}' instead of '${t.value}' for scoped prompt guidance`);
                 default:
                     break;
             }
@@ -283,18 +264,9 @@ class Parser {
     parseLet() {
         const line = this.tok.line;
         this.next();
-        const startTok = this.tok;
-        if (startTok.type === 'name' && KEYWORDS.has(startTok.value)) {
-            this.fail(`'${startTok.value}' is a reserved word and cannot be used as a variable name`);
-        }
-        if (startTok.type !== 'name')
-            this.fail(`expected a variable name but found ${this.describe(startTok)}`);
-        const target = this.toTarget(this.parsePostfix(), startTok);
-        const opTok = this.tok;
-        if (opTok.type !== 'op' || !ASSIGN_OPS.has(opTok.value))
-            this.fail(`expected '=' after the target of 'let' but found ${this.describe(opTok)}`);
-        this.next();
-        return { t: 'let', line, target, op: opTok.value, value: this.parseExpr() };
+        const name = this.expectIdent('a variable name');
+        this.expectOp('=');
+        return { t: 'let', line, name, value: this.parseExpr() };
     }
     parseIf() {
         const line = this.tok.line;
@@ -372,11 +344,14 @@ class Parser {
         return { t: 'restrict', line, clauses, body: this.parseBlock() };
     }
     parseSimpleStatement() {
-        const line = this.tok.line;
+        const start = this.tok;
+        const line = start.line;
         const e = this.parseExpr();
         const t = this.tok;
         if (t.type === 'op' && ASSIGN_OPS.has(t.value)) {
-            this.fail(`variables are modified with 'let' (write 'let <target> ${t.value} ...')`, t);
+            const target = this.toTarget(e, start);
+            this.next();
+            return { t: 'assign', line, target, op: t.value, value: this.parseExpr() };
         }
         return { t: 'expr', line, e };
     }
@@ -604,17 +579,12 @@ class Parser {
             case 'None':
                 this.next();
                 return { t: 'none' };
-            case 'think': {
+            case 'think':
+            case 'agent': {
                 this.next();
-                const mods = this.isOp('{') ? this.parseMods('think') : {};
-                return { t: 'think', mods, prompt: this.parsePrompt('think') };
+                const mods = this.isOp('{') ? this.parseMods(t.value) : {};
+                return { t: t.value, mods, prompt: this.parsePrompt(t.value) };
             }
-            case 'read_file':
-            case 'write_file':
-            case 'web_fetch':
-            case 'web_search':
-            case 'shell':
-                return this.parseToolCall(t.value);
             default:
                 if (KEYWORDS.has(t.value))
                     this.fail(`unexpected keyword '${t.value}'`);
@@ -628,7 +598,6 @@ class Parser {
         return this.parsePostfix();
     }
     parseMods(cmd) {
-        const schema = MODIFIER_SCHEMA[cmd];
         this.expectOp('{');
         this.skipNl();
         const out = {};
@@ -638,25 +607,13 @@ class Parser {
                 this.fail('expected a modifier name');
             const name = nameTok.value;
             this.next();
-            if (!(name in schema)) {
-                this.fail(`unknown modifier '${name}' for '${cmd}' (allowed: ${Object.keys(schema).join(', ')})`, nameTok);
+            if (!MODIFIER_NAMES.some((allowed) => allowed === name)) {
+                this.fail(`unknown modifier '${name}' for '${cmd}' (allowed: ${MODIFIER_NAMES.join(', ')})`, nameTok);
             }
             if (name in out)
                 this.fail(`duplicate modifier '${name}'`, nameTok);
             this.expectOp('=');
-            const valTok = this.tok;
-            let value;
-            if (valTok.type === 'str')
-                value = this.parseLiteralString(`modifier '${name}'`);
-            else if (this.isName('True') || this.isName('False'))
-                value = this.next().value === 'True';
-            else
-                return this.fail(`modifier '${name}' requires a quoted string or True/False`);
-            if (!schema[name].includes(value)) {
-                const allowed = schema[name].map((v) => (typeof v === 'string' ? `'${v}'` : v ? 'True' : 'False'));
-                this.fail(`invalid value ${typeof value === 'string' ? `'${value}'` : value ? 'True' : 'False'} for modifier '${name}' (allowed: ${allowed.join(', ')})`, valTok);
-            }
-            out[name] = value;
+            out[name] = this.parseExpr();
             this.skipNl();
             if (this.isOp(',')) {
                 this.next();
@@ -669,39 +626,6 @@ class Parser {
         this.next();
         return out;
     }
-    parseToolCall(tool) {
-        this.next();
-        const schema = TOOL_SCHEMA[tool];
-        const params = {};
-        if (this.isOp('{')) {
-            this.next();
-            this.skipNl();
-            while (!this.isOp('}')) {
-                const nameTok = this.tok;
-                if (nameTok.type !== 'name')
-                    this.fail('expected a parameter name');
-                const name = nameTok.value;
-                this.next();
-                if (!schema.params.includes(name)) {
-                    this.fail(`unknown parameter '${name}' for '${tool}' (allowed: ${schema.params.join(', ')})`, nameTok);
-                }
-                if (name in params)
-                    this.fail(`duplicate parameter '${name}'`, nameTok);
-                this.expectOp('=');
-                params[name] = this.parseExpr();
-                this.skipNl();
-                if (this.isOp(',')) {
-                    this.next();
-                    this.skipNl();
-                }
-                else if (!this.isOp('}')) {
-                    this.fail("expected ',' or '}' in tool parameters");
-                }
-            }
-            this.next();
-        }
-        return { t: 'tool', tool, params, instructions: this.parsePrompt(tool) };
-    }
     convertParts(parts) {
         return parts.map((p) => {
             if ('text' in p)

package/dist/recording.d.ts

@@ -0,0 +1,17 @@
+import { type LlmBackend, type LlmRequest, type LlmResponse } from './llm.js';
+export declare class RecordingBackend implements LlmBackend {
+    private readonly backend;
+    private readonly file;
+    readonly mode = "record";
+    constructor(backend: LlmBackend, file: string);
+    call(req: LlmRequest): Promise<LlmResponse>;
+    close(): Promise<void>;
+}
+export declare class ReplayBackend implements LlmBackend {
+    readonly mode = "replay";
+    private readonly entries;
+    private position;
+    constructor(file: string);
+    call(req: LlmRequest): Promise<LlmResponse>;
+    close(): Promise<void>;
+}

package/dist/recording.js

@@ -0,0 +1,93 @@
+import * as fs from 'node:fs';
+import { LlmError } from './llm.js';
+function requestKey(req) {
+    return JSON.stringify({
+        kind: req.kind, prompt: req.prompt, model: req.model ?? null,
+        reasoningEffort: req.reasoningEffort ?? null, showReasoning: req.showReasoning,
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseLine(line, number) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (e) {
+        if (!(e instanceof SyntaxError))
+            throw e;
+        throw new LlmError(`invalid recording JSON at line ${number}: ${e.message}`);
+    }
+}
+export class RecordingBackend {
+    backend;
+    file;
+    mode = 'record';
+    constructor(backend, file) {
+        this.backend = backend;
+        this.file = file;
+        fs.writeFileSync(file, JSON.stringify({ format: 'spl-generation', version: 1 }) + '\n', { flag: 'wx', mode: 0o600 });
+    }
+    async call(req) {
+        if (req.kind === 'agent')
+            throw new LlmError('agent actions cannot be recorded; record generation-only workflows');
+        const request = requestKey(req);
+        const response = await this.backend.call(req);
+        try {
+            fs.appendFileSync(this.file, JSON.stringify({ request, response }) + '\n');
+        }
+        catch (e) {
+            if (!(e instanceof Error))
+                throw e;
+            throw new LlmError(`could not save recording: ${e.message}`);
+        }
+        return response;
+    }
+    close() {
+        return this.backend.close();
+    }
+}
+export class ReplayBackend {
+    mode = 'replay';
+    entries;
+    position = 0;
+    constructor(file) {
+        const lines = fs.readFileSync(file, 'utf8').trimEnd().split(/\r?\n/);
+        const header = parseLine(lines.shift() ?? '', 1);
+        if (!isRecord(header) || header.format !== 'spl-generation' || header.version !== 1) {
+            throw new LlmError('unsupported recording format/version');
+        }
+        this.entries = lines.map((line, i) => {
+            const entry = parseLine(line, i + 2);
+            if (!isRecord(entry) || typeof entry.request !== 'string' || !isRecord(entry.response)
+                || typeof entry.response.text !== 'string' || !isRecord(entry.response.effective)
+                || (entry.response.reasoning !== undefined && typeof entry.response.reasoning !== 'string')) {
+                throw new LlmError(`invalid recording entry at line ${i + 2}`);
+            }
+            return {
+                request: entry.request,
+                response: {
+                    text: entry.response.text,
+                    effective: entry.response.effective,
+                    reasoning: entry.response.reasoning,
+                },
+            };
+        });
+    }
+    async call(req) {
+        if (req.kind === 'agent')
+            throw new LlmError('agent actions cannot be replayed');
+        const entry = this.entries[this.position];
+        if (!entry)
+            throw new LlmError(`recording exhausted at call ${this.position + 1}`);
+        if (entry.request !== requestKey(req))
+            throw new LlmError(`replay request mismatch at call ${this.position + 1}`);
+        this.position++;
+        return structuredClone(entry.response);
+    }
+    async close() {
+        if (this.position !== this.entries.length) {
+            throw new LlmError(`replay ended with ${this.entries.length - this.position} unused recorded response(s)`);
+        }
+    }
+}

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import { type Value } from './values.js';
+export declare function compileSchema(schema: Value): (value: Value) => void;