@arnilo/prism-coding-agent 0.0.8 → 0.0.11

package/CHANGELOG.md

@@ -1,4 +1,41 @@
 # Changelog
+## [Unreleased]
+
+## [0.0.11] - 2026-07-22
+
+### Docs
+
+- Documented ask_user_decision multi/free-text/suspend glue + `runCodingGoalVerify` in `docs/coding-agent-tools.md` / README.
+
+### Added
+
+- `runCodingGoalVerify` / `createCodingGoalVerifyWorkflow`: thin goal→verify composition over plan Markdown, named checks, workflow suspend/approve, and bounded PR handoff (peer `@arnilo/prism-workflows`). No Goal table / second runtime.
+- Opt-in `createAskUserDecisionTool({ ask })`: model proposes 2+ options with exactly 3 pros + 3 cons each; host `ask` returns `selectedId` / `selectedIds` / `customText`. Supports `selectionMode: "single" | "multiple"` and `allowCustom` (custom XOR selection; default/hard custom bytes match question caps). Not in `createCodingTools` / `createAllTools` / `createReadOnlyTools`.
+- Durable ask-user helpers: `suspendAskUserDecision`, `createAskUserDecisionResumeValidator`, `validateAskUserDecisionResume`, `validateAskUserDecisionAgentResume` (workflow-first; agent path reuses same validator without new `AgentRunInterruption` kinds).
+
+## [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 +45,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 +64,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()`, opt-in `createAskUserDecisionTool({ ask })`, 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`.** No tool is auto-registered; hosts pick factories (or filter aggregator output) and may mix in their own `ToolDefinition`s.
 
-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
 
@@ -12,7 +12,7 @@ Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`ed
 npm install @arnilo/prism-coding-agent
 ```
 
-`@arnilo/prism` is a peer dependency.
+`@arnilo/prism` is a peer dependency. `runCodingGoalVerify` also peers `@arnilo/prism-workflows`.
 
 ## Usage
 
@@ -38,7 +38,7 @@ Shared `ToolsOptions.executionPolicy` applies to every tool returned by full, al
 Individual tools with options:
 
 ```ts
-import { createShellTool, createWriteTool } from "@arnilo/prism-coding-agent";
+import { createShellTool, createWriteTool, createAskUserDecisionTool } from "@arnilo/prism-coding-agent";
 
 const shell = createShellTool(process.cwd(), {
   shellPath: "/bin/bash",        // force bash; default: SHELL env → /bin/bash → sh
@@ -54,6 +54,14 @@ const remoteWrite = createWriteTool(process.cwd(), {
     mkdir: async (dir) => { /* mkdir -p remotely */ },
   },
 });
+
+// Opt-in: not in createCodingTools(). Host owns the UI.
+const askUser = createAskUserDecisionTool({
+  ask: async ({ question, options }) => {
+    const selectedId = await host.promptChoice(question, options);
+    return { selectedId };
+  },
+});
 ```
 
 ## Tools
