@arnilo/prism 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [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/dist/agent-loops.js

@@ -159,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));

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