@arnilo/prism 0.0.3 → 0.0.5

package/dist/contracts.d.ts

@@ -5,6 +5,7 @@ import type { SecretRedactor } from "./redaction.js";
 import type { PermissionPolicy } from "./security.js";
 import type { ManifestContributionDeclaration } from "./manifests.js";
 import type { ToolValidator } from "./tools.js";
+import type { AudioContent, DocumentContent, FileContent } from "./content.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 export interface JsonObject {
@@ -16,7 +17,8 @@ export interface ErrorInfo {
     readonly code?: string | number;
     readonly cause?: unknown;
 }
-export type ContentBlock = TextContent | ImageContent | ThinkingContent | ToolCallDeltaContent | ToolCallContent | ToolResultContent;
+export type { AudioContent, DocumentContent, FileContent } from "./content.js";
+export type ContentBlock = TextContent | ImageContent | AudioContent | FileContent | DocumentContent | ThinkingContent | ToolCallDeltaContent | ToolCallContent | ToolResultContent;
 export interface TextContent {
     readonly type: "text";
     readonly text: string;
@@ -26,6 +28,9 @@ export interface ImageContent {
     readonly mimeType?: string;
     readonly data?: string;
     readonly url?: string;
+    readonly resourceUri?: string;
+    readonly name?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface ThinkingContent {
     readonly type: "thinking";
@@ -71,11 +76,14 @@ export interface ModelConfig {
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface ModelCapabilities {
+    /** Known values include `text`, `image`, `audio`, `file`, and `document`. */
     readonly input?: readonly string[];
     readonly output?: readonly string[];
     readonly reasoning?: boolean;
     readonly tools?: boolean;
     readonly streaming?: boolean;
+    /** Native JSON-schema structured output support for this model. */
+    readonly structuredOutput?: boolean | "json_schema";
 }
 export interface ModelLimits {
     readonly contextWindow?: number;
@@ -121,6 +129,11 @@ export interface PromptCacheHints {
     readonly retention?: CacheRetention;
     readonly breakpoints?: readonly PromptCacheBreakpoint[];
 }
+export interface StructuredOutputOptions {
+    readonly name: string;
+    readonly schema: JsonObject;
+    readonly strict?: boolean;
+}
 export interface ProviderRequestOptions {
     readonly sessionId?: string;
     readonly cacheRetention?: CacheRetention;
@@ -135,6 +148,8 @@ export interface ProviderRequestOptions {
     readonly maxRetryDelayMs?: number;
     readonly compat?: JsonObject;
     readonly extra?: JsonObject;
+    /** Provider-neutral JSON-schema structured output request. Requires model `capabilities.structuredOutput`. */
+    readonly structuredOutput?: StructuredOutputOptions;
 }
 export interface ProviderRequest {
     readonly model: ModelConfig;
@@ -241,13 +256,7 @@ export interface AgentConfig {
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
     readonly resourceLoader?: ResourceLoader;
-    /** Host-owned metadata only: createAgent/session.run do not load or run these extensions. */
-    readonly extensions?: readonly Extension[];
     readonly store?: SessionStore;
-    /** Host-owned metadata only: createAgent/session.run do not read settings. */
-    readonly settings?: SettingsProvider;
-    /** Host-owned metadata only: createAgent/session.run do not resolve credentials. Pass resolvers to provider edges explicitly. */
-    readonly credentials?: CredentialResolver;
     readonly permission?: PermissionPolicy;
     readonly providerOptions?: ProviderRequestOptions;
     readonly providerRequestPolicies?: ProviderRequestPolicy | readonly ProviderRequestPolicy[];
@@ -289,13 +298,42 @@ export interface SubscribeOptions {
     /** What to do when `maxQueuedEvents` is reached. Defaults to `close`. */
     readonly overflow?: SubscriberOverflowPolicy;
 }
+export type AgentRunStatus = "succeeded" | "failed" | "aborted";
+/** Terminal result of `session.run()` / `session.prompt()`. Failed and aborted runs throw {@link AgentRunError} with this shape attached. */
+export interface AgentRunResult {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly status: AgentRunStatus;
+    /** Branch leaf after the run settles. */
+    readonly leafId?: string;
+    /** Concatenated text blocks from the final assistant message, or `""` when none. */
+    readonly text: string;
+    /** Content blocks from the final assistant message, or `[]` when none. */
+    readonly content: readonly ContentBlock[];
+    /** Final assistant message when the run produced one. */
+    readonly message?: Message;
+    /** Aggregate usage across provider turns (`run_total` scope). */
+    readonly usage?: Usage;
+    /** Present when `status` is `"failed"` or when a failed attempt still produced partial output. */
+    readonly error?: ErrorInfo;
+    /** String form of the abort reason when `status` is `"aborted"`. */
+    readonly abortReason?: string;
+}
+export declare class AgentRunError extends Error {
+    readonly result: AgentRunResult;
+    constructor(result: AgentRunResult, options?: {
+        readonly cause?: unknown;
+    });
+}
 export interface AgentSession {
     readonly id: string;
     /** Current branch leaf entry id; advances on every append/run and is re-pointed by `checkout`.
      *  Undefined until the first entry lands (a fresh session with no history). */
     readonly leafId: string | undefined;
-    run(input: string | Message | readonly Message[], options?: RunOptions): Promise<void>;
-    prompt(input: string, options?: RunOptions): Promise<void>;
+    run(input: string | Message | readonly Message[], options?: RunOptions): Promise<AgentRunResult>;
+    prompt(input: string, options?: RunOptions): Promise<AgentRunResult>;
+    /** Subscribe first, then start exactly one run and yield only that run's events until it terminates. */
+    stream(input: string | Message | readonly Message[], options?: RunOptions & SubscribeOptions): AsyncIterable<AgentEvent>;
     compact(options?: CompactionOptions): Promise<CompactionResult>;
     subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
     abort(reason?: unknown): void;
@@ -304,6 +342,20 @@ export interface AgentSession {
     fork(options?: AgentSessionForkOptions): AgentSession;
     clone(options?: AgentSessionCloneOptions): Promise<AgentSession>;
 }
+export interface ProviderTurnMetadata {
+    readonly providerId: string;
+    readonly model: ModelConfig;
+    readonly requestId?: string;
+    readonly latencyMs?: number;
+    readonly attempt?: number;
+    readonly httpStatus?: number;
+    readonly rateLimitRemaining?: number;
+    readonly rateLimitResetMs?: number;
+}
+export interface ToolExecutionMetadata {
+    readonly durationMs: number;
+    readonly status: ToolCallStatus;
+}
 export type AgentEvent = {
     readonly type: "agent_started";
     readonly sessionId: string;
@@ -323,6 +375,20 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly turn: number;
+} | {
+    readonly type: "provider_turn_started";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly metadata: ProviderTurnMetadata;
+} | {
+    readonly type: "provider_turn_finished";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly metadata: ProviderTurnMetadata;
+    readonly usage?: Usage;
+    readonly error?: ErrorInfo;
 } | {
     readonly type: "message_started";
     readonly sessionId: string;
@@ -356,12 +422,14 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly result: ToolResult;
+    readonly metadata: ToolExecutionMetadata;
 } | {
     readonly type: "tool_execution_error";
     readonly sessionId: string;
     readonly runId: string;
     readonly call: ToolCallContent;
     readonly error: ErrorInfo;
+    readonly metadata: ToolExecutionMetadata;
 } | {
     readonly type: "tool_execution_blocked";
     readonly sessionId: string;
@@ -370,6 +438,7 @@ export type AgentEvent = {
     readonly name: string;
     readonly reason: string;
     readonly error: ErrorInfo;
+    readonly metadata: ToolExecutionMetadata;
 } | {
     readonly type: "queue_updated";
     readonly sessionId: string;
@@ -442,6 +511,8 @@ export interface ToolDefinition {
     readonly name: string;
     readonly description?: string;
     readonly parameters?: JsonObject;
+    /** Force any provider turn containing this tool to dispatch sequentially. */
+    readonly exclusive?: boolean;
     execute(args: JsonObject, context: ToolExecutionContext): Promise<ToolResult> | ToolResult;
 }
 export interface ToolRegistry {
@@ -647,6 +718,8 @@ export interface OAuthLoginCallbacks {
         readonly message: string;
         readonly choices: readonly string[];
     }): string | undefined | Promise<string | undefined>;
+    /** Aborts OAuth login flows and device-code polling when signaled. */
+    readonly signal?: AbortSignal;
 }
 export interface OAuthCredentials {
     readonly access?: string;
@@ -832,6 +905,83 @@ export interface PersistenceQuery {
     readonly limit?: number;
     readonly order?: "asc" | "desc";
 }
+/** Generic versioned checkpoint key. Namespaces prevent consumer collisions. */
+export interface CheckpointKey extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly signal?: AbortSignal;
+}
+/** Input for an optimistic checkpoint write. Versions must strictly increase. */
+export interface CheckpointSaveInput extends CheckpointKey {
+    readonly version: number;
+    /** Exact current version required before update; use 0 for create-only. */
+    readonly expectedVersion?: number;
+    /** Monotonic lease fence. Lower or absent worker fences cannot replace a fenced record. */
+    readonly fencingToken?: number;
+    readonly value: unknown;
+    readonly category?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Durable generic checkpoint record. */
+export interface CheckpointRecord extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly version: number;
+    readonly fencingToken?: number;
+    readonly value: unknown;
+    readonly category?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Bounded checkpoint query. */
+export interface CheckpointQuery extends PersistenceQuery, OwnershipScope {
+    readonly namespace?: string;
+    readonly keyPrefix?: string;
+    readonly category?: string | readonly string[];
+    readonly signal?: AbortSignal;
+}
+/** Generic versioned checkpoint capability for persistence adapters. */
+export interface CheckpointStore {
+    saveCheckpoint(input: CheckpointSaveInput): Promise<CheckpointRecord>;
+    loadCheckpoint(input: CheckpointKey): Promise<CheckpointRecord | null>;
+    listCheckpoints(query?: CheckpointQuery): Promise<PersistencePage<CheckpointRecord>>;
+    deleteCheckpoint(input: CheckpointKey): Promise<boolean>;
+}
+/** Generic lease key. Ownership fields are part of the trust boundary. */
+export interface LeaseKey extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly signal?: AbortSignal;
+}
+export interface LeaseAcquireInput extends LeaseKey {
+    readonly ownerId: string;
+    readonly ttlMs: number;
+}
+export interface LeaseClaimInput extends LeaseKey {
+    readonly ownerId: string;
+    readonly token: string;
+    readonly ttlMs?: number;
+}
+export interface LeaseRecord extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly ownerId: string;
+    readonly token: string;
+    readonly fencingToken: number;
+    readonly acquiredAt: string;
+    readonly expiresAt: string;
+    readonly updatedAt: string;
+}
+/** Atomic distributed lease capability. Expired rows retain fencing counters. */
+export interface LeaseStore {
+    tryAcquireLease(input: LeaseAcquireInput): Promise<LeaseRecord | null>;
+    renewLease(input: LeaseClaimInput & {
+        readonly ttlMs: number;
+    }): Promise<LeaseRecord | null>;
+    releaseLease(input: LeaseClaimInput): Promise<boolean>;
+    getLease(input: LeaseKey): Promise<LeaseRecord | null>;
+}
 /** Stored session record. Does not include provider objects or credentials. */
 export interface SessionRecord extends OwnershipScope {
     readonly id: string;
@@ -908,12 +1058,16 @@ export interface ToolCallRecord extends OwnershipScope {
     readonly redacted: boolean;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-/** Stored usage row. */
+export type UsageScope = "provider_turn" | "run_total";
+/** Stored usage row. `scope` prevents provider-turn and aggregate totals from being summed together. */
 export interface UsageRecord extends OwnershipScope {
     readonly id: string;
     readonly sessionId: string;
     readonly runId?: string;
     readonly entryId?: string;
+    readonly scope: UsageScope;
+    readonly turn?: number;
+    readonly attempt?: number;
     readonly usage: Usage;
     readonly recordedAt: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -927,6 +1081,59 @@ export interface RunLedger {
 }
 /** Union of records that may be handed to a {@link RunLedger}. */
 export type RunLedgerRecord = RunRecord | AgentEventRecord | ToolCallRecord | UsageRecord;
+/** Immutable human feedback linked to an existing owned run/trace and optional evaluations. */
+export interface RunFeedbackRecord extends OwnershipScope {
+    readonly id: string;
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly traceId?: string;
+    readonly rating?: number;
+    readonly comment?: string;
+    readonly tags: readonly string[];
+    readonly scorerIds: readonly string[];
+    readonly evaluationIds: readonly string[];
+    readonly createdAt: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface AppendRunFeedbackInput extends OwnershipScope {
+    readonly id: string;
+    readonly runId: string;
+    readonly sessionId?: string;
+    readonly traceId?: string;
+    readonly rating?: number;
+    readonly comment?: string;
+    readonly tags?: readonly string[];
+    readonly scorerIds?: readonly string[];
+    readonly evaluationIds?: readonly string[];
+    readonly createdAt?: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+/** Cursor-paginated, ownership-scoped feedback query. */
+export interface RunFeedbackQuery extends PersistenceQuery, OwnershipScope {
+    readonly runId?: string;
+    readonly sessionId?: string;
+    readonly traceId?: string;
+    readonly rating?: number;
+    readonly scorerId?: string;
+    readonly evaluationId?: string;
+    readonly tag?: string;
+    readonly fromCreatedAt?: string;
+    readonly toCreatedAt?: string;
+    readonly signal?: AbortSignal;
+}
+export interface DeleteRunFeedbackInput extends OwnershipScope {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+/** Feedback storage seam. Records are append-only; correction uses a new record and deletion is explicit. */
+export interface RunFeedbackStore {
+    append(input: AppendRunFeedbackInput): Promise<RunFeedbackRecord>;
+    query(query: RunFeedbackQuery): Promise<PersistencePage<RunFeedbackRecord>>;
+    delete(input: DeleteRunFeedbackInput): Promise<boolean>;
+}
 /** Stored agent definition version. Does not include provider credentials/resolvers/provider instances. */
 export interface AgentDefinitionRecord extends OwnershipScope {
     readonly id: string;
@@ -1031,6 +1238,9 @@ export interface UsageQuery extends PersistenceQuery, OwnershipScope {
     readonly sessionId?: string;
     readonly runId?: string;
     readonly entryId?: string;
+    readonly scope?: UsageScope;
+    readonly turn?: number;
+    readonly attempt?: number;
     readonly fromRecordedAt?: string;
     readonly toRecordedAt?: string;
 }
@@ -1058,11 +1268,17 @@ export interface MigrationQuery extends PersistenceQuery {
  * Production database-neutral persistence store contract.
  * Hosts implement this interface to provide durable, paginated storage
  * for sessions, entries, runs, events, tool calls, usage, agent definitions,
- * and migrations. No SQL client, ORM, host file storage, or network dependency is
+ * and migrations, with optional generic checkpoint and atomic lease capabilities. No SQL client, ORM, host file storage, or network dependency is
  * required by the contract.
  */
 export interface ProductionPersistenceStore {
     readonly name?: string;
+    /** Optional generic write capability for resumable consumers such as workflows. */
+    readonly checkpoints?: CheckpointStore;
+    /** Optional atomic distributed lease capability for coordinators and workers. */
+    readonly leases?: LeaseStore;
+    /** Optional immutable run/trace feedback storage capability. */
+    readonly feedback?: RunFeedbackStore;
     querySessions(query: SessionQuery): Promise<PersistencePage<SessionRecord>>;
     queryBranches(query: BranchQuery): Promise<PersistencePage<BranchRecord>>;
     queryEntries(query: SessionEntryQuery): Promise<PersistencePage<SessionEntry>>;
@@ -1201,9 +1417,12 @@ export interface LoopContext {
     readonly input: AgentInput;
     readonly inputMessages: readonly Message[];
     readonly maxToolRounds: number;
+    /** Maximum independent tool calls dispatched concurrently per provider turn. Default `1`. */
+    readonly toolConcurrency: number;
     assemble(nextInput: AgentInput, toolResults?: readonly ToolResult[], turn?: number): Promise<ProviderRequest>;
     generate(request: ProviderRequest): Promise<ProviderTurnResult>;
     dispatchToolCall(call: ToolCallContent): Promise<ToolResult>;
+    isToolCallExclusive?(call: ToolCallContent): boolean;
     appendMessage(message: Message): Promise<void>;
     emit(event: AgentEvent): void;
 }
@@ -1213,12 +1432,18 @@ export interface AgentLoopStrategy {
 }
 export type AgentLoopOptions = {
     readonly strategy: "single-shot";
+    /** Independent tool calls per turn run concurrently up to this limit. Default `1` (sequential). */
+    readonly toolConcurrency?: number;
 } | {
     readonly strategy: "generate-validate-revise";
     readonly validator: ArtifactValidator<unknown>;
     readonly parser?: ArtifactParser<unknown>;
     readonly repairer?: ArtifactRepairer<unknown>;
     readonly maxRevisions?: number;
+    /** Native provider JSON-schema output. Ignored when `structuredOutputMode` is `artifact-loop`. */
+    readonly structuredOutput?: StructuredOutputOptions;
+    /** `native` maps schema to capable providers; `artifact-loop` keeps repair turns only. */
+    readonly structuredOutputMode?: "native" | "artifact-loop";
 };
 export interface ArtifactValidation {
     readonly ok: boolean;

package/dist/contracts.js

@@ -1,3 +1,11 @@
+export class AgentRunError extends Error {
+    result;
+    constructor(result, options) {
+        super(result.error?.message ?? (result.status === "aborted" ? "Agent run aborted" : "Agent run failed"), options);
+        this.name = "AgentRunError";
+        this.result = result;
+    }
+}
 export const SESSION_ENTRY_KINDS = [
     "message",
     "event",

package/dist/event-multiplexer.d.ts

@@ -0,0 +1,23 @@
+export type EventOverflowPolicy = "close" | "drop_oldest" | "drop_newest";
+export interface EventOverflowInfo {
+    readonly droppedEvents: number;
+    readonly maxQueuedEvents: number;
+    readonly policy: EventOverflowPolicy;
+}
+export interface EventMultiplexerOptions<T> {
+    readonly maxQueuedEvents?: number;
+    readonly overflow?: EventOverflowPolicy;
+    readonly overflowEvent?: (info: EventOverflowInfo) => T;
+    readonly compare?: (a: T, b: T) => number;
+    readonly signal?: AbortSignal;
+}
+export interface EventMultiplexer<T> {
+    publish(event: T): void;
+    observe<S>(source: AsyncIterable<S>, map: (event: S) => T): () => void;
+    subscribe(): AsyncIterable<T>;
+    close(): void;
+    readonly droppedEvents: number;
+    readonly closed: boolean;
+}
+/** Bounded single-consumer fan-in for arbitrary async event sources. */
+export declare function createEventMultiplexer<T>(options?: EventMultiplexerOptions<T>): EventMultiplexer<T>;

package/dist/event-multiplexer.js

@@ -0,0 +1,136 @@
+/** Bounded single-consumer fan-in for arbitrary async event sources. */
+export function createEventMultiplexer(options = {}) {
+    const maxQueuedEvents = Math.max(1, options.maxQueuedEvents ?? 1024);
+    const overflow = options.overflow ?? "close";
+    const queue = [];
+    const stops = new Set();
+    let waiter;
+    let isClosed = false;
+    let droppedEvents = 0;
+    let overflowNotified = false;
+    const abort = () => close();
+    if (options.signal?.aborted)
+        isClosed = true;
+    else
+        options.signal?.addEventListener("abort", abort, { once: true });
+    function publish(event) {
+        if (isClosed)
+            return;
+        if (waiter) {
+            const resolve = waiter;
+            waiter = undefined;
+            resolve({ value: event, done: false });
+            return;
+        }
+        if (queue.length < maxQueuedEvents) {
+            queue.push(event);
+            return;
+        }
+        droppedEvents += 1;
+        const notice = !overflowNotified && options.overflowEvent
+            ? options.overflowEvent({ droppedEvents, maxQueuedEvents, policy: overflow })
+            : undefined;
+        overflowNotified = true;
+        if (overflow === "close") {
+            queue.length = 0;
+            if (notice !== undefined)
+                queue.push(notice);
+            options.signal?.removeEventListener("abort", abort);
+            finishSources();
+            isClosed = true;
+            return;
+        }
+        if (overflow === "drop_newest") {
+            if (notice !== undefined)
+                queue[queue.length - 1] = notice;
+            return;
+        }
+        queue.shift();
+        if (notice !== undefined) {
+            queue.push(notice);
+            if (queue.length >= maxQueuedEvents)
+                queue.shift();
+        }
+        queue.push(event);
+    }
+    function observe(source, map) {
+        if (isClosed)
+            return () => undefined;
+        const iterator = source[Symbol.asyncIterator]();
+        let stopped = false;
+        const stop = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            stops.delete(stop);
+            void iterator.return?.();
+        };
+        stops.add(stop);
+        void (async () => {
+            try {
+                while (!stopped && !isClosed) {
+                    const next = await iterator.next();
+                    if (next.done)
+                        break;
+                    publish(map(next.value));
+                }
+            }
+            catch {
+                // Source failure ends that source; owners surface source errors separately.
+            }
+            finally {
+                stop();
+            }
+        })();
+        return stop;
+    }
+    function finishSources() {
+        for (const stop of [...stops])
+            stop();
+        stops.clear();
+    }
+    function close() {
+        if (isClosed)
+            return;
+        isClosed = true;
+        options.signal?.removeEventListener("abort", abort);
+        finishSources();
+        queue.length = 0;
+        if (waiter) {
+            const resolve = waiter;
+            waiter = undefined;
+            resolve({ value: undefined, done: true });
+        }
+    }
+    async function* subscribe() {
+        while (true) {
+            if (queue.length > 0) {
+                if (options.compare)
+                    queue.sort(options.compare);
+                yield queue.shift();
+                continue;
+            }
+            if (isClosed)
+                return;
+            const next = await new Promise((resolve) => {
+                waiter = resolve;
+            });
+            if (next.done)
+                return;
+            yield next.value;
+        }
+    }
+    return {
+        publish,
+        observe,
+        subscribe,
+        close,
+        get droppedEvents() {
+            return droppedEvents;
+        },
+        get closed() {
+            return isClosed;
+        },
+    };
+}
+//# sourceMappingURL=event-multiplexer.js.map

package/dist/execution-policy.d.ts

@@ -0,0 +1,28 @@
+export type ExecutionRisk = "low" | "medium" | "high";
+export interface ExecutionAction {
+    readonly kind: "shell" | "read" | "write" | "edit" | string;
+    readonly operation: string;
+    readonly paths?: readonly string[];
+    readonly command?: string;
+    readonly risk?: ExecutionRisk;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ExecutionDecision {
+    readonly allowed: boolean;
+    readonly reason?: string;
+    readonly modified?: Partial<ExecutionAction>;
+    /** When true, tool definitions should expose `exclusive: true` for pre-dispatch serialization. */
+    readonly exclusive?: boolean;
+}
+export interface ExecutionPolicy {
+    check(action: ExecutionAction): ExecutionDecision | Promise<ExecutionDecision>;
+}
+export declare class ExecutionDeniedError extends Error {
+    readonly action: ExecutionAction;
+    readonly decision: ExecutionDecision;
+    readonly code = "ERR_PRISM_EXECUTION_DENIED";
+    constructor(action: ExecutionAction, decision: ExecutionDecision);
+}
+export declare function checkExecution(policy: ExecutionPolicy | undefined, action: ExecutionAction): Promise<ExecutionDecision>;
+export declare function applyExecutionDecision(action: ExecutionAction, decision: ExecutionDecision): ExecutionAction;
+export declare function assertExecutionAllowed(policy: ExecutionPolicy | undefined, action: ExecutionAction): Promise<ExecutionAction>;

package/dist/execution-policy.js

@@ -0,0 +1,24 @@
+export class ExecutionDeniedError extends Error {
+    action;
+    decision;
+    code = "ERR_PRISM_EXECUTION_DENIED";
+    constructor(action, decision) {
+        super(decision.reason ?? `Execution denied for ${action.kind}:${action.operation}`);
+        this.action = action;
+        this.decision = decision;
+        this.name = "ExecutionDeniedError";
+    }
+}
+export async function checkExecution(policy, action) {
+    return policy ? await policy.check(action) : { allowed: true };
+}
+export function applyExecutionDecision(action, decision) {
+    return decision.modified ? { ...action, ...decision.modified } : action;
+}
+export async function assertExecutionAllowed(policy, action) {
+    const decision = await checkExecution(policy, action);
+    if (!decision.allowed)
+        throw new ExecutionDeniedError(action, decision);
+    return applyExecutionDecision(action, decision);
+}
+//# sourceMappingURL=execution-policy.js.map