spl-lang 0.1.1 → 0.3.0

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}`);
@@ -86,6 +95,7 @@ class Interpreter {
     }
     async execStmt(s, env) {
         try {
+            this.opts.logger.deterministic(`line ${s.line} (${s.t}): ${this.program.lines[s.line - 1]?.trim() ?? ''}`);
             return await this.execStmtInner(s, env);
         }
         catch (e) {
@@ -100,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;
@@ -189,11 +202,13 @@ class Interpreter {
                 }
             }
             case 'restrict': {
-                const restriction = makeRestriction(s.kind, await this.eval(s.arg, env), this.cwd);
                 const saved = this.restrictions;
-                this.restrictions = saved.with(restriction);
-                this.opts.logger.debug(`restrict ${s.kind}: ${restriction.values.join(', ')}`);
                 try {
+                    for (const clause of s.clauses) {
+                        const restriction = makeRestriction(clause.kind, await this.eval(clause.arg, env), this.cwd);
+                        this.restrictions = this.restrictions.with(restriction);
+                        this.opts.logger.debug(`restrict ${clause.kind}: ${restriction.values.join(', ')}`);
+                    }
                     return await this.execBlock(s.body, env);
                 }
                 finally {
@@ -212,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;
         }
@@ -316,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) {
@@ -481,30 +486,14 @@ 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.debug(`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.debug(`llm response:\n${res.text}`);
+            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();
         }
         catch (e) {
@@ -515,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,14 +1,14 @@
-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';
 export type ReasoningLevel = 'low' | 'medium' | 'high';
 export interface Constraint {
-    kind: 'enforce' | 'forbid';
+    kind: 'instruct' | 'avoid';
     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 === 'instruct' ? '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/logger.d.ts

@@ -9,4 +9,7 @@ export declare class Logger {
     warn(msg: string): void;
     info(msg: string): void;
     debug(msg: string): void;
+    /** LLM transcripts are visible at every non-silent level, without labeling them as errors. */
+    llm(msg: string): void;
+    deterministic(msg: string): void;
 }

package/dist/logger.js

@@ -24,4 +24,11 @@ export class Logger {
     debug(msg) {
         this.emit('debug', 'debug', msg);
     }
+    /** LLM transcripts are visible at every non-silent level, without labeling them as errors. */
+    llm(msg) {
+        this.emit('error', 'llm', msg);
+    }
+    deterministic(msg) {
+        this.emit('error', 'deterministic', msg);
+    }
 }

package/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+import type { MCPServerConfig } from '@github/copilot-sdk';
+import type { Restrictions } from './restrict.js';
+export type McpServers = Record<string, MCPServerConfig>;
+/** Loads the supported VS Code mcp.json subset; never executes commands or connects to servers. */
+export declare function loadMcpConfig(file: string, cwd: string): McpServers;
+export declare function filterMcpServers(servers: McpServers, restrictions: Restrictions): McpServers;
+export declare function configuredMcpTool(servers: McpServers, server: string, tool: string): boolean;

package/dist/mcp.js

@@ -0,0 +1,108 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Loads the supported VS Code mcp.json subset; never executes commands or connects to servers. */
+export function loadMcpConfig(file, cwd) {
+    const fail = (message) => { throw new Error(`MCP config '${file}': ${message}`); };
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        return fail(`cannot read JSON: ${e.message}`);
+    }
+    if (!object(config) || !object(config.servers))
+        return fail("expected an object with a 'servers' object");
+    if (config.inputs !== undefined)
+        return fail("'inputs' are not supported; use environment variables instead");
+    const expand = (value) => value.replace(/\$\{([^}]+)\}/g, (_, key) => {
+        if (key === 'workspaceFolder')
+            return cwd;
+        if (key.startsWith('env:')) {
+            const name = key.slice(4);
+            const value = process.env[name];
+            if (value !== undefined)
+                return value;
+            return fail(`environment variable '${name}' is not set`);
+        }
+        return fail(`unsupported variable '\${${key}}'`);
+    });
+    const strings = (value, field) => {
+        if (value === undefined)
+            return undefined;
+        if (!object(value))
+            return fail(`${field} must be an object of strings`);
+        const entries = Object.entries(value).map(([key, val]) => {
+            if (typeof val !== 'string')
+                return fail(`${field}.${key} must be a string`);
+            return [key, expand(val)];
+        });
+        return Object.fromEntries(entries);
+    };
+    const servers = Object.create(null);
+    for (const [name, raw] of Object.entries(config.servers)) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(name))
+            return fail(`invalid server name '${name}'`);
+        if (!object(raw))
+            return fail(`server '${name}' must be an object`);
+        const type = raw.type ?? 'stdio';
+        const local = type === 'stdio';
+        if (!local && type !== 'http' && type !== 'sse')
+            return fail(`server '${name}' has unsupported type '${String(type)}'`);
+        const fields = local ? ['type', 'command', 'args', 'env', 'cwd', 'tools', 'timeout'] : ['type', 'url', 'headers', 'tools', 'timeout'];
+        for (const field of Object.keys(raw)) {
+            if (!fields.includes(field))
+                return fail(`server '${name}' has unsupported field '${field}'`);
+        }
+        if (raw.tools !== undefined && (!Array.isArray(raw.tools) || raw.tools.some((t) => typeof t !== 'string' || !/^(?:\*|[A-Za-z0-9_.-]+)$/.test(t)))) {
+            return fail(`server '${name}': tools must be an array of tool names or '*'`);
+        }
+        if (raw.timeout !== undefined && (typeof raw.timeout !== 'number' || !Number.isFinite(raw.timeout) || raw.timeout <= 0)) {
+            return fail(`server '${name}': timeout must be a positive number of milliseconds`);
+        }
+        const common = { tools: raw.tools, timeout: raw.timeout };
+        if (local) {
+            if (typeof raw.command !== 'string' || raw.command.trim() === '')
+                return fail(`server '${name}': command must be a non-empty string`);
+            if (raw.args !== undefined && (!Array.isArray(raw.args) || raw.args.some((v) => typeof v !== 'string'))) {
+                return fail(`server '${name}': args must be an array of strings`);
+            }
+            if (raw.cwd !== undefined && typeof raw.cwd !== 'string')
+                return fail(`server '${name}': cwd must be a string`);
+            servers[name] = {
+                ...common, type: 'stdio', command: expand(raw.command),
+                args: raw.args?.map(expand),
+                env: strings(raw.env, `${name}.env`),
+                workingDirectory: raw.cwd === undefined ? cwd : path.resolve(cwd, expand(raw.cwd)),
+            };
+        }
+        else {
+            if (typeof raw.url !== 'string')
+                return fail(`server '${name}': url must be a string`);
+            const url = expand(raw.url);
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                return fail(`server '${name}': invalid URL`);
+            }
+            if (!['http:', 'https:'].includes(parsed.protocol))
+                return fail(`server '${name}': URL must use http or https`);
+            servers[name] = { ...common, type, url, headers: strings(raw.headers, `${name}.headers`) };
+        }
+    }
+    return servers;
+}
+export function filterMcpServers(servers, restrictions) {
+    return Object.fromEntries(Object.entries(servers).flatMap(([name, config]) => {
+        const tools = restrictions.mcpTools(name, config.tools);
+        return tools.length ? [[name, { ...config, tools }]] : [];
+    }));
+}
+export function configuredMcpTool(servers, server, tool) {
+    if (!Object.hasOwn(servers, server))
+        return false;
+    const tools = servers[server].tools;
+    return tools === undefined || tools.includes('*') || tools.includes(tool);
+}

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;