spl-lang 0.2.0 → 0.3.1

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

@@ -30,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;

package/dist/tools.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
 import { Failure } from './errors.js';
 const MAX_TEXT = 200_000;
 const SHELL_TIMEOUT_MS = 120_000;
@@ -251,11 +252,17 @@ function isDirSwitch(executable, arg) {
 export class ToolHost {
     restrictions;
     cwd;
-    constructor(restrictions, cwd) {
+    replay;
+    raw;
+    constructor(restrictions, cwd, replay = false, raw = false) {
         this.restrictions = restrictions;
         this.cwd = cwd;
+        this.replay = replay;
+        this.raw = raw;
     }
     async invoke(name, params) {
+        if (this.replay && name !== 'read_file')
+            throw new Failure('restriction_violation', `replay blocks ${name}; only local reads and recorded generation are allowed`);
         switch (name) {
             case 'read_file': return this.readFile(needString(name, params, 'path'));
             case 'write_file': {
@@ -272,7 +279,8 @@ export class ToolHost {
     async readFile(p) {
         const canonical = this.restrictions.checkPath(p, 'read');
         try {
-            return truncate(await fs.readFile(canonical, 'utf8'));
+            const text = await fs.readFile(canonical, 'utf8');
+            return this.raw ? text : truncate(text);
         }
         catch (e) {
             throw new Failure('tool_error', `read_file '${p}': ${e.message}`);
@@ -303,7 +311,16 @@ export class ToolHost {
                 current = this.restrictions.checkUrl(new URL(res.headers.get('location'), current).href);
                 continue;
             }
-            const body = truncate(await res.text());
+            let text;
+            try {
+                text = await res.text();
+            }
+            catch (e) {
+                if (!(e instanceof Error))
+                    throw e;
+                throw new Failure('tool_error', `web_fetch '${current.href}': ${e.message}`);
+            }
+            const body = this.raw ? text : truncate(text);
             if (!res.ok)
                 throw new Failure('tool_error', `web_fetch '${current.href}': HTTP ${res.status}\n${body}`);
             return body;
@@ -417,12 +434,15 @@ export class ToolHost {
         return new Promise((resolve, reject) => {
             const child = spawn(command, opts.args ?? [], { cwd: this.cwd, shell: opts.shell, windowsHide: true });
             let out = '';
-            const collect = (d) => {
-                if (out.length < MAX_TEXT * 2)
-                    out += d.toString('utf8');
+            const collect = (text) => {
+                if (this.raw || out.length < MAX_TEXT * 2)
+                    out += text;
             };
-            child.stdout.on('data', collect);
-            child.stderr.on('data', collect);
+            for (const stream of [child.stdout, child.stderr]) {
+                const decoder = new StringDecoder('utf8');
+                stream.on('data', (data) => collect(decoder.write(data)));
+                stream.on('end', () => collect(decoder.end()));
+            }
             const timer = setTimeout(() => child.kill(), SHELL_TIMEOUT_MS);
             child.on('error', (e) => {
                 clearTimeout(timer);
@@ -430,7 +450,7 @@ export class ToolHost {
             });
             child.on('close', (code, signal) => {
                 clearTimeout(timer);
-                const text = truncate(out);
+                const text = this.raw ? out : truncate(out);
                 if (code === 0)
                     resolve(text);
                 else

package/dist/values.d.ts

@@ -17,7 +17,7 @@ export interface UserFunction {
 export interface BuiltinFunction {
     __fn: 'builtin';
     name: string;
-    call: (args: Value[]) => Value;
+    call: (args: Value[]) => Value | Promise<Value>;
 }
 export type FunctionValue = UserFunction | BuiltinFunction;
 export declare const runtimeError: (msg: string) => Failure;

package/docs/syntax.ebnf

@@ -1,98 +1,82 @@
-(* Semantic Prompt Language (SPL) - syntax in EBNF.
-   Notation: ISO-style. { x } = zero or more, [ x ] = optional, ( ) = grouping, | = alternative.
-   Statements are separated by newlines or ';'. Newlines are insignificant inside ( ) and [ ].
-   '#' starts a comment that runs to the end of the line. *)
+(* SPL 0.3. { x } means repetition; [ x ] means optional.
+   Statements end at newline, ';', '}' or EOF. Newlines inside () and [] are ignored.
+   '#' starts a comment. Opening block braces must be on the keyword's line. *)
 
-program        = { directive , NL } , { statement , ( NL | ";" ) } ;
-directive      = "@" , "{" , directive_item , { "," , directive_item } , "}" ;
-directive_item = "model" , "=" , plain_string ;           (* only allowed before the first statement *)
+program        = { directive , separator } , { statement , separator } ;
+separator      = NL | ";" | end_of_block | EOF ;
+directive      = "@" , "{" , "model" , "=" , plain_string , [ "," ] , "}" ;
+block          = "{" , { statement , separator } , "}" ;
 
-block          = "{" , { statement , ( NL | ";" ) } , "}" ;   (* '{' must be on the same line as its keyword; as a statement it is a nested scope *)
-
-statement      = let_stmt | if_stmt | for_stmt | while_stmt | def_stmt | block
-               | "return" , [ expr ]          (* anywhere: ends the function, or the script when at the top level *)
-               | "break" | "continue" | "pass" (* break/continue only inside loops *)
-               | try_stmt | assert_stmt | fail_stmt | success_stmt
-               | constraint_stmt | restrict_stmt | expr ;
-
-(* Every modification of a variable starts with 'let'; a bare  x = 1  is a syntax error.
-   Scoping: 'let NAME = ...' binds in the current scope. A bare block { ... }, a function body and its parameters
-   open a new scope, so 'let' there shadows an outer variable. if/elif/else, for, while, try/except, enforce, forbid
-   and restrict bodies do NOT open a scope: 'let' inside them updates the enclosing variable, which is how results
-   of LLM commands leave an enforce/forbid/restrict block. Reading a name searches the scopes outwards.
-   Compound forms (let x += 1) read the visible value and bind the result in the current scope. *)
-let_stmt       = "let" , target , ( "=" | "+=" | "-=" | "*=" | "/=" | "//=" | "%=" ) , expr ;
-target         = NAME | postfix "." NAME | postfix "[" expr "]" ;
-
-if_stmt         = "if" , expr , block , { NL* "elif" , expr , block } , [ NL* "else" , block ] ;
+statement      = declaration | assignment | if_stmt | for_stmt | while_stmt
+               | def_stmt | try_stmt | guidance_stmt | restrict_stmt | block
+               | "return" , [ expr ] | "success" , [ expr ]
+               | "assert" , expr , [ expr ] | "fail" , expr
+               | "break" | "continue" | "pass" | expr ;
+declaration    = "let" , NAME , "=" , expr ;
+assignment     = target , ( "=" | "+=" | "-=" | "*=" | "/=" | "//=" | "%=" ) , expr ;
+target         = NAME | postfix , "." , NAME | postfix , "[" , expr , "]" ;
+if_stmt        = "if" , expr , block , { NL* , "elif" , expr , block } , [ NL* , "else" , block ] ;
 for_stmt       = "for" , NAME , { "," , NAME } , "in" , expr , block ;
 while_stmt     = "while" , expr , block ;
-def_stmt       = "def" , NAME , "(" , [ NAME , { "," , NAME } ] , ")" , block ;
+def_stmt       = "def" , NAME , "(" , [ NAME , { "," , NAME } , [ "," ] ] , ")" , block ;
 try_stmt       = "try" , block , NL* , "except" , NAME , block ;
+guidance_stmt  = ( "enforce" | "forbid" ) , expr , block ;
+restrict_stmt  = "restrict" , restrict_clause , { "," , restrict_clause } , block ;
+restrict_clause = [ "fs" | "net" | "exec" | "mcp" ] , expr ;
 
-assert_stmt    = "assert" , expr , [ expr ] ;              (* optional message *)
-fail_stmt      = "fail" , expr ;
-success_stmt   = "success" , [ expr ] ;
-
-constraint_stmt = ( "enforce" | "forbid" ) , expr , block ;
-restrict_stmt   = "restrict" , restrict_clause , { "," , restrict_clause } , block ;
-restrict_clause = [ "fs" | "net" | "exec" | "mcp" ] , expr ;  (* default kind: fs; clauses intersect *)
+(* let declares/redeclares in the current function or script. All blocks share that scope.
+   Name assignment requires a declared local; it cannot rebind an enclosing function/script.
+   Functions read lexical enclosing scopes; collection mutations can share state.
+   Loop variables and caught failure names are local bindings.
+   return exits the innermost function, or the script at top level.
+   success exits the script, including when used in a function. *)
 
-(* Expressions, lowest to highest precedence *)
 expr           = or_expr , [ "if" , or_expr , "else" , expr ] ;
 or_expr        = and_expr , { "or" , and_expr } ;
 and_expr       = not_expr , { "and" , not_expr } ;
 not_expr       = "not" , not_expr | comparison ;
-comparison     = sum , { ( "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not" "in" ) , sum } ;
+comparison     = sum , { ( "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not" , "in" ) , sum } ;
 sum            = term , { ( "+" | "-" ) , term } ;
 term           = unary , { ( "*" | "/" | "//" | "%" ) , unary } ;
-unary          = ( "-" | "+" ) , unary | llm_call | power ;
+unary          = ( "-" | "+" ) , unary | "?" , [ modifiers ] , postfix | power ;
 power          = postfix , [ "**" , unary ] ;
 postfix        = primary , { call | index | slice | member } ;
-call           = "(" , [ expr , { "," , expr } ] , ")" ;
+call           = "(" , [ expr , { "," , expr } , [ "," ] ] , ")" ;
 index          = "[" , expr , "]" ;
 slice          = "[" , [ expr ] , ":" , [ expr ] , "]" ;
 member         = "." , NAME ;
-
 primary        = NUMBER | string | "True" | "False" | "None" | NAME
                | "(" , expr , ")" | list | dict
-               | think_call | tool_call ;
+               | ( "think" | "agent" ) , [ modifiers ] , postfix ;
 list           = "[" , [ expr , { "," , expr } , [ "," ] ] , "]" ;
 dict           = "{" , [ expr , ":" , expr , { "," , expr , ":" , expr } , [ "," ] ] , "}" ;
+modifiers      = "{" , [ modifier , { "," , modifier } , [ "," ] ] , "}" ;
+modifier       = ( "len" | "fmt" | "reasoning" | "show" | "schema" | "repairs" | "model" ) , "=" , expr ;
 
-(* LLM commands. '?' is a prefix operator (see 'unary'). The prompt operand is a postfix expression,
-   so  ?'a' + b  is  (?'a') + b  and  -?'n'  is  -(?'n').
-   Every modifier and parameter is optional: ?'q', think 'q' and read_file 'what to do' run with defaults. *)
-llm_call       = "?" , [ ask_mods ] , postfix ;
-think_call     = "think" , [ think_mods ] , postfix ;
-tool_call      = tool_name , [ tool_params ] , postfix ;    (* the last operand holds the instructions *)
-
-ask_mods       = "{" , ask_mod , { "," , ask_mod } , "}" ;
-ask_mod        = "len" , "=" , ( "'word'" | "'sentence'" | "'paragraph'" | "'long'" )
-               | "fmt" , "=" , ( "'text'" | "'object'" ) ;
-think_mods     = "{" , think_mod , { "," , think_mod } , "}" ;
-think_mod      = "level" , "=" , ( "'low'" | "'medium'" | "'high'" )
-               | "show" , "=" , ( "True" | "False" ) ;      (* each modifier at most once *)
-
-tool_name      = "read_file" | "write_file" | "web_fetch" | "web_search" | "shell" ;
-tool_params    = "{" , [ tool_param , { "," , tool_param } ] , "}" ;
-(* When every parameter the tool needs is given, the runtime runs the tool and passes its output to the instructions.
-   When one is missing, the LLM calls the tool itself; the parameters that were given stay fixed. *)
-tool_param     = "path" , "=" , expr       (* read_file, write_file *)
-               | "content" , "=" , expr    (* write_file; the LLM writes the file when omitted *)
-               | "url" , "=" , expr        (* web_fetch *)
-               | "query" , "=" , expr      (* web_search *)
-               | "command" , "=" , expr ;  (* shell *)
+(* Unknown/duplicate modifier names are syntax errors. Values are expressions, validated at runtime:
+   len: word/sentence/paragraph/long (guidance only)
+   fmt: text/json/object; schema implies json unless fmt is explicit
+   reasoning: low/medium/high; think and agent default to medium
+   show: True/False; schema: synchronous strict JSON Schema draft-07 object or boolean
+   repairs: integer 0..5 (additional generation attempts, default 0); agents require 0
+   model: non-empty string; CLI override > per-call model > header > SDK default
+   Generation (? and think) has no tools. agent explicitly enables restricted runtime/MCP tools.
+   Raw tools are ordinary positional functions: read_file(path), write_file(path, content),
+   web_fetch(url), web_search(query), shell(command). They never invoke a model.
+   enforce/forbid are scoped prompt guidance.
+   schema/assert validate data; restrict checks actions. *)
 
-(* Lexical rules *)
-string         = [ "r" ] , ( "'" | '"' | "'''" | '"""' ) , { char | escape | interpolation } , closing_quote ;
-plain_string   = string without interpolation ;
+string         = [ "r" ] , quote , { char | escape | interpolation } , closing_quote ;
+quote          = "'" | '"' | "'''" | '"""' ;
+plain_string   = string_without_interpolation ;
 escape         = "\" , ( "n" | "t" | "r" | "0" | "\" | "'" | '"' | "{" | "}" ) ;
-interpolation  = "{" , expr , "}" ;        (* "{{" and "}}" are literal braces; raw strings (r'...') have no escapes or interpolation *)
+interpolation  = "{" , expr , "}" ;
 NUMBER         = digit+ , [ "." , digit+ ] , [ ( "e" | "E" ) , [ "+" | "-" ] , digit+ ] ;
-NAME           = ( letter | "_" ) , { letter | digit | "_" } ;   (* not a reserved word *)
+NAME           = ( letter | "_" ) , { letter | digit | "_" } ;
 NL             = newline ;
 
-(* Reserved words:
-   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 read_file write_file web_fetch web_search shell *)
+(* "{{"/"}}" are literal braces; raw strings have no interpolation or escapes.
+   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',
+   let x += ... and let d.key = ... . *)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spl-lang",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Semantic Prompt Language: a Python-like language with LLM calls built into the syntax",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,8 @@
   ],
   "license": "ISC",
   "dependencies": {
-    "@github/copilot-sdk": "^1.0.22"
+    "@github/copilot-sdk": "^1.0.22",
+    "ajv": "^8.17.1"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",