@arnilo/prism 0.7.0 → 0.8.0

package/dist/agent-session/session/provider-round.js

@@ -1,7 +1,7 @@
 /** Provider-round phase of runInternal (plan 059). */
 import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "../../guardrails.js";
 import { createProviderTurnMetadata, readProviderHttpStatus } from "../../observability.js";
-import { providerToolCallDeltaContent } from "../../provider-events.js";
+import { providerError, providerToolCallDeltaContent } from "../../provider-events.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "../../redaction.js";
 import { createDefaultRetryPolicy, waitForRetry } from "../../retry.js";
 import { bridgeAbort, errorFromInfo, isSteerSoftInterrupt, jsonBytes, mergeRetry, ProviderTurnFailure, providerContent, randomId, reconstructMissingToolCalls, SteerSoftInterrupt, throwIfAborted, } from "../helpers.js";
@@ -70,13 +70,13 @@ export async function recordProviderUsage(ctx, turnUsage, turn, attempt) {
     };
     await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
 }
-export async function generateWithRetry(session, request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage) {
+export async function generateWithRetry(session, request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage, toolResults = []) {
     const retry = mergeRetry(session.agent.config.retry, options.retry);
     const secrets = [...requestSecrets, ...(retry?.secrets ?? [])];
     const policy = retry?.policy ?? (retry ? createDefaultRetryPolicy(retry) : undefined);
     for (let attempt = 1;; attempt += 1) {
         try {
-            return await generateProviderTurn(session, request, runId, signal, secrets, turn, attempt, recordUsage);
+            return await generateProviderTurn(session, request, runId, signal, secrets, turn, attempt, recordUsage, toolResults);
         }
         catch (error) {
             if (error instanceof GuardrailError || isSteerSoftInterrupt(error))
@@ -100,7 +100,7 @@ export async function generateWithRetry(session, request, runId, options, signal
         }
     }
 }
-export async function generateProviderTurn(session, request, runId, signal, secrets = [], turn = 1, attempt = 1, recordUsage) {
+export async function generateProviderTurn(session, request, runId, signal, secrets = [], turn = 1, attempt = 1, recordUsage, toolResults = []) {
     session.activeLimits.charge("maxProviderAttempts");
     session.activeLimits.charge("maxRequestBytes", jsonBytes(request));
     const startedAt = performance.now();
@@ -189,7 +189,13 @@ export async function generateProviderTurn(session, request, runId, signal, secr
                 stage: "output",
                 guardrails: session.activeGuardrails,
                 value: { content, calls, messageId, started, usage },
-                context: { sessionId: session.id, runId, metadata: session.activeMetadata ?? {}, signal: turnAbort.signal },
+                context: {
+                    sessionId: session.id,
+                    runId,
+                    metadata: session.activeMetadata ?? {},
+                    signal: turnAbort.signal,
+                    toolResults,
+                },
                 redactor: session.activeRedactor,
                 emit: (event) => session.emit(event),
             }));
@@ -223,7 +229,7 @@ export async function generateProviderTurn(session, request, runId, signal, secr
             throw new SteerSoftInterrupt();
         }
         const latencyMs = Math.round(performance.now() - startedAt);
-        const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : errorToErrorInfo(error, secrets);
+        const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : providerError(error, secrets).error;
         await recordTurnUsage();
         session.emit({
             type: "provider_turn_finished",

package/dist/agent-session/session/tool-round.js

@@ -251,8 +251,9 @@ export function bindDispatchToolCall(ctx) {
         if (ctx.session.activeGatedRound?.has(call.id)) {
             return { toolCallId: call.id, name: call.name, metadata: { approvalPending: true } };
         }
+        ctx.toolCalls += 1;
         try {
-            return await dispatchToolCall({
+            const result = await dispatchToolCall({
                 call,
                 registry: ctx.registry,
                 context: {
@@ -329,6 +330,8 @@ export function bindDispatchToolCall(ctx) {
                 },
                 validate: ctx.validate,
             });
+            ctx.toolResults.push(result);
+            return result;
         }
         catch (error) {
             if (error instanceof AgentDelegationSuspendedError && !error.toolCall)

package/dist/agent-session/session/types.d.ts

@@ -2,7 +2,7 @@
 import type { ActiveDurableRun } from "../../agent-approval.js";
 import type { PendingToolCall } from "../../agent-run-state.js";
 import type { AttentionStickyFrontier, PersistedAttentionStickyFrontier } from "../../attention-compiler.js";
-import type { Agent, AgentEvent, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, ToolDefinition, ToolEffectStore, ToolRegistry, Usage } from "../../contracts.js";
+import type { Agent, AgentEvent, AgentFinishReason, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, ToolDefinition, ToolEffectStore, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
 import type { AgentIdentity } from "../../identity.js";
 import type { AgentInput } from "../../input.js";
 import type { SecretRedactor } from "../../redaction.js";
@@ -87,6 +87,11 @@ export type SessionHost = {
     snapshot(): Promise<SessionContextSnapshot>;
 };
 export declare function asSessionHost(session: unknown): SessionHost;
+/** Why a run's loop ended, plus the host's stop detail when `RunOptions.turnPolicy` stopped it. */
+export type RunStopInfo = {
+    readonly reason: AgentFinishReason;
+    readonly detail?: string;
+};
 export type RoundContext = {
     session: SessionHost;
     input: AgentInput;
@@ -117,6 +122,12 @@ export type RoundContext = {
         message: string;
         code?: string | number;
     } | undefined;
+    /** Host tool calls dispatched in this run; the turn-boundary context's `toolCalls` (plan 084 Task 2). */
+    toolCalls: number;
+    /** Completed host tool results from this run, for output evidence guardrails (plan 084 Task 5). */
+    toolResults: ToolResult[];
+    /** Set when a `RunOptions.turnPolicy` stop ended the loop (plan 084 Task 2). */
+    runStop?: RunStopInfo;
     runUsage: {
         add(usage: Usage): void;
         value(): Usage | undefined;

package/dist/agent-session/session.d.ts

@@ -95,6 +95,8 @@ export declare class RuntimeAgentSession implements AgentSession {
         readonly limit?: import("../contracts.js").RunLimitBreach;
         readonly error?: ErrorInfo;
         readonly abortReason?: string;
+        readonly stopReason?: import("../contracts.js").AgentFinishReason;
+        readonly stopDetail?: string;
         readonly runState?: AgentRunState;
         readonly interruption?: import("../contracts.js").AgentRunInterruption;
     }): AgentRunResult;

package/dist/agent-session/session.js

@@ -232,6 +232,8 @@ export class RuntimeAgentSession {
             limit: input.limit,
             error: input.error,
             abortReason: input.abortReason,
+            stopReason: input.stopReason,
+            stopDetail: input.stopDetail,
             runState: input.runState,
             interruption: input.interruption,
         };

package/dist/checkpoints.js

@@ -23,8 +23,11 @@ export function createMemoryCheckpointStore(options = {}) {
             }
             const id = recordKey(input);
             const existing = records.get(id);
-            if (existing)
-                assertOwnership(input, existing);
+            // A foreign-owned record is indistinguishable from a CAS miss: never an
+            // ownership-shaped error (plan 080 Task 3).
+            if (existing && !ownershipMatches(input, existing)) {
+                throw new CheckpointConflictError(`Checkpoint compare-and-swap failed (expected ${input.expectedVersion ?? 0}, current ${existing.version})`);
+            }
             if (input.expectedVersion !== undefined && input.expectedVersion !== (existing?.version ?? 0)) {
                 throw new CheckpointConflictError(`Checkpoint compare-and-swap failed (expected ${input.expectedVersion}, current ${existing?.version ?? 0})`);
             }
@@ -66,8 +69,7 @@ export function createMemoryCheckpointStore(options = {}) {
             const record = records.get(recordKey(input));
             if (!record)
                 return null;
-            assertOwnership(input, record);
-            return record;
+            return ownershipMatches(input, record) ? record : null;
         },
         async listCheckpoints(query = {}) {
             throwIfAborted(query.signal);
@@ -94,8 +96,7 @@ export function createMemoryCheckpointStore(options = {}) {
             const record = records.get(id);
             if (!record)
                 return false;
-            assertOwnership(input, record);
-            return records.delete(id);
+            return ownershipMatches(input, record) ? records.delete(id) : false;
         },
     };
 }
@@ -121,11 +122,6 @@ function ownershipFilterMatches(expected, actual) {
         (expected.accountId === undefined || expected.accountId === actual.accountId) &&
         (expected.userId === undefined || expected.userId === actual.userId));
 }
-function assertOwnership(expected, actual) {
-    if (!ownershipMatches(expected, actual)) {
-        throw new CheckpointConflictError("Checkpoint ownership mismatch");
-    }
-}
 function cloneJson(value, label) {
     try {
         const encoded = JSON.stringify(value);

package/dist/contracts-core/content.d.ts

@@ -7,10 +7,13 @@ export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 export interface JsonObject {
     readonly [key: string]: JsonValue;
 }
+export type ProviderFailureClass = "quota" | "auth" | "rate_limited" | "transient" | "permanent" | "unknown";
 export interface ErrorInfo {
     readonly name?: string;
     readonly message: string;
     readonly code?: string | number;
+    /** Advisory classification stamped only for provider failures; it never changes retry behavior. */
+    readonly failureClass?: ProviderFailureClass;
     /** Provider backpressure hint (e.g. from a `Retry-After` header); retry policies
      *  honor it capped at their own `maxDelayMs`. */
     readonly retryAfterMs?: number;
@@ -102,6 +105,8 @@ export interface ModelCapabilities {
     readonly output?: readonly string[];
     readonly reasoning?: boolean;
     readonly tools?: boolean;
+    /** Advisory, conformance-derived tool-call behavior. Absent means unknown; it never changes runtime tool validation. */
+    readonly toolCallStrictness?: "strict" | "lenient" | "legacy";
     readonly streaming?: boolean;
     /** Native JSON-schema structured output support for this model. */
     readonly structuredOutput?: boolean | "json_schema";

package/dist/contracts-core/loop.d.ts

@@ -4,6 +4,48 @@ import type { AgentEvent, AgentFinishReason, ProviderTurnResult, ToolResult } fr
 import type { AgentInput } from "../input.js";
 import type { JsonValue, Message, ToolCallContent, Usage } from "./content.js";
 import type { ProviderRequest, StructuredOutputOptions } from "./provider.js";
+/**
+ * Metadata-only view of a run at a provider-turn boundary (plan 084 Task 2). Hosts branch on
+ * counters, never content: tool arguments, prompts, and tool results are not fields.
+ */
+export interface TurnBoundaryContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    /** 1-based index of the provider turn this boundary precedes. */
+    readonly turn: number;
+    /** Provider turns already completed in this run (`turn - 1`; 0 at the first boundary). */
+    readonly turns: number;
+    /** Host tool calls dispatched so far in this run. */
+    readonly toolCalls: number;
+    /** Run-total usage so far, when the provider reported any. */
+    readonly usage?: Usage;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/** Synchronous decision at a turn boundary. `stop` ends the run cleanly; `continue` runs the turn. */
+export type TurnStopDecision = {
+    readonly action: "continue";
+} | {
+    readonly action: "stop";
+    readonly reason: string;
+};
+/**
+ * Host turn policy (plan 084 Task 2). Evaluated before every provider request, at the same
+ * boundary a `checkpointPolicy: "every-turn"` checkpoint is written. Omit it and the run keeps
+ * its exact 0.8.x turn structure (no callback, no reads).
+ */
+export interface TurnPolicyOptions {
+    /**
+     * Clean turn cap. Reaching it stops the run (`stopReason: "turn_limit"`) instead of failing it
+     * with a limit breach. A run overlay may only narrow `limits.maxTurns`; widening throws.
+     */
+    readonly maxTurns?: number;
+    /**
+     * Consulted before every provider request. Returning `stop` ends the run cleanly with
+     * `stopReason: "host_policy"` and a resumable checkpoint (`decision: "continue"` resumes it).
+     * Must be synchronous and must not throw; a throw fails the run with `ERR_PRISM_TURN_POLICY`.
+     */
+    readonly stop?: (context: TurnBoundaryContext) => TurnStopDecision;
+}
 export interface LoopContext {
     readonly sessionId: string;
     readonly runId: string;

package/dist/contracts-core/run-limits.d.ts

@@ -70,6 +70,8 @@ export interface GuardrailContext<S extends GuardrailStage> {
     readonly runId: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** Same-run completed host tool results, available only at the output stage. */
+    readonly toolResults?: S extends "output" ? readonly ToolResult[] : never;
     readonly metadata: Readonly<Record<string, unknown>>;
     readonly signal: AbortSignal;
 }

package/dist/contracts-protocol.d.ts

@@ -1,4 +1,4 @@
-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, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, TurnPolicyOptions, Usage } from "./contracts-core.js";
 import type { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
@@ -125,6 +125,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;
@@ -170,7 +175,8 @@ export interface DelegatedAgentStep {
         readonly label?: string;
     };
 }
-export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal";
+/** 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";
 export type AgentEvent = {
     readonly type: "agent_started";
     readonly sessionId: string;
@@ -180,8 +186,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;
@@ -538,6 +546,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. */

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

@@ -1,5 +1,5 @@
 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 { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.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";
@@ -143,6 +143,17 @@ 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;
     readonly maxStateBytes?: number;
@@ -183,8 +194,13 @@ 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[];
 }
@@ -194,6 +210,8 @@ export interface AgentRunResumeOptions {
     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;
     /**
@@ -207,9 +225,8 @@ export interface AgentRunResumeOptions {
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies (requires `persistSessionState` too). */
     readonly includeSkillBodies?: boolean;
 }
-/** 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;
@@ -251,6 +268,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. */

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/host-composition.d.ts

@@ -24,6 +24,10 @@ export interface HostCompositionOptions {
     readonly workspaceRoot?: string;
     readonly sandboxRoots?: readonly string[];
     readonly credentialRefs?: readonly string[];
+    readonly connectedApps?: {
+        readonly appIds: readonly string[];
+        readonly serverIds: readonly string[];
+    };
     readonly governance?: HostCompositionGovernance;
     readonly redactor?: SecretRedactor;
     /** Explicit opt-in for live network checks; inert by default. */
@@ -38,6 +42,10 @@ export interface HostCompositionReport {
     readonly profile: "personal" | "business";
     readonly effectiveTools: readonly HostCompositionToolReport[];
     readonly credentialReferences: readonly string[];
+    readonly connectedApps?: {
+        readonly appIds: readonly string[];
+        readonly serverIds: readonly string[];
+    };
     readonly ownership: {
         readonly tenantId?: string;
         readonly accountId?: string;
@@ -66,6 +74,11 @@ export interface HostCompositionReport {
         readonly warnings: readonly string[];
     };
 }
+/** Classifies a store by declared kind/durability and constructor name — never reads contents or connection strings (plan 084 Task 4 reuses it for run-bundle snapshots). */
+export declare function describeStorage(store: unknown, checkpoints: unknown): {
+    kind: string;
+    durable: boolean;
+};
 /**
  * Inspects a host composition in an inert, bounded, and secret-redacting manner.
  * Performs zero network calls by default.