@arnilo/prism-coding-agent 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -1,4 +1,27 @@
 # Changelog
+## [0.0.10] - 2026-07-21
+
+### Changed
+
+- Released with exact 0.0.10 graph.
+
+### Notes
+
+- Sandbox composition / workspace-mode contract lives in `@arnilo/prism-coding-security` (required `workspaceMode`, same-tree Git via `createGitTools(composition.workspaceRoot, { execFile })`). Coding-agent tool surfaces unchanged for 0.0.10.
+
+## [0.0.96] - 2026-07-21
+
+### Changed
+
+- Released with exact 0.0.96 graph.
+
+## [0.0.9] - 2026-07-21
+
+- Added bounded native `repo_list` / `repo_search` tools with streaming walks, literal/regex search, finite depth/entry/match/scan/time caps, and pluggable `RepositoryOperations`.
+- `createCodingTools()` / `createAllTools()` now include list/search; `createReadOnlyTools()` deliberately expands to `read` + `repo_list` + `repo_search`.
+- Added opt-in structured Git tools via `createGitTools()` / `createGitOperations()`: status (porcelain v2), bounded diff, branch validate/create/switch, worktree add/list/remove, patch check/apply/reverse with rollback, explicit-path commit (host `commitIdentity`), and bounded PR handoff artifacts. Named `coding_check` runs host-declared executables only. Git uses argument arrays with hooks/credential prompts/external diff disabled and never pushes.
+- Added bounded durable coding-plan/checkpoint helpers (`writeCodingPlanFile`, `buildCodingCheckpointMetadata`, `assertCodingResumeAllowed`, `fingerprintJson`) so hosts compose plans/todos/background resume from existing workflow primitives without a second runtime.
+- Added network-free adversarial evaluation fixtures (`eval-fixtures.test.ts`) grading safe native list vs shell, Git injection, dirty-tree rollback, named-check failure, PR-handoff artifacts, and prompt-injection file content via `@arnilo/prism-evals`.
 
 ## [0.0.8] - 2026-07-20
 
@@ -8,11 +31,6 @@
 
 - Released with the exact 0.0.7 first-party package graph.
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
 ## [0.0.6] - 2026-07-19
 
 ### Added
@@ -32,7 +50,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Pinned the required `@arnilo/prism` peer and package metadata to 0.0.5; runtime behavior is unchanged.
 
-
 ## [0.0.4] - 2026-07-14
 
 ### Added

package/README.md

@@ -1,10 +1,10 @@
 # @arnilo/prism-coding-agent
 
-Optional first-party coding tools package for [Prism](https://www.npmjs.com/package/@arnilo/prism). Provides host shell/filesystem tools — `shell`, `read`, `write`, `edit` — as Prism `ToolDefinition` objects. **Inert until a host imports it and registers the tools into a `ToolRegistry`.**
+Optional first-party coding tools package for [Prism](https://www.npmjs.com/package/@arnilo/prism). Provides host shell/filesystem/repository tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search` — plus opt-in structured Git/check tools via `createGitTools()` and durable plan/checkpoint helpers for workflow composition — as Prism `ToolDefinition` objects. **Inert until a host imports it and registers the tools into a `ToolRegistry`.**
 
-Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies).
+Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies). List/search/Git are native Prism tools.
 
