spl-lang 0.5.0 → 0.6.0

package/dist/cli.js

@@ -12,7 +12,7 @@ import { run } from './interpreter.js';
 import { JsonFileStore, MemoryStore, loadStoreModule } from './store.js';
 import { toJson } from './values.js';
 import { loadMcpConfig } from './mcp.js';
-import { RecordingBackend, ReplayBackend } from './recording.js';
+import { RecordingBackend, ReplayBackend, TraceBackend } from './recording.js';
 const HELP = `spl - Semantic Prompt Language interpreter
 
 Usage: spl <script.spl> [options]
@@ -29,8 +29,10 @@ Options:
   --store <file.json>     persist top-level variables in a JSON file
   --store-module <path>   custom variable store: module exporting createStore() -> { load(), save(vars) }
   --timeout <seconds>     per LLM call timeout (default: 300)
+  --trace <file.jsonl>    trace all LLM requests, responses, and failures (new file)
   --record <file.jsonl>   record generation responses (new file; no agents)
-  --replay <file.jsonl>   offline generation replay; only local reads allowed
+  --replay <file.jsonl>   replay LLM results without Copilot/MCP; explicit script tools still run
+                          Legacy --record files allow only local reads and no stores.
   --cwd <dir>             base directory for relative paths and restrictions (default: current directory)
   --check                 validate script syntax and any --mcp config without executing
   -v, --version           print version
@@ -85,6 +87,7 @@ async function main() {
                 store: { type: 'string' },
                 'store-module': { type: 'string' },
                 timeout: { type: 'string' },
+                trace: { type: 'string' },
                 record: { type: 'string' },
                 replay: { type: 'string' },
                 cwd: { type: 'string' },
@@ -122,10 +125,12 @@ async function main() {
         usageError('--timeout must be a positive number');
     if (values.store && values['store-module'])
         usageError('--store and --store-module are mutually exclusive');
-    if (values.record && values.replay)
-        usageError('--record and --replay are mutually exclusive');
-    if (values.replay && (values.store || values['store-module']))
-        usageError('--replay cannot use a persistent variable store');
+    if ([values.trace, values.record, values.replay].filter((value) => value !== undefined).length > 1) {
+        usageError('--trace, --record, and --replay are mutually exclusive');
+    }
+    if ([values.trace, values.record, values.replay].some((value) => value !== undefined && value.trim() === '')) {
+        usageError('--trace, --record, and --replay require a non-empty file path');
+    }
     const cwd = path.resolve(values.cwd ?? process.cwd());
     const file = positionals[0];
     let source;
@@ -155,13 +160,6 @@ async function main() {
     }
     if (values.check)
         return 0;
-    let store;
-    try {
-        store = values.store ? new JsonFileStore(values.store) : values['store-module'] ? await loadStoreModule(values['store-module']) : new MemoryStore();
-    }
-    catch (e) {
-        return usageError(e.message);
-    }
     let backend;
     try {
         if (values.replay)
@@ -170,6 +168,8 @@ async function main() {
             backend = new CopilotBackend({ logger, cwd, timeoutMs: timeoutSec * 1000, mcpServers });
             if (values.record)
                 backend = new RecordingBackend(backend, values.record);
+            if (values.trace)
+                backend = new TraceBackend(backend, values.trace);
         }
     }
     catch (e) {
@@ -177,9 +177,19 @@ async function main() {
             throw e;
         return usageError(`cannot open recording: ${e.message}`);
     }
+    if (backend.mode === 'replay' && (values.store || values['store-module'])) {
+        return usageError('--replay of legacy --record files cannot use a persistent variable store');
+    }
+    let store;
+    try {
+        store = values.store ? new JsonFileStore(values.store) : values['store-module'] ? await loadStoreModule(values['store-module']) : new MemoryStore();
+    }
+    catch (e) {
+        return usageError(e.message);
+    }
     let result;
     try {
-        result = await run(program, { backend, logger, store: values.replay ? undefined : store, cwd, model: values.model, args: values.arg });
+        result = await run(program, { backend, logger, store: backend.mode === 'replay' ? undefined : store, cwd, model: values.model, args: values.arg });
     }
     finally {
         try {

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { run, type RunOptions, type RunResult } from './interpreter.js';
 export { Failure, SplSyntaxError, type FailurePayload, type StatusCode } from './errors.js';
 export { Logger, type LogLevel } from './logger.js';
 export { CopilotBackend } from './copilot.js';
-export { RecordingBackend, ReplayBackend } from './recording.js';
+export { RecordingBackend, ReplayBackend, TraceBackend } from './recording.js';
 export { loadMcpConfig, type McpServers } from './mcp.js';
 export { login, logout, authStatus, AuthError } from './auth.js';
 export { JsonFileStore, MemoryStore, loadStoreModule, type VariableStore } from './store.js';

package/dist/index.js

@@ -3,7 +3,7 @@ export { run } from './interpreter.js';
 export { Failure, SplSyntaxError } from './errors.js';
 export { Logger } from './logger.js';
 export { CopilotBackend } from './copilot.js';
-export { RecordingBackend, ReplayBackend } from './recording.js';
+export { RecordingBackend, ReplayBackend, TraceBackend } from './recording.js';
 export { loadMcpConfig } from './mcp.js';
 export { login, logout, authStatus, AuthError } from './auth.js';
 export { JsonFileStore, MemoryStore, loadStoreModule } from './store.js';

package/dist/interpreter.js

@@ -571,7 +571,7 @@ class Interpreter {
         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) {
+        if (kind === 'agent' && (this.opts.backend.mode === 'record' || this.opts.backend.mode === 'replay')) {
             throw new Failure('restriction_violation', 'agents cannot run in record/replay mode; record generation-only workflows');
         }
         const options = {};

package/dist/llm.d.ts

@@ -24,7 +24,7 @@ export interface LlmResponse {
     effective: Record<string, unknown>;
 }
 export interface LlmBackend {
-    readonly mode?: 'record' | 'replay';
+    readonly mode?: 'record' | 'replay' | 'trace' | 'workflow-replay';
     call(req: LlmRequest): Promise<LlmResponse>;
     close(): Promise<void>;
 }

package/dist/recording.d.ts

@@ -7,8 +7,16 @@ export declare class RecordingBackend implements LlmBackend {
     call(req: LlmRequest): Promise<LlmResponse>;
     close(): Promise<void>;
 }
+export declare class TraceBackend implements LlmBackend {
+    private readonly backend;
+    private readonly file;
+    readonly mode = "trace";
+    constructor(backend: LlmBackend, file: string);
+    call(req: LlmRequest): Promise<LlmResponse>;
+    close(): Promise<void>;
+}
 export declare class ReplayBackend implements LlmBackend {
-    readonly mode = "replay";
+    readonly mode: 'replay' | 'workflow-replay';
     private readonly entries;
     private position;
     constructor(file: string);

package/dist/recording.js

@@ -1,14 +1,36 @@
 import * as fs from 'node:fs';
+import { Failure } from './errors.js';
 import { LlmError } from './llm.js';
-function requestKey(req) {
-    return JSON.stringify({
+function traceRequest(req) {
+    return {
         kind: req.kind, prompt: req.prompt, model: req.model ?? null,
         reasoningEffort: req.reasoningEffort ?? null, showReasoning: req.showReasoning,
-    });
+    };
+}
+function requestKey(req) {
+    return JSON.stringify(traceRequest(req));
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isResponse(value) {
+    return isRecord(value) && typeof value.text === 'string' && isRecord(value.effective)
+        && (value.reasoning === undefined || typeof value.reasoning === 'string');
+}
+function isTraceRequest(value) {
+    return isRecord(value) && (value.kind === 'ask' || value.kind === 'think' || value.kind === 'agent')
+        && typeof value.prompt === 'string' && (value.model === null || typeof value.model === 'string')
+        && (value.reasoningEffort === null || value.reasoningEffort === 'low' || value.reasoningEffort === 'medium' || value.reasoningEffort === 'high')
+        && typeof value.showReasoning === 'boolean';
+}
+function isTraceError(value) {
+    const codes = [
+        'assertion_failed', 'explicit_failure', 'invalid_format', 'validation_failed',
+        'restriction_violation', 'llm_error', 'tool_error', 'runtime_error',
+    ];
+    return isRecord(value) && typeof value.reason === 'string'
+        && codes.some((code) => code === value.status_code);
+}
 function parseLine(line, number) {
     try {
         return JSON.parse(line);
@@ -47,35 +69,81 @@ export class RecordingBackend {
         return this.backend.close();
     }
 }
+export class TraceBackend {
+    backend;
+    file;
+    mode = 'trace';
+    constructor(backend, file) {
+        this.backend = backend;
+        this.file = file;
+        fs.writeFileSync(file, JSON.stringify({ format: 'spl-trace', version: 1 }) + '\n', { flag: 'wx', mode: 0o600 });
+    }
+    async call(req) {
+        const request = traceRequest(req);
+        let outcome;
+        let failure;
+        try {
+            outcome = { response: await this.backend.call(req) };
+        }
+        catch (e) {
+            failure = e instanceof Error ? e : new LlmError(String(e));
+            outcome = { error: {
+                    status_code: e instanceof Failure ? e.statusCode : 'llm_error',
+                    reason: e instanceof Failure ? e.reason : e instanceof Error ? e.message : String(e),
+                } };
+        }
+        try {
+            fs.appendFileSync(this.file, JSON.stringify({ request, ...outcome }) + '\n');
+        }
+        catch (e) {
+            if (!(e instanceof Error))
+                throw e;
+            throw new LlmError(`could not save trace: ${e.message}`);
+        }
+        if ('error' in outcome)
+            throw failure;
+        return outcome.response;
+    }
+    close() {
+        return this.backend.close();
+    }
+}
 export class ReplayBackend {
-    mode = 'replay';
+    mode;
     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) {
+        if (!isRecord(header) || (header.format !== 'spl-generation' && header.format !== 'spl-trace') || header.version !== 1) {
             throw new LlmError('unsupported recording format/version');
         }
+        this.mode = header.format === 'spl-trace' ? 'workflow-replay' : 'replay';
         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')) {
+            if (!isRecord(entry))
+                throw new LlmError(`invalid recording entry at line ${i + 2}`);
+            let request;
+            if (this.mode === 'workflow-replay' && isTraceRequest(entry.request)) {
+                request = JSON.stringify(traceRequest(entry.request));
+            }
+            else if (this.mode === 'replay' && typeof entry.request === 'string') {
+                request = entry.request;
+            }
+            else {
                 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,
-                },
-            };
+            if (isResponse(entry.response) && entry.error === undefined) {
+                return { request, outcome: { response: entry.response } };
+            }
+            if (this.mode === 'workflow-replay' && entry.response === undefined && isTraceError(entry.error)) {
+                return { request, outcome: { error: entry.error } };
+            }
+            throw new LlmError(`invalid recording entry at line ${i + 2}`);
         });
     }
     async call(req) {
-        if (req.kind === 'agent')
+        if (req.kind === 'agent' && this.mode === 'replay')
             throw new LlmError('agent actions cannot be replayed');
         const entry = this.entries[this.position];
         if (!entry)
@@ -83,7 +151,11 @@ export class ReplayBackend {
         if (entry.request !== requestKey(req))
             throw new LlmError(`replay request mismatch at call ${this.position + 1}`);
         this.position++;
-        return structuredClone(entry.response);
+        if ('error' in entry.outcome) {
+            const { status_code, reason } = entry.outcome.error;
+            throw new Failure(status_code, reason);
+        }
+        return structuredClone(entry.outcome.response);
     }
     async close() {
         if (this.position !== this.entries.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spl-lang",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Semantic Prompt Language: a Python-like language with LLM calls built into the syntax",
   "type": "module",
   "main": "./dist/index.js",