@arnilo/prism 0.0.5 → 0.0.7

package/CHANGELOG.md

@@ -5,7 +5,45 @@ 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.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
+
+- Caller-gated model discovery: `listOpenAIModels`, `listKimiModels`, `listZaiModels`, `listOpenRouterModels`, and `listOpenCodeGoModels`. Provider setup remains network-free; hosts explicitly fetch and register current models.
+- Shared `ThinkingLevel` helpers and use-case model bindings. Background compaction and observational-memory jobs can use an explicit provider/model or a supplied session-model fallback.
+- Opt-in sequential artifact-loop tools: `loop: { strategy: "generate-validate-revise", toolCalls: "bounded" }`. Tool rounds use existing authorization/redaction/ledger paths, share `maxToolRounds` across candidates, and fail with `artifact_failed` metadata `{ reason: "tool_round_limit" }` after exhaustion.
+- Checksummed SQLite/PostgreSQL migration histories and catalog-shape verification, bounded JSON Schema compilation LRU, and public `assertFiniteVector` validation.
+
+### Changed
+
+- Provider packages now document and implement current cache, reasoning, streaming, and discovery behavior. OpenAI Responses replay/function-call/SSE argument handling is corrected; Kimi adds optional Moonshot support; Z.AI and OpenCode Go catalogs/routes were refreshed; OpenRouter discovery/reasoning and NeuralWatt thinking controls are hardened. AI SDK remains host-model-owned.
+- Workflow definitions now require a non-empty `revision`; cancellation requires exact ownership and the current workflow definition. All workflow limits have finite hard caps.
+- Coding tools now enforce bounded streamed reads, write/edit inputs, shell wall time, total output, and spill-file lifecycle. Custom coding operation interfaces now receive bounded read/stat/write/edit options and abort signals.
+- Encrypted credential helpers `encryptBytes`, `decryptBytes`, and envelope rotation are asynchronous. Existing credential files must meet restrictive Unix permission requirements. Linux Secret Service/GNOME Keyring byte-array reads are accepted by the keychain store.
+- MCP Streamable HTTP requires HTTPS and explicit `allowedOrigins`; loopback HTTP requires explicit opt-in. Discovery, schemas, results, and response bodies are bounded.
+- Compaction and observational-memory workers now have finite turn/call/transcript/error budgets. A2A streaming uses strict incremental UTF-8 and LF/CRLF SSE parsing.
+- Generated Prism, workflow, and evaluation IDs use cryptographic UUIDs; non-finite embedding vectors now fail before scoring or persistence.
+
+### Security
+
+- Fixed cross-owner workflow cancellation and duplicate active-run overwrite risks.
+- Added fail-closed limits and validation at file, process, credential, MCP, migration, schema, vector, provider-worker, and A2A trust boundaries.
+
+### Upgrade notes
+
+- Finish or deliberately migrate pre-0.0.6 workflow runs/checkpoints before upgrading: their definition hashes lack the required revision.
+- Update workflow definitions with `revision`, cancellation callers with `workflow` plus exact ownership, MCP HTTP configs with `allowedOrigins`, and custom coding/credential integrations for the changed interfaces above.
 
 ## [0.0.5] - 2026-07-16
 

package/dist/agent-loops.d.ts

