@arnilo/prism 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+## [0.0.8] - 2026-07-20
+
+### Added
+
+- Added OpenTelemetry GenAI agent/provider/tool hierarchy, context propagation, delegation/guardrail spans, bounded trace references, and evaluation linkage.
+- Added bounded evaluation trace resolution, host model judges, deterministic pairwise reports, serialized artifacts, and CI threshold assertions.
+- Added MCP resources/prompts/roots/sampling/elicitation plus principal-bound Streamable HTTP sessions on pinned SDK 1.29.0, and full A2A 1.0 durable task/rich-part/reconnect/push interoperability.
+- Added immutable-revision CodeQL/dependency/SBOM/license/secret/attestation release gates, weekly dependency updates, and protected bounded provider/MCP/A2A/web live canaries.
+- Added optional `@arnilo/prism-web-tools` with bounded host-selected Brave/Exa search, Firecrawl Markdown/schema extraction, stable citations, late credentials, and explicit untrusted-content results.
+- Added optional `createBatchedRunLedger()` with bounded FIFO/backpressure, explicit durability/flush status, terminal acknowledgement, and documented buffered crash-loss semantics.
+- Added one-leaf, one-second runtime session snapshot caching with mutation/checkout/resume invalidation and reproducible network-free 0.0.8 performance evidence.
+- Versioned all 31 first-party manifests and exact internal ranges to 0.0.8; no tag or publication was created.
+
+### Fixed
+
+- `generateValidateReviseLoop` routes artifact parse failures through the revision budget (`metadata.reason: "parse_error"`, repairer receives `value: undefined`) instead of returning silently after one provider turn.
+- `@arnilo/prism-provider-opencode-go` Anthropic route sends provider-owned `x-api-key` and `anthropic-version: 2023-06-01` headers alongside Bearer, fixing HTTP 401 on MiniMax/Qwen models; `structuredOutput: "json_schema"` is no longer inferred from OpenAI routing alone (verified models only), fixing HTTP 400 on `deepseek-v4-pro`; both stream parsers require protocol completion evidence and fail truncated streams with a terminal `error` instead of a false `done`.
+- `@arnilo/prism-provider-kimi` aligns with official contracts: featured Coding `k3` defaults `reasoning_effort: "high"`, 256K-class context windows use the exact `262_144`, the featured Moonshot catalog adds `kimi-k2.7-code-highspeed`/`kimi-k2.6`/`kimi-k2.5`, routing keys (`route`, `preserve_thinking`) no longer leak into wire bodies, the Coding route sends provider-owned `x-api-key`/`anthropic-version` headers, and both stream parsers fail truncated streams instead of emitting `done`.
+
+## [0.0.7] - 2026-07-19
+
+### Added
+
+- Typed `Guardrails` for input, provider output, tool input, and tool output. Guardrail decisions are bounded/redacted `guardrail_decision` events; provider output is buffered before exposure when output checks are configured.
+- Workflow tool nodes and MCP server tool registrations now route optional tool guardrails through shared `dispatchToolCall()`.
+- `RunLimits` adds validated, narrowing-only budgets for turns, provider attempts, tool rounds/calls, wall time, request/response bytes, token usage, and optional single-currency cost. Breaches emit one `run_limit_exceeded` event and return `AgentRunError.result.limit`.
+- Opt-in durable built-in agent runs can suspend before a tool side effect and resume through versioned, bounded, redacted checkpoint state with CAS approval, ownership/fingerprint checks, and no automatic replay of an ambiguous dispatched tool.
+- `createSecureAgent()` composes strict tool schemas/validation, trust and permission gates, redaction, finite limits, exact ownership, and durable pre-tool approval without changing low-level `createAgent()` defaults.
+- `createAgentRunLifecycle()` adds explicit, ownership-scoped durable agent status/resume capability for selected server and MCP exposures; no lifecycle route/tool is enabled by default.
+
 ## [0.0.6] - 2026-07-19
 
 ### Added

package/README.md

@@ -53,6 +53,7 @@ npm install @arnilo/prism-sdk @arnilo/prism-provider-openai  # application profi
 npm install @arnilo/prism-all                               # every first-party package
 npm install @arnilo/prism-server @arnilo/prism-workflows    # optional Web API boundary
 npm install @arnilo/prism-supervisor                         # optional local delegation + A2A 1.0
