spl-lang 0.0.0-stage → 0.1.0

package/dist/copilot.js

@@ -0,0 +1,192 @@
+import { CopilotClient, defineTool } from '@github/copilot-sdk';
+import { loadToken } from './auth.js';
+import { Failure } from './errors.js';
+import { LlmError } from './llm.js';
+import { TOOL_SPECS } from './tools.js';
+const SYSTEM_MESSAGE = [
+    'You are the execution engine of an automated script. Your reply is stored in a variable and used by the program.',
+    'Reply with exactly what was asked for: no preamble, no sign-off, no commentary.',
+    'Use the provided tools (read_file, write_file, web_fetch, web_search, shell) only when the task needs them. No other tools exist.',
+].join(' ');
+const TOOL_NAMES = Object.keys(TOOL_SPECS);
+export class CopilotBackend {
+    opts;
+    client;
+    models;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async getClient() {
+        if (!this.client) {
+            const token = loadToken();
+            const client = new CopilotClient(token ? { gitHubToken: token } : {});
+            try {
+                await client.start();
+                const status = await client.getAuthStatus();
+                if (!status.isAuthenticated) {
+                    throw new Error(`not authenticated with GitHub Copilot${status.statusMessage ? ` (${status.statusMessage})` : ''}; run 'spl login'`);
+                }
+            }
+            catch (e) {
+                await client.stop().catch(() => undefined);
+                throw new LlmError(`cannot start the Copilot runtime: ${e.message}`);
+            }
+            this.client = client;
+        }
+        return this.client;
+    }
+    listModels(client) {
+        this.models ??= client.listModels().catch((e) => {
+            this.opts.logger.debug(`could not list models: ${e.message}`);
+            return undefined;
+        });
+        return this.models;
+    }
+    /** Maps the `think` level to the SDK reasoning effort, warning when the model cannot honor it. */
+    async resolveEffort(client, req) {
+        if (!req.reasoningEffort)
+            return undefined;
+        if (!req.model)
+            return req.reasoningEffort; // default model unknown; session creation is retried without it on error
+        const info = (await this.listModels(client))?.find((m) => m.id === req.model);
+        const supported = info?.supportedReasoningEfforts;
+        if (info && !supported?.includes(req.reasoningEffort)) {
+            this.opts.logger.warn(`model '${req.model}' does not support reasoning effort '${req.reasoningEffort}'; using the model default`);
+            return undefined;
+        }
+        return req.reasoningEffort;
+    }
+    /** Fails on a model id the runtime does not offer; it would otherwise silently fall back to the default model. */
+    async checkModel(client, model) {
+        if (!model)
+            return;
+        const models = await this.listModels(client);
+        if (models && !models.some((m) => m.id === model)) {
+            throw new LlmError(`unknown model '${model}' (available: ${models.map((m) => m.id).join(', ')})`);
+        }
+    }
+    async call(req) {
+        const client = await this.getClient();
+        await this.checkModel(client, req.model);
+        let effort = await this.resolveEffort(client, req);
+        let violation;
+        let session;
+        const block = (failure) => {
+            violation ??= failure;
+            void session?.abort().catch(() => undefined);
+        };
+        const tools = TOOL_NAMES.map((name) => {
+            const spec = TOOL_SPECS[name];
+            return defineTool(name, {
+                description: spec.description,
+                overridesBuiltInTool: true,
+                parameters: { type: 'object', properties: spec.properties, required: spec.required, additionalProperties: false },
+                handler: async (args) => {
+                    const params = { ...args };
+                    if (req.pinned?.tool === name)
+                        Object.assign(params, req.pinned.params);
+                    try {
+                        return await req.tools.invoke(name, params);
+                    }
+                    catch (e) {
+                        if (!(e instanceof Failure))
+                            throw e;
+                        if (e.statusCode === 'restriction_violation') {
+                            block(e);
+                            return { textResultForLlm: JSON.stringify(e.payload()), resultType: 'denied', error: e.reason };
+                        }
+                        return { textResultForLlm: e.reason, resultType: 'failure', error: e.reason };
+                    }
+                },
+            });
+        });
+        const baseConfig = {
+            model: req.model,
+            tools,
+            availableTools: TOOL_NAMES,
+            systemMessage: { mode: 'append', content: SYSTEM_MESSAGE },
+            workingDirectory: this.opts.cwd,
+            onPermissionRequest: (r) => decidePermission(r, req.restrictions, block),
+        };
+        try {
+            try {
+                session = await client.createSession({ ...baseConfig, reasoningEffort: effort });
+            }
+            catch (e) {
+                if (!effort)
+                    throw e;
+                this.opts.logger.warn(`reasoning effort '${effort}' was rejected (${e.message}); using the model default`);
+                effort = undefined;
+                session = await client.createSession(baseConfig);
+            }
+            const reasoning = [];
+            session.on('assistant.reasoning', (ev) => {
+                reasoning.push(ev.data.content);
+                if (req.showReasoning)
+                    this.opts.logger.info(`reasoning: ${ev.data.content}`);
+            });
+            let answer;
+            try {
+                answer = await session.sendAndWait({ prompt: req.prompt }, this.opts.timeoutMs);
+            }
+            catch (e) {
+                if (violation)
+                    throw violation;
+                throw new LlmError(e.message);
+            }
+            if (violation)
+                throw violation;
+            const text = answer?.data?.content;
+            if (typeof text !== 'string' || text.trim() === '')
+                throw new LlmError('the model returned an empty response');
+            const usedModel = answer?.data?.model;
+            return {
+                text,
+                reasoning: reasoning.length ? reasoning.join('\n') : undefined,
+                effective: {
+                    backend: 'copilot-sdk',
+                    model: usedModel ?? req.model ?? 'default',
+                    reasoningEffort: effort ?? null,
+                },
+            };
+        }
+        finally {
+            await session?.disconnect().catch(() => undefined);
+        }
+    }
+    async close() {
+        await this.client?.stop().catch(() => undefined);
+        this.client = undefined;
+    }
+}
+/**
+ * Hard enforcement at the permission layer. Only the five runtime tools are exposed to the model, so any
+ * other request is denied; requests that would violate a restriction are additionally reported as violations.
+ */
+export function decidePermission(r, restrictions, block) {
+    try {
+        if (r.kind === 'custom-tool' && TOOL_NAMES.includes(r.toolName)) {
+            return { kind: 'approve-once' }; // the tool itself performs the restriction checks
+        }
+        if (r.kind === 'read')
+            restrictions.checkPath(r.path, 'read');
+        else if (r.kind === 'write')
+            restrictions.checkPath(r.fileName, 'write');
+        else if (r.kind === 'url')
+            restrictions.checkUrl(r.url);
+        else if (r.kind === 'shell') {
+            const s = r;
+            for (const c of s.commands)
+                restrictions.checkExec(c.identifier);
+            for (const p of s.possiblePaths)
+                restrictions.checkPath(p, 'read');
+        }
+    }
+    catch (e) {
+        if (e instanceof Failure && e.statusCode === 'restriction_violation') {
+            block(e);
+            return { kind: 'reject', feedback: JSON.stringify(e.payload()) };
+        }
+    }
+    return { kind: 'reject', feedback: 'Only the read_file, write_file, web_fetch, web_search and shell tools may be used.' };
+}

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+export type StatusCode = 'assertion_failed' | 'explicit_failure' | 'invalid_format' | 'restriction_violation' | 'llm_error' | 'tool_error' | 'runtime_error';
+export interface FailurePayload {
+    status: 'failure';
+    reason: string;
+    command: string;
+    line: number;
+    status_code: StatusCode;
+}
+/** A script-level failure. Stops the script unless caught by try/except. */
+export declare class Failure extends Error {
+    readonly statusCode: StatusCode;
+    reason: string;
+    command: string;
+    line: number;
+    located: boolean;
+    constructor(statusCode: StatusCode, reason: string);
+    locate(line: number, command: string): this;
+    payload(): FailurePayload;
+}
+/** Thrown by `success`: stops the script with a result. */
+export declare class SuccessSignal {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
+/** Strict syntax error found while parsing; never catchable by scripts. */
+export declare class SplSyntaxError extends Error {
+    readonly line: number;
+    readonly col: number;
+    constructor(message: string, line: number, col: number);
+    format(file: string): string;
+}

package/dist/errors.js

@@ -0,0 +1,52 @@
+/** A script-level failure. Stops the script unless caught by try/except. */
+export class Failure extends Error {
+    statusCode;
+    reason;
+    command = '';
+    line = 0;
+    located = false;
+    constructor(statusCode, reason) {
+        super(reason);
+        this.name = 'Failure';
+        this.statusCode = statusCode;
+        this.reason = reason;
+    }
+    locate(line, command) {
+        if (!this.located) {
+            this.line = line;
+            this.command = command;
+            this.located = true;
+        }
+        return this;
+    }
+    payload() {
+        return {
+            status: 'failure',
+            reason: this.reason,
+            command: this.command,
+            line: this.line,
+            status_code: this.statusCode,
+        };
+    }
+}
+/** Thrown by `success`: stops the script with a result. */
+export class SuccessSignal {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+/** Strict syntax error found while parsing; never catchable by scripts. */
+export class SplSyntaxError extends Error {
+    line;
+    col;
+    constructor(message, line, col) {
+        super(message);
+        this.line = line;
+        this.col = col;
+        this.name = 'SplSyntaxError';
+    }
+    format(file) {
+        return `${file}:${this.line}:${this.col}: syntax error: ${this.message}`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { parse } from './parser.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 { login, logout, authStatus, AuthError } from './auth.js';
+export { JsonFileStore, MemoryStore, loadStoreModule, type VariableStore } from './store.js';
+export type { LlmBackend, LlmRequest, LlmResponse } from './llm.js';
+export type { Program } from './ast.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { parse } from './parser.js';
+export { run } from './interpreter.js';
+export { Failure, SplSyntaxError } from './errors.js';
+export { Logger } from './logger.js';
+export { CopilotBackend } from './copilot.js';
+export { login, logout, authStatus, AuthError } from './auth.js';
+export { JsonFileStore, MemoryStore, loadStoreModule } from './store.js';

package/dist/interpreter.d.ts

@@ -0,0 +1,25 @@
+import type { Program } from './ast.js';
+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 Value } from './values.js';
+export interface RunOptions {
+    backend: LlmBackend;
+    logger: Logger;
+    store?: VariableStore;
+    /** Working directory for relative paths, `restrict` folders and tools. */
+    cwd?: string;
+    /** Overrides the `@{model=...}` directive. */
+    model?: string;
+    maxCallDepth?: number;
+}
+export type RunResult = {
+    status: 'success';
+    value: Value;
+    hasValue: boolean;
+} | {
+    status: 'failure';
+    failure: FailurePayload;
+};
+export declare function run(program: Program, opts: RunOptions): Promise<RunResult>;