@arnilo/prism 0.0.24 → 0.0.26

package/dist/contracts.d.ts

@@ -508,14 +508,144 @@ export interface SubscribeOptions {
     readonly overflow?: SubscriberOverflowPolicy;
 }
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
-export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval";
+export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
+export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
+export type PendingDecisionKind = "tool_approval" | "elicitation";
+/** Redacted match scope for one pending or sticky decision; never contains raw tool arguments. */
+export interface DecisionScope {
+    readonly toolName?: string;
+    readonly effectKind?: ToolEffectKind;
+    /** Redacted principal reference (tenant/kind/id); never a credential. */
+    readonly identity?: string;
+    /** Bounded argument-value constraints; deep-equal matched per key. */
+    readonly actionConstraints?: Readonly<Record<string, JsonValue>>;
+    /** SHA-256 of canonical JSON arguments; present instead of raw arguments. */
+    readonly argumentsHash?: string;
+}
+/** One redacted, unresolved approval request inside a suspended durable run. */
+export interface PendingDecision {
+    /** Unique within the run; nested runs use supervisor-prefixed ids. */
+    readonly approvalId: string;
+    readonly kind: PendingDecisionKind;
+    readonly toolCallId?: string;
+    readonly scope: DecisionScope;
+    /** Bounded, redacted. */
+    readonly reason: string;
+    /** Typed payload contract for elicitation decisions. */
+    readonly elicitationSchema?: JsonObject;
+    /** Delegation chain, root-first; core-written, never client-supplied. */
+    readonly attribution?: {
+        readonly path: readonly string[];
+    };
+}
 /** Redacted safe-boundary descriptor; never contains tool arguments. */
 export interface AgentRunInterruption {
     readonly kind: AgentRunInterruptionKind;
     readonly reason: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** All unresolved approval requests of this suspension; absent for legacy single approvals. */
+    readonly pendingDecisions?: readonly PendingDecision[];
+}
+/** One host decision applied to one pending approval request. */
+export interface RunDecision {
+    readonly approvalId: string;
+    readonly outcome: ApprovalOutcome;
+    /** Bounded to 2 KiB; redacted. */
+    readonly reason?: string;
+    /** Revalidated (schema, guardrails, policy) before dispatch; produces a new arguments hash. */
+    readonly modifiedArguments?: JsonObject;
+    /** Elicitation payload; validated against the pending decision's elicitationSchema. */
+    readonly elicitation?: JsonObject;
+}
+/** Run-scoped sticky decision; exact scope match, rechecked against policy, dropped at run end. */
+export interface StickyDecision {
+    readonly scope: DecisionScope;
+    readonly outcome: "allow_for_run" | "reject_for_run";
+    readonly reason?: string;
+    readonly decidedAt: string;
+    /** Delegation path when the sticky was created for a nested-run decision. */
+    readonly attribution?: {
+        readonly path: readonly string[];
+    };
+}
+/** Root-visible link between one nested approval and the child-run approval id. */
+export interface NestedRunApproval {
+    /** Root-visible approval id (hashed, non-enumerating across runs). */
+    readonly id: string;
+    /** Approval id as the nested run recorded it. */
+    readonly childApprovalId: string;
+}
+/** Root-visible link between a suspended nested run and the tool call that hosted it. */
+export interface NestedRunRef {
+    readonly runId: string;
+    readonly sessionId?: string;
+    readonly toolCallId: string;
+    /** Redacted delegation path (child ids, root first). */
+    readonly path: readonly string[];
+    readonly approvals: readonly NestedRunApproval[];
+    /** Decisions persisted by a partial batch, keyed by root-visible approval id. */
+    readonly decisions?: Readonly<Record<string, RunDecision>>;
+}
+/** Outcome of resuming a nested run through the host-supplied hook. */
+export type NestedRunOutcome = {
+    readonly status: "suspended";
+    readonly pendingDecisions: readonly PendingDecision[];
+} | {
+    readonly status: "completed";
+    readonly value?: JsonValue;
+} | {
+    readonly status: "failed";
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Host hook that resumes a nested run (supervisor child) with child-visible decisions.
+ * Used both when a nested suspension first surfaces (sticky auto-apply) and when root
+ * decisions route back to the child on resume.
+ */
+export type ResumeNestedRun = (nested: {
+    readonly ref: AgentRunRef;
+    readonly toolCallId: string;
+    readonly path: readonly string[];
+}, decisions: readonly RunDecision[]) => Promise<NestedRunOutcome>;
+/**
+ * Thrown by a delegated-run host (e.g. the supervisor) when a nested run suspends on
+ * pending decisions inside a tool execution. Core converts it into a root suspension
+ * with attributed, root-visible approval ids; the dispatching wrapper attaches `toolCall`.
+ */
+export declare class AgentDelegationSuspendedError extends Error {
+    readonly ref: AgentRunRef;
+    readonly pendingDecisions: readonly PendingDecision[];
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    readonly path?: readonly string[] | undefined;
+    readonly code = "ERR_PRISM_DELEGATION_SUSPENDED";
+    toolCall?: ToolCallContent;
+    constructor(ref: AgentRunRef, pendingDecisions: readonly PendingDecision[], 
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    path?: readonly string[] | undefined);
+}
+/** Shared decision-contract violations. Unknown and foreign approval ids share one non-enumerating error. */
+export declare class AgentDecisionError extends Error {
+    readonly code: "ERR_PRISM_DECISION_STALE" | "ERR_PRISM_DECISION_UNKNOWN" | "ERR_PRISM_DECISION_DUPLICATE" | "ERR_PRISM_DECISION_SCOPE" | "ERR_PRISM_DECISION_INVALID" | "ERR_PRISM_DECISION_LIMIT";
+    constructor(code: "ERR_PRISM_DECISION_STALE" | "ERR_PRISM_DECISION_UNKNOWN" | "ERR_PRISM_DECISION_DUPLICATE" | "ERR_PRISM_DECISION_SCOPE" | "ERR_PRISM_DECISION_INVALID" | "ERR_PRISM_DECISION_LIMIT", message: string, options?: {
+        readonly cause?: unknown;
+    });
 }
+export declare const DEFAULT_MAX_PENDING_DECISIONS = 32;
+export declare const HARD_MAX_PENDING_DECISIONS = 128;
+export declare const DEFAULT_MAX_STICKY_DECISIONS = 64;
+export declare const HARD_MAX_STICKY_DECISIONS = 256;
+export declare const MAX_DECISION_REASON_BYTES: number;
+export declare const HARD_MAX_DECISION_REASON_BYTES: number;
+export declare const MAX_ELICITATION_BYTES: number;
+export declare const HARD_MAX_ELICITATION_BYTES: number;
+export declare const MAX_ACTION_CONSTRAINTS = 32;
+export declare const HARD_MAX_ACTION_CONSTRAINTS = 64;
+/** Maximum delegation attribution depth for surfaced nested pending decisions. */
+export declare const MAX_ATTRIBUTION_DEPTH = 8;
+export declare const MAX_ACTION_CONSTRAINT_BYTES: number;
+export declare const HARD_MAX_ACTION_CONSTRAINT_BYTES: number;
 export interface AgentRunStateOptions {
     readonly checkpoints: CheckpointStore;
     /** Host-authored immutable revision required for durable runs. */
@@ -524,6 +654,8 @@ export interface AgentRunStateOptions {
     readonly interruptBeforeTool?: boolean;
     readonly maxStateBytes?: number;
     readonly fencingToken?: number;
+    /** Enables sticky auto-apply when a nested suspension first surfaces during this run. */
+    readonly resumeNestedRun?: ResumeNestedRun;
 }
 /** Versioned, redacted checkpoint payload. Treat as opaque except status/version/interruption. */
 export interface AgentRunState {
@@ -540,8 +672,11 @@ export interface AgentRunState {
     readonly version?: number;
 }
 export interface AgentRunResume {
-    readonly decision: "approve" | "deny";
     readonly expectedVersion: number;
+    /** Legacy single-approval path; `approve` allows all pending once, `deny` terminates the run denied. */
+    readonly decision?: "approve" | "deny";
+    /** Batch decision path; exactly one of decision/decisions. Applied as one atomic CAS transition. */
+    readonly decisions?: readonly RunDecision[];
 }
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
@@ -549,6 +684,8 @@ export interface AgentRunResumeOptions {
     readonly definitionRevision: string;
     readonly ownership?: OwnershipScope;
     readonly fencingToken?: number;
+    /** Routes root decisions for nested-run approvals back to the child (e.g. supervisor). */
+    readonly resumeNestedRun?: ResumeNestedRun;
 }
 /** Bounded, abortable options for `resumeAgentRunStream()`. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {
@@ -566,6 +703,13 @@ export declare class AgentRunStateError extends Error {
     readonly code = "ERR_PRISM_AGENT_RUN_STATE";
     constructor(message: string);
 }
+/** Durable-loop contract violations: hook-less custom strategy on a durable run, invalid snapshot, or revision drift. */
+export declare class AgentLoopStateError extends Error {
+    readonly code: "ERR_PRISM_LOOP_NOT_DURABLE" | "ERR_PRISM_LOOP_SNAPSHOT" | "ERR_PRISM_LOOP_REVISION";
+    constructor(code: "ERR_PRISM_LOOP_NOT_DURABLE" | "ERR_PRISM_LOOP_SNAPSHOT" | "ERR_PRISM_LOOP_REVISION", message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
 /** Terminal result of `session.run()` / `session.prompt()`. Failed and aborted runs throw {@link AgentRunError} with this shape attached. */
 export interface AgentRunResult {
     readonly sessionId: string;
@@ -847,6 +991,19 @@ export interface ToolEffectDeclaration {
 }
 /** Runs after argument validation. It must be synchronous, deterministic, bounded, and side-effect-free. */
 export type ToolEffectClassifier = (args: JsonObject, context: ToolExecutionContext) => ToolEffectDeclaration;
+/**
+ * Elicitation contract declared by a tool. When a durable gated run suspends on this tool,
+ * the pending decision has kind `elicitation` and carries this schema as its payload contract;
+ * the resume decision's `elicitation` payload resolves the call without executing it.
+ */
+export interface ToolElicitationRequest {
+    /** Typed payload contract; bounded to HARD_MAX_ELICITATION_BYTES when serialized. */
+    readonly schema: JsonObject;
+    /** Human-facing reason (e.g. the question); bounded to MAX_DECISION_REASON_BYTES. */
+    readonly reason?: string;
+    /** Answer-shape validation beyond structural schema checks; throw to reject the payload. */
+    readonly validate?: (payload: JsonObject) => void;
+}
 export interface ToolDefinition {
     readonly name: string;
     readonly description?: string;
@@ -855,6 +1012,8 @@ export interface ToolDefinition {
     readonly exclusive?: boolean;
     /** Optional side-effect declaration. Omitted tools retain legacy unmanaged dispatch. */
     readonly effect?: ToolEffectDeclaration | ToolEffectClassifier;
+    /** Optional elicitation contract for durable gating; return undefined to fall back to plain tool approval. */
+    readonly elicitation?: (args: JsonObject, context: ToolExecutionContext) => ToolElicitationRequest | undefined;
     execute(args: JsonObject, context: ToolExecutionContext): Promise<ToolResult> | ToolResult;
 }
 export interface ToolRegistry {
@@ -2022,8 +2181,13 @@ export interface LoopContext {
     /** Maximum independent tool calls dispatched concurrently per provider turn. Default `1`. */
     readonly toolConcurrency: number;
     assemble(nextInput: AgentInput, toolResults?: readonly ToolResult[], turn?: number): Promise<ProviderRequest>;
-    /** Charges a complete tool round before any call in it can start. */
-    chargeToolRound?(calls: readonly ToolCallContent[]): void;
+    /**
+     * Charges a complete tool round before any call in it can start. On durable interrupt
+     * runs this is also the round-level approval gate: it collects every gated call of the
+     * round into one suspension. Loops must await it; dispatch without it falls back to
+     * per-call single-decision suspensions.
+     */
+    chargeToolRound?(calls: readonly ToolCallContent[]): void | Promise<void>;
     generate(request: ProviderRequest): Promise<ProviderTurnResult>;
     dispatchToolCall(call: ToolCallContent): Promise<ToolResult>;
     isToolCallExclusive?(call: ToolCallContent): boolean;
@@ -2033,10 +2197,23 @@ export interface LoopContext {
     hasPendingSteers?(): boolean;
     /** Drain pending steers into history/session. Returns true when any were applied. */
     applyPendingSteers?(): Promise<boolean>;
+    /** Snapshot captured at the last suspension when the strategy declared snapshot/restore. Present only on resume. */
+    readonly restoredLoopState?: JsonValue;
 }
 export interface AgentLoopStrategy {
     readonly name: string;
+    /** Host-authored loop revision. Joins the durable-run fingerprint when snapshot hooks are present. */
+    readonly revision?: string;
     run(ctx: LoopContext): Promise<Usage | undefined>;
+    /**
+     * Capture loop-local resumable state at suspension. Must return a JSON-compatible value;
+     * core bounds and redacts it inside the durable run-state envelope. Declare together with
+     * `restore`; a custom strategy without both hooks is rejected before any provider call on
+     * durable runs (`AgentLoopStateError` / `ERR_PRISM_LOOP_NOT_DURABLE`).
+     */
+    snapshot?(): JsonValue;
+    /** Rehydrate from a previously captured snapshot; must throw on drift. Called before `run` on resume. */
+    restore?(snapshot: JsonValue): void;
 }
 export type AgentLoopOptions = {
     readonly strategy: "single-shot";

package/dist/contracts.js

@@ -1,3 +1,47 @@
+/**
+ * Thrown by a delegated-run host (e.g. the supervisor) when a nested run suspends on
+ * pending decisions inside a tool execution. Core converts it into a root suspension
+ * with attributed, root-visible approval ids; the dispatching wrapper attaches `toolCall`.
+ */
+export class AgentDelegationSuspendedError extends Error {
+    ref;
+    pendingDecisions;
+    path;
+    code = "ERR_PRISM_DELEGATION_SUSPENDED";
+    toolCall;
+    constructor(ref, pendingDecisions, 
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    path) {
+        super("Delegated run suspended");
+        this.ref = ref;
+        this.pendingDecisions = pendingDecisions;
+        this.path = path;
+        this.name = "AgentDelegationSuspendedError";
+    }
+}
+/** Shared decision-contract violations. Unknown and foreign approval ids share one non-enumerating error. */
+export class AgentDecisionError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AgentDecisionError";
+    }
+}
+export const DEFAULT_MAX_PENDING_DECISIONS = 32;
+export const HARD_MAX_PENDING_DECISIONS = 128;
+export const DEFAULT_MAX_STICKY_DECISIONS = 64;
+export const HARD_MAX_STICKY_DECISIONS = 256;
+export const MAX_DECISION_REASON_BYTES = 2 * 1024;
+export const HARD_MAX_DECISION_REASON_BYTES = 8 * 1024;
+export const MAX_ELICITATION_BYTES = 16 * 1024;
+export const HARD_MAX_ELICITATION_BYTES = 64 * 1024;
+export const MAX_ACTION_CONSTRAINTS = 32;
+export const HARD_MAX_ACTION_CONSTRAINTS = 64;
+/** Maximum delegation attribution depth for surfaced nested pending decisions. */
+export const MAX_ATTRIBUTION_DEPTH = 8;
+export const MAX_ACTION_CONSTRAINT_BYTES = 4 * 1024;
+export const HARD_MAX_ACTION_CONSTRAINT_BYTES = 16 * 1024;
 export class AgentRunStateError extends Error {
     code = "ERR_PRISM_AGENT_RUN_STATE";
     constructor(message) {
@@ -5,6 +49,15 @@ export class AgentRunStateError extends Error {
         this.name = "AgentRunStateError";
     }
 }
+/** Durable-loop contract violations: hook-less custom strategy on a durable run, invalid snapshot, or revision drift. */
+export class AgentLoopStateError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AgentLoopStateError";
+    }
+}
 export class AgentRunError extends Error {
     result;
     constructor(result, options) {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { resolveAgentDefinition } from "./agent-definitions.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop, } from "./agent-loops.js";
 export type { AgentRunLifecycle, AgentRunLifecycleAgent, AgentRunLifecycleOptions, AgentRunLifecycleRequest, AgentRunLifecycleStreamRequest, } from "./agent-run-lifecycle.js";
 export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
-export type { StoredAgentRunState } from "./agent-run-state.js";
+export type { PendingToolCall, StoredAgentRunState } from "./agent-run-state.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export type { ArtifactApproval, ArtifactApprovalState, ArtifactCitation, ArtifactDecisionState, ArtifactDeliveryToken, ArtifactRecord, ArtifactRevision, } from "./artifacts.js";
@@ -20,8 +20,8 @@ export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMe
 export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission, ContextBudgetOmissionKind, ContextBudgetReport, } from "./context-budget.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
 export type * from "./contracts.js";
-export type { ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, } from "./contracts.js";
-export { AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export type { ApprovalOutcome, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, ResumeNestedRun, RunDecision, StickyDecision, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, MAX_ATTRIBUTION_DEPTH, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, HARD_MAX_STICKY_DECISIONS, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions, } from "./contributions.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
@@ -105,5 +105,5 @@ export type { ToolEffectErrorCode } from "./tool-effects.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.0.24";
+export declare const version = "0.0.26";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -10,7 +10,7 @@ export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compac
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
-export { AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, MAX_ATTRIBUTION_DEPTH, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, HARD_MAX_STICKY_DECISIONS, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
@@ -57,6 +57,6 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export { createMemoryToolEffectStore, ToolEffectError } from "./tool-effects.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.0.24";
+export const version = "0.0.26";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolEffectStore, ToolRegistry, ToolResult } from "./contracts.js";
+import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolEffectDeclaration, ToolEffectStore, ToolRegistry, ToolResult } from "./contracts.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import { type SecretRedactor } from "./redaction.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
@@ -57,3 +57,4 @@ export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
 export declare function createToolRegistry(tools?: readonly ToolDefinition[], options?: ToolRegistryOptions): ToolRegistry;
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 export declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>;
+export declare function resolveToolEffectDeclaration(tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext): ToolEffectDeclaration | undefined;

package/dist/tools.js

@@ -153,7 +153,8 @@ export async function dispatchToolCall(options) {
     }
     catch (error) {
         await failBeforeEffect(effect, isSuspended(error) ? "failed_retryable" : "failed_terminal");
-        if (isSuspended(error))
+        // Loop-state contract errors (snapshot capture) are terminal run errors, not tool errors.
+        if (isSuspended(error) || isLoopStateError(error) || isDelegationSuspended(error))
             throw error;
         return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
     }
@@ -222,6 +223,14 @@ export async function dispatchToolCall(options) {
     catch (error) {
         if (completedResult)
             return completedResult;
+        // Nested-run suspensions must propagate to the run loop, never become tool errors.
+        if (isDelegationSuspended(error)) {
+            if (effect && (effect.dispatched || dispatchAttempted))
+                await unknownEffectResult(effect, mediatedCall);
+            else
+                await failBeforeEffect(effect, "failed_retryable");
+            throw error;
+        }
         if (effect && (effect.dispatched || dispatchAttempted))
             return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
         await failBeforeEffect(effect, "failed_terminal");
@@ -298,7 +307,7 @@ async function prepareToolEffect(tool, call, context, options) {
         },
     };
 }
-function resolveToolEffectDeclaration(tool, args, context) {
+export function resolveToolEffectDeclaration(tool, args, context) {
     const classifierContext = Object.freeze({
         sessionId: context.sessionId,
         runId: context.runId,
@@ -389,6 +398,12 @@ function effectErrorResult(call, code, message) {
 function isSuspended(error) {
     return error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED";
 }
+function isLoopStateError(error) {
+    return typeof error?.code === "string" && error.code.startsWith("ERR_PRISM_LOOP_");
+}
+function isDelegationSuspended(error) {
+    return error?.code === "ERR_PRISM_DELEGATION_SUSPENDED";
+}
 async function checkCall(call, options, startedAt) {
     const context = options.context;
     const tool = options.registry.get(call.name);

package/docs/0.1.0-readiness.md

@@ -1,12 +1,12 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.0.24** is the current release line (Phase 7 distributed events and recoverable tool effects); **1.0** readiness remains operator-gated, not automatic.
+Status: **0.0.26** is the current release line (Phase 9 coding intelligence, managed processes, forge, and safe egress); **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table. The
 **Last evidence** column records the 2026-07-26 **0.0.16** baseline snapshot
 (Phase 11, Node v24.18.0, Linux x86_64). Treat it as historical floor evidence,
 not the current release tag. Re-run each gate on the target release tree before
-cutting 0.0.24 / 1.0. The decision to cut 1.0 stays with the operator after
+cutting 0.0.26 / 1.0. The decision to cut 1.0 stays with the operator after
 operator-gated legs run in a protected environment and Phase 12 demand evidence
 exists.
 
@@ -14,15 +14,16 @@ Evidence trail: [`docs/review-coverage-2026-07-26-phase-11.md`](./review-coverag
 (addenda 0–9), [`docs/release-and-install.md`](./release-and-install.md),
 [`docs/migration.md`](./migration.md), [`docs/performance.md`](./performance.md).
 
-## Current line (0.0.24)
+## Current line (0.0.26)
 
 | Item | Status |
 |---|---|
-| Published graph | **47** publishable manifests at **0.0.24** (`docs/release-and-install.md`) |
-| Phase 7 distributed events/effects | `AgentEventSource`, `ToolEffectStore`, AG-UI MCP/A2A fronting; enterprise `toolEffects`; schema v6/v7 + enterprise migration 002 |
-| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.23 → 0.0.24 distributed events and recoverable tool effects` |
-| Protected database evidence | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; `benchmark-0.0.24.json` under Task 0 ceilings |
-| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.24 database evidence is recorded separately |
+| Published graph | **48** publishable manifests at **0.0.26** (`docs/release-and-install.md`) |
+| Phase 9 coding intelligence / processes / forge / egress | Git-aware enumeration, LSP language intelligence, managed process sessions, GitHub forge with idempotent handoff, allow-list egress proxy with rebinding defense |
+| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.25 → 0.0.26 coding intelligence, processes, forge, and egress` |
+| Network-free Phase 9 evidence | `scripts/phase9-conformance.test.mjs`; `benchmark-0.0.26.json` under Task 0 ceilings |
+| Protected database evidence (Phase 7) | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; `benchmark-0.0.24.json` under prior ceilings |
+| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.26 Phase 9 evidence is recorded separately |
 
 ## Gate table
 

package/docs/a2a.md

@@ -39,6 +39,30 @@ const handler = createA2AHandler({
 
 Parts, messages, artifacts, histories, metadata, and aggregate responses are untrusted. Rich content remains in A2A task/message/artifact contracts for host mapping; it is never promoted to system instructions or automatically loaded as a Prism resource.
 
+## AG-UI server-side exposure (Task 13, 0.0.26)
+
+`createAgUiA2AServer()` in `@arnilo/prism-ag-ui` fronts one host-selected **local AG-UI agent** as an A2A 1.0 server, the reverse direction of `createAgUiA2AAdapter()`: remote A2A clients start and stream local runs through the same AG-UI input allow-list and event mapper as the AG-UI SSE path (same projection, redaction, and byte caps). It reuses this package's `createA2AHandler` transport/lifecycle; it creates no second runtime, task store, or worker. Requires the optional `@arnilo/prism-supervisor` peer (imported lazily; plain `@arnilo/prism-ag-ui` imports keep working without it).
+
+```ts
+import { createAgentEventSourceAgUiReplay, createAgUiA2AServer } from "@arnilo/prism-ag-ui";
+
+const server = await createAgUiA2AServer({
+  card: agentCard,                                   // A2A agent card (streaming: true)
+  authorize: (input) => authorizeA2A(input),         // A2A auth → { ownership } (also the AG-UI authorization)
+  sessionFactory: ({ threadId, authorization, signal, input }) =>
+    createAgUiSession(authorization, input),         // same shape as createAgUiHandler
+  input: { project: projectAgUiInput },              // AG-UI full-input allow-list
+  projection, redactor, a2ui, limits,                // AG-UI mapper options
+  durable: {                                         // optional: GetTask/SubscribeToTask after a run finishes
+    source: persistence.events,                      // durable AgentEventSource
+    resolveTask: async ({ id, authorization }) => ({ task, run }), // host-owned task→run correlation
+  },
+});
+// host mounts: new Request(url, init) → server(request)
+```
+
+Semantics: `SendMessage` runs the local agent to completion and returns a terminal task with collected text artifacts; `SendStreamingMessage` (client `returnImmediately: true`) streams text/activity/state as bounded A2A artifact updates, then a terminal task. `agent_suspended` closes the stream with `TASK_STATE_INPUT_REQUIRED`; continuation stays host-owned (AG-UI resume). `GetTask`/`ListTasks`/`CancelTask` cover a bounded in-memory registry of tasks started on this instance; with `durable`, `SubscribeToTask`/`GetTask` also resolve host-correlated runs and replay the durable source with cursor event ids (at-least-once; clients dedupe by `eventId`). Text parts become the AG-UI user message; raw/data/url parts stay disabled unless `parts` selects them, and then arrive only in `forwardedProps.a2a` for `input.project`. Task ids default to `task-<uuid>`; hosts may own them via `selectTaskId`. `tasks` may be supplied to replace the built-in lifecycle entirely. A2A remains separately mounted — no route is added to `createPrismHandler()`.
+
 ## Implementation example
 
 ```ts

package/docs/ag-ui-adoption.md

@@ -7,7 +7,7 @@ This page records Prism's compatibility review against official AG-UI `@ag-ui/co
 Official material reviewed:
 
 - [Events](https://docs.ag-ui.com/concepts/events), [messages](https://docs.ag-ui.com/concepts/messages), [tools](https://docs.ag-ui.com/concepts/tools), [state](https://docs.ag-ui.com/concepts/state), [reasoning](https://docs.ag-ui.com/concepts/reasoning), [interrupts](https://docs.ag-ui.com/concepts/interrupts), [capabilities](https://docs.ag-ui.com/concepts/capabilities), [serialization](https://docs.ag-ui.com/concepts/serialization), [server quickstart](https://docs.ag-ui.com/quickstart/server), and [protocol architecture](https://docs.ag-ui.com/concepts/architecture).
-- Official [MCP/A2A/AG-UI relationship](https://docs.ag-ui.com/agentic-protocols), [integrations](https://docs.ag-ui.com/integrations), [`@ag-ui/mcp-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-middleware), [`@ag-ui/mcp-apps-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-apps-middleware), [`@ag-ui/a2a`](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/a2a/typescript), and [`@ag-ui/a2a-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2a-middleware).
+- Official [MCP/A2A/AG-UI relationship](https://docs.ag-ui.com/agentic-protocols), [integrations](https://docs.ag-ui.com/integrations), [`@ag-ui/mcp-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-middleware), [`@ag-ui/mcp-apps-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-apps-middleware), [`@ag-ui/a2ui-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2ui-middleware) (Prism ships an in-package opt-in painter with frozen caps; no runtime dependency), [`@ag-ui/a2a`](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/a2a/typescript), and [`@ag-ui/a2a-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2a-middleware).
 - A2A [current specification](https://a2a-protocol.org/latest/specification/) and [streaming rules](https://a2a-protocol.org/latest/topics/streaming-and-async/).
 - MCP Apps [SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp) and the [`io.modelcontextprotocol/ui` draft specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx).