spl-lang 0.4.1 → 0.6.0

package/README.md

@@ -42,6 +42,10 @@ under `~/.spl` (override with `SPL_HOME`); `spl logout` removes those saved cred
   `{}` remains an empty dict. Functions still require explicit `return`.
 - **Logging:** `log(...)` defaults to info. `log{level=debug}(...)` selects error/info/debug;
   bare level names, strings and expressions are accepted and checked at runtime.
+- **Runtime inputs:** `$env.NAME` / `$env['NAME']` reads process environment strings;
+  `$args[i]` reads repeated CLI `--arg` strings in order (empty list by default).
+  Missing environment names and out-of-range argument indexes return `None`.
+  Both are read-only snapshots, including through aliases, and are not automatically persisted.
 
 Common generation modifiers are `len`, `fmt`, `reasoning`, `show`, `schema`, `repairs`,
 and `model`. Values are evaluated once, then validated before calling the model.
@@ -67,6 +71,7 @@ spl script.spl [--model id] [--mcp file.json] [--cwd dir] [--timeout seconds]
                [--store file.json | --store-module module]
                [--record file.jsonl | --replay file.jsonl]
                [--log-level error|info|debug] [--silent] [--check]
+               [--arg value ...]
 ```
 
 Results are printed on stdout, logs on stderr. Full prompts/responses and statement traces
@@ -87,6 +92,8 @@ The package exports `parse`, `run`, `Logger`, `CopilotBackend`, `RecordingBacken
 `ReplayBackend`, variable stores, authentication helpers, and related types.
 Call `close()` on the backend after running; replay also checks for unused entries there.
 Custom backends must honor the request kind: only `agent` may execute tools.
