spl-lang 0.1.1 → 0.3.0

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', 'instruct', 'avoid', '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) {
@@ -264,14 +242,17 @@ class Parser {
                     this.next();
                     return { t: 'success', line, value: this.atStatementEnd() ? undefined : this.parseExpr() };
                 }
-                case 'enforce':
-                case 'forbid': {
+                case 'instruct':
+                case 'avoid': {
                     const kind = t.value;
                     this.next();
                     const text = this.parseExpr();
                     return { t: 'constraint', line, kind, text, body: this.parseBlock() };
                 }
                 case 'restrict': return this.parseRestrict();
+                case 'enforce':
+                case 'forbid':
+                    this.fail(`'${t.value}' was removed; use '${t.value === 'enforce' ? 'instruct' : 'avoid'}' for prompt guidance, or assert/schema for validation`);
                 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;
@@ -355,21 +327,31 @@ class Parser {
     parseRestrict() {
         const line = this.tok.line;
         this.next();
-        let kind = 'fs';
-        const t = this.tok;
-        if (t.type === 'name' && (t.value === 'fs' || t.value === 'net' || t.value === 'exec')) {
-            kind = t.value;
+        const clauses = [];
+        for (;;) {
+            let kind = 'fs';
+            const t = this.tok;
+            if (t.type === 'name' && (t.value === 'fs' || t.value === 'net' || t.value === 'exec' || t.value === 'mcp')) {
+                kind = t.value;
+                this.next();
+            }
+            clauses.push({ kind, arg: this.parseExpr() });
+            if (!this.isOp(','))
+                break;
             this.next();
+            this.skipNl();
         }
-        const arg = this.parseExpr();
-        return { t: 'restrict', line, kind, arg, body: this.parseBlock() };
+        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 };
     }
@@ -597,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}'`);
@@ -621,7 +598,6 @@ class Parser {
         return this.parsePostfix();
     }
     parseMods(cmd) {
-        const schema = MODIFIER_SCHEMA[cmd];
         this.expectOp('{');
         this.skipNl();
         const out = {};
@@ -631,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();
@@ -662,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/restrict.d.ts

@@ -20,6 +20,9 @@ export declare class Restrictions {
     checkUrl(url: string): URL;
     checkHost(host: string): void;
     checkExec(name: string): void;
+    checkMcp(server: string, tool: string): void;
+    /** Narrows configured tools before the SDK starts servers or advertises their tools. */
+    mcpTools(server: string, configured?: readonly string[]): string[];
     /** Human-readable guidance for the LLM (the first enforcement layer). */
     guidance(): string[];
 }

package/dist/restrict.js

@@ -127,6 +127,24 @@ export class Restrictions {
             }
         }
     }
+    checkMcp(server, tool) {
+        for (const r of this.list) {
+            if (r.kind === 'mcp' && !r.values.some((v) => v === server || v === `${server}/*` || v === `${server}/${tool}`)) {
+                throw violation(`MCP tool '${server}/${tool}' blocked: allowed MCP servers/tools are ${r.values.join(', ')}`);
+            }
+        }
+    }
+    /** Narrows configured tools before the SDK starts servers or advertises their tools. */
+    mcpTools(server, configured = ['*']) {
+        let tools = [...configured];
+        for (const r of this.list) {
+            if (r.kind !== 'mcp' || r.values.includes(server) || r.values.includes(`${server}/*`))
+                continue;
+            const allowed = r.values.filter((v) => v.startsWith(`${server}/`)).map((v) => v.slice(server.length + 1));
+            tools = tools.includes('*') ? allowed : tools.filter((t) => allowed.includes(t));
+        }
+        return [...new Set(tools)];
+    }
     /** Human-readable guidance for the LLM (the first enforcement layer). */
     guidance() {
         return this.list.map((r) => {
@@ -134,7 +152,9 @@ export class Restrictions {
                 return `File system: you may read and write only inside: ${r.values.join(', ')}. Any other path will be blocked.`;
             if (r.kind === 'net')
                 return `Network: you may only access these hosts: ${r.values.join(', ')}. Any other host will be blocked.`;
-            return `Shell: you may only run these executables: ${r.values.join(', ')}, one simple command at a time (no pipes, redirects or chaining). Anything else will be blocked.`;
+            if (r.kind === 'mcp')
+                return `MCP: you may only call these servers/tools: ${r.values.join(', ')}. Anything else will be blocked.`;
+            return `Shell: you may only run these executables: ${r.values.join(', ')}. Anything else will be blocked.`;
         });
     }
 }
@@ -154,5 +174,11 @@ export function makeRestriction(kind, raw, cwd) {
         return { kind, values: [...new Set(items.map((i) => canonicalPath(i, cwd)))] };
     if (kind === 'net')
         return { kind, values: [...new Set(items.map(normalizeHost))] };
+    if (kind === 'mcp') {
+        if (items.some((v) => !/^[A-Za-z0-9_.-]+(?:\/(?:[A-Za-z0-9_.-]+|\*))?$/.test(v))) {
+            throw new Failure('runtime_error', 'restrict mcp expects server names or server/tool selectors');
+        }
+        return { kind, values: [...new Set(items)] };
+    }
     return { kind, values: [...new Set(items.map(normalizeExec))] };
 }

package/dist/schema.d.ts

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

package/dist/schema.js

@@ -0,0 +1,40 @@
+import { Ajv } from 'ajv';
+import { Failure } from './errors.js';
+import { isDict, runtimeError, toJson } from './values.js';
+const ajv = new Ajv({ allErrors: true, strict: true });
+function errorPath(error) {
+    const parts = error.instancePath.split('/').slice(1).map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+    if (error.keyword === 'required')
+        parts.push(String(error.params.missingProperty));
+    if (error.keyword === 'additionalProperties')
+        parts.push(String(error.params.additionalProperty));
+    return parts.reduce((path, part) => {
+        if (/^(0|[1-9]\d*)$/.test(part))
+            return `${path}[${part}]`;
+        return /^[a-zA-Z_]\w*$/.test(part) ? `${path ? `${path}.` : ''}${part}` : `${path}[${JSON.stringify(part)}]`;
+    }, '') || '$';
+}
+export function compileSchema(schema) {
+    if (typeof schema !== 'boolean' && !isDict(schema))
+        throw runtimeError('schema must be a JSON Schema object or boolean');
+    const json = toJson(schema);
+    if (typeof json !== 'boolean' && (typeof json !== 'object' || json === null))
+        throw runtimeError('invalid schema');
+    let validate;
+    try {
+        validate = ajv.compile(json);
+        if ('$async' in validate && validate.$async)
+            throw new Error('asynchronous schemas are not supported');
+    }
+    catch (e) {
+        if (!(e instanceof Error))
+            throw e;
+        throw runtimeError(`invalid schema: ${e.message}`);
+    }
+    return (value) => {
+        if (!validate(value)) {
+            const details = (validate.errors ?? []).map((error) => `${errorPath(error)}: ${error.message}`).join('; ');
+            throw new Failure('validation_failed', details);
+        }
+    };
+}

package/dist/tools.d.ts

@@ -12,6 +12,10 @@ export interface ToolSpec {
 export declare const TOOL_SPECS: Record<ToolName, ToolSpec>;
 /** Splits a simple command line, honoring '...' and "..." quoting. No escapes, no expansion. */
 export declare function splitCommand(command: string): string[];
+/** Splits a command string by chain/pipeline separators (&&, ||, |, ;, &, \n) outside quotes. */
+export declare function splitChainedCommands(command: string): string[];
+/** Finds nested $(...) or `...` command substitutions outside single quotes. */
+export declare function extractSubstitutions(command: string): string[];
 export interface SearchResult {
     title: string;
     url: string;
@@ -26,7 +30,9 @@ export declare function parseSearchResults(html: string): SearchResult[];
 export declare class ToolHost {
     private readonly restrictions;
     private readonly cwd;
-    constructor(restrictions: Restrictions, cwd: string);
+    private readonly replay;
+    private readonly raw;
+    constructor(restrictions: Restrictions, cwd: string, replay?: boolean, raw?: boolean);
     invoke(name: ToolName, params: Record<string, unknown>): Promise<string>;
     private readFile;
     private writeFile;
@@ -34,5 +40,7 @@ export declare class ToolHost {
     /** Searches DuckDuckGo's HTML endpoint (no API key); it is a network call, so `restrict net` applies to it. */
     private webSearch;
     private shell;
+    private checkCommandRestrictions;
+    private checkSubcommand;
     private run;
 }