@arnilo/prism 0.8.0 → 0.10.0

package/dist/guardrail-packs/coding-standard.js

@@ -0,0 +1,63 @@
+import { resolve as resolvePath, sep } from "node:path";
+import { GuardrailPackError } from "./errors.js";
+/** File-mutating prism coding tool names (plan 092 Task 1: `shell`/`read` are not mutations). */
+const MUTATING_TOOLS = ["write", "edit", "delete", "move"];
+const PATH_ARGS = ["path", "paths", "from", "to"];
+const TEST_FILE_PATTERN = /(^|[\\/])(?:__tests__|tests?|specs?)[\\/]|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+const MAX_ROOTS = 16;
+function pathStrings(args) {
+    const paths = [];
+    for (const key of PATH_ARGS) {
+        const value = args[key];
+        if (typeof value === "string")
+            paths.push(value);
+        else if (Array.isArray(value))
+            paths.push(...value.filter((item) => typeof item === "string"));
+    }
+    return paths;
+}
+function readRoots(value, cwd) {
+    if (value === undefined)
+        return [cwd];
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_ROOTS) {
+        throw new GuardrailPackError(`coding-standard options.roots must be a non-empty string array (max ${MAX_ROOTS})`);
+    }
+    return value.map((root) => {
+        if (typeof root !== "string" || !root.trim())
+            throw new GuardrailPackError("coding-standard options.roots entries must be non-empty strings");
+        return resolvePath(cwd, root);
+    });
+}
+/** Lazy containment: no symlink resolution (a link inside a root can still point out); execution policy/sandbox remains the hard boundary. */
+function outsideRoots(candidate, roots, cwd) {
+    const resolved = resolvePath(cwd, candidate);
+    return !roots.some((root) => resolved === root || resolved.startsWith(root.endsWith(sep) ? root : `${root}${sep}`));
+}
+/** Canned coding hygiene: file mutations confined to configured roots, test files read-only. */
+export const codingStandardPack = {
+    id: "coding-standard",
+    version: 1,
+    description: "Restricts file mutation to configured workspace roots and blocks test-file rewrites.",
+    build(options) {
+        const cwd = resolvePath(typeof options.cwd === "string" ? options.cwd : process.cwd());
+        const roots = readRoots(options.roots, cwd);
+        return {
+            rules: [
+                {
+                    id: "no-unrelated-file-edits",
+                    tool: MUTATING_TOOLS,
+                    reason: "File edits are restricted to the configured workspace roots",
+                    deny: (args) => pathStrings(args).some((candidate) => outsideRoots(candidate, roots, cwd)),
+                },
+                {
+                    id: "no-test-rewrites",
+                    tool: MUTATING_TOOLS,
+                    pattern: TEST_FILE_PATTERN,
+                    argPath: PATH_ARGS,
+                    reason: "Test files are read-only under this pack",
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=coding-standard.js.map

package/dist/guardrail-packs/destructive-commands.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned destructive shell/SQL patterns on the `shell` tool's `command` argument. */
+export declare const destructiveCommandsPack: GuardrailPackDefinition;

package/dist/guardrail-packs/destructive-commands.js

@@ -0,0 +1,46 @@
+/** Shell commands that destroy data or history. Denies `--force-with-lease` too: both rewrite remote history. */
+const DESTRUCTIVE_COMMANDS = [
+    {
+        id: "no-recursive-force-delete",
+        pattern: /\brm\s+(?:[^\n;&|]*?\s)?-(?=[a-z]*r)(?=[a-z]*f)[a-z]+/i,
+        reason: "Recursive force delete is not allowed",
+    },
+    {
+        id: "no-long-flag-force-delete",
+        pattern: /\brm\s+[^\n;&|]*--recursive\b[^\n;&|]*--force\b|\brm\s+[^\n;&|]*--force\b[^\n;&|]*--recursive\b/i,
+        reason: "Recursive force delete is not allowed",
+    },
+    {
+        id: "no-force-push",
+        pattern: /\bgit\s+push\b[^\n;&|]*(?:--force\b|(?:^|\s)-f(?:\s|$))/i,
+        reason: "Force push is not allowed",
+    },
+    {
+        id: "no-destructive-sql",
+        pattern: /\b(?:drop|truncate)\s+table\b/i,
+        reason: "Destructive SQL is not allowed",
+    },
+    {
+        id: "no-device-overwrite",
+        pattern: /\bmkfs(?:\.\w+)?\b|\bdd\b[^\n;&|]*\bof=\/dev\//i,
+        reason: "Raw device overwrite is not allowed",
+    },
+];
+/** Canned destructive shell/SQL patterns on the `shell` tool's `command` argument. */
+export const destructiveCommandsPack = {
+    id: "destructive-commands",
+    version: 1,
+    description: "Blocks destructive shell and SQL commands (recursive force delete, force push, drop table, device overwrite).",
+    build() {
+        return {
+            rules: DESTRUCTIVE_COMMANDS.map(({ id, pattern, reason }) => ({
+                id,
+                tool: "shell",
+                pattern,
+                argPath: "command",
+                reason,
+            })),
+        };
+    },
+};
+//# sourceMappingURL=destructive-commands.js.map

package/dist/guardrail-packs/errors.d.ts

@@ -0,0 +1,7 @@
+/** Guardrail pack config/compile error (plan 092 Task 2). Config mistakes fail closed at compile time. */
+export declare class GuardrailPackError extends Error {
+    readonly code = "ERR_PRISM_GUARDRAIL_PACK";
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+    });
+}

package/dist/guardrail-packs/errors.js

@@ -0,0 +1,9 @@
+/** Guardrail pack config/compile error (plan 092 Task 2). Config mistakes fail closed at compile time. */
+export class GuardrailPackError extends Error {
+    code = "ERR_PRISM_GUARDRAIL_PACK";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "GuardrailPackError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/guardrail-packs/index.d.ts

@@ -0,0 +1,4 @@
+import type { GuardrailPackDefinition } from "./types.js";
+export declare const BUILT_IN_GUARDRAIL_PACKS: ReadonlyMap<string, GuardrailPackDefinition>;
+/** Built-in pack ids, in registry order. */
+export declare const BUILT_IN_GUARDRAIL_PACK_IDS: readonly string[];

package/dist/guardrail-packs/index.js

@@ -0,0 +1,15 @@
+/** Built-in guardrail pack registry (plan 092 Task 2). Definitions are pure data + pure factories. */
+import { codingStandardPack } from "./coding-standard.js";
+import { destructiveCommandsPack } from "./destructive-commands.js";
+import { secretsHygienePack } from "./secrets-hygiene.js";
+import { validationRespectPack } from "./validation-respect.js";
+const DEFINITIONS = [
+    codingStandardPack,
+    destructiveCommandsPack,
+    validationRespectPack,
+    secretsHygienePack,
+];
+export const BUILT_IN_GUARDRAIL_PACKS = new Map(DEFINITIONS.map((definition) => [definition.id, definition]));
+/** Built-in pack ids, in registry order. */
+export const BUILT_IN_GUARDRAIL_PACK_IDS = DEFINITIONS.map((definition) => definition.id);
+//# sourceMappingURL=index.js.map

package/dist/guardrail-packs/secrets-hygiene.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned secret hygiene: any tool argument carrying credential-shaped material is denied. */
+export declare const secretsHygienePack: GuardrailPackDefinition;

package/dist/guardrail-packs/secrets-hygiene.js

@@ -0,0 +1,23 @@
+/**
+ * Known credential shapes, all quantifier-bounded so a hostile argument string cannot blow up the regex.
+ * Prism redaction matches exact known values only (plan 092 Task 1), so these patterns ship with the pack.
+ */
+const SECRET_PATTERN = /(?:sk-[A-Za-z0-9]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.|xox[baprs]-[A-Za-z0-9-]{10,})/;
+/** Canned secret hygiene: any tool argument carrying credential-shaped material is denied. */
+export const secretsHygienePack = {
+    id: "secrets-hygiene",
+    version: 1,
+    description: "Blocks tool calls whose arguments carry secret-shaped material (API keys, tokens, private keys).",
+    build() {
+        return {
+            rules: [
+                {
+                    id: "no-secret-material-in-arguments",
+                    pattern: SECRET_PATTERN,
+                    reason: "Tool arguments contain secret-shaped material",
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=secrets-hygiene.js.map

package/dist/guardrail-packs/types.d.ts

@@ -0,0 +1,26 @@
+/** Internal guardrail-pack definition types (plan 092 Task 2). Not SDK surface; hosts configure packs via `AgentSessionConfig.guardrailPacks`. */
+import type { GuardrailRule, GuardrailRuleContext } from "../contracts-core/guardrail-packs.js";
+import type { ToolResult } from "../contracts-protocol.js";
+/** Plan 104 Task 2: pack-owned durable-state codec. The pack decides what a checkpoint carries. */
+interface GuardrailPackStateCodec {
+    /** Serialize the live state for a checkpoint; `undefined` when nothing needs persisting. */
+    readonly snapshot: (state: Record<string, unknown>) => Readonly<Record<string, unknown>> | undefined;
+    /** Parse a persisted snapshot back into state fields; throw `GuardrailPackError` on a malformed value. */
+    readonly parse: (json: unknown) => Record<string, unknown>;
+}
+/** What a pack's `build` returns: restrictive rules plus an optional pure result observer. */
+export interface GuardrailPackRules {
+    readonly rules: readonly GuardrailRule[];
+    /** Records tool results into pack-local state (never denies); a throw fails closed as a guardrail tripwire. */
+    readonly observe?: (state: Record<string, unknown>, result: ToolResult, context: GuardrailRuleContext) => void;
+    /** Optional codec making the pack's state survive a durable resume; a pack without one persists nothing. */
+    readonly state?: GuardrailPackStateCodec;
+}
+export interface GuardrailPackDefinition {
+    readonly id: string;
+    readonly version: number;
+    readonly description: string;
+    /** Pure factory: options in, rules out. No session access, no I/O. */
+    readonly build: (options: Readonly<Record<string, unknown>>) => GuardrailPackRules;
+}
+export {};

package/dist/guardrail-packs/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/guardrail-packs/validation-respect.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned "respect failed validation": once a validation tool result fails, file mutations are denied until one passes. */
+export declare const validationRespectPack: GuardrailPackDefinition;

package/dist/guardrail-packs/validation-respect.js

@@ -0,0 +1,69 @@
+import { GuardrailPackError } from "./errors.js";
+const MUTATING_TOOLS = ["write", "edit", "delete", "move"];
+/** Validation-style tool names. `shell` is opt-in (`validationTools`): a non-zero shell exit is a failure signal too. */
+const DEFAULT_VALIDATION_TOOLS = ["test", "run_tests", "validate", "validation", "lint", "typecheck", "check"];
+const MAX_VALIDATION_TOOLS = 16;
+const MAX_VALIDATION_TOOL_CHARS = 128;
+/** A tool result failed when it carries an error, or reported a non-zero `exitCode` (the shell tool's shape). */
+function resultFailed(result) {
+    if (result.error !== undefined)
+        return true;
+    const value = result.value;
+    if (!value || typeof value !== "object" || !("exitCode" in value))
+        return false;
+    const exitCode = value.exitCode;
+    return typeof exitCode === "number" && exitCode !== 0;
+}
+function readValidationTools(value) {
+    if (value === undefined)
+        return DEFAULT_VALIDATION_TOOLS;
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_VALIDATION_TOOLS) {
+        throw new GuardrailPackError(`validation-respect options.validationTools must be a non-empty string array (max ${MAX_VALIDATION_TOOLS})`);
+    }
+    return value.map((name) => {
+        if (typeof name !== "string" || !name.trim()) {
+            throw new GuardrailPackError("validation-respect options.validationTools entries must be non-empty strings");
+        }
+        return name;
+    });
+}
+/** Canned "respect failed validation": once a validation tool result fails, file mutations are denied until one passes. */
+export const validationRespectPack = {
+    id: "validation-respect",
+    version: 1,
+    description: "Denies file mutations after a failed validation tool result until a later validation passes.",
+    build(options) {
+        const validationTools = readValidationTools(options.validationTools);
+        return {
+            observe(state, result, context) {
+                if (!validationTools.includes(context.toolName))
+                    return;
+                state.validationFailed = resultFailed(result) ? context.toolName : undefined;
+            },
+            // Plan 104 Task 2: one tool name (or nothing) survives a resume, so a mutation the suspended
+            // run denied stays denied. The codec is the pack's own bound: 128 chars, never arguments.
+            state: {
+                snapshot: (state) => (typeof state.validationFailed === "string" ? { validationFailed: state.validationFailed } : undefined),
+                parse: (json) => {
+                    const record = typeof json === "object" && json !== null ? json : {};
+                    const failed = record.validationFailed;
+                    if (failed === undefined)
+                        return {};
+                    if (typeof failed !== "string" || !failed.trim() || failed.length > MAX_VALIDATION_TOOL_CHARS) {
+                        throw new GuardrailPackError(`validation-respect persisted state.validationFailed must be a non-empty string of at most ${MAX_VALIDATION_TOOL_CHARS} chars`);
+                    }
+                    return { validationFailed: failed };
+                },
+            },
+            rules: [
+                {
+                    id: "no-mutation-after-failed-validation",
+                    tool: MUTATING_TOOLS,
+                    reason: "A previous validation result failed; fix it before mutating files",
+                    deny: (_args, context) => context.state.validationFailed !== undefined,
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=validation-respect.js.map

package/dist/guardrails.d.ts

@@ -1,6 +1,20 @@
-import type { AgentEvent, GuardrailContext, GuardrailRecord, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
+import type { AgentEvent, GuardrailContext, GuardrailPackRef, GuardrailRecord, GuardrailRule, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
+export { GuardrailPackError } from "./guardrail-packs/errors.js";
 import type { SecretRedactor } from "./redaction.js";
 export declare const MAX_GUARDRAIL_CONCURRENCY = 16;
+/** Guardrail pack compile bounds (plan 092 Task 2). All ceilings are config-shape limits, not runtime budgets. */
+export declare const MAX_GUARDRAIL_PACKS = 8;
+export declare const MAX_GUARDRAIL_PACK_RULES = 64;
+/**
+ * Plan 104 T4/T6: the bounded, redacted refusal line for a terminal record that came from a compiled
+ * pack rule — `<prefix> by guardrail rule pack:<pack>/<rule>`, plus the pack's own reason when it set
+ * one — or `undefined` for any other guardrail, so the caller keeps its own neutral text. Only the
+ * compiler writes the `pack`/`rule` metadata, so a host-written guardrail named `pack:…` is never
+ * presented as a pack rule. Reasons are redacted where the record is built, pack names are
+ * compiler-bounded to 128 bytes (the identity always survives the cap), and a long reason is
+ * truncated, so the same derivation serves the tool refusal and decision-time revalidation.
+ */
+export declare function guardrailRefusalText(record: GuardrailRecord, prefix?: string): string | undefined;
 export declare class GuardrailError extends Error {
     readonly code: string;
     readonly record: GuardrailRecord;
@@ -23,3 +37,49 @@ export interface GuardrailRunResult {
 /** Evaluate one typed stage. Default is declaration-order sequential; bounded parallel mode still reports declaration order. */
 export declare function runGuardrails<S extends GuardrailStage>(options: RunGuardrailsOptions<S>): Promise<GuardrailRunResult>;
 export declare function assertGuardrailsAllowed(result: GuardrailRunResult): void;
+/** One `guardrail:<stage>` identity row of a compiled pack, for run-bundle fingerprints. */
+export interface GuardrailPackRow {
+    readonly name: string;
+    readonly stage: "tool_input" | "tool_output";
+    readonly revision: string | null;
+}
+/** Plan 104 Task 2: one replayable pack row of a durable checkpoint (`id`, resolved version, host options). */
+interface GuardrailPackRefRow {
+    readonly id: string;
+    readonly version: number;
+    /** Host options the pack was compiled with, replayed verbatim on resume so enforcement is identical. */
+    readonly options?: Readonly<Record<string, unknown>>;
+    /**
+     * Plan 104 T3: the host's own rule list for an inline pack. Patterns are data and ride the
+     * checkpoint; a `deny` predicate or a `RegExp` pattern cannot round-trip and is refused at save.
+     */
+    readonly rules?: readonly GuardrailRule[];
+}
+/** Plan 104 Task 2: a compile result that can round-trip through a durable checkpoint. */
+interface CompiledGuardrailPacks {
+    readonly guardrails: Guardrails | undefined;
+    /** Rows a durable checkpoint replays; empty when no packs are configured. */
+    readonly packs: readonly GuardrailPackRefRow[];
+    /** Plan 104 T3: `ask` rules as the charge-time durable gate — a match records `interrupt`. */
+    readonly askGate?: Guardrails;
+    /** Plan 104 T3: the same rules as plain blocks, merged into a run that cannot suspend. */
+    readonly askBlocks?: Guardrails;
+    /** Pack-owned state snapshot (`{ <packId>: <pack state> }`); `undefined` when nothing needs persisting. */
+    readonly snapshotState: () => Record<string, Readonly<Record<string, unknown>>> | undefined;
+}
+/**
+ * Compiles `guardrailPacks` config onto the existing tool interception seams: one `tool_input`
+ * guardrail per rule (`name = pack:<pack>/<rule>`), plus one `tool_output` recorder for packs that
+ * observe results. Compiled once per session — patterns are compiled here, never per tool call.
+ * Throws `GuardrailPackError` on malformed config (fail closed); returns `undefined` when unset.
+ */
+export declare function compileGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): Guardrails | undefined;
+/**
+ * Plan 104 Task 2: the internal compile entry behind `compileGuardrailPacks`. Passing `initial`
+ * marks a durable restore — rows must then come from the installed registry, match its version, and
+ * parse through the pack's own state codec, so a mismatch fails closed instead of restoring a
+ * weaker policy. `snapshotState` is the checkpoint-side counterpart.
+ */
+export declare function compileGuardrailPacksWithState(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>, initial?: Readonly<Record<string, unknown>>): CompiledGuardrailPacks;
+/** Stable identity rows for the same config `compileGuardrailPacks` accepts (no state, no guardrails built). */
+export declare function describeGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): readonly GuardrailPackRow[];