@rivus/runtime 0.16.6 → 0.17.0

package/dist/chunks/agent-loop.d.ts

@@ -1,5 +1,128 @@
 import { Effect, Stream } from "effect";
-
+//#region src/core/application/agent-execution/contracts/agent-user-input.d.ts
+/**
+ * The structured input accepted by an Agent Run.  It is deliberately a data
+ * object: paths, credentials and provider specific handles are kept in the
+ * AttachmentAccess binding that accompanies a run.
+ */
+interface UserInput {
+  readonly version: 1;
+  readonly deliveryId: string;
+  readonly message: InputMessage;
+}
+interface InputMessage {
+  readonly id: string;
+  readonly source: "direct" | "quoted";
+  readonly author?: InputAuthor;
+  readonly sentAt?: string;
+  readonly parts: ReadonlyArray<InputPart>;
+}
+interface InputAuthor {
+  readonly id?: string;
+  readonly name?: string;
+}
+type InputNoticeReason = "permission_denied" | "expired" | "unsupported" | "limit_exceeded" | "invalid_content" | "unavailable";
+type InputPart = InputTextPart | InputImagePart | InputAttachmentPart | InputQuotePart | InputNoticePart;
+interface InputTextPart {
+  readonly type: "text";
+  readonly text: string;
+  /** Origin metadata is optional for compatibility with old structured callers. */
+  readonly source?: "direct" | "quoted";
+  readonly controlEligible?: boolean;
+}
+/** An image part references bytes that were prepared by the channel adapter. */
+interface InputImagePart {
+  readonly type: "image";
+  readonly attachmentId: string;
+  readonly mimeType: string;
+  readonly size?: number;
+}
+interface InputAttachmentPart {
+  readonly type: "attachment";
+  readonly attachmentId: string;
+  readonly mediaKind: "file" | "audio" | "video";
+  readonly durationMs?: number;
+  readonly fileName?: string;
+  readonly mimeType: string;
+  readonly size: number;
+}
+interface InputQuotePart {
+  readonly type: "quote";
+  readonly kind: "forward" | "reply";
+  readonly messages: ReadonlyArray<InputMessage>;
+}
+/** Reserved Bash action handled by the Run binding; never an OS executable. */
+declare const ATTACHMENT_RECOVERY_COMMAND = "rivus-attachment-recover";
+interface InputRecovery {
+  readonly toolName: string;
+  readonly arguments: Readonly<Record<string, string | number>>;
+}
+interface InputNoticePart {
+  readonly type: "notice";
+  readonly reason: InputNoticeReason;
+  readonly text: string;
+  /** Present only when the channel adapter has installed a trusted action. */
+  readonly recovery?: InputRecovery;
+}
+interface MaterializedAttachment {
+  readonly attachmentId: string;
+  readonly path: string;
+  readonly mimeType: string;
+  readonly size: number;
+  readonly mediaKind: "file" | "audio" | "video";
+  readonly fileName?: string;
+  readonly durationMs?: number;
+}
+/** Runtime identity used to bind an adapter grant to one active Run. */
+interface AttachmentAccessBinding {
+  readonly generationId?: string;
+  readonly runId: AgentRunId;
+  readonly sessionKey: SessionKey;
+  readonly signal: AbortSignal;
+}
+/**
+ * Run-scoped access to bytes and files prepared by an inbound adapter.
+ * Implementations must validate the tenant, endpoint, session generation and
+ * run before serving a request.  A path returned by materialize is a handle,
+ * never an authority by itself.
+ */
+interface AttachmentAccess {
+  /** Create a Run-bound view. The returned view must reject after revoke. */
+  readonly bind?: (binding: AttachmentAccessBinding) => AttachmentAccess;
+  /** Revoke this view and any adapter grant it wraps. */
+  readonly revoke?: () => void;
+  readonly readBytes: (attachmentId: string) => Effect.Effect<Uint8Array, unknown>;
+  readonly materialize: (attachmentId: string) => Effect.Effect<MaterializedAttachment, unknown>;
+  /** Whether a deployed tool can consume the given media kind. */
+  readonly canUnderstand?: (input: {
+    readonly mediaKind: "file" | "audio" | "video";
+    readonly mimeType: string;
+  }) => boolean;
+  /** Enforces the provider's native image count/size/vision budget. */
+  readonly canProvideImage?: (input: {
+    readonly mimeType: string;
+    readonly size: number;
+    readonly index: number;
+  }) => boolean;
+  /** Returns a recovery action only for an adapter-authenticated failure. */
+  readonly trustedRecovery?: (notice: InputNoticePart) => InputRecovery | undefined;
+  /** Executes an adapter-authorized recovery through the existing tool boundary. */
+  readonly executeRecovery?: (input: {
+    readonly toolName: string;
+    readonly arguments: Readonly<Record<string, string | number>>;
+    readonly signal?: AbortSignal;
+  }) => Effect.Effect<{
+    readonly outputPath: string;
+    readonly mimeType: string;
+    readonly sizeBytes: number;
+  } | undefined, unknown>;
+}
+interface AgentSteeringRequest {
+  readonly attachmentAccess?: AttachmentAccess;
+  readonly userInput: UserInput;
+}
+type AgentSteeringInput = string | UserInput | AgentSteeringRequest;
+//#endregion
 //#region src/core/application/agent-execution/contracts/agent-domain-events.d.ts
 type AgentRunId = string;
 type SessionKey = string;
