@arnilo/prism 0.7.0 → 0.9.0

package/dist/contracts-protocol.d.ts

@@ -1,4 +1,6 @@
-import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, Usage } from "./contracts-core.js";
+import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, BudgetAxisUsage, BudgetConsumedCounters, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, ProviderStopReason, RetryOptions, RunLimitBreach, RunLimitName, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, ToolCallSummary, TurnBudgets, TurnPolicyOptions, Usage } from "./contracts-core.js";
+import type { CacheUsageReport } from "./cache-helpers.js";
+import type { CheckpointRestoreAudit } from "./checkpoint-restore.js";
 import type { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
@@ -28,6 +30,7 @@ export type ProviderEvent = {
 } | {
     readonly type: "done";
     readonly usage?: Usage;
+    readonly stopReason?: ProviderStopReason;
 } | {
     readonly type: "error";
     readonly error: ErrorInfo;
@@ -108,6 +111,10 @@ export interface RunOptions {
     readonly toolNames?: readonly string[];
     /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
     readonly toolsDisclosure?: import("./tool-search.js").ToolsDisclosure;
+    /** Per-turn restrictive allow-list over the run grant. Overrides `AgentConfig.toolNarrowing`. */
+    readonly toolNarrowing?: import("./contracts-core/agent.js").ToolNarrowing;
+    /** Opt-in: tools hidden this turn stay callable by name (default off). Overrides agent config. */
+    readonly allowHiddenToolCalls?: true;
     readonly toolsSearch?: import("./tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
@@ -125,6 +132,11 @@ export interface RunOptions {
     readonly runState?: AgentRunStateOptions;
     /** Prompt provenance: copied verbatim onto this run's start and finish ledger records. */
     readonly promptVersion?: PromptVersionRef;
+    /**
+     * Host turn policy (plan 084 Task 2): a clean turn cap and/or a synchronous stop callback
+     * evaluated before every provider request. Omitted → no callback runs.
+     */
+    readonly turnPolicy?: TurnPolicyOptions;
 }
 export interface ProviderTurnMetadata {
     readonly providerId: string;
@@ -135,6 +147,17 @@ export interface ProviderTurnMetadata {
     readonly httpStatus?: number;
     readonly rateLimitRemaining?: number;
     readonly rateLimitResetMs?: number;
+    /** Why the provider turn stopped (plan 087 T1); present on `provider_turn_finished` only. */
+    readonly stopReason?: ProviderStopReason;
+    /** Effective budget state at turn end (plan 087 T1); present on `provider_turn_finished` only. */
+    readonly budgets?: TurnBudgets;
+    /** Provider-reported cache usage and derived hit rate; absent when cache usage is unknown. */
+    readonly cache?: CacheUsageReport;
+    /** Effective tool menu this turn. Names hashed in request order; never includes args. */
+    readonly tools?: {
+        readonly count: number;
+        readonly idsHash: string;
+    };
 }
 export interface ToolExecutionMetadata {
     readonly durationMs: number;
@@ -170,8 +193,20 @@ export interface DelegatedAgentStep {
         readonly label?: string;
     };
 }
-export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal";
-export type AgentEvent = {
+/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop; the rest are loop ceilings (F4). */
+export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy";
+/**
+ * Origin of an agent event forwarded from a delegated child (supervisor child-event passthrough).
+ * Present only on child events routed onto a parent stream; absent on a session's own events.
+ */
+export interface ChildEventOrigin {
+    readonly childId: string;
+    readonly delegationId: string;
+    /** Delegation depth: 1 is a direct child of the hosting supervisor. */
+    readonly depth: number;
+}
+/** Payload union of every agent event; the exported `AgentEvent` adds the optional child origin tag. */
+type AgentEventPayload = {
     readonly type: "agent_started";
     readonly sessionId: string;
     readonly runId: string;
@@ -180,8 +215,10 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly usage?: Usage;
-    /** Why the loop stopped, when a limit/ceiling ended the run cleanly (F4). Absent = natural end. */
+    /** Why the loop stopped, when a limit/ceiling or a host turn policy ended the run cleanly (F4). Absent = natural end. */
     readonly finishReason?: AgentFinishReason;
+    /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). Present only with `finishReason: "host_policy"`. */
+    readonly stopDetail?: string;
 } | {
     readonly type: "agent_suspended";
     readonly sessionId: string;
@@ -193,6 +230,8 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly version: number;
+    /** Plan 094 Task 3: audit of the external-state restore hooks that ran before this claim. */
+    readonly restore?: CheckpointRestoreAudit;
 } | {
     readonly type: "agent_denied";
     readonly sessionId: string;
@@ -209,6 +248,17 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly turn: number;
+} | {
+    /**
+     * Host middleware completed this turn without a provider request (plan 096). No `usage` field:
+     * a deterministic turn has no provider cost, so accounting must never zero-fill one.
+     */
+    readonly type: "deterministic_turn";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    /** Answering middleware id (provenance); ids only, never free host code. */
+    readonly middleware: string;
 } | {
     readonly type: "provider_turn_started";
     readonly sessionId: string;
@@ -273,6 +323,13 @@ export type AgentEvent = {
     readonly reason: string;
     readonly error: ErrorInfo;
     readonly metadata: ToolExecutionMetadata;
+} | {
+    /** Host `toolNarrowing` asked for names outside the run grant; those names were dropped. */
+    readonly type: "tool_narrowing_clamped";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly dropped: readonly string[];
 } | {
     readonly type: "guardrail_decision";
     readonly sessionId: string;
@@ -285,6 +342,16 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly breach: RunLimitBreach;
+} | {
+    /** Terminal attribution for a run that died on a run limit (plan 087 T2): which axis fired,
+     *  counters at exhaustion, how close the other axes were, and hashes of recent tool calls. */
+    readonly type: "budget_exhausted";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly limit: RunLimitName;
+    readonly consumed: BudgetConsumedCounters;
+    readonly closestOtherAxes: readonly BudgetAxisUsage[];
+    readonly recentToolCalls: readonly ToolCallSummary[];
 } | {
     readonly type: "queue_updated";
     readonly sessionId: string;
@@ -375,6 +442,14 @@ export type AgentEvent = {
     readonly attempt: number;
     readonly result: ArtifactValidation;
 };
+/**
+ * One agent event. `child` is set only when the event was forwarded from a delegated child
+ * (e.g. supervisor `report: "stream"` passthrough), so hosts can route it onto a parent stream
+ * without per-event-type special cases. It never replaces the event's own `sessionId`/`runId`.
+ */
+export type AgentEvent = AgentEventPayload & {
+    readonly child?: ChildEventOrigin;
+};
 export type ToolEffectKind = "none" | "local_mutation" | "external_mutation";
 export type ToolEffectIdempotency = "none" | "optional" | "required" | "tool_managed" | "unsupported";
 /** Static or validated-argument classification of one tool call's side-effect behavior. */
@@ -538,6 +613,10 @@ export interface RunRecord extends OwnershipScope {
     readonly startedAt: string;
     readonly finishedAt?: string;
     readonly abortReason?: string;
+    /** Present when the loop stopped on a ceiling or host policy instead of a natural end. */
+    readonly stopReason?: AgentFinishReason;
+    /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). */
+    readonly stopDetail?: string;
     readonly error?: ErrorInfo;
     readonly metadata?: Readonly<Record<string, unknown>>;
     /** Provenance ref copied from `RunOptions.promptVersion` when the host supplied one. */
@@ -676,4 +755,11 @@ export interface ProviderTurnResult {
     readonly messageId?: string;
     readonly started: boolean;
     readonly usage?: Usage;
+    /**
+     * Provenance for turns that did not come from the provider (plan 096):
+     * `{ deterministic: { middleware } }`. Copied onto the assistant `Message.metadata`, so it
+     * serializes with the transcript and survives replay. Absent for provider turns.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
+export {};

package/dist/contracts-run-state.d.ts

@@ -1,5 +1,6 @@
-import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
-import type { AgentEvent, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
+import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointRecord, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ContextMeter, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
+import type { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
+import type { CheckpointRestoreHook } from "./checkpoint-restore.js";
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
 export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
 export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
@@ -139,12 +140,38 @@ export declare const HARD_MAX_ACTION_CONSTRAINTS = 64;
 export declare const MAX_ATTRIBUTION_DEPTH = 8;
 export declare const MAX_ACTION_CONSTRAINT_BYTES: number;
 export declare const HARD_MAX_ACTION_CONSTRAINT_BYTES: number;
+/**
+ * Opaque host sidecar pinned to one checkpoint *record* (git commit, document version,
+ * workspace fingerprint) — never part of the run-state value, so it costs no `maxStateBytes`
+ * budget and is invisible to state parsing. Bounded to `MAX_AGENT_RUN_METADATA_BYTES` (4 KiB)
+ * and redacted like the state value at every write.
+ */
+export type AgentRunCheckpointMetadata = Readonly<Record<string, string>>;
+/** Host source for checkpoint sidecar metadata: a fixed map or a live provider resolved per write. */
+export type AgentRunCheckpointMetadataSource = AgentRunCheckpointMetadata | (() => AgentRunCheckpointMetadata | undefined);
 export interface AgentRunStateOptions {
     readonly checkpoints: CheckpointStore;
     /** Host-authored immutable revision required for durable runs. */
     readonly definitionRevision: string;
+    /**
+     * Durable checkpoint cadence (plan 084 Task 1). `"decision"` (default) persists only on
+     * suspension and terminal status. `"every-turn"` additionally persists a running-state
+     * checkpoint at each provider-turn boundary — after the previous turn's tool results are in
+     * the session store, before the next provider request — so a host process that dies mid-run
+     * can `resumeAgentRun(..., { decision: "continue" })` from the last turn instead of re-running
+     * the investigation. Costs one bounded, redacted checkpoint write per provider turn; the
+     * policy is recorded in the checkpoint, so a later resume keeps checkpointing without the host
+     * repeating the option.
+     */
+    readonly checkpointPolicy?: "decision" | "every-turn";
     /** Suspend every tool call before its side effect. */
     readonly interruptBeforeTool?: boolean;
+    /**
+     * Sidecar metadata written with every checkpoint of this run (and carried into a resumed
+     * run). A provider is resolved at each checkpoint write, so a host closure can pin state
+     * that moves mid-run (e.g. the current git commit). Absent = records stay byte-identical.
+     */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
     readonly maxStateBytes?: number;
     readonly fencingToken?: number;
     /** Enables sticky auto-apply when a nested suspension first surfaces during this run. */
@@ -183,17 +210,41 @@ export interface AgentRunState {
 }
 export interface AgentRunResume {
     readonly expectedVersion: number;
-    /** Legacy single-approval path; `approve` allows all pending once, `deny` terminates the run denied. */
-    readonly decision?: "approve" | "deny";
+    /**
+     * Legacy decision path. `approve` allows all pending decisions once; `deny` terminates the run
+     * as `denied`; `continue` resumes a running-state `"every-turn"` checkpoint that has no pending
+     * decisions (crash recovery). A suspended run still requires `approve`/`deny` or a decision
+     * batch — `continue` never bypasses an approval gate and is a host-API-only action.
+     */
+    readonly decision?: "approve" | "deny" | "continue";
     /** Batch decision path; exactly one of decision/decisions. Applied as one atomic CAS transition. */
     readonly decisions?: readonly RunDecision[];
 }
+/**
+ * Checkpoint handed to a restore hook (plan 094 Task 3). `checkpoint.value` is the raw stored
+ * run-state value; `metadata` is the redacted, bounded sidecar map hosts write via
+ * `AgentRunStateOptions.checkpointMetadata`.
+ */
+export interface AgentCheckpointRestoreContext {
+    readonly runId: string;
+    readonly sessionId: string;
+    /** Version of the checkpoint being claimed; a hook may pass it to an external system's own CAS. */
+    readonly version: number;
+    /** State being claimed: `running` for crash recovery, `suspended` for a decision resume. */
+    readonly status: AgentRunStatus | "running";
+    readonly metadata?: AgentRunCheckpointMetadata;
+    readonly checkpoint: CheckpointRecord;
+}
+/** Host code restoring one external layer before a durable resume applies. */
+export type AgentCheckpointRestoreHook = CheckpointRestoreHook<AgentCheckpointRestoreContext>;
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
     /** Current host-authored revision; must exactly match the checkpoint. */
     readonly definitionRevision: string;
     readonly ownership?: OwnershipScope;
     readonly fencingToken?: number;
+    /** Host abort for the resume: checked between steps and threaded into the resumed provider/tool turn. */
+    readonly signal?: AbortSignal;
     /** Routes root decisions for nested-run approvals back to the child (e.g. supervisor). */
     readonly resumeNestedRun?: ResumeNestedRun;
     /**
@@ -206,10 +257,23 @@ export interface AgentRunResumeOptions {
     readonly persistSessionState?: boolean;
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies (requires `persistSessionState` too). */
     readonly includeSkillBodies?: boolean;
+    /**
+     * Checkpoint sidecar metadata for the claim write (and the resumed run's later checkpoints).
+     * Absent = the record's existing metadata is preserved unchanged.
+     */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
+    /**
+     * Plan 094 Task 3: external-state restore hooks. Every hook must succeed (sequentially, each
+     * within `restoreHookTimeoutMs`) before the claim write and the conversation restore apply;
+     * the first failure throws `CheckpointRestoreError` naming the hook and leaves the checkpoint
+     * suspended. Hosts that register hooks on the lifecycle instead pass them once there.
+     */
+    readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
+    /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
+    readonly restoreHookTimeoutMs?: number;
 }
-/** Bounded, abortable options for `resumeAgentRunStream()`. */
+/** Bounded live-event options for `resumeAgentRunStream()`; `signal` is inherited from the base resume options. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {
-    readonly signal?: AbortSignal;
 }
 export interface AgentRunRef {
     readonly runId: string;
@@ -218,6 +282,8 @@ export interface AgentRunRef {
 export interface AgentRunStatusResult {
     readonly state: AgentRunState;
     readonly version: number;
+    /** Checkpoint sidecar metadata; absent when the record carries none (or carries only malformed entries). */
+    readonly metadata?: AgentRunCheckpointMetadata;
 }
 export declare class AgentRunStateError extends Error {
     readonly code = "ERR_PRISM_AGENT_RUN_STATE";
@@ -251,6 +317,10 @@ export interface AgentRunResult {
     readonly error?: ErrorInfo;
     /** String form of the abort reason when `status` is `"aborted"`. */
     readonly abortReason?: string;
+    /** Present when the loop stopped on a ceiling or host turn policy instead of a natural end. */
+    readonly stopReason?: AgentFinishReason;
+    /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). */
+    readonly stopDetail?: string;
     /** Present for durable suspended/terminal runs. Payload is redacted and bounded. */
     readonly runState?: AgentRunState;
     /** Present only while awaiting an operator decision. */
@@ -298,6 +368,12 @@ export interface AgentSession {
     abort(reason?: unknown): void;
     entries(): Promise<readonly SessionEntry[]>;
     checkout(leafId?: string): Promise<void>;
+    /**
+     * Context-fill read (plan 091 T2): latest provider turn's input tokens
+     * (reported or labeled estimate) plus the resolved per-request cap, run input
+     * budget, and used ratio. Before any provider turn it estimates stored history.
+     */
+    contextMeter(): ContextMeter;
     fork(options?: AgentSessionForkOptions): AgentSession;
     clone(options?: AgentSessionCloneOptions): Promise<AgentSession>;
 }

package/dist/evidence-grounding.d.ts

@@ -0,0 +1,29 @@
+import type { Guardrail, ToolResult } from "./contracts.js";
+export interface ClaimGroundingEvidence {
+    readonly value: number;
+    /** Refer to this governed figure as `[evidence:<ref>]` immediately after a claim. */
+    readonly ref?: string;
+}
+export interface ClaimGroundingEvidenceExtractorContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly toolResults: readonly ToolResult[];
+}
+/** Supplies host-governed figures without coupling this primitive to a host store or package. */
+export type ClaimGroundingEvidenceExtractor = (context: ClaimGroundingEvidenceExtractorContext) => readonly ClaimGroundingEvidence[];
+export interface ClaimGroundingGuardrailOptions {
+    /** False makes the returned guardrail a no-op. */
+    readonly requireEvidenceForNumbers: boolean;
+    /** Defaults to same-run tool results. A host extractor may return its own governed figures. */
+    readonly evidenceSources?: "tool_results" | ClaimGroundingEvidenceExtractor;
+    /** Defaults to block. Flag emits an allow record with `metadata.violation: true`. */
+    readonly onViolation?: "block" | "flag";
+    /** Exact numeric equality by default; rounded accepts half the final printed unit. */
+    readonly tolerance?: "exact" | "rounded";
+}
+/**
+ * Deterministic output guardrail for figures that must be grounded in same-run tool results
+ * or host-governed evidence. It never calls a provider, store, or extractor asynchronously.
+ */
+export declare function createClaimGroundingGuardrail(options: ClaimGroundingGuardrailOptions): Guardrail<"output">;

package/dist/evidence-grounding.js

@@ -0,0 +1,162 @@
+const MAX_EVIDENCE_FIGURES = 4096;
+const MAX_EVIDENCE_DEPTH = 16;
+const MAX_EVIDENCE_NODES = 16 * 1024;
+const MAX_EVIDENCE_TEXT_CHARS = 128 * 1024;
+const MAX_CLAIM_CHARS = 128;
+const MAX_CITATION_DISTANCE = 96;
+const EVIDENCE_CITATION = /\[evidence:([a-zA-Z0-9._:-]{1,128})\]/g;
+const NUMERIC_CLAIM = /(?<![\p{L}\p{N}_])~?[$€£¥]?[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?[kKmMbB]?%?(?![\p{L}\p{N}_])/gu;
+/**
+ * Deterministic output guardrail for figures that must be grounded in same-run tool results
+ * or host-governed evidence. It never calls a provider, store, or extractor asynchronously.
+ */
+export function createClaimGroundingGuardrail(options) {
+    const resolved = resolveOptions(options);
+    return {
+        name: "claim-grounding",
+        stage: "output",
+        revision: "1",
+        evaluate(context) {
+            if (!resolved.requireEvidenceForNumbers)
+                return { action: "allow" };
+            const figures = evidenceFigures(resolved.evidenceSources, context);
+            const refs = new Set(figures.flatMap((figure) => (figure.ref === undefined ? [] : [figure.ref])));
+            for (const claim of outputClaims(context.value.content)) {
+                const block = context.value.content[claim.contentIndex];
+                if (matchesEvidence(claim, figures, resolved.tolerance) || (block?.type === "text" && citesEvidence(block.text, claim.end, refs)))
+                    continue;
+                const metadata = {
+                    violation: true,
+                    claim: claim.text.slice(0, MAX_CLAIM_CHARS),
+                    contentIndex: claim.contentIndex,
+                    start: claim.end - claim.text.length,
+                    end: claim.end,
+                };
+                return resolved.onViolation === "block"
+                    ? { action: "block", reason: "claim_ungrounded", metadata }
+                    : { action: "allow", reason: "claim_ungrounded", metadata };
+            }
+            return { action: "allow" };
+        },
+    };
+}
+function resolveOptions(options) {
+    if (!options || typeof options.requireEvidenceForNumbers !== "boolean")
+        throw new TypeError("Claim grounding requireEvidenceForNumbers must be boolean");
+    const evidenceSources = options.evidenceSources ?? "tool_results";
+    if (evidenceSources !== "tool_results" && typeof evidenceSources !== "function")
+        throw new TypeError('Claim grounding evidenceSources must be "tool_results" or an extractor');
+    const onViolation = options.onViolation ?? "block";
+    if (onViolation !== "block" && onViolation !== "flag")
+        throw new TypeError('Claim grounding onViolation must be "block" or "flag"');
+    const tolerance = options.tolerance ?? "exact";
+    if (tolerance !== "exact" && tolerance !== "rounded")
+        throw new TypeError('Claim grounding tolerance must be "exact" or "rounded"');
+    return { requireEvidenceForNumbers: options.requireEvidenceForNumbers, evidenceSources, onViolation, tolerance };
+}
+function evidenceFigures(source, context) {
+    if (source !== "tool_results")
+        return source({
+            sessionId: context.sessionId,
+            runId: context.runId,
+            metadata: context.metadata,
+            toolResults: context.toolResults ?? [],
+        })
+            .filter(validFigure)
+            .slice(0, MAX_EVIDENCE_FIGURES);
+    const figures = [];
+    const budget = { chars: MAX_EVIDENCE_TEXT_CHARS, nodes: MAX_EVIDENCE_NODES };
+    for (const result of context.toolResults ?? []) {
+        if (result.error)
+            continue;
+        const ref = `tool:${result.toolCallId}`;
+        collectFigures(result.value, figures, ref, new WeakSet(), 0, budget);
+        for (const block of result.content ?? [])
+            if (block.type === "text")
+                collectTextFigures(block.text, figures, ref, budget);
+    }
+    return figures;
+}
+function validFigure(value) {
+    return typeof value?.value === "number" && Number.isFinite(value.value) && (value.ref === undefined || citationRef(value.ref));
+}
+function collectFigures(value, figures, ref, seen = new WeakSet(), depth = 0, budget = { chars: MAX_EVIDENCE_TEXT_CHARS, nodes: MAX_EVIDENCE_NODES }) {
+    if (figures.length >= MAX_EVIDENCE_FIGURES || depth > MAX_EVIDENCE_DEPTH || budget.nodes-- < 1)
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            figures.push({ value, ref });
+        return;
+    }
+    if (typeof value === "string") {
+        collectTextFigures(value, figures, ref, budget);
+        return;
+    }
+    if (!value || typeof value !== "object" || seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectFigures(item, figures, ref, seen, depth + 1, budget);
+        return;
+    }
+    for (const item of Object.values(value))
+        collectFigures(item, figures, ref, seen, depth + 1, budget);
+}
+function collectTextFigures(text, figures, ref, budget) {
+    const bounded = text.slice(0, budget.chars);
+    budget.chars -= bounded.length;
+    for (const claim of claims(bounded, 0)) {
+        if (figures.length >= MAX_EVIDENCE_FIGURES)
+            return;
+        figures.push({ value: claim.value, ref });
+    }
+}
+function outputClaims(content) {
+    const out = [];
+    for (let index = 0; index < content.length; index += 1) {
+        const block = content[index];
+        if (block?.type !== "text")
+            continue;
+        out.push(...claims(block.text, index));
+    }
+    return out;
+}
+function claims(text, contentIndex) {
+    const out = [];
+    NUMERIC_CLAIM.lastIndex = 0;
+    for (let match = NUMERIC_CLAIM.exec(text); match; match = NUMERIC_CLAIM.exec(text)) {
+        const token = match[0];
+        const parsed = parseNumber(token);
+        if (parsed === undefined)
+            continue;
+        out.push({ text: token, value: parsed.value, tolerance: parsed.tolerance, end: match.index + token.length, contentIndex });
+    }
+    return out;
+}
+function parseNumber(token) {
+    const compact = token.replace(/^~?[$€£¥]?[-+]?/, "").replace(/%$/, "");
+    const suffix = compact.at(-1)?.toLowerCase();
+    const multiplier = suffix === "k" ? 1_000 : suffix === "m" ? 1_000_000 : suffix === "b" ? 1_000_000_000 : 1;
+    const numberText = (multiplier === 1 ? compact : compact.slice(0, -1)).replace(/,/g, "");
+    const value = Number(numberText) * multiplier;
+    if (!Number.isFinite(value))
+        return undefined;
+    const fraction = numberText.split(".")[1]?.length ?? 0;
+    return { value, tolerance: 0.5 * multiplier * 10 ** -fraction };
+}
+function matchesEvidence(claim, figures, tolerance) {
+    return figures.some((figure) => Math.abs(figure.value - claim.value) <= (tolerance === "rounded" ? claim.tolerance : 0));
+}
+function citesEvidence(text, end, refs) {
+    const nearby = text.slice(end, end + MAX_CITATION_DISTANCE);
+    EVIDENCE_CITATION.lastIndex = 0;
+    for (let match = EVIDENCE_CITATION.exec(nearby); match; match = EVIDENCE_CITATION.exec(nearby))
+        if (refs.has(match[1] ?? ""))
+            return true;
+    return false;
+}
+function citationRef(value) {
+    return /^[a-zA-Z0-9._:-]{1,128}$/.test(value);
+}
+//# sourceMappingURL=evidence-grounding.js.map

package/dist/guardrail-packs/coding-standard.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned coding hygiene: file mutations confined to configured roots, test files read-only. */
+export declare const codingStandardPack: GuardrailPackDefinition;

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