+npm install @arnilo/prism-web-tools                          # optional bounded Brave/Exa/Firecrawl research
 ```
 
 See [docs/release-and-install.md](docs/release-and-install.md) for install
@@ -157,6 +158,7 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-mcp` | MCP client/tool bridge |
 | `@arnilo/prism-workflows` | bounded DAG workflows, durable suspend/resume, schedules/background runs, composition/state/replay, and multi-process coordination |
 | `@arnilo/prism-supervisor` | bounded local child delegation and A2A 1.0 interoperability |
+| `@arnilo/prism-web-tools` | host-selected bounded Brave/Exa search and Firecrawl Markdown/schema extraction |
 | `@arnilo/prism-observability-opentelemetry` | optional OpenTelemetry adapter |
 | `@arnilo/prism-credentials-node` | encrypted-file and keychain credentials |
 | `@arnilo/prism-session-store-sqlite` | SQLite persistence/checkpoints/leases/owned run feedback |
@@ -166,7 +168,7 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-base` | profile: core + compaction + JSON Schema validation |
 | `@arnilo/prism-code` | profile: base + coding tools/security + MCP |
 | `@arnilo/prism-sdk` | profile: base + workflows + MCP + credentials + OpenTelemetry |
-| `@arnilo/prism-all` | every first-party package, including both persistence adapters |
+| `@arnilo/prism-all` | every first-party package, including both persistence adapters and web tools |
 
 ## Scripts
 

package/dist/agent-loops.js

@@ -114,12 +114,14 @@ export function generateValidateReviseLoop(opts) {
                 const parsed = opts.parser
                     ? await opts.parser(text, artifactCtx)
                     : { ok: true, value: text };
-                // Parse failure ends the loop silently (terminal parse errors stay on `error`).
-                if (!parsed.ok || parsed.value === undefined)
-                    return usage;
+                // Parse failure consumes revision budget like a validation failure; the
+                // repairer receives `undefined` value plus a synthetic parse issue.
+                const parseFailure = !parsed.ok || parsed.value === undefined
+                    ? { ok: false, errors: [{ path: "$", message: parsed.error ?? "artifact parse failed" }], metadata: { reason: "parse_error" } }
+                    : undefined;
                 const attempt = ++attempts;
                 ctx.emit({ type: "artifact_validation_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt });
-                const result = await opts.validator(parsed.value, artifactCtx);
+                const result = parseFailure ?? await opts.validator(parsed.value, artifactCtx);
                 ctx.emit({ type: "artifact_validation_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                 if (result.ok) {
                     ctx.emit({ type: "artifact_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
@@ -130,7 +132,7 @@ export function generateValidateReviseLoop(opts) {
                     return usage;
                 }
                 ctx.emit({ type: "artifact_revision_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, failure: result });
-                const repair = await repairer(parsed.value, result, artifactCtx);
+                const repair = await repairer(parseFailure ? undefined : parsed.value, result, artifactCtx);
                 const repairMessages = inputMessages(repair).map((m) => ({ ...m, id: randomId("msg") }));
                 for (const message of repairMessages)
                     await ctx.appendMessage(message);
@@ -159,6 +161,7 @@ export function resolveToolConcurrency(options, config) {
 export async function dispatchToolCallsInOrder(calls, ctx) {
     if (calls.length === 0)
         return;
+    ctx.chargeToolRound?.(calls);
     const concurrency = calls.some((call) => ctx.isToolCallExclusive?.(call))
         ? 1
         : Math.max(1, Math.min(ctx.toolConcurrency, calls.length));

package/dist/agent-run-lifecycle.d.ts

@@ -0,0 +1,28 @@
+import type { Agent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunStatusResult, OwnershipScope } from "./contracts.js";
+import type { CheckpointStore } from "./contracts.js";
+export interface AgentRunLifecycleAgent {
+    readonly agent: Agent;
+    /** Current host-authored revision; it must match the stored revision. */
+    readonly definitionRevision: string;
+}
+export interface AgentRunLifecycleOptions {
+    readonly checkpoints: CheckpointStore;
+    readonly resolveAgent: (input: {
+        readonly agentId: string;
+        readonly ownership?: OwnershipScope;
+        readonly signal?: AbortSignal;
+    }) => AgentRunLifecycleAgent | Promise<AgentRunLifecycleAgent>;
+    readonly fencingToken?: number;
+}
+export interface AgentRunLifecycleRequest {
+    readonly ownership?: OwnershipScope;
+    readonly signal?: AbortSignal;
+    /** Adapter-selected capability; stored runs for another agent are non-enumerable. */
+    readonly agentId?: string;
+}
+export interface AgentRunLifecycle {
+    status(ref: AgentRunRef, options?: AgentRunLifecycleRequest): Promise<AgentRunStatusResult>;
+    resume(ref: AgentRunRef, resume: AgentRunResume, options?: AgentRunLifecycleRequest): Promise<AgentRunResult>;
+}
+/** Host capability for durable agent status/resume. Adapters supply authorized ownership only. */
+export declare function createAgentRunLifecycle(options: AgentRunLifecycleOptions): AgentRunLifecycle;

package/dist/agent-run-lifecycle.js

@@ -0,0 +1,33 @@
+import { AgentRunStateError } from "./contracts.js";
+import { loadAgentRunState, publicState } from "./agent-run-state.js";
+import { resumeAgentRun } from "./agents.js";
+function assertAgentId(actual, expected) {
+    if (expected !== undefined && actual !== expected)
+        throw new AgentRunStateError("Agent run capability mismatch");
+}
+/** Host capability for durable agent status/resume. Adapters supply authorized ownership only. */
+export function createAgentRunLifecycle(options) {
+    return {
+        async status(ref, request = {}) {
+            request.signal?.throwIfAborted();
+            const { state, record } = await loadAgentRunState(options.checkpoints, ref, request.ownership);
+            assertAgentId(state.agentId, request.agentId);
+            request.signal?.throwIfAborted();
+            return { state: publicState({ ...state, version: record.version }), version: record.version };
+        },
+        async resume(ref, resume, request = {}) {
+            request.signal?.throwIfAborted();
+            const { state } = await loadAgentRunState(options.checkpoints, ref, request.ownership);
+            assertAgentId(state.agentId, request.agentId);
+            const resolved = await options.resolveAgent({ agentId: state.agentId, ownership: request.ownership, signal: request.signal });
+            request.signal?.throwIfAborted();
+            return resumeAgentRun(resolved.agent, ref, resume, {
+                checkpoints: options.checkpoints,
+                ownership: request.ownership,
+                fencingToken: options.fencingToken,
+                definitionRevision: resolved.definitionRevision,
+            });
+        },
+    };
+}
+//# sourceMappingURL=agent-run-lifecycle.js.map

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

@@ -0,0 +1,53 @@
+import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, AgentRunStatusResult, CheckpointRecord, CheckpointStore, Message, ModelConfig, OwnershipScope, RunLimitCounters, ToolCallContent } from "./contracts.js";
+import type { SecretRedactor } from "./redaction.js";
+export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
+export declare const AGENT_RUN_STATE_SCHEMA_VERSION: 1;
+export declare const DEFAULT_MAX_AGENT_RUN_STATE_BYTES: number;
+export declare const HARD_MAX_AGENT_RUN_STATE_BYTES: number;
+export interface StoredAgentRunState extends AgentRunState {
+    readonly input?: readonly Message[];
+    readonly pending?: {
+        readonly call: ToolCallContent;
+        readonly status: "ready" | "dispatched";
+    };
+    readonly interruptBeforeTool?: boolean;
+    readonly counters: RunLimitCounters;
+    readonly deadlineAt: string;
+}
+export declare function agentFingerprint(agent: Agent, revision: string): string;
+export declare function agentId(agent: Agent): string;
+export declare function validateRunStateOptions(options: AgentRunStateOptions): void;
+export declare function loadAgentRunState(checkpoints: CheckpointStore, ref: AgentRunRef, ownership?: OwnershipScope): Promise<{
+    readonly record: CheckpointRecord;
+    readonly state: StoredAgentRunState;
+}>;
+export declare function saveAgentRunState(input: {
+    readonly checkpoints: CheckpointStore;
+    readonly state: StoredAgentRunState;
+    readonly expectedVersion: number;
+    readonly ownership?: OwnershipScope;
+    readonly fencingToken?: number;
+    readonly redactor?: SecretRedactor;
+    readonly maxStateBytes?: number;
+}): Promise<{
+    readonly record: CheckpointRecord;
+    readonly state: StoredAgentRunState;
+}>;
+export declare function statusFromState(state: StoredAgentRunState, version: number): AgentRunStatusResult;
+export declare function publicState(state: StoredAgentRunState): AgentRunState;
+export declare function initialAgentRunState(input: {
+    readonly agent: Agent;
+    readonly options: AgentRunStateOptions;
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly leafId?: string;
+    readonly model: ModelConfig;
+    readonly counters: RunLimitCounters;
+    readonly deadlineAt: string;
+    readonly status: "suspended" | "running";
+    readonly interruption?: AgentRunInterruption;
+    readonly messages?: readonly Message[];
+    readonly pending?: StoredAgentRunState["pending"];
+    readonly interruptBeforeTool?: boolean;
+}): StoredAgentRunState;
+export declare function parseAgentRunState(value: unknown, version?: number): StoredAgentRunState;

package/dist/agent-run-state.js

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import { AgentRunStateError } from "./contracts.js";
+export const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
+export const AGENT_RUN_STATE_SCHEMA_VERSION = 1;
+export const DEFAULT_MAX_AGENT_RUN_STATE_BYTES = 256 * 1024;
+export const HARD_MAX_AGENT_RUN_STATE_BYTES = 1024 * 1024;
+const MAX_DEPTH = 32;
+const MAX_PROPERTIES = 256;
+export function agentFingerprint(agent, revision) {
+    const config = agent.config;
+    const tools = !config.tools ? [] : "list" in config.tools ? config.tools.list() : config.tools;
+    const guardrails = [
+        ...(config.guardrails?.input ?? []),
+        ...(config.guardrails?.output ?? []),
+        ...(config.guardrails?.toolInput ?? []),
+        ...(config.guardrails?.toolOutput ?? []),
+    ];
+    const value = JSON.stringify({
+        id: config.id ?? config.name ?? "agent",
+        revision,
+        model: config.model,
+        tools: tools.map((tool) => ({ name: tool.name, parameters: tool.parameters, exclusive: tool.exclusive })),
+        guardrails: guardrails.map((guardrail) => ({ name: guardrail.name, stage: guardrail.stage, revision: guardrail.revision })),
+        loop: typeof config.loop === "object" && config.loop && "strategy" in config.loop ? config.loop.strategy : config.loop?.name ?? "single-shot",
+    });
+    return createHash("sha256").update(value).digest("hex");
+}
+export function agentId(agent) {
+    const id = agent.config.id ?? agent.config.name;
+    if (!id?.trim())
+        throw new AgentRunStateError("Durable agent runs require AgentConfig.id or name");
+    return id;
+}
+export function validateRunStateOptions(options) {
+    if (!options.definitionRevision.trim())
+        throw new AgentRunStateError("Durable agent runs require definitionRevision");
+    const bytes = options.maxStateBytes ?? DEFAULT_MAX_AGENT_RUN_STATE_BYTES;
+    if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > HARD_MAX_AGENT_RUN_STATE_BYTES) {
+        throw new AgentRunStateError(`maxStateBytes must be a positive safe integer at most ${HARD_MAX_AGENT_RUN_STATE_BYTES}`);
+    }
+}
+export async function loadAgentRunState(checkpoints, ref, ownership) {
+    const record = await checkpoints.loadCheckpoint({ namespace: AGENT_RUN_STATE_NAMESPACE, key: ref.runId, ...ownership });
+    if (!record)
+        throw new AgentRunStateError(`No durable agent run ${ref.runId}`);
+    if (ref.sessionId && record.value && typeof record.value === "object" && record.value.sessionId !== ref.sessionId) {
+        throw new AgentRunStateError("Agent run session mismatch");
+    }
+    return { record, state: parseAgentRunState(record.value, record.version) };
+}
+export async function saveAgentRunState(input) {
+    const bounded = boundState(input.redactor?.redact(input.state) ?? input.state, input.maxStateBytes ?? DEFAULT_MAX_AGENT_RUN_STATE_BYTES);
+    const record = await input.checkpoints.saveCheckpoint({
+        namespace: AGENT_RUN_STATE_NAMESPACE,
+        key: bounded.runId,
+        version: input.expectedVersion + 1,
+        expectedVersion: input.expectedVersion,
+        fencingToken: input.fencingToken,
+        value: bounded,
+        category: "agent-run",
+        ...input.ownership,
+    });
+    return { record, state: { ...bounded, version: record.version } };
+}
+export function statusFromState(state, version) {
+    return { state: publicState({ ...state, version }), version };
+}
+export function publicState(state) {
+    const { input: _input, pending: _pending, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, ...publicValue } = state;
+    return publicValue;
+}
+export function initialAgentRunState(input) {
+    validateRunStateOptions(input.options);
+    return {
+        schemaVersion: AGENT_RUN_STATE_SCHEMA_VERSION,
+        agentId: agentId(input.agent),
+        definitionRevision: input.options.definitionRevision,
+        fingerprint: agentFingerprint(input.agent, input.options.definitionRevision),
+        runId: input.runId,
+        sessionId: input.sessionId,
+        ...(input.leafId ? { leafId: input.leafId } : {}),
+        model: input.model,
+        status: input.status,
+        interruption: input.interruption,
+        input: input.messages,
+        pending: input.pending,
+        interruptBeforeTool: input.interruptBeforeTool,
+        counters: input.counters,
+        deadlineAt: input.deadlineAt,
+    };
+}
+export function parseAgentRunState(value, version) {
+    if (!value || typeof value !== "object")
+        throw new AgentRunStateError("Agent run state must be an object");
+    const state = value;
+    if (state.schemaVersion !== AGENT_RUN_STATE_SCHEMA_VERSION)
+        throw new AgentRunStateError(`Unsupported agent run state schemaVersion ${String(state.schemaVersion)}`);
+    if (!state.agentId || !state.definitionRevision || !state.fingerprint || !state.runId || !state.sessionId || !state.model || !state.status || !state.counters || !state.deadlineAt) {
+        throw new AgentRunStateError("Malformed agent run state");
+    }
+    return boundState({ ...state, version }, DEFAULT_MAX_AGENT_RUN_STATE_BYTES);
+}
+function boundState(state, maxBytes) {
+    checkShape(state, 0);
+    let text;
+    try {
+        text = JSON.stringify(state);
+    }
+    catch {
+        throw new AgentRunStateError("Agent run state must be JSON serializable");
+    }
+    if (Buffer.byteLength(text) > maxBytes)
+        throw new AgentRunStateError(`Agent run state exceeds ${maxBytes} bytes`);
+    return JSON.parse(text);
+}
+function checkShape(value, depth) {
+    if (depth > MAX_DEPTH)
+        throw new AgentRunStateError(`Agent run state exceeds depth ${MAX_DEPTH}`);
+    if (!value || typeof value !== "object")
+        return;
+    const entries = Array.isArray(value) ? value : Object.values(value);
+    if (!Array.isArray(value) && entries.length > MAX_PROPERTIES)
+        throw new AgentRunStateError(`Agent run state exceeds ${MAX_PROPERTIES} properties`);
+    for (const item of entries)
+        checkShape(item, depth + 1);
+}
+//# sourceMappingURL=agent-run-state.js.map

package/dist/agents.d.ts

@@ -1,5 +1,7 @@
-import type { Agent, AgentConfig, AgentSession, AgentSessionConfig } from "./contracts.js";
+import type { Agent, AgentConfig, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunRef, AgentSession, AgentSessionConfig } from "./contracts.js";
 export declare function createAgent(config: AgentConfig): Agent;
 export declare function createAgentSession(config: AgentSessionConfig & {
     readonly agent: Agent;
 }): AgentSession;
+/** Resume a persisted built-in run. A claimed/dispatched tool is never replayed automatically. */
+export declare function resumeAgentRun(agent: Agent, ref: AgentRunRef, resume: AgentRunResume, options: AgentRunResumeOptions): Promise<AgentRunResult>;