spl-lang 0.5.0 → 1.0.0

package/dist/recording.d.ts

@@ -1,4 +1,26 @@
+import { type StatusCode } from './errors.js';
 import { type LlmBackend, type LlmRequest, type LlmResponse } from './llm.js';
+interface TraceRequest {
+    kind: LlmRequest['kind'];
+    prompt: string;
+    model: string | null;
+    reasoningEffort: LlmRequest['reasoningEffort'] | null;
+    showReasoning: boolean;
+    naturalLanguage?: boolean;
+}
+type Outcome = {
+    response: LlmResponse;
+} | {
+    error: {
+        status_code: StatusCode;
+        reason: string;
+    };
+};
+export declare function traceRequest(req: LlmRequest | TraceRequest): TraceRequest;
+export declare function isResponse(value: unknown): value is LlmResponse;
+export declare function isTraceError(value: unknown): value is Extract<Outcome, {
+    error: unknown;
+}>['error'];
 export declare class RecordingBackend implements LlmBackend {
     private readonly backend;
     private readonly file;
@@ -7,11 +29,20 @@ 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);
     call(req: LlmRequest): Promise<LlmResponse>;
     close(): Promise<void>;
 }
+export {};

package/dist/recording.js

@@ -1,14 +1,39 @@
 import * as fs from 'node:fs';
+import { Failure } from './errors.js';
 import { LlmError } from './llm.js';
-function requestKey(req) {
-    return JSON.stringify({
+export function traceRequest(req) {
+    return {
         kind: req.kind, prompt: req.prompt, model: req.model ?? null,
         reasoningEffort: req.reasoningEffort ?? null, showReasoning: req.showReasoning,
-    });
+        ...(req.naturalLanguage ? { naturalLanguage: true } : {}),
+    };
+}
+function requestKey(req) {
+    return JSON.stringify(traceRequest(req));
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+export function isResponse(value) {
+    return isRecord(value) && typeof value.text === 'string' && isRecord(value.effective)
+        && (value.reasoning === undefined || typeof value.reasoning === 'string')
+        && (value.spl === undefined || typeof value.spl === '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'
+        && (value.naturalLanguage === undefined || typeof value.naturalLanguage === 'boolean');
+}
+export 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);
@@ -29,7 +54,7 @@ export class RecordingBackend {
         fs.writeFileSync(file, JSON.stringify({ format: 'spl-generation', version: 1 }) + '\n', { flag: 'wx', mode: 0o600 });
     }
     async call(req) {
-        if (req.kind === 'agent')
+        if (req.kind === 'agent' && !req.naturalLanguage)
             throw new LlmError('agent actions cannot be recorded; record generation-only workflows');
         const request = requestKey(req);
         const response = await this.backend.call(req);
@@ -47,35 +72,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' && !req.naturalLanguage && this.mode === 'replay')
             throw new LlmError('agent actions cannot be replayed');
         const entry = this.entries[this.position];
         if (!entry)
@@ -83,7 +154,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": "1.0.0",
   "description": "Semantic Prompt Language: a Python-like language with LLM calls built into the syntax",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,9 @@
   "license": "ISC",
   "dependencies": {
     "@github/copilot-sdk": "^1.0.22",
-    "ajv": "^8.17.1"
+    "ajv": "^8.17.1",
+    "marked": "^18.1.1",
+    "yaml": "^2.8.1"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",

package/docs/syntax.ebnf

@@ -1,97 +0,0 @@
-(* 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 , separator } , { statement , separator } ;
-separator      = NL | ";" | end_of_block | EOF ;
-directive      = "@" , "{" , "model" , "=" , plain_string , [ "," ] , "}" ;
-block          = "{" , { statement , separator } , "}" ;
-
-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 ;
-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 ;
-
-(* Every block creates a lexical child scope. let declares/redeclares locally and shadows parents.
-   Reads and assignments search outward for the first declaration; undeclared names are errors.
-   Each loop iteration has fresh locals; caught failure names belong to the handler scope.
-   Blocks/if yield their final expression, otherwise None. An unmatched if yields None.
-   {} remains an empty dict; { pass } is a block yielding None. Functions need explicit return.
-   return exits the innermost function, or the script at top level.
-   success exits the script, including when used in a function. *)
-
-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 } ;
-sum            = term , { ( "+" | "-" ) , term } ;
-term           = unary , { ( "*" | "/" | "//" | "%" ) , unary } ;
-unary          = ( "-" | "+" ) , unary | "?" , [ modifiers ] , postfix | power ;
-power          = postfix , [ "**" , unary ] ;
-postfix        = primary , { call | index | slice | member } ;
-call           = "(" , [ expr , { "," , expr } , [ "," ] ] , ")" ;
-index          = "[" , expr , "]" ;
-slice          = "[" , [ expr ] , ":" , [ expr ] , "]" ;
-member         = "." , 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 } , [ "," ] ] , "}" ;
-modifier       = ( "len" | "fmt" | "reasoning" | "show" | "schema" | "repairs" | "model" ) , "=" , expr ;
-log_expr       = "log" , "{" , [ "level" , "=" , log_level , [ "," ] ] , "}" , call ;
-log_level      = "error" | "info" | "debug" | expr ;
-
-(* Unknown/duplicate modifier names are syntax errors. Values are expressions, validated at runtime:
-   len: word/sentence/paragraph/long (guidance only)
-   fmt: integer/float/array/object/text/boolean/json; schema implies json unless fmt is explicit
-   Non-text formats require strict JSON of the selected type; float accepts finite numbers,
-   object excludes arrays, and json accepts any JSON value.
-   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.
-   log{level=...}(args) selects error/info/debug severity; plain log(args) defaults to info.
-   Level values are bare names, strings or expressions, validated before evaluating arguments.
-   Debug messages are emitted only at debug log level; silent suppresses all logs.
-   enforce/forbid are scoped prompt guidance.
-   schema/assert validate data; restrict checks actions. *)
-
-string         = [ "r" ] , quote , { char | escape | interpolation } , closing_quote ;
-quote          = "'" | '"' | "'''" | '"""' ;
-plain_string   = string_without_interpolation ;
-escape         = "\" , ( "n" | "t" | "r" | "0" | "\" | "'" | '"' | "{" | "}" ) ;
-interpolation  = "{" , expr , "}" ;
-NUMBER         = digit+ , [ "." , digit+ ] , [ ( "e" | "E" ) , [ "+" | "-" ] , digit+ ] ;
-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',
-   let x += ... and let d.key = ... . *)