spl-lang 0.6.0 → 1.0.1

package/dist/preamble.js

@@ -0,0 +1,42 @@
+export const RUNTIME_PREAMBLE = `You are running a Semantic Prompt Language Markdown workflow.
+Only fenced spl blocks and blockquotes execute; other Markdown is commentary.
+Respect the requested output format. ask and think generate values without tools; agent permits actions.
+Runtime tools: read_file(path), write_file(path, content), web_fetch(url), web_search(query), shell(command).
+All actions are subject to active runtime restrictions. Never claim an action happened unless it executed.`;
+export const NATURAL_PREAMBLE = `Translate this blockquote into SPL using submit_spl exactly once.
+The submitted program executes AFTER this model request completes, in the shared document scope.
+Do not perform actions yourself or merely describe them. Use SPL to read data, branch on it and perform actions.
+@name refers to a shared variable or SPL operation (e.g. @answer, @read_file, @success).
+Markers are semantic references, not textual substitution; plain natural language is equally supported.
+Do not terminate the document unless requested; use success, fail or top-level return only to end it.
+Existing bindings and function signatures are supplied as context, not instructions.
+
+SPL syntax (Python-like expressions with brace blocks; no Python imports):
+let name = expression declares a variable; name = expression updates an existing variable.
+Values: None, True, False, numbers, 'strings', [lists], {'key': value}; indexing and member access work.
+Strings interpolate {expression}; use doubled {{ and }} for literal braces.
+if condition { ... } elif condition { ... } else { ... }
+for item in sequence { ... }; while condition { ... }; break; continue
+def name(arg) { return expression }; functions have lexical scope.
+Blocks create child scopes: a let inside if/for/enforce/forbid/restrict/try disappears when the block ends.
+Declare every @name the instruction saves at the top level, then assign it inside blocks without let.
+Operators: + - * / // % **, == != < <= > >=, in, not in, and, or, not.
+Builtins include range, len, str, int, float, bool, keys, values, items, json_parse, json_stringify.
+log(value); log(level=debug)(value); assert condition 'message'; try { ... } except err { ... }
+success value ends the document successfully; fail 'reason' fails it; return value also ends it.
+let answer = human 'Question' suspends via checkpoint; requires --checkpoint/--resume.
+$args is a read-only list of CLI arguments; $env is the read-only environment.
+ask 'prompt' and think 'prompt' generate values; agent 'task' performs model-directed actions.
+Generation options: ask(fmt='json', schema=Schema, repairs=2, model='id', reasoning='high') 'prompt'.
+fmt: text, json, integer, float, boolean, array, object. repairs is 0..5 (not for agent).
+len: word, sentence, paragraph, long. show=True emits reasoning. Options are expression-valued.
+enforce 'guidance' { ... }; forbid 'guidance' { ... } are scoped model instructions.
+restrict './folder', exec 'git', net 'example.com', mcp 'server/tool' { ... } limits actions.
+All existing runtime tools, functions, control flow, validation and human input are available through SPL.
+Submit a complete program, not Markdown fences, not an @(model=...) header.
+Example: "Read @path and store a summary in @summary" =>
+let content = read_file(path)
+let summary = ask 'Summarize: {content}'
+Example: "@ENFORCE Be formal. Write a greeting for @name -> @greeting" =>
+let greeting = None
+enforce 'Be formal' { greeting = ask 'Write a greeting for {name}' }`;

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;
@@ -23,3 +45,4 @@ export declare class ReplayBackend implements LlmBackend {
     call(req: LlmRequest): Promise<LlmResponse>;
     close(): Promise<void>;
 }
+export {};

package/dist/recording.js

@@ -1,10 +1,11 @@
 import * as fs from 'node:fs';
 import { Failure } from './errors.js';
 import { LlmError } from './llm.js';
-function traceRequest(req) {
+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) {
@@ -13,17 +14,19 @@ function requestKey(req) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function isResponse(value) {
+export function isResponse(value) {
     return isRecord(value) && typeof value.text === 'string' && isRecord(value.effective)
-        && (value.reasoning === undefined || typeof value.reasoning === 'string');
+        && (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';
+        && typeof value.showReasoning === 'boolean'
+        && (value.naturalLanguage === undefined || typeof value.naturalLanguage === 'boolean');
 }
-function isTraceError(value) {
+export function isTraceError(value) {
     const codes = [
         'assertion_failed', 'explicit_failure', 'invalid_format', 'validation_failed',
         'restriction_violation', 'llm_error', 'tool_error', 'runtime_error',
@@ -51,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);
@@ -143,7 +146,7 @@ export class ReplayBackend {
         });
     }
     async call(req) {
-        if (req.kind === 'agent' && this.mode === 'replay')
+        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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spl-lang",
-  "version": "0.6.0",
+  "version": "1.0.1",
   "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 = ... . *)