@@ -64,6 +72,10 @@ 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()`. |
+| `ask_user_decision` | via `createAskUserDecisionTool({ ask })` | Opt-in user choice: question + options (3 pros/3 cons); `selectionMode` single\|multiple; `allowCustom` for XOR free-text; host `ask` returns `selectedId` / `selectedIds` / `customText`. Durable: `suspendAskUserDecision` + resume validators. Not in default aggregators. |
 
 ### pi name mapping
 
@@ -71,17 +83,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`, `createAskUserDecisionTool`, `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`, `runCodingGoalVerify`, `createCodingGoalVerifyWorkflow`, `suspendAskUserDecision`, `createAskUserDecisionResumeValidator`, `validateAskUserDecisionResume`, `validateAskUserDecisionAgentResume`. 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/ask-user-decision.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Opt-in `ask_user_decision` tool: model proposes choices with pros/cons;
+ * host-injected `ask` blocks until the user picks one or more option ids.
+ *
+ * Durable path (opt-in): `suspendAskUserDecision` / `validateAskUserDecisionResume`
+ * compose `@arnilo/prism-workflows` suspend/resume — no Goal DB, no second store.
+ * Blocking `ask()` remains the default. Agent durable interruption kinds are
+ * unchanged; hosts reuse the same resume validator against host-held request data.
+ *
+ * Not included in `createCodingTools` / `createAllTools` / `createReadOnlyTools`.
+ */
+import type { ExecutionPolicy, JsonObject, ToolDefinition } from "@arnilo/prism";
+import { type WorkflowResumeValidator, type WorkflowSuspension } from "@arnilo/prism-workflows";
+export declare const ASK_USER_DECISION_TOOL_NAME: "ask_user_decision";
+export declare const ASK_USER_DECISION_SUSPEND_REASON: "ask_user_decision";
+/** Exactly three rationale bullets per side. */
+export declare const ASK_USER_DECISION_RATIONALE_COUNT: 3;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_OPTIONS = 6;
+export declare const HARD_MAX_ASK_USER_DECISION_OPTIONS = 16;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES = 2048;
+export declare const HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES = 8192;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES = 512;
+export declare const HARD_MAX_ASK_USER_DECISION_LABEL_BYTES = 2048;
+export declare const DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES = 512;
+export declare const HARD_MAX_ASK_USER_DECISION_BULLET_BYTES = 2048;
+/** Same ceiling as question text — free-text answers stay short. */
+export declare const DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES = 2048;
+export declare const HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES = 8192;
+export type AskUserDecisionSelectionMode = "single" | "multiple";
+export interface AskUserDecisionOption {
+    readonly id: string;
+    readonly label: string;
+    readonly pros: readonly [string, string, string];
+    readonly cons: readonly [string, string, string];
+}
+export interface AskUserDecisionRequest {
+    readonly question: string;
+    readonly options: readonly AskUserDecisionOption[];
+    readonly selectionMode: AskUserDecisionSelectionMode;
+    readonly allowCustom: boolean;
+    readonly toolCallId: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Host answer shapes. Custom text is XOR with selection (v1): never both.
+ * `allowCustom` must be true for `{ customText }`.
+ */
+export type AskUserDecisionAnswer = {
+    readonly selectedId: string;
+    readonly selectedIds?: never;
+    readonly customText?: never;
+} | {
+    readonly selectedIds: readonly string[];
+    readonly selectedId?: never;
+    readonly customText?: never;
+} | {
+    readonly selectedId: string;
+    readonly selectedIds: readonly string[];
+    readonly customText?: never;
+} | {
+    readonly customText: string;
+    readonly selectedId?: never;
+    readonly selectedIds?: never;
+};
+export type ResolvedAskUserDecisionAnswer = {
+    readonly kind: "selection";
+    readonly selectedId: string;
+    readonly selectedIds: readonly string[];
+} | {
+    readonly kind: "custom";
+    readonly customText: string;
+};
+export type AskUserDecisionHandler = (request: AskUserDecisionRequest) => Promise<AskUserDecisionAnswer>;
+export interface AskUserDecisionToolOptions {
+    /** Required host UI/callback — tool fails closed without it. */
+    readonly ask: AskUserDecisionHandler;
+    readonly executionPolicy?: ExecutionPolicy;
+    readonly maxOptions?: number;
+    readonly maxQuestionBytes?: number;
+    readonly maxLabelBytes?: number;
+    readonly maxBulletBytes?: number;
+    readonly maxCustomTextBytes?: number;
+}
+export interface ResolvedAskUserDecisionLimits {
+    readonly maxOptions: number;
+    readonly maxQuestionBytes: number;
+    readonly maxLabelBytes: number;
+    readonly maxBulletBytes: number;
+    readonly maxCustomTextBytes: number;
+}
+export declare function resolveAskUserDecisionLimits(options?: Pick<AskUserDecisionToolOptions, "maxOptions" | "maxQuestionBytes" | "maxLabelBytes" | "maxBulletBytes" | "maxCustomTextBytes">): ResolvedAskUserDecisionLimits;
+/** Normalize host answer against mode + allowCustom. Exported for tests. */
+export declare function resolveAskUserDecisionAnswer(answer: AskUserDecisionAnswer | null | undefined, selectionMode: AskUserDecisionSelectionMode, options: readonly AskUserDecisionOption[], gates: {
+    readonly allowCustom: boolean;
+    readonly maxCustomTextBytes: number;
+}): ResolvedAskUserDecisionAnswer;
+/** Parse + validate model args into a bounded decision request. Exported for tests. */
+export declare function parseAskUserDecisionArgs(args: Record<string, unknown>, limits: ResolvedAskUserDecisionLimits): {
+    question: string;
+    options: AskUserDecisionOption[];
+    selectionMode: AskUserDecisionSelectionMode;
+    allowCustom: boolean;
+};
+/**
+ * Create the opt-in `ask_user_decision` tool.
+ * Host must supply `ask`; factory throws if missing.
+ */
+export declare function createAskUserDecisionTool(options: AskUserDecisionToolOptions): ToolDefinition;
+/** Durable decision payload for workflow suspension `data` (no AbortSignal / secrets). */
+export interface AskUserDecisionSuspendData {
+    readonly question: string;
+    readonly options: readonly AskUserDecisionOption[];
+    readonly selectionMode: AskUserDecisionSelectionMode;
+    readonly allowCustom: boolean;
+    readonly toolCallId?: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+}
+export interface SuspendAskUserDecisionOptions {
+    readonly reason?: string;
+    readonly maxCustomTextBytes?: number;
+}
+/** JSON Schema describing resume `input` (= AskUserDecisionAnswer). */
+export declare function askUserDecisionResumeSchema(request: Pick<AskUserDecisionSuspendData, "selectionMode" | "allowCustom" | "options">): JsonObject;
+export declare function toAskUserDecisionSuspendData(request: {
+    readonly question: string;
+    readonly options: readonly AskUserDecisionOption[];
+    readonly selectionMode: AskUserDecisionSelectionMode;
+    readonly allowCustom: boolean;
+    readonly toolCallId?: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+}): AskUserDecisionSuspendData;
+/**
+ * Return from a workflow node to pause for a user decision (opt-in durable path).
+ * Host resumes via `resumeWorkflow` + `createAskUserDecisionResumeValidator` / `validateAskUserDecisionResume`.
+ */
+export declare function suspendAskUserDecision(request: AskUserDecisionSuspendData | Pick<AskUserDecisionRequest, "question" | "options" | "selectionMode" | "allowCustom" | "toolCallId" | "sessionId" | "runId">, options?: SuspendAskUserDecisionOptions): WorkflowSuspension<AskUserDecisionAnswer>;
+/**
+ * Validate resume input against the original decision request.
+ * Shared by workflow `validateResume` and host-held agent resume adapters.
+ */
+export declare function validateAskUserDecisionResume(request: AskUserDecisionSuspendData, value: unknown, limits?: Pick<ResolvedAskUserDecisionLimits, "maxCustomTextBytes">): ResolvedAskUserDecisionAnswer;
+/**
+ * Workflow `validateResume` adapter. Reads durable request from `suspension.data`
+ * (written by `suspendAskUserDecision`). Deny paths skip answer validation.
+ */
+export declare function createAskUserDecisionResumeValidator(limits?: Pick<ResolvedAskUserDecisionLimits, "maxCustomTextBytes">): WorkflowResumeValidator;
+/**
+ * Thin agent-path adapter: same validation as workflow resume, for hosts that
+ * persist `AskUserDecisionSuspendData` outside `AgentRunInterruption` (core kinds
+ * unchanged in 0.0.11). Call after operator supplies an answer.
+ */
+export declare function validateAskUserDecisionAgentResume(input: {
+    readonly request: AskUserDecisionSuspendData;
+    readonly answer: unknown;
+    readonly maxCustomTextBytes?: number;
+}): ResolvedAskUserDecisionAnswer;