@@ -6,6 +6,7 @@ export declare function generateValidateReviseLoop(opts: {
     readonly parser?: ArtifactParser<unknown>;
     readonly repairer?: ArtifactRepairer<unknown>;
     readonly maxRevisions?: number;
+    readonly toolCalls?: "disabled" | "bounded";
 }): AgentLoopStrategy;
 export declare function resolveToolConcurrency(options: {
     loop?: AgentLoopStrategy | AgentLoopOptions;

package/dist/agent-loops.js

@@ -1,4 +1,5 @@
 import { inputMessages } from "./input.js";
+import { createId } from "./ids.js";
 function throwIfAborted(signal) {
     if (signal.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
@@ -55,10 +56,8 @@ function defaultRepairer() {
     });
 }
 // ponytail: GenerateValidateReviseLoop reuses LoopContext primitives only —
-// no provider/retry/store/event re-implementation. T is host-defined, Prism
-// never instantiates it. No tools in artifact revisions (roadmap scope is
-// generate→validate→revise; tool coupling deferred). Phase 28 fires
-// artifact_* events at the marked seams (noop here).
+// no provider/retry/store/event re-implementation. Bounded artifact tools use
+// same dispatcher at concurrency one; add parallelism only with ordering need.
 export function generateValidateReviseLoop(opts) {
     const max = opts.maxRevisions ?? 3;
     const repairer = opts.repairer ?? defaultRepairer();
@@ -68,12 +67,14 @@ export function generateValidateReviseLoop(opts) {
             let usage;
             let nextInput = ctx.input;
             let pendingHistory = [];
-            for (let turn = 1; turn <= max + 1; turn += 1) {
+            let toolRounds = 0;
+            let attempts = 0;
+            for (let turn = 1; attempts <= max; turn += 1) {
                 throwIfAborted(ctx.signal);
                 ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
                 const request = await ctx.assemble(nextInput, undefined, turn);
                 throwIfAborted(ctx.signal);
-                const { content, messageId, started, usage: turnUsage } = await ctx.generate(request);
+                const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
                 usage = turnUsage ?? usage;
                 if (pendingHistory.length > 0) {
                     ctx.history.push(...pendingHistory);
@@ -88,10 +89,17 @@ export function generateValidateReviseLoop(opts) {
                     ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });
                 }
                 ctx.emit({ type: "turn_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn });
-                const text = content
-                    .filter((b) => b.type === "text")
-                    .map((b) => b.text)
-                    .join("");
+                if (opts.toolCalls === "bounded" && calls.length > 0) {
+                    if (toolRounds >= ctx.maxToolRounds) {
+                        const result = { ok: false, errors: [{ message: "maximum tool rounds exceeded" }], metadata: { reason: "tool_round_limit" } };
+                        ctx.emit({ type: "artifact_failed", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt: attempts + 1, result });
+                        return usage;
+                    }
+                    toolRounds += 1;
+                    await dispatchToolCallsInOrder(calls, { ...ctx, toolConcurrency: 1 });
+                    nextInput = [];
+                    continue;
+                }
                 const artifactCtx = {
                     sessionId: ctx.sessionId,
                     runId: ctx.runId,
@@ -99,13 +107,17 @@ export function generateValidateReviseLoop(opts) {
                     signal: ctx.signal,
                     metadata: ctx.metadata,
                 };
+                const text = content
+                    .filter((b) => b.type === "text")
+                    .map((b) => b.text)
+                    .join("");
                 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;
-                const attempt = turn;
+                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);
                 ctx.emit({ type: "artifact_validation_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
@@ -113,7 +125,7 @@ export function generateValidateReviseLoop(opts) {
                     ctx.emit({ type: "artifact_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                     return usage;
                 }
-                if (turn > max) {
+                if (attempt > max) {
                     ctx.emit({ type: "artifact_failed", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                     return usage;
                 }
@@ -124,7 +136,6 @@ export function generateValidateReviseLoop(opts) {
                     await ctx.appendMessage(message);
                 pendingHistory = repairMessages;
                 nextInput = repairMessages;
-                continue;
             }
             return usage;
         },
@@ -148,6 +159,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));
@@ -195,13 +207,12 @@ export function resolveLoop(options, config) {
                 parser: loop.parser,
                 repairer: loop.repairer,
                 maxRevisions: loop.maxRevisions,
+                toolCalls: loop.toolCalls,
             });
         }
         throw new Error(`Unknown agent loop strategy: ${strategy}`);
     }
     return loop;
 }
-function randomId(prefix) {
-    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
-}
+const randomId = createId;
 //# sourceMappingURL=agent-loops.js.map

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>;