spl-lang 0.5.0 → 1.0.0

package/dist/cli.js

@@ -2,20 +2,23 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
 import { CopilotBackend } from './copilot.js';
 import { AuthError, login, logout } from './auth.js';
 import { Failure, SplSyntaxError } from './errors.js';
 import { LlmError } from './llm.js';
 import { Logger } from './logger.js';
-import { parse } from './parser.js';
+import { usesHuman } from './parser.js';
+import { parseMarkdown } from './markdown.js';
 import { run } from './interpreter.js';
 import { JsonFileStore, MemoryStore, loadStoreModule } from './store.js';
 import { toJson } from './values.js';
 import { loadMcpConfig } from './mcp.js';
-import { RecordingBackend, ReplayBackend } from './recording.js';
+import { RecordingBackend, ReplayBackend, TraceBackend } from './recording.js';
+import { Checkpoint, CheckpointError, checkpointFingerprint } from './checkpoint.js';
 const HELP = `spl - Semantic Prompt Language interpreter
 
-Usage: spl <script.spl> [options]
+Usage: spl <workflow.md> [options]
        spl login               authenticate with GitHub Copilot (device flow in the browser)
        spl logout              remove the credentials saved by 'spl login'
 
@@ -23,21 +26,32 @@ Options:
   --log-level <level>     error | info | debug (default: info). Logs go to stderr.
                           All levels include LLM transcripts and [deterministic] statement traces.
   --silent                suppress all logs; only the result is printed
-  --model <id>            model override (takes precedence over @{model=...})
+  --model <id>            model override (takes precedence over frontmatter)
   --arg <value>           script argument exposed in $args (repeatable; also --arg=value)
   --mcp <file.json>       MCP servers in VS Code mcp.json format
   --store <file.json>     persist top-level variables in a JSON file
   --store-module <path>   custom variable store: module exporting createStore() -> { load(), save(vars) }
   --timeout <seconds>     per LLM call timeout (default: 300)
+  --trace <file.jsonl>    trace all LLM requests, responses, and failures (new file)
   --record <file.jsonl>   record generation responses (new file; no agents)
-  --replay <file.jsonl>   offline generation replay; only local reads allowed
+  --replay <file.jsonl>   replay LLM results without Copilot/MCP; explicit script tools still run
+                          Legacy --record files allow only local reads and no stores.
+  --checkpoint <file>    start a new resumable run; with --resume, continue that journal
+                          New runs never overwrite an existing file.
+  --resume [file]        inspect pending input, or resume with an answer
+                          Omit file when using --checkpoint <file>.
+  --answer-for <id>      ID of the pending human request being answered
+  --answer <text>        exact free-text answer (requires --resume and --answer-for)
+  --answer-file <file>   read the answer from a UTF-8 file instead of --answer
   --cwd <dir>             base directory for relative paths and restrictions (default: current directory)
   --check                 validate script syntax and any --mcp config without executing
   -v, --version           print version
   -h, --help              print this help
 
 The script result (the value of 'success' or 'return', or the failure payload) is written to stdout.
-Exit codes: 0 success, 1 uncaught script failure, 2 syntax or usage error.`;
+Resumable runs print JSON envelopes and never read stdin.
+Exit codes: 0 success, 1 uncaught script failure, 2 syntax or usage error,
+3 waiting for human input, 70 internal/infrastructure error.`;
 function version() {
     const pkg = new URL('../package.json', import.meta.url);
     return JSON.parse(fs.readFileSync(pkg, 'utf8')).version;
@@ -46,6 +60,71 @@ function usageError(msg) {
     process.stderr.write(`spl: ${msg}\nTry 'spl --help'.\n`);
     process.exit(2);
 }
+async function checkpointCommand(source, program, values, cwd, logger, mcpServers) {
+    let checkpoint;
+    try {
+        const directory = fileURLToPath(new URL('.', import.meta.url));
+        const runtime = checkpointFingerprint([
+            version(), process.version,
+            ...fs.readdirSync(directory).filter((name) => name.endsWith('.js')).sort()
+                .map((name) => [name, fs.readFileSync(path.join(directory, name), 'utf8')]),
+        ]);
+        const context = {
+            source, runtime, cwd, args: values.arg,
+            configuration: { model: values.model ?? null, mcp: mcpServers ?? null },
+        };
+        checkpoint = values.resume !== undefined
+            ? Checkpoint.resume(values.resume, context)
+            : Checkpoint.create(values.checkpoint, context);
+        if (values.resume !== undefined) {
+            if (values.answer === undefined && values['answer-file'] === undefined) {
+                const envelope = { status: 'waiting_for_input', ...checkpoint.request };
+                checkpoint.close();
+                process.stdout.write(JSON.stringify(envelope) + '\n');
+                return 3;
+            }
+            let answer = values.answer;
+            if (values['answer-file'] !== undefined) {
+                try {
+                    answer = fs.readFileSync(values['answer-file'], 'utf8');
+                }
+                catch (error) {
+                    throw new CheckpointError(`cannot read answer file: ${error.message}`);
+                }
+            }
+            checkpoint.answer(values['answer-for'], answer);
+        }
+        const backend = new CopilotBackend({ logger, cwd, timeoutMs: Number(values.timeout ?? 300) * 1000, mcpServers });
+        let result;
+        try {
+            result = await run(program, { backend, logger, cwd, model: values.model, checkpoint });
+        }
+        finally {
+            await backend.close();
+        }
+        if (result.status === 'waiting_for_input') {
+            checkpoint.close();
+            process.stdout.write(JSON.stringify({ status: result.status, ...result.request }) + '\n');
+            return 3;
+        }
+        checkpoint.finish(result.status);
+        const envelope = result.status === 'success'
+            ? { status: result.status, run_id: checkpoint.runId, has_value: result.hasValue, value: toJson(result.value) }
+            : { status: result.status, run_id: checkpoint.runId, failure: result.failure };
+        checkpoint.close();
+        process.stdout.write(JSON.stringify(envelope) + '\n');
+        return result.status === 'success' ? 0 : 1;
+    }
+    catch (error) {
+        if (!(error instanceof CheckpointError) || error.kind !== 'usage')
+            throw error;
+        process.stderr.write(`spl: ${error.message}\n`);
+        return 2;
+    }
+    finally {
+        checkpoint?.close();
+    }
+}
 async function loginCommand() {
     try {
         const status = await login((line) => process.stdout.write(line + '\n'));
@@ -73,25 +152,48 @@ function logoutCommand() {
 }
 async function main() {
     let parsed;
+    let resumeWithCheckpoint = false;
     try {
+        const options = {
+            'log-level': { type: 'string' },
+            silent: { type: 'boolean' },
+            model: { type: 'string' },
+            arg: { type: 'string', multiple: true },
+            mcp: { type: 'string' },
+            store: { type: 'string' },
+            'store-module': { type: 'string' },
+            timeout: { type: 'string' },
+            trace: { type: 'string' },
+            record: { type: 'string' },
+            replay: { type: 'string' },
+            checkpoint: { type: 'string' },
+            resume: { type: 'string' },
+            'answer-for': { type: 'string' },
+            answer: { type: 'string' },
+            'answer-file': { type: 'string' },
+            cwd: { type: 'string' },
+            check: { type: 'boolean' },
+            version: { type: 'boolean', short: 'v' },
+            help: { type: 'boolean', short: 'h' },
+        };
+        const args = process.argv.slice(2);
+        // parseArgs has no optional string options; locate bare --resume using tokens.
+        const { tokens } = parseArgs({
+            args, options: { ...options, resume: { type: 'boolean' } },
+            allowPositionals: true, strict: false, tokens: true,
+        });
+        const checkpointHasScript = tokens.some((token) => token.kind === 'option' && token.name === 'checkpoint')
+            && tokens.filter((token) => token.kind === 'positional').length === 1;
+        const bareResume = new Set(tokens
+            .filter((token) => token.kind === 'option' && token.name === 'resume'
+            && token.value === undefined
+            && (checkpointHasScript || args[token.index + 1] === undefined || args[token.index + 1].startsWith('-')))
+            .map((token) => token.index));
+        resumeWithCheckpoint = bareResume.size > 0;
         parsed = parseArgs({
+            args: args.filter((_, index) => !bareResume.has(index)),
             allowPositionals: true,
-            options: {
-                'log-level': { type: 'string' },
-                silent: { type: 'boolean' },
-                model: { type: 'string' },
-                arg: { type: 'string', multiple: true },
-                mcp: { type: 'string' },
-                store: { type: 'string' },
-                'store-module': { type: 'string' },
-                timeout: { type: 'string' },
-                record: { type: 'string' },
-                replay: { type: 'string' },
-                cwd: { type: 'string' },
-                check: { type: 'boolean' },
-                version: { type: 'boolean', short: 'v' },
-                help: { type: 'boolean', short: 'h' },
-            },
+            options,
         });
     }
     catch (e) {
@@ -122,12 +224,40 @@ async function main() {
         usageError('--timeout must be a positive number');
     if (values.store && values['store-module'])
         usageError('--store and --store-module are mutually exclusive');
-    if (values.record && values.replay)
-        usageError('--record and --replay are mutually exclusive');
-    if (values.replay && (values.store || values['store-module']))
-        usageError('--replay cannot use a persistent variable store');
+    if ([values.trace, values.record, values.replay].filter((value) => value !== undefined).length > 1) {
+        usageError('--trace, --record, and --replay are mutually exclusive');
+    }
+    if ([values.trace, values.record, values.replay].some((value) => value !== undefined && value.trim() === '')) {
+        usageError('--trace, --record, and --replay require a non-empty file path');
+    }
+    if (resumeWithCheckpoint) {
+        if (values.resume !== undefined)
+            usageError('use either --resume <file> or --resume --checkpoint <file>');
+        if (values.checkpoint === undefined)
+            usageError('--resume requires a file: use --resume <file> or --resume --checkpoint <file>');
+        values.resume = values.checkpoint;
+        delete values.checkpoint;
+    }
+    const resumable = values.checkpoint !== undefined || values.resume !== undefined;
+    if (values.checkpoint !== undefined && values.resume !== undefined)
+        usageError('--checkpoint and --resume are mutually exclusive');
+    if ([values.checkpoint, values.resume, values['answer-for'], values['answer-file']].some((value) => value !== undefined && !value.trim())) {
+        usageError('checkpoint, resume, answer-for, and answer-file require non-empty values');
+    }
+    if (resumable && [values.store, values['store-module'], values.trace, values.record, values.replay].some((value) => value !== undefined)) {
+        usageError('resumable runs cannot use --store, --store-module, --trace, --record, or --replay');
+    }
+    const answering = values.answer !== undefined || values['answer-file'] !== undefined;
+    if (values.answer !== undefined && values['answer-file'] !== undefined)
+        usageError('--answer and --answer-file are mutually exclusive');
+    if ((answering || values['answer-for'] !== undefined) && values.resume === undefined)
+        usageError('answer flags require --resume');
+    if (answering !== (values['answer-for'] !== undefined))
+        usageError('an answer requires --answer-for, and --answer-for requires an answer');
     const cwd = path.resolve(values.cwd ?? process.cwd());
     const file = positionals[0];
+    if (!/\.md$/i.test(file))
+        usageError('only .md workflows are executable; wrap SPL in a fenced spl block and add extension/version frontmatter');
     let source;
     try {
         source = fs.readFileSync(file, 'utf8');
@@ -137,7 +267,7 @@ async function main() {
     }
     let program;
     try {
-        program = parse(source);
+        program = parseMarkdown(source);
     }
     catch (e) {
         if (e instanceof SplSyntaxError) {
@@ -155,13 +285,10 @@ async function main() {
     }
     if (values.check)
         return 0;
-    let store;
-    try {
-        store = values.store ? new JsonFileStore(values.store) : values['store-module'] ? await loadStoreModule(values['store-module']) : new MemoryStore();
-    }
-    catch (e) {
-        return usageError(e.message);
-    }
+    if (resumable)
+        return checkpointCommand(source, program, values, cwd, logger, mcpServers);
+    if (usesHuman(program))
+        usageError('human input requires --checkpoint or --resume');
     let backend;
     try {
         if (values.replay)
@@ -170,6 +297,8 @@ async function main() {
             backend = new CopilotBackend({ logger, cwd, timeoutMs: timeoutSec * 1000, mcpServers });
             if (values.record)
                 backend = new RecordingBackend(backend, values.record);
+            if (values.trace)
+                backend = new TraceBackend(backend, values.trace);
         }
     }
     catch (e) {
@@ -177,9 +306,19 @@ async function main() {
             throw e;
         return usageError(`cannot open recording: ${e.message}`);
     }
+    if (backend.mode === 'replay' && (values.store || values['store-module'])) {
+        return usageError('--replay of legacy --record files cannot use a persistent variable store');
+    }
+    let store;
+    try {
+        store = values.store ? new JsonFileStore(values.store) : values['store-module'] ? await loadStoreModule(values['store-module']) : new MemoryStore();
+    }
+    catch (e) {
+        return usageError(e.message);
+    }
     let result;
     try {
-        result = await run(program, { backend, logger, store: values.replay ? undefined : store, cwd, model: values.model, args: values.arg });
+        result = await run(program, { backend, logger, store: backend.mode === 'replay' ? undefined : store, cwd, model: values.model, args: values.arg });
     }
     finally {
         try {
@@ -197,6 +336,8 @@ async function main() {
         process.stdout.write(JSON.stringify(result.failure, null, 4) + '\n');
         return 1;
     }
+    if (result.status === 'waiting_for_input')
+        throw new CheckpointError('unexpected human suspension without a checkpoint', 'infrastructure');
     if (result.hasValue) {
         const v = result.value;
         process.stdout.write((typeof v === 'string' ? v : JSON.stringify(toJson(v), null, 2)) + '\n');

package/dist/copilot.js

@@ -1,6 +1,7 @@
 import { CopilotClient, defineTool } from '@github/copilot-sdk';
 import { loadToken } from './auth.js';
-import { Failure } from './errors.js';
+import { Failure, SplSyntaxError } from './errors.js';
+import { parse } from './parser.js';
 import { LlmError } from './llm.js';
 import { TOOL_SPECS } from './tools.js';
 import { configuredMcpTool, filterMcpServers } from './mcp.js';
@@ -81,7 +82,8 @@ export class CopilotBackend {
             violation ??= failure;
             void session?.abort().catch(() => undefined);
         };
-        const agent = req.kind === 'agent';
+        const agent = req.kind === 'agent' && !req.naturalLanguage;
+        let submitted;
         const tools = (agent ? TOOL_NAMES : []).map((name) => {
             const spec = TOOL_SPECS[name];
             return defineTool(name, {
@@ -105,15 +107,50 @@ export class CopilotBackend {
                 },
             });
         });
+        if (req.naturalLanguage) {
+            tools.push(defineTool('submit_spl', {
+                description: 'Submit one complete SPL program to execute after this request, in shared document scope. No actions occur during submission.',
+                parameters: {
+                    type: 'object', properties: { source: { type: 'string' } },
+                    required: ['source'], additionalProperties: false,
+                },
+                handler: async (args) => {
+                    if (!args || typeof args !== 'object' || !('source' in args) ||
+                        typeof args.source !== 'string' || !args.source.trim()) {
+                        return { resultType: 'failure', textResultForLlm: 'source must be non-empty SPL code' };
+                    }
+                    if (submitted !== undefined) {
+                        return { resultType: 'failure', textResultForLlm: 'a program has already been submitted' };
+                    }
+                    try {
+                        const program = parse(args.source);
+                        if (program.directives.model !== undefined) {
+                            return { resultType: 'failure', textResultForLlm: 'use model modifiers, not a model header' };
+                        }
+                    }
+                    catch (error) {
+                        if (!(error instanceof SplSyntaxError))
+                            throw error;
+                        return { resultType: 'failure', textResultForLlm: error.message };
+                    }
+                    submitted = args.source;
+                    return 'Program accepted for execution after this request. Do not submit again.';
+                },
+            }));
+        }
         const mcpServers = agent ? filterMcpServers(this.opts.mcpServers ?? {}, req.restrictions) : {};
         const baseConfig = {
             model: req.model,
             tools,
-            availableTools: [...(agent ? TOOL_NAMES : []), ...Object.keys(mcpServers).map((name) => `mcp:${name}-*`)],
+            availableTools: [...tools.map((tool) => tool.name), ...Object.keys(mcpServers).map((name) => `mcp:${name}-*`)],
             mcpServers,
             systemMessage: { mode: 'append', content: SYSTEM_MESSAGE },
             workingDirectory: this.opts.cwd,
-            onPermissionRequest: (r) => agent ? decidePermission(r, req.restrictions, block, mcpServers) : this.denyGenerationPermission(block),
+            onPermissionRequest: (r) => {
+                if (req.naturalLanguage && r.kind === 'custom-tool' && r.toolName === 'submit_spl')
+                    return { kind: 'approve-once' };
+                return agent ? decidePermission(r, req.restrictions, block, mcpServers) : this.denyGenerationPermission(block);
+            },
         };
         try {
             try {
@@ -143,12 +180,15 @@ export class CopilotBackend {
             }
             if (violation)
                 throw violation;
-            const text = answer?.data?.content;
+            if (req.naturalLanguage && submitted === undefined)
+                throw new LlmError('natural-language request did not call submit_spl');
+            const text = answer?.data?.content ?? (submitted !== undefined ? 'SPL program submitted.' : undefined);
             if (typeof text !== 'string' || text.trim() === '')
                 throw new LlmError('the model returned an empty response');
             const usedModel = answer?.data?.model;
             return {
                 text,
+                ...(submitted !== undefined ? { spl: submitted } : {}),
                 reasoning: reasoning.length ? reasoning.join('\n') : undefined,
                 effective: {
                     backend: 'copilot-sdk',

package/dist/index.d.ts

@@ -1,9 +1,11 @@
-export { parse } from './parser.js';
+export { parse, usesHuman } from './parser.js';
+export { parseMarkdown, extractMarkdown, isWorkflowMarkdown } from './markdown.js';
 export { run, type RunOptions, type RunResult } from './interpreter.js';
 export { Failure, SplSyntaxError, type FailurePayload, type StatusCode } from './errors.js';
 export { Logger, type LogLevel } from './logger.js';
 export { CopilotBackend } from './copilot.js';
-export { RecordingBackend, ReplayBackend } from './recording.js';
+export { RecordingBackend, ReplayBackend, TraceBackend } from './recording.js';
+export { Checkpoint, CheckpointError, checkpointFingerprint, type CheckpointContext, type HumanRequest } from './checkpoint.js';
 export { loadMcpConfig, type McpServers } from './mcp.js';
 export { login, logout, authStatus, AuthError } from './auth.js';
 export { JsonFileStore, MemoryStore, loadStoreModule, type VariableStore } from './store.js';

package/dist/index.js

@@ -1,9 +1,11 @@
-export { parse } from './parser.js';
+export { parse, usesHuman } from './parser.js';
+export { parseMarkdown, extractMarkdown, isWorkflowMarkdown } from './markdown.js';
 export { run } from './interpreter.js';
 export { Failure, SplSyntaxError } from './errors.js';
 export { Logger } from './logger.js';
 export { CopilotBackend } from './copilot.js';
-export { RecordingBackend, ReplayBackend } from './recording.js';
+export { RecordingBackend, ReplayBackend, TraceBackend } from './recording.js';
+export { Checkpoint, CheckpointError, checkpointFingerprint } from './checkpoint.js';
 export { loadMcpConfig } from './mcp.js';
 export { login, logout, authStatus, AuthError } from './auth.js';
 export { JsonFileStore, MemoryStore, loadStoreModule } from './store.js';

package/dist/interpreter.d.ts

@@ -3,6 +3,7 @@ import { type FailurePayload } from './errors.js';
 import { type LlmBackend } from './llm.js';
 import type { Logger } from './logger.js';
 import { type VariableStore } from './store.js';
+import { type Checkpoint, type HumanRequest } from './checkpoint.js';
 import { type Value } from './values.js';
 export interface RunOptions {
     backend: LlmBackend;
@@ -10,11 +11,12 @@ export interface RunOptions {
     store?: VariableStore;
     /** Working directory for relative paths, `restrict` folders and tools. */
     cwd?: string;
-    /** Overrides the `@{model=...}` directive. */
+    /** Overrides the `@(model=...)` directive. */
     model?: string;
     /** Script arguments exposed as read-only `$args`; defaults to an empty list. */
     args?: readonly string[];
     maxCallDepth?: number;
+    checkpoint?: Checkpoint;
 }
 export type RunResult = {
     status: 'success';
@@ -23,5 +25,8 @@ export type RunResult = {
 } | {
     status: 'failure';
     failure: FailurePayload;
+} | {
+    status: 'waiting_for_input';
+    request: HumanRequest;
 };
 export declare function run(program: Program, opts: RunOptions): Promise<RunResult>;