-> ⚠️ **These tools perform real shell and filesystem operations on the host. They provide no sandbox.** Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. See the [coding agent tools docs](https://github.com/ashiqrniloy/prism/blob/main/docs/coding-agent-tools.md) and the [host security guide](https://github.com/ashiqrniloy/prism/blob/main/docs/host-security.md).
+> ⚠️ **These tools perform real shell and filesystem operations on the host. They provide no sandbox.** Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. For disposable sandbox composition with required `workspaceMode`, use `@arnilo/prism-coding-security` (`createSandboxCodingComposition`). See the [coding agent tools docs](https://github.com/ashiqrniloy/prism/blob/main/docs/coding-agent-tools.md) and the [host security guide](https://github.com/ashiqrniloy/prism/blob/main/docs/host-security.md).
 
 ## Install
 
@@ -64,6 +64,9 @@ const remoteWrite = createWriteTool(process.cwd(), {
 | `read` | `{ path, offset?, limit? }` | Streamed bounded text page or bounded `[note, ImageContent]`. |
 | `write` | `{ path, content }` | Bounded UTF-8 input; `Successfully wrote N bytes (M lines) to <abs>`. |
 | `edit` | `{ path, edits: [{oldText,newText}] }` | Bounded target/input/count; `Successfully replaced N block(s)` + diff metadata. |
+| `repo_list` | `{ path?, includeHidden?, maxDepth?, maxResults?, offset? }` | Deterministic relative entries; skips hidden/excluded basenames; does not follow symlinks; paginates with `nextOffset`. |
+| `repo_search` | `{ query, path?, mode?, caseSensitive?, includeHidden?, context?, maxMatches? }` | Literal (default) or bounded regex matches with context; skips binary/excluded paths; finite scan/match/time caps. |
+| `git_*` / `coding_check` | via `createGitTools(cwd, { commitIdentity, checks? })` | Opt-in structured Git status/diff/branch/worktree/apply/commit/PR-handoff and named checks. Not in `createCodingTools()`. |
 
 ### pi name mapping
 
@@ -71,17 +74,20 @@ const remoteWrite = createWriteTool(process.cwd(), {
 | --- | --- |
 | `shell` | `bash` |
 | `read` / `write` / `edit` | `read` / `write` / `edit` |
+| `repo_list` / `repo_search` | _(native; no pi equivalent shipped)_ |
 
 ## Exports
 
-Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createLocalBashOperations`.
+Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createRepoListTool`, `createRepoSearchTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createGitTools`, `createCodingCheckTool`, `createLocalBashOperations`, `createLocalRepositoryOperations`, `createGitOperations`.
 
-Helpers: `detectSupportedImageMimeType`, `detectSupportedImageMimeTypeFromFile`, `getShellConfig`, `killProcessTree`, `waitForChildProcess`, `withFileMutationQueue`. Default/hard coding limit constants are exported for host configuration.
+Helpers: `detectSupportedImageMimeType`, `detectSupportedImageMimeTypeFromFile`, `getShellConfig`, `killProcessTree`, `waitForChildProcess`, `withFileMutationQueue`, `resolveRepositoryLimits`, `writeCodingPlanFile`, `readCodingPlanFile`, `buildCodingCheckpointMetadata`, `validateCodingCheckpointMetadata`, `assertCodingResumeAllowed`, `fingerprintJson`. Default/hard coding, repository, Git, and plan/checkpoint limit constants are exported for host configuration.
 
 Option/operation types: `ToolsOptions`, `ShellToolOptions`/`BashOperations`, `ReadToolOptions`/`ReadOperations`/`ReadTextOptions`/`ReadTextResult`, `WriteToolOptions`/`WriteOperations`, `EditToolOptions`/`EditOperations`/`EditToolDetails`.
 
 Text reads stop after one page or `maxScanBytes` instead of loading the file. Custom `ReadOperations` must implement bounded `readText` and `statFile`; custom `EditOperations` must implement `statFile` and honor the supplied read cap/signal. Successful truncated shell output is retained in an exclusive Unix `0600` temp file owned by the host; timeout, abort, output-limit, and spill failures remove unpublished spill files. Hosts should delete published `metadata.fullOutputPath` files after use.
 
+Network-free adversarial evaluation fixtures live in `src/__tests__/eval-fixtures.test.ts` and reuse `@arnilo/prism-evals` for CI thresholds. See `examples/coding-browser-evaluation.ts` and `docs/evaluations.md`.
+
 ## License
 
 MIT

package/dist/artifacts.d.ts

@@ -0,0 +1,6 @@
+import type { ArtifactWriter } from "./git.js";
+export declare function sha256Hex(data: Buffer): string;
+/** Write artifacts under a host directory as `file://` URIs with SHA-256 metadata. */
+export declare function createDirectoryArtifactWriter(rootDir: string): ArtifactWriter;
+/** Spill into the process temp directory (tests / ephemeral hosts). */
+export declare function createTempArtifactWriter(prefix?: string): ArtifactWriter;

package/dist/artifacts.js

@@ -0,0 +1,35 @@
+/**
+ * Host-owned artifact helpers for Git patch/bundle/PR-handoff spill.
+ *
+ * Prism never pushes, authenticates to GitHub/GitLab, or opens a PR. Artifacts
+ * are written only through an explicit host callback or a bounded temp-file writer.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** Write artifacts under a host directory as `file://` URIs with SHA-256 metadata. */
+export function createDirectoryArtifactWriter(rootDir) {
+    return async ({ kind, filename, bytes }) => {
+        const safeName = filename.replace(/[^A-Za-z0-9._-]+/g, "_");
+        const dir = join(rootDir, kind);
+        await mkdir(dir, { recursive: true });
+        const path = join(dir, `${randomBytes(8).toString("hex")}-${safeName}`);
+        await writeFile(path, bytes, { mode: 0o600 });
+        return {
+            kind,
+            uri: `file://${path}`,
+            sha256: sha256Hex(bytes),
+            bytes: bytes.length,
+        };
+    };
+}
+/** Spill into the process temp directory (tests / ephemeral hosts). */
+export function createTempArtifactWriter(prefix = "prism-git-artifact") {
+    const root = join(tmpdir(), `${prefix}-${randomBytes(6).toString("hex")}`);
+    return createDirectoryArtifactWriter(root);
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/checks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Named check tool: host declares fixed executable+args; model selects only a name.
+ */
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+export interface NamedCheckDefinition {
+    /** Absolute executable path, or a basename resolved only via host-supplied env PATH. */
+    readonly file: string;
+    readonly args: readonly string[];
+    readonly cwd?: string;
+    /** Exact env allow-list (never inherits process.env unless host copies values in). */
+    readonly env?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+}
+export interface CodingCheckToolOptions {
+    readonly executionPolicy?: ExecutionPolicy;
+    readonly checks: Readonly<Record<string, NamedCheckDefinition>>;
+    readonly maxConcurrency?: number;
+    readonly maxDiagnosticLines?: number;
+    readonly maxOutputBytes?: number;
+    readonly defaultTimeoutMs?: number;
+}
+/**
+ * Create the `coding_check` tool. Model may only select a declared name — never
+ * executable path or arguments.
+ */
+export declare function createCodingCheckTool(cwd: string, options: CodingCheckToolOptions): ToolDefinition;

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;