+Embedding callers can pass `args: ['first', 'second']` in `RunOptions`; omitted
+arguments default to `[]`, not the host's `process.argv`. Each run snapshots `process.env`.
 See [embedding](../docs/internals.html#embedding).
 
 ## Migration

package/dist/ast.d.ts

@@ -14,6 +14,9 @@ export type Expr = {
     t: 'name';
     name: string;
     line: number;
+} | {
+    t: 'special';
+    name: 'env' | 'args';
 } | {
     t: 'list';
     items: Expr[];

package/dist/builtins.js

@@ -1,4 +1,4 @@
-import { compareValues, equals, fromJson, hasKey, isDict, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
+import { assertMutable, compareValues, equals, fromJson, hasKey, isDict, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
 function arity(name, args, min, max = min) {
     if (args.length < min || args.length > max) {
         const expected = min === max ? `${min}` : `${min}-${max}`;
@@ -346,5 +346,10 @@ export function callMethod(self, name, args) {
     if (!table || !Object.prototype.hasOwnProperty.call(table, name)) {
         throw runtimeError(`${typeName(self)} has no method '${name}'`);
     }
+    const mutating = isList(self)
+        ? ['append', 'extend', 'insert', 'pop', 'remove', 'reverse', 'sort', 'clear']
+        : isDict(self) ? ['pop', 'update', 'clear'] : [];
+    if (mutating.includes(name))
+        assertMutable(self);
     return table[name](self, args);
 }

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]
@@ -24,12 +24,15 @@ Options:
                           All levels include LLM transcripts and [deterministic] statement traces.
   --silent                suppress all logs; only the result is printed
   --model <id>            model override (takes precedence over @{model=...})
+  --arg <value>           script argument exposed in $args (repeatable; also --arg=value)
   --mcp <file.json>       MCP servers in VS Code mcp.json format
   --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
@@ -79,10 +82,12 @@ async function main() {
                 'log-level': { type: 'string' },
                 silent: { type: 'boolean' },
                 model: { type: 'string' },
+                arg: { type: 'string', multiple: true },
                 mcp: { type: 'string' },
                 store: { type: 'string' },
                 'store-module': { type: 'string' },
                 timeout: { type: 'string' },
+                trace: { type: 'string' },
                 record: { type: 'string' },
                 replay: { type: 'string' },
                 cwd: { type: 'string' },
@@ -120,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;
@@ -153,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)
@@ -168,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) {
@@ -175,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 });
+        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.d.ts

@@ -12,6 +12,8 @@ export interface RunOptions {
     cwd?: string;
     /** Overrides the `@{model=...}` directive. */
     model?: string;
+    /** Script arguments exposed as read-only `$args`; defaults to an empty list. */
+    args?: readonly string[];
     maxCallDepth?: number;
 }
 export type RunResult = {

package/dist/interpreter.js

@@ -5,7 +5,7 @@ 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, toJson, truthy, typeName, } from './values.js';
+import { assertMutable, compareValues, equals, hasKey, isDict, isFunction, isList, newDict, runtimeError, setKey, str, toJson, truthy, typeName, } from './values.js';
 class ExpressionSignal {
     signal;
     constructor(signal) {
@@ -24,6 +24,8 @@ class Interpreter {
     cwd;
     model;
     maxDepth;
+    runtimeEnv = newDict();
+    runtimeArgs;
     constraints = [];
     restrictions;
     depth = 0;
@@ -34,6 +36,13 @@ class Interpreter {
         this.store = opts.store ?? new MemoryStore();
         this.model = opts.model ?? program.directives.model;
         this.maxDepth = opts.maxCallDepth ?? 200;
+        for (const [name, value] of Object.entries(process.env)) {
+            if (value !== undefined)
+                setKey(this.runtimeEnv, name, value);
+        }
+        this.runtimeArgs = [...(opts.args ?? [])];
+        Object.freeze(this.runtimeEnv);
+        Object.freeze(this.runtimeArgs);
         this.restrictions = new Restrictions(this.cwd);
         this.builtins = makeBuiltins({ log: (m) => opts.logger.info(`log: ${m}`) });
         for (const tool of Object.keys(TOOL_SPECS)) {
@@ -263,6 +272,7 @@ class Interpreter {
             return;
         }
         const obj = await this.eval(target.obj, env);
+        assertMutable(obj);
         if (target.t === 'member') {
             if (!isDict(obj))
                 throw runtimeError(`cannot set member '${target.name}' on ${typeName(obj)}`);
@@ -314,6 +324,7 @@ class Interpreter {
                 return null;
             }
             case 'name': return this.lookup(e.name, env);
+            case 'special': return e.name === 'env' ? this.runtimeEnv : this.runtimeArgs;
             case 'list': {
                 const out = [];
                 for (const it of e.items)
@@ -379,8 +390,11 @@ class Interpreter {
         }
     }
     getKey(d, k) {
-        if (!hasKey(d, k))
+        if (!hasKey(d, k)) {
+            if (d === this.runtimeEnv)
+                return null;
             throw runtimeError(`key '${k}' not found`);
+        }
         return d[k];
     }
     async evalCall(callee, argExprs, env) {
@@ -493,13 +507,13 @@ class Interpreter {
         if (typeof index !== 'number' || !Number.isInteger(index))
             throw runtimeError(`indices must be integers, got ${typeName(index)}`);
         const i = index < 0 ? list.length + index : index;
-        if (i < 0 || i >= list.length)
+        if ((i < 0 || i >= list.length) && list !== this.runtimeArgs)
             throw runtimeError(`index ${index} out of range`);
         return i;
     }
     index(obj, index) {
         if (isList(obj))
-            return obj[this.listIndex(obj, index)];
+            return obj[this.listIndex(obj, index)] ?? null;
         if (typeof obj === 'string') {
             const chars = Array.from(obj);
             return chars[this.listIndex(chars, index)];
@@ -557,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/lexer.js

@@ -71,8 +71,10 @@ export function tokenize(src, opts = {}) {
             tokens.push(readString(raw));
             continue;
         }
-        if (isNameStart(c)) {
-            let j = i;
+        if (isNameStart(c) || c === '$') {
+            if (c === '$' && (i + 1 >= src.length || !isNameStart(src[i + 1])))
+                err("unexpected character '$'");
+            let j = i + (c === '$' ? 1 : 0);
             while (j < src.length && isNameChar(src[j]))
                 j++;
             const value = src.slice(i, j);

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/parser.js

@@ -69,6 +69,8 @@ class Parser {
         if (t.type !== 'name')
             this.fail(`expected ${what} but found ${this.describe(t)}`);
         const name = t.value;
+        if (name.startsWith('$'))
+            this.fail(`special variable '${name}' cannot be used as ${what}`);
         if (KEYWORDS.has(name))
             this.fail(`'${name}' is a reserved word and cannot be used as ${what}`);
         this.next();
@@ -476,7 +478,7 @@ class Parser {
             else if (this.isOp('.')) {
                 this.next();
                 const t = this.tok;
-                if (t.type !== 'name')
+                if (t.type !== 'name' || t.value.startsWith('$'))
                     this.fail("expected a member name after '.'");
                 this.next();
                 e = { t: 'member', obj: e, name: t.value };
@@ -585,6 +587,12 @@ class Parser {
         return this.fail(`unexpected ${this.describe(t)}`);
     }
     parseNamePrimary(t) {
+        if (t.value.startsWith('$')) {
+            if (t.value !== '$env' && t.value !== '$args')
+                this.fail(`unknown special variable '${t.value}'`);
+            this.next();
+            return { t: 'special', name: t.value === '$env' ? 'env' : 'args' };
+        }
         switch (t.value) {
             case 'True':
                 this.next();

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/dist/values.d.ts

@@ -21,6 +21,7 @@ export interface BuiltinFunction {
 }
 export type FunctionValue = UserFunction | BuiltinFunction;
 export declare const runtimeError: (msg: string) => Failure;
+export declare function assertMutable(v: Value): void;
 export declare function isFunction(v: unknown): v is FunctionValue;
 export declare function isList(v: unknown): v is Value[];
 export declare function isDict(v: unknown): v is {

package/dist/values.js

@@ -1,5 +1,10 @@
 import { Failure } from './errors.js';
 export const runtimeError = (msg) => new Failure('runtime_error', msg);
+export function assertMutable(v) {
+    if (typeof v === 'object' && v !== null && Object.isFrozen(v)) {
+        throw runtimeError('cannot modify a read-only value');
+    }
+}
 export function isFunction(v) {
     return typeof v === 'object' && v !== null && '__fn' in v && (v.__fn === 'user' || v.__fn === 'builtin');
 }

package/docs/syntax.ebnf

@@ -46,9 +46,10 @@ call           = "(" , [ expr , { "," , expr } , [ "," ] ] , ")" ;
 index          = "[" , expr , "]" ;
 slice          = "[" , [ expr ] , ":" , [ expr ] , "]" ;
 member         = "." , NAME ;
-primary        = NUMBER | string | "True" | "False" | "None" | NAME
+primary        = NUMBER | string | "True" | "False" | "None" | NAME | special_var
                | "(" , expr , ")" | list | dict | block | if_stmt | log_expr
                | ( "think" | "agent" ) , [ modifiers ] , postfix ;
+special_var    = "$env" | "$args" ;
 list           = "[" , [ expr , { "," , expr } , [ "," ] ] , "]" ;
 dict           = "{" , [ expr , ":" , expr , { "," , expr , ":" , expr } , [ "," ] ] , "}" ;
 modifiers      = "{" , [ modifier , { "," , modifier } , [ "," ] ] , "}" ;
@@ -84,6 +85,12 @@ NAME           = ( letter | "_" ) , { letter | digit | "_" } ;
 NL             = newline ;
 
 (* "{{"/"}}" are literal braces; raw strings have no interpolation or escapes.
+   $env is a read-only process-environment dict snapshot; missing keys return None.
+   $args is a read-only list of repeated CLI --arg strings (empty by default);
+   out-of-range integer indexes return None, and negative indexes count from the end.
+   Both are available in every scope and interpolation, cannot be rebound or mutated
+   (including through aliases), and are not automatically persisted.
+   Other $-prefixed names are syntax errors. Ordinary dict/list missing reads still fail.
    Reserved words: let if elif else for in while def return try except assert fail success
    enforce forbid restrict think agent break continue pass and or not True False None.
    Removed syntax: think{level=...}, tool{param=...} 'instructions',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spl-lang",
-  "version": "0.4.1",
+  "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",