@@ -8,6 +131,8 @@ interface AgentRunAccepted {
   readonly runId: AgentRunId;
   readonly sessionKey: SessionKey;
   readonly prompt: string;
+  /** Structured input is retained for replay; `prompt` remains the legacy view. */
+  readonly userInput?: UserInput;
   readonly occurredAt: Date;
 }
 interface AgentTurnStarted {
@@ -138,13 +263,6 @@ interface AgentRunCancelled {
   readonly occurredAt: Date;
 }
 type AgentDomainEvent = AgentRunAccepted | AgentTurnStarted | AssistantTextDelta | AssistantThinkingDelta | AgentModelExecutionStarted | AgentModelExecutionEnded | AgentSkillExecutionStarted | AgentSkillExecutionEnded | AgentToolExecutionStarted | AgentToolExecutionUpdated | AgentToolExecutionEnded | AgentTurnCompleted | AgentRunCompleted | AgentRunFailed | AgentRunCancelled;
-type AgentToolExecutionEvent = AgentToolExecutionStarted | AgentToolExecutionUpdated | AgentToolExecutionEnded;
-type AgentModelExecutionEvent = AgentModelExecutionStarted | AgentModelExecutionEnded;
-type TerminalAgentDomainEvent = AgentRunCompleted | AgentRunFailed | AgentRunCancelled;
-declare function isAssistantTextDeltaEvent(event: AgentDomainEvent): event is AssistantTextDelta;
-declare function isAssistantThinkingDeltaEvent(event: AgentDomainEvent): event is AssistantThinkingDelta;
-declare function isAgentToolExecutionEvent(event: AgentDomainEvent): event is AgentToolExecutionEvent;
-declare function isTerminalAgentDomainEvent(event: AgentDomainEvent): event is TerminalAgentDomainEvent;
 //#endregion
 //#region src/core/application/agent-execution/contracts/agent-run-state.d.ts
 type AgentRunPhase = "idle" | "accepted" | "running" | "completed" | "failed" | "cancelled";
@@ -153,6 +271,7 @@ interface AgentRunState {
   readonly runId?: AgentRunId;
   readonly sessionKey?: SessionKey;
   readonly prompt?: string;
+  readonly userInput?: UserInput;
   readonly finalText: string;
   readonly errorMessage?: string;
   readonly cancellationReason?: string;
@@ -194,6 +313,7 @@ interface AgentRunSummary {
   readonly finalText: string;
   readonly phase: AgentRunPhase;
   readonly prompt?: string;
+  readonly userInput?: UserInput;
   readonly runId: AgentRunId;
   readonly sessionKey?: SessionKey;
   readonly startedAt?: Date;
@@ -222,7 +342,6 @@ interface AgentHistory {
   readonly sessions: ReadonlyArray<AgentSessionSummary>;
   readonly totalEvents: number;
 }
-declare function replayAgentHistory(events: ReadonlyArray<AgentDomainEvent>): AgentHistory;
 //#endregion
 //#region src/core/application/agent-execution/transcript/agent-transcript.d.ts
 interface AgentTranscript {
@@ -247,22 +366,14 @@ interface AgentTranscriptTurn {
   readonly toolExecutionCount: number;
   readonly updatedAt: Date;
   readonly userText: string;
+  readonly userInput?: UserInput;
 }
 type AgentTranscriptMessageRole = "assistant" | "user";
 interface AgentTranscriptMessage {
   readonly content: string;
   readonly role: AgentTranscriptMessageRole;
+  readonly userInput?: UserInput;
 }
-interface AgentConversationMessagesOptions {
-  readonly text: string;
-  readonly transcript?: AgentTranscript;
-}
-declare function replayAgentTranscript(events: ReadonlyArray<AgentDomainEvent>, sessionKey: SessionKey): AgentTranscript;
-declare function createAgentTranscriptTurn(summary: AgentRunSummary & {
-  readonly sessionKey: SessionKey;
-}): AgentTranscriptTurn;
-declare function createAgentTranscriptMessages(transcript: AgentTranscript): ReadonlyArray<AgentTranscriptMessage>;
-declare function createAgentConversationMessages(options: AgentConversationMessagesOptions): ReadonlyArray<AgentTranscriptMessage>;
 //#endregion
 //#region src/core/application/agent-execution/invocation/agent-invocation.d.ts
 interface AgentMemoryInvocationIdentity {
@@ -311,25 +422,30 @@ interface BackgroundSessionAgentInvocationOrigin {
 type AgentInvocationOrigin = FeishuAgentInvocationOrigin | LocalCliAgentInvocationOrigin | AutomationAgentInvocationOrigin | BackgroundSessionAgentInvocationOrigin;
 //#endregion
 //#region src/core/application/agent-execution/loop/agent-loop.d.ts
-interface AgentLoopInput$1 {
+interface AgentLoopInput {
   readonly abortSignal: AbortSignal;
+  readonly attachmentAccess?: AttachmentAccess;
   readonly invocation?: AgentInvocationOrigin;
   readonly messages?: ReadonlyArray<AgentTranscriptMessage>;
   readonly runId: AgentRunId;
   readonly sessionKey: SessionKey;
   /** Optional mailbox for user steering while the run is active. */
-  readonly steering?: AgentSteeringChannel$1;
+  readonly steering?: AgentSteeringChannel;
   readonly text: string;
+  readonly userInput?: UserInput;
   readonly previousSessionState?: AgentRunState;
   readonly previousSessionTranscript?: AgentTranscript;
 }
-interface AgentSteeringChannel$1 {
+interface AgentSteeringChannel {
+  /** Legacy text mailbox. Kept unchanged for existing provider adapters. */
   next(): Effect.Effect<string>;
   /** Seal admission at provider completion and return accepted messages still waiting. */
   close?(): Effect.Effect<readonly string[]>;
+  /** Structured mailbox used by adapters that advertise structured steering. */
+  nextInput?(): Effect.Effect<AgentSteeringInput>;
+  closeInput?(): Effect.Effect<readonly AgentSteeringInput[]>;
 }
 type AgentLoopEvent = AgentLoopTurnStart | AgentLoopTextDelta | AgentLoopThinkingDelta | AgentLoopModelExecutionStart | AgentLoopModelExecutionEnd | AgentLoopSkillExecutionStart | AgentLoopSkillExecutionEnd | AgentLoopToolExecutionStart | AgentLoopToolExecutionUpdate | AgentLoopToolExecutionEnd;
-type AgentLoopEventLike = AgentLoopEvent | string;
 interface AgentLoopTextDelta {
   readonly type: "assistant_text_delta";
   readonly delta: string;
@@ -401,81 +517,13 @@ interface AgentLoopToolExecutionEnd {
   readonly result: unknown;
   readonly isError: boolean;
 }
-interface AgentLoop$1 {
-  run(input: AgentLoopInput$1): Stream.Stream<AgentLoopEvent, unknown>;
-  /** Provider adapters opt in only when they can consume steering safely. */
-  readonly supportsSteering?: boolean;
-}
-interface TextAgentLoopOptions$1 {
-  readonly generate: (input: AgentLoopInput$1) => Effect.Effect<string, unknown>;
-}
-type AgentLoopToolExecutionStartOptions = Omit<AgentLoopToolExecutionStart, "type">;
-type AgentLoopToolExecutionUpdateOptions = Omit<AgentLoopToolExecutionUpdate, "type">;
-type AgentLoopToolExecutionEndOptions = Omit<AgentLoopToolExecutionEnd, "type">;
-type AgentLoopModelExecutionStartOptions = Omit<AgentLoopModelExecutionStart, "type">;
-type AgentLoopModelExecutionEndOptions = Omit<AgentLoopModelExecutionEnd, "type">;
-type AgentLoopSkillExecutionStartOptions = Omit<AgentLoopSkillExecutionStart, "type">;
-type AgentLoopSkillExecutionEndOptions = Omit<AgentLoopSkillExecutionSucceeded, "type"> | Omit<AgentLoopSkillExecutionFailed, "type">;
-declare function createAgentLoopTextDelta(delta: string): AgentLoopTextDelta;
-declare function createAgentLoopTurnStart(): AgentLoopTurnStart;
-declare function normalizeAgentLoopEvent(event: AgentLoopEventLike): AgentLoopEvent;
-declare function createAgentLoopThinkingDelta(delta: string): AgentLoopThinkingDelta;
-declare function createAgentLoopModelExecutionStart(options: AgentLoopModelExecutionStartOptions): AgentLoopModelExecutionStart;
-declare function createAgentLoopModelExecutionEnd(options: AgentLoopModelExecutionEndOptions): AgentLoopModelExecutionEnd;
-declare function createAgentLoopSkillExecutionStart(options: AgentLoopSkillExecutionStartOptions): AgentLoopSkillExecutionStart;
-declare function createAgentLoopSkillExecutionEnd(options: AgentLoopSkillExecutionEndOptions): AgentLoopSkillExecutionEnd;
-declare function createAgentLoopToolExecutionStart(options: AgentLoopToolExecutionStartOptions): AgentLoopToolExecutionStart;
-declare function createAgentLoopToolExecutionUpdate(options: AgentLoopToolExecutionUpdateOptions): AgentLoopToolExecutionUpdate;
-declare function createAgentLoopToolExecutionEnd(options: AgentLoopToolExecutionEndOptions): AgentLoopToolExecutionEnd;
-interface EventAgentLoopOptions$1 {
-  readonly events: ReadonlyArray<AgentLoopEventLike> | ((input: AgentLoopInput$1) => ReadonlyArray<AgentLoopEventLike> | Promise<ReadonlyArray<AgentLoopEventLike>>);
-}
-declare function createEventAgentLoop$1(options: EventAgentLoopOptions$1): AgentLoop$1;
-declare function createTextAgentLoop$1(options: TextAgentLoopOptions$1): AgentLoop$1;
-//#endregion
-//#region src/adapters/compatibility/agent-execution/loop/agent-loop.d.ts
-interface AgentLoopInput {
-  readonly runId: AgentRunId;
-  readonly sessionKey: SessionKey;
-  readonly text: string;
-  readonly abortSignal: AbortSignal;
-  readonly previousSessionState?: AgentRunState;
-  readonly previousSessionTranscript?: AgentTranscript;
-  readonly messages?: ReadonlyArray<AgentTranscriptMessage>;
-  readonly invocation?: AgentInvocationOrigin;
-  /** Optional mailbox for user steering while the run is active. */
-  readonly steering?: AgentSteeringChannel;
-}
-interface AgentSteeringChannel {
-  next(signal?: AbortSignal): Promise<string>;
-  close?(): Promise<readonly string[]>;
-}
 interface AgentLoop {
   run(input: AgentLoopInput): Stream.Stream<AgentLoopEvent, unknown>;
   /** Provider adapters opt in only when they can consume steering safely. */
   readonly supportsSteering?: boolean;
+  /** Structured steering is a separate capability from the legacy text mailbox. */
+  readonly supportsStructuredSteering?: boolean;
 }
-type AgentLoopCallbackOutput = Iterable<AgentLoopEventLike> | AsyncIterable<AgentLoopEventLike> | Stream.Stream<AgentLoopEventLike, unknown>;
-type AgentLoopCallbackResult = AgentLoopCallbackOutput | PromiseLike<AgentLoopCallbackOutput> | Effect.Effect<AgentLoopCallbackOutput, unknown>;
-type AgentLoopCallback = (input: AgentLoopInput) => AgentLoopCallbackResult;
-interface AsyncIterableAgentLoopOptions {
-  readonly run: (input: AgentLoopInput) => AsyncIterable<AgentLoopEventLike>;
-}
-interface EventAgentLoopOptions {
-  readonly events: ReadonlyArray<AgentLoopEventLike> | ((input: AgentLoopInput) => ReadonlyArray<AgentLoopEventLike> | Promise<ReadonlyArray<AgentLoopEventLike>>);
-}
-type TextAgentLoopCallback = (input: AgentLoopInput) => string | Promise<string>;
-interface TextAgentLoopOptions {
-  readonly generate: (input: AgentLoopInput) => Effect.Effect<string, unknown>;
-}
-declare function createEventAgentLoop(options: EventAgentLoopOptions): AgentLoop;
-declare function createAsyncIterableAgentLoop(options: AsyncIterableAgentLoopOptions): AgentLoop;
-declare function createAgentLoopFromCallback(run: AgentLoopCallback): AgentLoop;
-declare function createTextAgentLoop(options: TextAgentLoopOptions): AgentLoop;
-declare function createTextAgentLoopFromCallback(generate: TextAgentLoopCallback): AgentLoop;
-declare function toEffectAgentLoop(loop: AgentLoop): AgentLoop$1;
-declare function fromEffectAgentLoop(loop: AgentLoop$1): AgentLoop;
-declare function toEffectAgentLoopInput(input: AgentLoopInput): AgentLoopInput$1;
-declare function toCompatibilityAgentLoopInput(input: AgentLoopInput$1): AgentLoopInput;
 //#endregion
-export { createAgentLoopTurnStart as $, AgentLoopSkillExecutionStart as A, AgentModelUsage as At, AgentLoopTurnStart as B, AgentToolExecutionUpdated as Bt, AgentLoopInput$1 as C, AgentRunState as Ct, AgentLoopModelExecutionStartOptions as D, AgentModelExecutionEnded as Dt, AgentLoopModelExecutionStart as E, AgentDomainEvent as Et, AgentLoopToolExecutionEndOptions as F, AgentSkillExecutionEnded as Ft, createAgentLoopModelExecutionStart as G, SessionKey as Gt, EventAgentLoopOptions$1 as H, AgentTurnStarted as Ht, AgentLoopToolExecutionStart as I, AgentSkillExecutionStarted as It, createAgentLoopTextDelta as J, isAssistantTextDeltaEvent as Jt, createAgentLoopSkillExecutionEnd as K, TerminalAgentDomainEvent as Kt, AgentLoopToolExecutionStartOptions as L, AgentToolExecutionEnded as Lt, AgentLoopTextDelta as M, AgentRunCompleted as Mt, AgentLoopThinkingDelta as N, AgentRunFailed as Nt, AgentLoopSkillExecutionEnd as O, AgentModelExecutionEvent as Ot, AgentLoopToolExecutionEnd as P, AgentRunId as Pt, createAgentLoopToolExecutionUpdate as Q, AgentLoopToolExecutionUpdate as R, AgentToolExecutionEvent as Rt, AgentLoopEventLike as S, AgentRunPhase as St, AgentLoopModelExecutionEndOptions as T, AgentToolExecutionState as Tt, TextAgentLoopOptions$1 as U, AssistantTextDelta as Ut, AgentSteeringChannel$1 as V, AgentTurnCompleted as Vt, createAgentLoopModelExecutionEnd as W, AssistantThinkingDelta as Wt, createAgentLoopToolExecutionEnd as X, isTerminalAgentDomainEvent as Xt, createAgentLoopThinkingDelta as Y, isAssistantThinkingDeltaEvent as Yt, createAgentLoopToolExecutionStart as Z, toCompatibilityAgentLoopInput as _, replayAgentTranscript as _t, AgentLoopInput as a, AutomationAgentInvocationOrigin as at, AgentLoop$1 as b, AgentSessionSummary as bt, EventAgentLoopOptions as c, LocalCliAgentInvocationOrigin as ct, createAgentLoopFromCallback as d, AgentTranscriptMessage as dt, createEventAgentLoop$1 as et, createAsyncIterableAgentLoop as f, AgentTranscriptMessageRole as ft, fromEffectAgentLoop as g, createAgentTranscriptTurn as gt, createTextAgentLoopFromCallback as h, createAgentTranscriptMessages as ht, AgentLoopCallbackResult as i, AgentMemoryInvocationIdentity as it, AgentLoopSkillExecutionStartOptions as j, AgentRunAccepted as jt, AgentLoopSkillExecutionEndOptions as k, AgentModelExecutionStarted as kt, TextAgentLoopCallback as l, AgentConversationMessagesOptions as lt, createTextAgentLoop as m, createAgentConversationMessages as mt, AgentLoopCallback as n, normalizeAgentLoopEvent as nt, AgentSteeringChannel as o, BackgroundSessionAgentInvocationOrigin as ot, createEventAgentLoop as p, AgentTranscriptTurn as pt, createAgentLoopSkillExecutionStart as q, isAgentToolExecutionEvent as qt, AgentLoopCallbackOutput as r, AgentInvocationOrigin as rt, AsyncIterableAgentLoopOptions as s, FeishuAgentInvocationOrigin as st, AgentLoop as t, createTextAgentLoop$1 as tt, TextAgentLoopOptions as u, AgentTranscript as ut, toEffectAgentLoop as v, AgentHistory as vt, AgentLoopModelExecutionEnd as w, AgentSkillExecutionState as wt, AgentLoopEvent as x, replayAgentHistory as xt, toEffectAgentLoopInput as y, AgentRunSummary as yt, AgentLoopToolExecutionUpdateOptions as z, AgentToolExecutionStarted as zt };
+export { UserInput as C, MaterializedAttachment as S, AttachmentAccessBinding as _, AgentTranscript as a, InputPart as b, AgentRunSummary as c, AgentDomainEvent as d, AgentRunId as f, AttachmentAccess as g, AgentSteeringInput as h, AgentMemoryInvocationIdentity as i, AgentSessionSummary as l, ATTACHMENT_RECOVERY_COMMAND as m, AgentLoopInput as n, AgentTranscriptTurn as o, SessionKey as p, AgentInvocationOrigin as r, AgentHistory as s, AgentLoop as t, AgentRunState as u, InputMessage as v, InputRecovery as x, InputNoticePart as y };
+export {};

package/dist/chunks/agent-user-input.js

@@ -0,0 +1,109 @@
+//#region src/core/application/agent-execution/contracts/agent-user-input.ts
+/** Reserved Bash action handled by the Run binding; never an OS executable. */
+const ATTACHMENT_RECOVERY_COMMAND = "rivus-attachment-recover";
+function isAgentSteeringRequest(value) {
+	return typeof value === "object" && value !== null && "userInput" in value;
+}
+/** Detach caller-owned nested arrays before an input enters a Run or mailbox. */
+function cloneUserInput(input) {
+	return structuredClone(input);
+}
+function cloneAgentSteeringInput(input) {
+	if (typeof input === "string") return input;
+	if (isAgentSteeringRequest(input)) return {
+		...input.attachmentAccess ? { attachmentAccess: input.attachmentAccess } : {},
+		userInput: cloneUserInput(input.userInput)
+	};
+	return cloneUserInput(input);
+}
+/**
+* Validate data crossing a persistence or adapter boundary before any access
+* binding is consulted. The structural check deliberately does not validate
+* or grant a notice recovery action; only AttachmentAccess can do that.
+*/
+function isValidUserInput(value, limits = {}) {
+	const maxDepth = limits.maxDepth ?? 4;
+	const maxMessages = limits.maxMessages ?? 100;
+	const maxPartsPerMessage = limits.maxPartsPerMessage ?? 256;
+	const maxTextCharacters = limits.maxTextCharacters ?? 1e5;
+	const seen = /* @__PURE__ */ new Set();
+	let messageCount = 0;
+	let textCharacters = 0;
+	if (!isRecord(value) || value.version !== 1 || !isNonEmptyString(value.deliveryId, 512)) return false;
+	return validateMessage(value.message, "direct", 0);
+	function validateMessage(value, expectedSource, depth) {
+		if (depth > maxDepth || !isRecord(value) || seen.has(value)) return false;
+		seen.add(value);
+		if (++messageCount > maxMessages || value.source !== expectedSource || !isNonEmptyString(value.id, 512)) return false;
+		if (value.author !== void 0 && (!isRecord(value.author) || !optionalString(value.author.id, 512) || !optionalString(value.author.name, 512))) return false;
+		if (value.sentAt !== void 0 && !isNonEmptyString(value.sentAt, 128)) return false;
+		if (!Array.isArray(value.parts) || value.parts.length > maxPartsPerMessage) return false;
+		for (const part of value.parts) if (!validatePart(part, expectedSource, depth)) return false;
+		return true;
+	}
+	function validatePart(value, messageSource, depth) {
+		if (!isRecord(value) || typeof value.type !== "string") return false;
+		if (value.type === "text") {
+			if (typeof value.text !== "string" || value.source !== void 0 && value.source !== messageSource) return false;
+			if (value.controlEligible !== void 0 && typeof value.controlEligible !== "boolean") return false;
+			textCharacters += value.text.length;
+			return textCharacters <= maxTextCharacters;
+		}
+		if (value.type === "image") return isNonEmptyString(value.attachmentId, 512) && isNonEmptyString(value.mimeType, 256) && optionalNonNegativeInteger(value.size);
+		if (value.type === "attachment") return isNonEmptyString(value.attachmentId, 512) && isNonEmptyString(value.mimeType, 256) && (value.mediaKind === "file" || value.mediaKind === "audio" || value.mediaKind === "video") && nonNegativeInteger(value.size) && optionalString(value.fileName, 512) && optionalNonNegativeInteger(value.durationMs);
+		if (value.type === "quote") {
+			if (value.kind !== "forward" && value.kind !== "reply" || !Array.isArray(value.messages)) return false;
+			return value.messages.every((message) => validateMessage(message, "quoted", depth + 1));
+		}
+		if (value.type === "notice") {
+			if (!noticeReason(value.reason) || typeof value.text !== "string") return false;
+			textCharacters += value.text.length;
+			if (textCharacters > maxTextCharacters) return false;
+			if (value.recovery !== void 0) {
+				if (!isRecord(value.recovery) || !isNonEmptyString(value.recovery.toolName, 256) || !isRecord(value.recovery.arguments)) return false;
+				for (const [key, argument] of Object.entries(value.recovery.arguments)) {
+					if (typeof argument === "string") textCharacters += argument.length;
+					if (textCharacters > maxTextCharacters || !isNonEmptyString(key, 256) || !(typeof argument === "string" || typeof argument === "number" && Number.isFinite(argument))) return false;
+				}
+			}
+			return true;
+		}
+		return false;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isNonEmptyString(value, maxLength) {
+	return typeof value === "string" && value.length > 0 && value.length <= maxLength;
+}
+function optionalString(value, maxLength) {
+	return value === void 0 || typeof value === "string" && value.length <= maxLength;
+}
+function nonNegativeInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function optionalNonNegativeInteger(value) {
+	return value === void 0 || nonNegativeInteger(value);
+}
+function noticeReason(value) {
+	return value === "permission_denied" || value === "expired" || value === "unsupported" || value === "limit_exceeded" || value === "invalid_content" || value === "unavailable";
+}
+/** A stable textual compatibility projection for old prompt/history APIs. */
+function projectUserInputText(input) {
+	return projectMessageText(input.message);
+}
+function projectMessageText(message) {
+	return message.parts.flatMap((part) => {
+		switch (part.type) {
+			case "text": return [part.text];
+			case "image": return [`[图片 ${part.attachmentId}]`];
+			case "attachment": return [`[${part.mediaKind === "audio" ? "音频" : part.mediaKind === "video" ? "视频" : "文件"}${part.fileName ? ` ${part.fileName}` : ""}]`];
+			case "notice": return [part.text];
+			case "quote": return part.messages.flatMap(projectMessageText);
+		}
+	}).filter((text) => text.length > 0).join("\n");
+}
+//#endregion
+export { isValidUserInput as a, isAgentSteeringRequest as i, cloneAgentSteeringInput as n, projectUserInputText as o, cloneUserInput as r, ATTACHMENT_RECOVERY_COMMAND as t };
+

package/dist/chunks/rivus-runtime-tool.d.ts

@@ -1,6 +1,5 @@
-import { Pt as AgentRunId, it as AgentMemoryInvocationIdentity, rt as AgentInvocationOrigin } from "./agent-loop.js";
+import { f as AgentRunId, i as AgentMemoryInvocationIdentity, r as AgentInvocationOrigin } from "./agent-loop.js";
 import { Effect } from "effect";
-
 //#region src/core/application/agent-execution/contracts/model-runtime.d.ts
 /**
  * Runtime-owned model contracts. These describe the actual model binding and
@@ -237,6 +236,69 @@ interface AgentModelContentObserver {
   observeOutput(observation: AgentModelOutputObservation): void;
 }
 //#endregion
+//#region src/core/domain/tool-operation/value-objects/binding.d.ts
+interface ToolOperationBinding {
+  readonly agentId: string;
+  readonly inputDigest: string;
+  readonly instanceId: string;
+  readonly sourceMessageId: string;
+  readonly toolId: string;
+  readonly toolVersion: string;
+}
+//#endregion
+//#region src/core/domain/tool-operation/aggregate/snapshot.d.ts
+type ToolOperationState = {
+  readonly status: "pending";
+} | {
+  readonly result: unknown;
+  readonly status: "completed";
+} | {
+  readonly reason: string;
+  readonly status: "reconciliation-required";
+} | {
+  readonly status: "aborted";
+};
+interface ToolOperationReconciliationAction {
+  readonly actorId: string;
+  readonly at: string;
+  readonly note: string;
+}
+interface ToolOperationReconciliation extends ToolOperationReconciliationAction {
+  readonly outcome: "applied" | "not-applied";
+}
+interface ToolOperationSnapshot {
+  readonly binding: ToolOperationBinding;
+  readonly operationId: string;
+  readonly reconciliation?: ToolOperationReconciliation;
+  readonly revision: number;
+  readonly state: ToolOperationState;
+}
+type ToolOperationRecord = ToolOperationSnapshot;
+type ToolOperationReconciliationOutcome = {
+  readonly result: unknown;
+  readonly status: "applied";
+} | {
+  readonly status: "not-applied";
+};
+type ToolOperationBeginResult = {
+  readonly status: "acquired";
+} | {
+  readonly result: unknown;
+  readonly status: "completed";
+} | {
+  readonly status: "blocked";
+  readonly reason: string;
+};
+type ToolOperationInspectResult = {
+  readonly status: "missing";
+} | {
+  readonly result: unknown;
+  readonly status: "completed";
+} | {
+  readonly status: "blocked";
+  readonly reason: string;
+};
+//#endregion
 //#region src/core/application/agent-execution/invocation/agent-invocation-identity.d.ts
 interface NormalizedAgentInvocation {
   readonly allowedActorOpenIds: ReadonlyArray<string>;
@@ -292,10 +354,30 @@ interface InvocationAuthorityIdentity {
 declare function createInvocationAuthority(authority: InvocationAuthority, identity?: InvocationAuthorityIdentity): InvocationAuthorityRef;
 declare function resolveInvocationAuthority(reference: InvocationAuthorityRef): InvocationAuthority;
 //#endregion
+//#region src/core/application/tool-execution/brokerage/tool-input-digest.d.ts
+type ToolInputDigest = (canonicalJson: string) => string;
+declare function createToolInputDigest(input: unknown, digest: ToolInputDigest): string;
+//#endregion
+//#region src/core/application/tool-execution/operation/tool-operation-ledger.d.ts
+interface ToolOperationLedger {
+  abort(operationId: string, binding: ToolOperationBinding): Effect.Effect<void, unknown>;
+  begin(operationId: string, binding: ToolOperationBinding): Effect.Effect<ToolOperationBeginResult, unknown>;
+  complete(operationId: string, binding: ToolOperationBinding, result: unknown): Effect.Effect<void, unknown>;
+  inspect(operationId: string, binding: ToolOperationBinding): Effect.Effect<ToolOperationInspectResult, unknown>;
+  reconciliationRequired(): ReadonlyArray<ToolOperationRecord>;
+  reconcile(input: {
+    readonly action: ToolOperationReconciliationAction;
+    readonly expectedRevision: number;
+    readonly operationId: string;
+    readonly outcome: ToolOperationReconciliationOutcome;
+  }): Effect.Effect<ToolOperationRecord, unknown>;
+  requireReconciliation(operationId: string, binding: ToolOperationBinding, reason: string): Effect.Effect<void, unknown>;
+  unresolvedForSource(sourceMessageId: string): ReadonlyArray<ToolOperationRecord>;
+}
+//#endregion
 //#region src/core/application/tool-execution/authority/tool-risk-policy.d.ts
 type ToolRisk = "observe" | "mutate" | "irreversible" | "host-control";
 type ToolIdempotency = "none" | "supported" | "required";
-declare function requiresToolApproval(risk: ToolRisk): boolean;
 //#endregion
 //#region src/core/application/tool-execution/brokerage/tool-broker-ports.d.ts
 interface AuthorizationPolicyState {
@@ -374,6 +456,23 @@ declare class ToolExecutorInputRejected extends Error {
   readonly name = "ToolExecutorInputRejected";
 }
 //#endregion
+//#region src/core/application/tool-execution/brokerage/tool-broker.d.ts
+interface ToolBrokerOptions {
+  readonly approvals: ToolApprovalService;
+  readonly catalog: ToolCatalog;
+  readonly digest: ToolInputDigest;
+  readonly hostTools?: ReadonlyArray<ToolDescriptor>;
+  readonly operations?: ToolOperationLedger;
+  readonly policy: AuthorizationPolicyProvider;
+}
+interface ToolBroker {
+  execute(request: ToolExecutionRequest): Effect.Effect<unknown, unknown>;
+}
+declare class ToolInvocationDenied extends Error {
+  readonly name = "ToolInvocationDenied";
+}
+declare function createToolBroker(options: ToolBrokerOptions): ToolBroker;
+//#endregion
 //#region src/core/application/tool-execution/contracts/rivus-runtime-tool.d.ts
 declare const RIVUS_RUNTIME_TOOL_IDS: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
 type RivusRuntimeToolId = (typeof RIVUS_RUNTIME_TOOL_IDS)[number];
@@ -383,4 +482,5 @@ interface RivusRuntimeToolGrantSet {
 }
 declare function isRivusRuntimeToolId(value: string): value is RivusRuntimeToolId;
 //#endregion
-export { RegisteredRivusSkill as $, AgentModelContentObserver as A, RivusToolExecutionOrigin as B, InvocationMemoryAuthority as C, resolveInvocationAuthority as D, createInvocationAuthority as E, RivusMemoryAuthority as F, RivusToolIdempotency as G, RivusToolFactoryContext as H, RivusMemoryScope as I, ModelChangeBoundaryDeadlineError as J, RivusToolInputRejected as K, RivusResolvedToolDescriptor as L, AgentModelOutputObservation as M, RegisteredRivusTool as N, NormalizedAgentInvocation as O, RivusHostToolDescriptor as P, RunAdmissionOptions as Q, RivusToolDescriptor as R, InvocationAuthorityRef as S, InvocationToolGrantSet as T, RivusToolGrantSet as U, RivusToolExecutor as V, RivusToolGrantSetOperations as W, RunAdmission as X, ModelChangeClock as Y, RunAdmissionLease as Z, ToolRisk as _, AuthorizationPolicyProvider as a, ModelChangeExecutionBudget as at, InvocationAuthority as b, ToolApprovalService as c, ModelChangeRuntimeContext as ct, ToolExecutionContext as d, ModelReference as dt, RivusSkillDescriptor as et, ToolExecutionOrigin as f, ToolIdempotency as g, ToolExecutorInputRejected as h, isRivusRuntimeToolId as i, ModelChangeBudgetReservation as it, AgentModelInputObservation as j, normalizeAgentInvocation as k, ToolCatalog as l, ModelChangeRuntimePort as lt, ToolExecutor as m, RivusRuntimeToolGrantSet as n, ModelBinding as nt, AuthorizationPolicyState as o, ModelChangePaidCallKind as ot, ToolExecutionRequest as p, RivusToolRisk as q, RivusRuntimeToolId as r, ModelChangeActivationResult as rt, ToolApprovalRequest as s, ModelChangeRestoreResult as st, RIVUS_RUNTIME_TOOL_IDS as t, RivusSkillGrantSet as tt, ToolDescriptor as u, ModelChangeValidationResult as ut, requiresToolApproval as v, InvocationMemoryScope as w, InvocationAuthorityIdentity as x, InvalidInvocationAuthority as y, RivusToolExecutionContext as z };
+export { RivusMemoryScope as A, RivusToolRisk as B, NormalizedAgentInvocation as C, AgentModelContentObserver as D, ToolOperationRecord as E, RivusToolFactoryContext as F, RunAdmissionOptions as G, ModelChangeClock as H, RivusToolGrantSet as I, RivusSkillGrantSet as J, RegisteredRivusSkill as K, RivusToolGrantSetOperations as L, RivusToolDescriptor as M, RivusToolExecutionContext as N, RegisteredRivusTool as O, RivusToolExecutor as P, ModelReference as Q, RivusToolIdempotency as R, resolveInvocationAuthority as S, ToolOperationReconciliationAction as T, RunAdmission as U, ModelChangeBoundaryDeadlineError as V, RunAdmissionLease as W, ModelChangePaidCallKind as X, ModelBinding as Y, ModelChangeRuntimePort as Z, createToolInputDigest as _, ToolBroker as a, InvocationToolGrantSet as b, createToolBroker as c, ToolDescriptor as d, ToolExecutionContext as f, ToolInputDigest as g, ToolOperationLedger as h, isRivusRuntimeToolId as i, RivusResolvedToolDescriptor as j, RivusHostToolDescriptor as k, AuthorizationPolicyState as l, ToolExecutorInputRejected as m, RivusRuntimeToolGrantSet as n, ToolBrokerOptions as o, ToolExecutionRequest as p, RivusSkillDescriptor as q, RivusRuntimeToolId as r, ToolInvocationDenied as s, RIVUS_RUNTIME_TOOL_IDS as t, ToolApprovalRequest as u, InvalidInvocationAuthority as v, normalizeAgentInvocation as w, createInvocationAuthority as x, InvocationAuthorityRef as y, RivusToolInputRejected as z };
+export {};

package/dist/chunks/{tool-input-digest.js → tool-risk-policy.js}

@@ -1,8 +1,3 @@
-//#region src/core/application/tool-execution/contracts/rivus-tool.ts
-var RivusToolInputRejected = class extends Error {
-	name = "RivusToolInputRejected";
-};
-//#endregion
 //#region src/core/application/agent-execution/invocation/agent-invocation-identity.ts
 /**
 * Background-session conversationId is captured only from the explicit origin
@@ -67,11 +62,6 @@ function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 //#endregion
-//#region src/core/application/tool-execution/authority/tool-risk-policy.ts
-function requiresToolApproval(risk) {
-	return risk === "irreversible" || risk === "host-control";
-}
-//#endregion
 //#region src/core/application/tool-execution/brokerage/tool-input-digest.ts
 var InvalidStableJson = class extends Error {
 	name = "InvalidStableJson";
@@ -87,9 +77,6 @@ function createToolInputDigest(input, digest) {
 		throw error;
 	}
 }
-function normalizeStableJson(value) {
-	return JSON.parse(serializeStableJson(value, /* @__PURE__ */ new Set()));
-}
 function serializeStableJson(value, ancestors) {
 	if (value === null) return "null";
 	if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
@@ -116,4 +103,10 @@ function serializeStableJson(value, ancestors) {
 	}
 }
 //#endregion
-export { requiresToolApproval as a, resolveInvocationAuthority as c, normalizeStableJson as i, normalizeAgentInvocation as l, InvalidToolInput as n, InvalidInvocationAuthority as o, createToolInputDigest as r, createInvocationAuthority as s, InvalidStableJson as t, RivusToolInputRejected as u };
+//#region src/core/application/tool-execution/authority/tool-risk-policy.ts
+function requiresToolApproval(risk) {
+	return risk === "irreversible" || risk === "host-control";
+}
+//#endregion
+export { createInvocationAuthority as a, InvalidInvocationAuthority as i, InvalidToolInput as n, resolveInvocationAuthority as o, createToolInputDigest as r, normalizeAgentInvocation as s, requiresToolApproval as t };
+