@arnilo/prism-coding-agent 0.0.96 → 0.1.1

package/dist/delete.js

@@ -0,0 +1,119 @@
+import { lstat, readdir, rmdir, unlink } from "node:fs/promises";
+import { CODING_LOCAL_EFFECT } from "./effects.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { resolveContainedMutationPath } from "./mutation-path.js";
+const defaultDeleteOperations = {
+    lstat: async (path) => {
+        const st = await lstat(path);
+        return {
+            isFile: () => st.isFile(),
+            isDirectory: () => st.isDirectory(),
+            isSymbolicLink: () => st.isSymbolicLink(),
+            size: st.size,
+        };
+    },
+    unlink: (path) => unlink(path).then(() => { }),
+    rmdir: (path) => rmdir(path).then(() => { }),
+    readdir: (path) => readdir(path),
+};
+function errorResult(toolCallId, message) {
+    return {
+        toolCallId,
+        name: "delete",
+        content: [{ type: "text", text: message }],
+        error: { message },
+    };
+}
+export function createDeleteTool(cwd, options) {
+    const ops = options?.operations ?? defaultDeleteOperations;
+    return {
+        name: "delete",
+        effect: CODING_LOCAL_EFFECT,
+        description: "High-risk: permanently delete a single file or empty directory in the workspace. Non-empty directories are rejected (no recursive delete). No trash/recycle — host undo is not automatic. Prefer edit/write when content can be fixed in place.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file or empty directory to delete (relative or absolute)" },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+        async execute(args, context) {
+            const toolCallId = context.toolCallId;
+            const path = typeof args.path === "string" ? args.path : "";
+            if (path.length === 0) {
+                return errorResult(toolCallId, "path is required and must be a non-empty string.");
+            }
+            try {
+                let absolutePath;
+                try {
+                    absolutePath = await resolveContainedMutationPath(cwd, path);
+                }
+                catch (error) {
+                    const err = error;
+                    if (err.code === "ENOENT")
+                        return errorResult(toolCallId, `No such file or directory: ${path}`);
+                    throw error;
+                }
+                const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
+                    kind: "delete",
+                    operation: "delete",
+                    paths: [absolutePath],
+                    risk: "high",
+                    metadata: { sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+                }, toolCallId, "delete", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
+                if (!policyCheck.allowed)
+                    return policyCheck.result;
+                const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+                return await withFileMutationQueue(allowedPath, async () => {
+                    if (context.signal?.aborted)
+                        return errorResult(toolCallId, "Operation aborted");
+                    let st;
+                    try {
+                        st = await ops.lstat(allowedPath, { signal: context.signal });
+                    }
+                    catch (error) {
+                        const err = error;
+                        if (err.code === "ENOENT")
+                            return errorResult(toolCallId, `No such file or directory: ${path}`);
+                        const message = error instanceof Error ? error.message : String(error);
+                        return errorResult(toolCallId, message);
+                    }
+                    if (context.signal?.aborted)
+                        return errorResult(toolCallId, "Operation aborted");
+                    if (st.isFile() || st.isSymbolicLink()) {
+                        await ops.unlink(allowedPath, { signal: context.signal });
+                        options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "delete", toolCallId });
+                        return {
+                            toolCallId,
+                            name: "delete",
+                            content: [{ type: "text", text: `Successfully deleted ${allowedPath}` }],
+                            metadata: { path: allowedPath, kind: st.isSymbolicLink() ? "symlink" : "file", bytes: st.size },
+                        };
+                    }
+                    if (st.isDirectory()) {
+                        const entries = await ops.readdir(allowedPath, { signal: context.signal });
+                        if (entries.length > 0) {
+                            return errorResult(toolCallId, `Directory is not empty: ${path}. Recursive delete is not supported.`);
+                        }
+                        await ops.rmdir(allowedPath, { signal: context.signal });
+                        options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "delete", toolCallId });
+                        return {
+                            toolCallId,
+                            name: "delete",
+                            content: [{ type: "text", text: `Successfully deleted empty directory ${allowedPath}` }],
+                            metadata: { path: allowedPath, kind: "directory" },
+                        };
+                    }
+                    return errorResult(toolCallId, `Unsupported file type: ${path}`);
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return errorResult(toolCallId, message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=delete.js.map

package/dist/edit-diff.js

@@ -88,10 +88,7 @@ function applyReplacements(content, replacements, offset = 0) {
     for (let i = replacements.length - 1; i >= 0; i--) {
         const replacement = replacements[i];
         const matchIndex = replacement.matchIndex - offset;
-        result =
-            result.substring(0, matchIndex) +
-                replacement.newText +
-                result.substring(matchIndex + replacement.matchLength);
+        result = result.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);
     }
     return result;
 }

package/dist/edit.d.ts

@@ -21,6 +21,8 @@
  */
 import { Buffer } from "node:buffer";
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import type { CodingLifecycleEvent } from "./lifecycle.js";
+import { type ReadBeforeWriteOptions } from "./read-path-set.js";
 export interface Edit {
     oldText: string;
     newText: string;
@@ -59,7 +61,7 @@ export interface EditOperations {
         size: number;
     }>;
 }
-export interface EditToolOptions {
+export interface EditToolOptions extends ReadBeforeWriteOptions {
     /** Structured pre-execution policy checked before filesystem writes. */
     executionPolicy?: ExecutionPolicy;
     /** Custom operations backend (default: local filesystem). */
@@ -70,5 +72,7 @@ export interface EditToolOptions {
     maxInputBytes?: number;
     /** Maximum replacements per call (default 100). */
     maxEdits?: number;
+    /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+    onEvent?: (event: CodingLifecycleEvent) => void;
 }
 export declare function createEditTool(cwd: string, options?: EditToolOptions): ToolDefinition;

package/dist/edit.js

@@ -20,17 +20,20 @@
  *    completed, the edit is real and is reported as success rather than a misleading "aborted".
  */
 import { Buffer } from "node:buffer";
-import { access as fsAccess, stat as fsStat, writeFile as fsWriteFile, } from "node:fs/promises";
 import { constants } from "node:fs";
+import { access as fsAccess, stat as fsStat } from "node:fs/promises";
+import { atomicWriteUtf8File } from "./atomic-write.js";
+import { CODING_LOCAL_EFFECT } from "./effects.js";
 import { readFileBounded } from "./bounded-file.js";
+import { applyEditsToNormalizedContent, detectLineEnding, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, stripBom, } from "./edit-diff.js";
 import { enforceExecutionPolicy } from "./execution-policy.js";
-import { resolveToCwd } from "./path-utils.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { DEFAULT_MAX_EDIT_FILE_BYTES, DEFAULT_MAX_EDIT_INPUT_BYTES, DEFAULT_MAX_EDITS, HARD_MAX_EDIT_FILE_BYTES, HARD_MAX_EDIT_INPUT_BYTES, HARD_MAX_EDITS, validateCodingLimit, } from "./limits.js";
-import { applyEditsToNormalizedContent, detectLineEnding, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, stripBom, } from "./edit-diff.js";
+import { resolveToCwd } from "./path-utils.js";
+import { refuseReadBeforeWrite } from "./read-path-set.js";
 const defaultEditOperations = {
     readFile: (path, options) => readFileBounded(path, options.maxBytes, options.signal),
-    writeFile: (path, content, options) => fsWriteFile(path, content, { encoding: "utf-8", signal: options?.signal }),
+    writeFile: (path, content, options) => atomicWriteUtf8File(path, content, { signal: options?.signal }),
     access: (path) => fsAccess(path, constants.R_OK | constants.W_OK),
     statFile: async (path) => ({ size: (await fsStat(path)).size }),
 };
@@ -93,11 +96,16 @@ export function createEditTool(cwd, options) {
     const maxEdits = validateCodingLimit("maxEdits", options?.maxEdits ?? DEFAULT_MAX_EDITS, HARD_MAX_EDITS);
     return {
         name: "edit",
-        description: "Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes.",
+        effect: CODING_LOCAL_EFFECT,
+        description: "Edit a single file using exact-then-fuzzy text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. Exact match is tried first; if it fails, fuzzy match (unicode normalize + whitespace collapse) may still succeed silently — prefer exact oldText to avoid wrong-region edits. Duplicate/ambiguous matches fail closed and leave the file unchanged. If two changes affect the same block or nearby lines, merge them into one edit. Do not include large unchanged regions just to connect distant changes. When the host enabled requireReadBeforeWrite, read the path first or pass force=true.",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Path to the file to edit (relative or absolute)" },
+                force: {
+                    type: "boolean",
+                    description: "Bypass read-before-write guard when the host enabled requireReadBeforeWrite.",
+                },
                 edits: {
                     type: "array",
                     description: "One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.",
@@ -124,6 +132,7 @@ export function createEditTool(cwd, options) {
                 return errorResult(toolCallId, `edit input exceeds ${maxInputBytes} byte limit.`);
             }
             const prepared = prepareEditArguments(args);
+            const force = args.force === true;
             if (prepared.path.length === 0) {
                 return errorResult(toolCallId, "path is required and must be a non-empty string.");
             }
@@ -140,10 +149,13 @@ export function createEditTool(cwd, options) {
                     paths: [absolutePath],
                     risk: "medium",
                     metadata: { editCount: edits.length, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
-                }, toolCallId, "edit");
+                }, toolCallId, "edit", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+                const rbwRefusal = refuseReadBeforeWrite("edit", prepared.path, allowedPath, options, force);
+                if (rbwRefusal)
+                    return errorResult(toolCallId, rbwRefusal);
                 return await withFileMutationQueue(allowedPath, async () => {
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
@@ -191,14 +203,13 @@ export function createEditTool(cwd, options) {
                         return errorResult(toolCallId, "Operation aborted");
                     const finalContent = bom + restoreLineEndings(newContent, originalEnding);
                     await ops.writeFile(allowedPath, finalContent, { signal: context.signal });
+                    options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "edit", toolCallId });
                     const diffResult = generateDiffString(baseContent, newContent);
                     const patch = generateUnifiedPatch(prepared.path, baseContent, newContent);
                     return {
                         toolCallId,
                         name: "edit",
-                        content: [
-                            { type: "text", text: `Successfully replaced ${edits.length} block(s) in ${prepared.path}.` },
-                        ],
+                        content: [{ type: "text", text: `Successfully replaced ${edits.length} block(s) in ${prepared.path}.` }],
                         metadata: {
                             diff: diffResult.diff,
                             patch,

package/dist/effects.d.ts

@@ -0,0 +1,33 @@
+import type { JsonObject, ToolEffectDeclaration, ToolEffectRecord, ToolResult } from "@arnilo/prism";
+export declare const CODING_OBSERVATION_EFFECT: {
+    readonly kind: "none";
+    readonly idempotency: "none";
+};
+export declare const CODING_LOCAL_EFFECT: {
+    readonly kind: "local_mutation";
+    readonly idempotency: "optional";
+};
+export declare const CODING_UNSUPPORTED_EFFECT: {
+    readonly kind: "external_mutation";
+    readonly idempotency: "unsupported";
+};
+export declare function classifyGitBranchEffect(args: JsonObject): ToolEffectDeclaration;
+export declare function classifyGitWorktreeEffect(args: JsonObject): ToolEffectDeclaration;
+export declare function classifyGitApplyEffect(args: JsonObject): ToolEffectDeclaration;
+export interface CodingEffectReconciliationInput {
+    readonly cwd: string;
+    readonly record: Pick<ToolEffectRecord, "toolCallId" | "toolName">;
+    readonly args: JsonObject;
+    readonly signal?: AbortSignal;
+}
+export type CodingEffectReconciliation = {
+    readonly status: "completed";
+    readonly result: ToolResult;
+} | {
+    readonly status: "unknown";
+};
+/**
+ * Checks only exact local postconditions. Callers retain the pending call arguments,
+ * then pass a completed result to ToolEffectStore.resolveUnknown() when this returns one.
+ */
+export declare function reconcileCodingToolEffect(input: CodingEffectReconciliationInput): Promise<CodingEffectReconciliation>;

package/dist/effects.js

@@ -0,0 +1,89 @@
+import { readFile, stat } from "node:fs/promises";
+import { Buffer } from "node:buffer";
+import { HARD_MAX_WRITE_BYTES } from "./limits.js";
+import { resolveContainedMutationPath } from "./mutation-path.js";
+export const CODING_OBSERVATION_EFFECT = { kind: "none", idempotency: "none" };
+export const CODING_LOCAL_EFFECT = { kind: "local_mutation", idempotency: "optional" };
+export const CODING_UNSUPPORTED_EFFECT = { kind: "external_mutation", idempotency: "unsupported" };
+export function classifyGitBranchEffect(args) {
+    return args.action === "list" || args.action === "validate" ? CODING_OBSERVATION_EFFECT : CODING_LOCAL_EFFECT;
+}
+export function classifyGitWorktreeEffect(args) {
+    return args.action === "list" ? CODING_OBSERVATION_EFFECT : CODING_LOCAL_EFFECT;
+}
+export function classifyGitApplyEffect(args) {
+    return args.action === "check" ? CODING_OBSERVATION_EFFECT : CODING_LOCAL_EFFECT;
+}
+/**
+ * Checks only exact local postconditions. Callers retain the pending call arguments,
+ * then pass a completed result to ToolEffectStore.resolveUnknown() when this returns one.
+ */
+export async function reconcileCodingToolEffect(input) {
+    input.signal?.throwIfAborted();
+    const completed = () => ({
+        status: "completed",
+        result: {
+            toolCallId: input.record.toolCallId,
+            name: input.record.toolName,
+            content: [{ type: "text", text: "Local tool postcondition verified." }],
+            value: { reconciled: true },
+        },
+    });
+    try {
+        if (input.record.toolName === "write") {
+            const path = stringArg(input.args, "path");
+            const content = stringArg(input.args, "content");
+            if (path === undefined || content === undefined || Buffer.byteLength(content, "utf8") > HARD_MAX_WRITE_BYTES)
+                return { status: "unknown" };
+            const target = await resolveContainedMutationPath(input.cwd, path);
+            const expected = Buffer.from(content, "utf8");
+            if ((await stat(target)).size !== expected.length)
+                return { status: "unknown" };
+            return (await readFile(target)).equals(expected) ? completed() : { status: "unknown" };
+        }
+        if (input.record.toolName === "delete") {
+            const path = stringArg(input.args, "path");
+            if (path === undefined)
+                return { status: "unknown" };
+            await resolveContainedMutationPath(input.cwd, path, { allowMissing: true });
+            return (await missing(input.cwd, path)) ? completed() : { status: "unknown" };
+        }
+        if (input.record.toolName === "move") {
+            const from = stringArg(input.args, "from");
+            const to = stringArg(input.args, "to");
+            if (from === undefined || to === undefined)
+                return { status: "unknown" };
+            await Promise.all([
+                resolveContainedMutationPath(input.cwd, from, { allowMissing: true }),
+                resolveContainedMutationPath(input.cwd, to, { allowMissing: true }),
+            ]);
+            if (await missing(input.cwd, from)) {
+                try {
+                    await resolveContainedMutationPath(input.cwd, to);
+                    return completed();
+                }
+                catch {
+                    return { status: "unknown" };
+                }
+            }
+        }
+    }
+    catch {
+        // Containment/read failure is not proof that an effect did not happen.
+    }
+    return { status: "unknown" };
+}
+function stringArg(args, name) {
+    const value = args[name];
+    return typeof value === "string" ? value : undefined;
+}
+async function missing(cwd, path) {
+    try {
+        await resolveContainedMutationPath(cwd, path);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ENOENT" || error.code === "ENOTDIR";
+    }
+}
+//# sourceMappingURL=effects.js.map

package/dist/execution-policy.d.ts

@@ -1,6 +1,11 @@
-import type { ExecutionAction, ExecutionPolicy } from "@arnilo/prism";
-import type { ToolResult } from "@arnilo/prism";
-export declare function enforceExecutionPolicy(policy: ExecutionPolicy | undefined, action: ExecutionAction, toolCallId: string, toolName: string): Promise<{
+import type { ExecutionAction, ExecutionPolicy, ToolResult } from "@arnilo/prism";
+export declare function enforceExecutionPolicy(policy: ExecutionPolicy | undefined, action: ExecutionAction, toolCallId: string, toolName: string, 
+/** Called once on policy denial so one site emits lifecycle permission_denied for every tool. */
+onDenied?: (input: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly reason: string;
+}) => void): Promise<{
     allowed: true;
     action: ExecutionAction;
 } | {

package/dist/execution-policy.js

@@ -1,5 +1,7 @@
 import { assertExecutionAllowed, ExecutionDeniedError } from "@arnilo/prism";
-export async function enforceExecutionPolicy(policy, action, toolCallId, toolName) {
+export async function enforceExecutionPolicy(policy, action, toolCallId, toolName, 
+/** Called once on policy denial so one site emits lifecycle permission_denied for every tool. */
+onDenied) {
     if (!policy)
         return { allowed: true, action };
     try {
@@ -8,10 +10,11 @@ export async function enforceExecutionPolicy(policy, action, toolCallId, toolNam
     }
     catch (error) {
         const message = error instanceof ExecutionDeniedError
-            ? error.decision.reason ?? error.message
+            ? (error.decision.reason ?? error.message)
             : error instanceof Error
                 ? error.message
                 : String(error);
+        onDenied?.({ toolCallId, toolName, reason: message });
         return {
             allowed: false,
             result: {

package/dist/file-mutation-queue.js

@@ -19,8 +19,7 @@ function isMissingPathError(error) {
     return (typeof error === "object" &&
         error !== null &&
         "code" in error &&
-        (error.code === "ENOENT" ||
-            error.code === "ENOTDIR"));
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
 }
 async function getMutationQueueKey(filePath) {
     const resolvedPath = resolve(filePath);

package/dist/forge/github.d.ts

@@ -0,0 +1,2 @@
+import type { CreateGitHubForgeOptions, ForgeOperations } from "./types.js";
+export declare function createGitHubForge(options: CreateGitHubForgeOptions): ForgeOperations;