@arnilo/prism-coding-agent 0.0.8 → 0.0.11

package/dist/checks.js

@@ -0,0 +1,249 @@
+import { spawn } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { DEFAULT_CHECK_TIMEOUT_MS, DEFAULT_MAX_CHECK_CONCURRENCY, DEFAULT_MAX_CHECK_DIAGNOSTIC_LINES, DEFAULT_MAX_CHECK_NAMES, DEFAULT_MAX_CHECK_OUTPUT_BYTES, HARD_CHECK_TIMEOUT_MS, HARD_MAX_BYTES, HARD_MAX_CHECK_CONCURRENCY, HARD_MAX_CHECK_DIAGNOSTIC_LINES, HARD_MAX_CHECK_NAMES, HARD_MAX_CHECK_OUTPUT_BYTES, validateCodingLimit, } from "./limits.js";
+import { OutputAccumulator } from "./output-accumulator.js";
+class Semaphore {
+    max;
+    active = 0;
+    waiters = [];
+    constructor(max) {
+        this.max = max;
+    }
+    async acquire() {
+        if (this.active < this.max) {
+            this.active++;
+            return;
+        }
+        await new Promise((resolve) => this.waiters.push(resolve));
+        this.active++;
+    }
+    release() {
+        this.active--;
+        const next = this.waiters.shift();
+        if (next)
+            next();
+    }
+}
+function errorResult(toolCallId, message) {
+    return {
+        toolCallId,
+        name: "coding_check",
+        content: [{ type: "text", text: message }],
+        error: { message },
+    };
+}
+function validateCheckMap(checks) {
+    const names = Object.keys(checks);
+    if (names.length < 1)
+        throw new Error("checks must declare at least one named command");
+    validateCodingLimit("checkNames", names.length, HARD_MAX_CHECK_NAMES);
+    const map = new Map();
+    for (const name of names) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name)) {
+            throw new Error(`invalid check name: ${name}`);
+        }
+        const def = checks[name];
+        if (!def || typeof def.file !== "string" || def.file.length === 0) {
+            throw new Error(`check ${name} requires a non-empty file`);
+        }
+        if (!Array.isArray(def.args) || def.args.some((a) => typeof a !== "string" || a.includes("\0"))) {
+            throw new Error(`check ${name} args must be strings without NUL`);
+        }
+        map.set(name, def);
+    }
+    void DEFAULT_MAX_CHECK_NAMES;
+    return map;
+}
+async function runNamedCheck(def, cwd, options) {
+    if (options.signal?.aborted) {
+        return { exitCode: null, output: "", timedOut: false, aborted: true };
+    }
+    const displayBytes = Math.min(50 * 1024, HARD_MAX_BYTES, options.maxBytes);
+    const accumulator = new OutputAccumulator({
+        maxLines: options.maxLines,
+        maxBytes: displayBytes,
+        maxTotalOutputBytes: options.maxBytes,
+        tempFilePrefix: "prism-check",
+    });
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let timedOut = false;
+        let aborted = false;
+        let child;
+        let timer;
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            accumulator.finish();
+            const snap = accumulator.snapshot({ persistIfTruncated: false });
+            if (snap.fullOutputPath) {
+                void rm(snap.fullOutputPath, { force: true }).catch(() => undefined);
+            }
+            resolve({
+                exitCode,
+                output: snap.content,
+                timedOut,
+                aborted,
+            });
+        };
+        const onAbort = () => {
+            aborted = true;
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        };
+        try {
+            const env = { PATH: "/usr/bin:/bin", LANG: "C", ...(def.env ?? {}) };
+            child = spawn(def.file, [...def.args], {
+                cwd: def.cwd ?? cwd,
+                env,
+                stdio: ["ignore", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+                windowsHide: true,
+                shell: false,
+            });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        child.stdout.on("data", (chunk) => accumulator.append(chunk));
+        child.stderr.on("data", (chunk) => accumulator.append(chunk));
+        child.on("error", (error) => {
+            if (!settled) {
+                settled = true;
+                reject(error);
+            }
+        });
+        child.on("close", (code) => finish(code));
+        timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        }, options.timeoutMs);
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Create the `coding_check` tool. Model may only select a declared name — never
+ * executable path or arguments.
+ */
+export function createCodingCheckTool(cwd, options) {
+    const checks = validateCheckMap(options.checks);
+    const maxConcurrency = validateCodingLimit("maxConcurrency", options.maxConcurrency ?? DEFAULT_MAX_CHECK_CONCURRENCY, HARD_MAX_CHECK_CONCURRENCY);
+    const maxDiagnosticLines = validateCodingLimit("maxDiagnosticLines", options.maxDiagnosticLines ?? DEFAULT_MAX_CHECK_DIAGNOSTIC_LINES, HARD_MAX_CHECK_DIAGNOSTIC_LINES);
+    const maxOutputBytes = validateCodingLimit("maxOutputBytes", options.maxOutputBytes ?? DEFAULT_MAX_CHECK_OUTPUT_BYTES, HARD_MAX_CHECK_OUTPUT_BYTES);
+    const defaultTimeoutMs = validateCodingLimit("defaultTimeoutMs", options.defaultTimeoutMs ?? DEFAULT_CHECK_TIMEOUT_MS, HARD_CHECK_TIMEOUT_MS);
+    const semaphore = new Semaphore(maxConcurrency);
+    const names = [...checks.keys()].sort();
+    return {
+        name: "coding_check",
+        description: `Run a host-declared named check. Allowed names: ${names.join(", ")}. The model cannot choose executables or arguments.`,
+        exclusive: true,
+        parameters: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Declared check name",
+                    enum: names,
+                },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        async execute(args, context) {
+            const toolCallId = context.toolCallId;
+            if (context.signal?.aborted)
+                return errorResult(toolCallId, "Operation aborted");
+            const name = typeof args.name === "string" ? args.name : "";
+            const def = checks.get(name);
+            if (!def)
+                return errorResult(toolCallId, `unknown check name: ${name}`);
+            if (!isAbsolute(def.file) && !(def.env && typeof def.env.PATH === "string")) {
+                return errorResult(toolCallId, `check ${name} file must be absolute unless env.PATH is explicitly provided`);
+            }
+            const timeoutMs = validateCodingLimit("timeoutMs", def.timeoutMs ?? defaultTimeoutMs, HARD_CHECK_TIMEOUT_MS);
+            const policyCheck = await enforceExecutionPolicy(options.executionPolicy, {
+                kind: "check",
+                operation: name,
+                paths: [def.cwd ?? cwd],
+                risk: "medium",
+                metadata: {
+                    checkName: name,
+                    file: def.file,
+                    args: def.args,
+                    sessionId: context.sessionId,
+                    runId: context.runId,
+                    signal: context.signal,
+                },
+            }, toolCallId, "coding_check");
+            if (!policyCheck.allowed)
+                return policyCheck.result;
+            await semaphore.acquire();
+            try {
+                const result = await runNamedCheck(def, cwd, {
+                    signal: context.signal,
+                    timeoutMs,
+                    maxLines: maxDiagnosticLines,
+                    maxBytes: maxOutputBytes,
+                });
+                if (result.aborted)
+                    return errorResult(toolCallId, "Operation aborted");
+                if (result.timedOut) {
+                    return {
+                        toolCallId,
+                        name: "coding_check",
+                        content: [{ type: "text", text: `${result.output}\n[check timed out]`.trim() }],
+                        error: { message: `check ${name} timed out` },
+                        metadata: { name, exitCode: result.exitCode, timedOut: true },
+                    };
+                }
+                const footer = result.exitCode === 0 ? "" : `\n[check exited with code ${result.exitCode}]`;
+                return {
+                    toolCallId,
+                    name: "coding_check",
+                    content: [
+                        {
+                            type: "text",
+                            text: `${result.output}${footer}`.trim() || `(check ${name} produced no output)`,
+                        },
+                    ],
+                    metadata: {
+                        name,
+                        exitCode: result.exitCode,
+                        summary: result.exitCode === 0 ? "passed" : `failed (${result.exitCode})`,
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return errorResult(toolCallId, message);
+            }
+            finally {
+                semaphore.release();
+            }
+        },
+    };
+}
+//# sourceMappingURL=checks.js.map

package/dist/coding-checkpoint.d.ts

@@ -0,0 +1,159 @@
+import type { JsonObject } from "@arnilo/prism";
+export declare const CODING_CHECKPOINT_SCHEMA_VERSION: 1;
+/** Workflow shared-state key that holds coding checkpoint metadata. */
+export declare const CODING_STATE_KEY = "coding";
+export type CodingArtifactKind = "plan" | "workspace" | "patch" | "bundle" | "diff" | "other";
+export type CodingTaskStatus = "planned" | "editing" | "checking" | "awaiting_approval" | "ready_for_handoff" | "completed" | "failed" | "cancelled";
+export interface CodingArtifactRef {
+    readonly kind: CodingArtifactKind;
+    readonly uri: string;
+    readonly sha256: string;
+    readonly bytes: number;
+}
+export interface CodingTodoItem {
+    readonly id: string;
+    readonly text: string;
+    readonly done: boolean;
+}
+export interface CodingCheckSummary {
+    readonly name: string;
+    readonly exitCode: number;
+    readonly summary: string;
+}
+export interface CodingFingerprints {
+    /** Workflow definition revision string. */
+    readonly workflowRevision: string;
+    /** Optional definition hash captured after `defineWorkflow`. */
+    readonly definitionHash?: string;
+    /** Host-pinned sandbox/image digest when a disposable sandbox is used. */
+    readonly imageDigest?: string;
+    /** Host-computed hash of the selected tool surface. */
+    readonly toolFingerprint: string;
+    /** Host-computed hash of the selected execution/approval policy. */
+    readonly policyFingerprint: string;
+}
+export interface CodingHandoffSummary {
+    readonly base: string;
+    readonly head: string;
+    readonly changedPathCount: number;
+    readonly checkCount: number;
+    readonly artifact?: CodingArtifactRef;
+}
+export interface CodingCheckpointMetadata {
+    readonly schemaVersion: typeof CODING_CHECKPOINT_SCHEMA_VERSION;
+    readonly taskId: string;
+    readonly workspaceRoot: string;
+    readonly baseBranch: string;
+    readonly branch: string;
+    readonly worktreePath?: string;
+    /** Workspace-relative plan path (for example `plans/task-1.md`). */
+    readonly planPath: string;
+    readonly plan: CodingArtifactRef;
+    readonly workspaceExport?: CodingArtifactRef;
+    readonly artifacts: readonly CodingArtifactRef[];
+    readonly checks: readonly CodingCheckSummary[];
+    readonly handoff?: CodingHandoffSummary;
+    readonly status: CodingTaskStatus;
+    readonly fingerprints: CodingFingerprints;
+    readonly todos: readonly CodingTodoItem[];
+    readonly updatedAt: string;
+}
+export interface CodingCheckpointLimitOptions {
+    readonly maxPlanBytes?: number;
+    readonly maxTodos?: number;
+    readonly maxTodoTextBytes?: number;
+    readonly maxArtifacts?: number;
+    readonly maxArtifactBytes?: number;
+    readonly maxCheckSummaryBytes?: number;
+    readonly maxCheckpointBytes?: number;
+}
+export interface ResolvedCodingCheckpointLimits {
+    readonly maxPlanBytes: number;
+    readonly maxTodos: number;
+    readonly maxTodoTextBytes: number;
+    readonly maxArtifacts: number;
+    readonly maxArtifactBytes: number;
+    readonly maxCheckSummaryBytes: number;
+    readonly maxCheckpointBytes: number;
+}
+export declare class CodingCheckpointError extends Error {
+    readonly code = "ERR_PRISM_CODING_CHECKPOINT";
+    constructor(message: string);
+}
+export declare function resolveCodingCheckpointLimits(options?: CodingCheckpointLimitOptions): ResolvedCodingCheckpointLimits;
+/** Deterministic SHA-256 fingerprint over a JSON-stable encoding. */
+export declare function fingerprintJson(value: unknown): string;
+export declare function createCodingArtifactRef(input: {
+    readonly kind: CodingArtifactKind;
+    readonly uri: string;
+    readonly bytes: Buffer;
+    readonly maxBytes?: number;
+}): CodingArtifactRef;
+export declare function verifyCodingArtifactBytes(ref: CodingArtifactRef, bytes: Buffer, limits?: CodingCheckpointLimitOptions): void;
+export declare function createCodingPlanMarkdown(input: {
+    readonly title: string;
+    readonly taskId: string;
+    readonly status?: CodingTaskStatus;
+    readonly todos: readonly {
+        readonly id?: string;
+        readonly text: string;
+        readonly done?: boolean;
+    }[];
+    readonly notes?: string;
+    readonly limits?: CodingCheckpointLimitOptions;
+}): string;
+export declare function parseCodingPlanTodos(markdown: string, limits?: CodingCheckpointLimitOptions): CodingTodoItem[];
+export declare function writeCodingPlanFile(input: {
+    readonly workspaceRoot: string;
+    readonly planPath: string;
+    readonly markdown: string;
+    readonly limits?: CodingCheckpointLimitOptions;
+}): Promise<CodingArtifactRef>;
+export declare function readCodingPlanFile(input: {
+    readonly workspaceRoot: string;
+    readonly planPath: string;
+    readonly expected?: CodingArtifactRef;
+    readonly limits?: CodingCheckpointLimitOptions;
+}): Promise<{
+    markdown: string;
+    artifact: CodingArtifactRef;
+    todos: CodingTodoItem[];
+}>;
+export declare function buildCodingCheckpointMetadata(input: {
+    readonly taskId: string;
+    readonly workspaceRoot: string;
+    readonly baseBranch: string;
+    readonly branch: string;
+    readonly planPath: string;
+    readonly plan: CodingArtifactRef;
+    readonly fingerprints: CodingFingerprints;
+    readonly status?: CodingTaskStatus;
+    readonly todos?: readonly CodingTodoItem[];
+    readonly worktreePath?: string;
+    readonly workspaceExport?: CodingArtifactRef;
+    readonly artifacts?: readonly CodingArtifactRef[];
+    readonly checks?: readonly CodingCheckSummary[];
+    readonly handoff?: CodingHandoffSummary;
+    readonly updatedAt?: string;
+    readonly limits?: CodingCheckpointLimitOptions;
+}): CodingCheckpointMetadata;
+export declare function validateCodingCheckpointMetadata(value: unknown, limits?: CodingCheckpointLimitOptions): CodingCheckpointMetadata;
+/**
+ * Fail closed before resume/import when ownership-equivalent fingerprints diverge
+ * or artifact references cannot be verified.
+ */
+export declare function assertCodingResumeAllowed(input: {
+    readonly metadata: CodingCheckpointMetadata;
+    readonly expected: CodingFingerprints;
+    readonly expectedWorkspaceRoot?: string;
+    readonly expectedBaseBranch?: string;
+    readonly planBytes?: Buffer;
+    readonly workspaceExportBytes?: Buffer;
+    readonly limits?: CodingCheckpointLimitOptions;
+}): CodingCheckpointMetadata;
+/** Extract and validate `state.coding` when present. */
+export declare function readCodingCheckpointFromState(state: Readonly<Record<string, unknown>>, limits?: CodingCheckpointLimitOptions): CodingCheckpointMetadata | undefined;
+export declare function codingCheckpointStatePatch(metadata: CodingCheckpointMetadata): JsonObject;
+/** Exported for tests that need a quick digest helper without importing crypto. */
+export declare function codingSha256Hex(data: Buffer | string): string;
+export declare function codingPlanPathForTask(taskId: string): string;