effect-agent 0.1.0-beta.85 → 0.1.0-beta.87

package/dist/engine/RunOptions.mjs

@@ -0,0 +1,122 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { o as Selection } from "../ToolExposure-C93U1sPu.mjs";
+import { ChildRunUsage, UsageCompleteness } from "../core/Usage.mjs";
+import { RunPolicyUsage } from "../core/RunPolicyUsage.mjs";
+import { Context, Effect, Layer, Schema } from "effect";
+//#region src/engine/RunOptions.ts
+var RunOptions_exports = /* @__PURE__ */ __exportAll({
+	AgentUpdateAcceptance: () => AgentUpdateAcceptance,
+	CommandDrainPolicy: () => CommandDrainPolicy,
+	CurrentToolFailureObserver: () => CurrentToolFailureObserver,
+	ModelUsageAccounting: () => ModelUsageAccounting,
+	RunContextPreparation: () => RunContextPreparation,
+	RunContextPreparationPassthrough: () => RunContextPreparationPassthrough,
+	RunResumeUsageSchema: () => RunResumeUsageSchema,
+	RunSchedulingOverride: () => RunSchedulingOverride,
+	RunToolAuthorization: () => RunToolAuthorization,
+	RunToolScheduling: () => RunToolScheduling,
+	RunTurnResumeSettledCallSchema: () => RunTurnResumeSettledCallSchema,
+	toolFailureObserverLayer: () => toolFailureObserverLayer
+});
+/** Resolved once per Run; durable coordinators capture it at Layer acquisition. Default absent. */
+const CurrentToolFailureObserver = Context.Reference("@effect-agent/engine/CurrentToolFailureObserver", { defaultValue: () => void 0 });
+/** The sole installation seam, shared by ephemeral Runs and durable platform options. */
+const toolFailureObserverLayer = (observer) => Layer.succeed(CurrentToolFailureObserver)(observer);
+/** Number of queued inputs consumed at one documented Turn seam. */
+const CommandDrainPolicy = Schema.Literals(["one", "all"]);
+/**
+* Host-owned model-context preparation, independent of action-time Tool authorization.
+*
+* Runs use this service when provided; durable coordinators capture it while their runtime
+* Layer is acquired. Implementations acquire dependencies in their Layer and preserve the
+* declared error tags. Layer acquisition failures belong to the providing Effect, not this union.
+* Without this service, Runs apply no host context loading. Provide `ContextCompactor`
+* separately to select native compaction; neither service replaces `RunToolAuthorization`.
+*/
+var RunContextPreparation = class extends Context.Service()("@effect-agent/engine/RunContextPreparation") {};
+/** Explicit no-preparer Layer used by compatible runtime assemblies. */
+const RunContextPreparationPassthrough = Layer.succeed(RunContextPreparation)({});
+/**
+* Host action-time authority for native and programmatic application Tools. Implementations close over
+* their dependencies at Layer construction and return a denial when execution is not authorized.
+* Durable coordinators capture this service once and retain it across replacement Attempts.
+* Ephemeral Runs also resolve this service at their Run boundary. A typed per-run
+* `RunOptions.toolAuthorization` overrides it while retaining its own error and requirement channel.
+*/
+var RunToolAuthorization = class RunToolAuthorization extends Context.Service()("@effect-agent/engine/RunToolAuthorization") {
+	/** Explicit compatibility policy: Tool execution requires no additional host authorization. */
+	static allowAll = Layer.succeed(RunToolAuthorization, { authorize: () => Effect.succeed({ _tag: "allowed" }) });
+};
+/**
+* Attempt-local accounting for provider invocations without retained usage.
+* Staging is infallible and does not itself persist records. Durable runtime
+* composition supplies the canonical Turn accumulator; ephemeral entry points
+* explicitly supply the no-op implementation.
+*/
+var ModelUsageAccounting = class ModelUsageAccounting extends Context.Service()("@effect-agent/engine/ModelUsageAccounting") {
+	static layerEphemeral = Layer.succeed(ModelUsageAccounting, { noteIncompleteUsage: () => Effect.void });
+};
+/**
+* Accepts an interpreter-validated update before semantic publication. Durable hosts bind this
+* port to the emitting Attempt and return its canonical identity and sequence. Infrastructure
+* failures must also halt that Attempt before any subsequent event is committed.
+* Ephemeral entry points explicitly accept only into their Run-local event stream.
+*/
+var AgentUpdateAcceptance = class AgentUpdateAcceptance extends Context.Service()("@effect-agent/engine/AgentUpdateAcceptance") {
+	static layerEphemeral = Layer.succeed(AgentUpdateAcceptance, { accept: (update) => Effect.succeed(update) });
+};
+/**
+* One already-settled Tool Call of a Turn being resumed; injected without execution.
+*
+* The engine decodes this Schema at the recovery boundary before the value can
+* enter official history. The result remains the exact canonical JSON value
+* carried by the Tool message.
+*/
+const RunTurnResumeSettledCallSchema = Schema.Struct({
+	toolSelection: Schema.optionalKey(Selection),
+	id: Schema.NonEmptyString,
+	result: Schema.Json,
+	isFailure: Schema.Boolean,
+	/** Engine-owned rejection evidence; never inferred from the encoded result. */
+	budgetRejected: Schema.optionalKey(Schema.Literal(true))
+});
+/**
+* Canonical cumulative usage and Stop Policy accounting restored from prior Attempts.
+* Turns and declared Tool calls include a pending resumed batch. The failure
+* streak excludes that entire batch, whose terminal outcomes the engine folds once.
+* Programmatic reservations include pending work and are never refunded.
+*
+* Counts and microdollars are non-negative safe integers. The most recent
+* call cannot exceed its cumulative total. Every committed Turn has a model
+* call, and a failure streak cannot exceed the declared Tool call count.
+*/
+const RunResumeUsageSchema = Schema.Struct({
+	...RunPolicyUsage.fields,
+	modelCalls: Schema.Natural,
+	inputTokens: Schema.Natural,
+	outputTokens: Schema.Natural,
+	lastInputTokens: Schema.Natural,
+	lastOutputTokens: Schema.Natural,
+	costMicrousd: Schema.Natural,
+	usageStatus: Schema.optionalKey(UsageCompleteness),
+	pricingStatus: Schema.optionalKey(UsageCompleteness),
+	unobservedModelCalls: Schema.optionalKey(Schema.Natural),
+	/** Verified direct-child reports, deduplicated by Run ID across Attempts. */
+	children: Schema.optionalKey(Schema.Array(ChildRunUsage))
+}).check(Schema.makeFilter((usage) => usage.lastInputTokens <= usage.inputTokens && usage.lastOutputTokens <= usage.outputTokens, { expected: "last-call token usage no greater than cumulative token usage" }), Schema.makeFilter((usage) => usage.modelCalls >= usage.committedTurns && usage.consecutiveToolFailures <= usage.toolCalls, { expected: "model calls covering committed Turns and a failure streak within declared Tool calls" }));
+/** Run-level scheduler override; it may only make the Agent's finite bound stricter. */
+const RunSchedulingOverride = Schema.Union([Schema.Struct({
+	mode: Schema.Literal("bounded"),
+	concurrency: Schema.Int.check(Schema.isGreaterThan(0))
+}), Schema.Struct({ mode: Schema.Literal("sequential") })]);
+/**
+* Host Tool scheduling, captured by durable runtimes across replacement Attempts.
+* The Agent's admitted concurrency remains the upper bound. A sequential Tool
+* forms a barrier around neighboring parallel batches, including on recovery.
+* Ephemeral Runs may override this reference with `RunOptions.scheduling`.
+*/
+const RunToolScheduling = Context.Reference("@effect-agent/engine/RunToolScheduling", { defaultValue: () => ({}) });
+//#endregion
+export { AgentUpdateAcceptance, CommandDrainPolicy, CurrentToolFailureObserver, ModelUsageAccounting, RunContextPreparation, RunContextPreparationPassthrough, RunResumeUsageSchema, RunSchedulingOverride, RunToolAuthorization, RunToolScheduling, RunTurnResumeSettledCallSchema, RunOptions_exports as t, toolFailureObserverLayer };
+
+//# sourceMappingURL=RunOptions.mjs.map

package/dist/engine/RunOptions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunOptions.mjs","names":[],"sources":["../../src/engine/RunOptions.ts"],"sourcesContent":["import { type Cause, Effect, Context, type DateTime, Layer, Schema } from \"effect\";\nimport type { LanguageModel, Model, Prompt, Response } from \"effect/unstable/ai\";\n\nimport { type AnyDefinition } from \"../core/Agent.ts\";\nimport { type AgentInputError } from \"../core/AgentError.ts\";\nimport { type AgentPolicy } from \"../core/AgentPolicy.ts\";\nimport type { Update, UpdateError } from \"../core/AgentUpdates.ts\";\nimport {\n  type AgentId,\n  type ThreadId,\n  type DelegationId,\n  type ReceiptId,\n  type RunId,\n  type SubmissionId,\n  type ToolCallId,\n  type TurnId,\n} from \"../core/Identifiers.ts\";\nimport { type MemoryRecallError } from \"../core/MemoryReference.ts\";\nimport { RunPolicyUsage } from \"../core/RunPolicyUsage.ts\";\nimport {\n  type SubagentBudgetReservation,\n  type DelegationDepth,\n  type SubagentParentLink,\n  type SubagentGrant,\n  type ToolExecutionKind,\n} from \"../core/SubagentContract.ts\";\nimport type { Snapshot } from \"../core/ToolExposure.ts\";\nimport { Selection } from \"../core/ToolExposure.ts\";\nimport {\n  ChildRunUsage,\n  UsageCompleteness,\n  type RunTotals,\n  type ModelCallUsage,\n} from \"../core/Usage.ts\";\nimport type { WorkerBudgetScope, FrameworkMessage } from \"../core/Worker.ts\";\nimport type { CompactionError, ContextMessageTokenEstimator } from \"./ContextCompactor.ts\";\nimport type { ContextRolloverSelection, ModelCallContext } from \"./ContextWindow.ts\";\nimport type { RunStepHook, ToolExecutionClassValue } from \"./DurableStep.ts\";\n\n/** Live, trusted application diagnostics. Never persisted, transported, or automatically logged. */\ninterface ToolFailureIdentity {\n  readonly agentId: AgentId;\n  readonly threadId: ThreadId;\n  readonly runId: RunId;\n  readonly turnId: TurnId;\n  readonly toolName: string;\n  /** Best-effort error tag, with the existing `UnknownError` fallback. */\n  readonly tag: string;\n}\n\n/** A model-declared Handler returned a declared failure instead of failing the Run. */\nexport interface ModelToolFailure extends ToolFailureIdentity {\n  readonly _tag: \"ModelToolFailure\";\n  readonly kind: \"declared-failure\";\n  /** Raw provider identity, without the telemetry ID filter. */\n  readonly toolCallId: ToolCallId;\n  readonly executionClass: ToolExecutionClassValue;\n  readonly message?: never;\n  readonly cause?: never;\n}\n\ninterface ProgrammaticToolFailureIdentity extends ToolFailureIdentity {\n  readonly _tag: \"ProgrammaticToolFailure\";\n  /** `${parentToolCallId}#${sequenceIndex}`, raw and unique only within this in-memory pass. */\n  readonly toolCallId: string;\n  readonly parentToolCallId: ToolCallId;\n  /** Presence means the Handler started and consumed budget; side effects may exist. */\n  readonly sequenceIndex: number;\n  readonly executionClass: ToolExecutionClassValue;\n}\n\ninterface ProgrammaticDeclaredFailure extends ProgrammaticToolFailureIdentity {\n  readonly kind: \"declared-failure\";\n  readonly message?: never;\n  readonly cause?: never;\n}\n\ninterface ProgrammaticHandlerFailure extends ProgrammaticToolFailureIdentity {\n  readonly kind: \"handler-error\";\n  readonly message?: never;\n  /** The original, uncollapsed Cause captured before the broker's diagnostic projection. */\n  readonly cause: Cause.Cause<unknown>;\n}\n\ninterface ProgrammaticDiagnosticFailure extends ProgrammaticToolFailureIdentity {\n  readonly kind: \"infrastructure\" | \"protocol\";\n  /** At most 4096 UTF-8 bytes. Never a declared payload. */\n  readonly message: string;\n  /** Original Cause when one exists; never fabricated from a source-less rejection. */\n  readonly cause?: Cause.Cause<unknown> | undefined;\n}\n\n/** A programmatic Handler started and its failure became a broker outcome. */\nexport type ProgrammaticToolFailure =\n  | ProgrammaticDeclaredFailure\n  | ProgrammaticHandlerFailure\n  | ProgrammaticDiagnosticFailure;\n\n/** A programmatic invocation was rejected before its Handler started. No inner identity exists. */\nexport interface ProgrammaticPreflightFailure extends ToolFailureIdentity {\n  readonly _tag: \"ProgrammaticPreflightFailure\";\n  readonly kind: \"infrastructure\" | \"protocol\";\n  readonly parentToolCallId: ToolCallId;\n  /** Absent if the Tool could not be resolved. */\n  readonly executionClass?: ToolExecutionClassValue | undefined;\n  /** At most 4096 UTF-8 bytes. */\n  readonly message: string;\n  /** Original Cause only for Cause-backed rejection, never fabricated from an outcome. */\n  readonly cause?: Cause.Cause<unknown> | undefined;\n}\n\n/** Plain readonly interfaces, intentionally not persisted or transported Schemas (RUN-036). */\nexport type ToolFailureObservation =\n  | ModelToolFailure\n  | ProgrammaticToolFailure\n  | ProgrammaticPreflightFailure;\n\n/**\n * Trusted in-process observation of non-propagating application Tool failures (RUN-036).\n * Capture reporting dependencies before installation. Delivery is inline under the existing\n * Tool permit for started calls; preflight reporting is serialized per broker. Delivery is at\n * most once per in-memory attempt, with isolated observer/reporter defects.\n * External interruption may end delivery. Replacement Attempts may repeat IDs and observations.\n * Never reenter ToolBroker, RunEventSink, or Agent execution, or intentionally self-interrupt.\n */\nexport interface RunToolFailureObserver {\n  readonly observe: (observation: ToolFailureObservation) => Effect.Effect<void>;\n}\n\n/** Resolved once per Run; durable coordinators capture it at Layer acquisition. Default absent. */\nexport const CurrentToolFailureObserver = Context.Reference<RunToolFailureObserver | undefined>(\n  \"@effect-agent/engine/CurrentToolFailureObserver\",\n  { defaultValue: () => undefined },\n);\n\n/** The sole installation seam, shared by ephemeral Runs and durable platform options. */\nexport const toolFailureObserverLayer = (observer: RunToolFailureObserver): Layer.Layer<never> =>\n  Layer.succeed(CurrentToolFailureObserver)(observer);\n\n/** Number of queued inputs consumed at one documented Turn seam. */\nexport const CommandDrainPolicy = Schema.Literals([\"one\", \"all\"]);\nexport type CommandDrainPolicy = typeof CommandDrainPolicy.Type;\n\n/** Engine-normalized input command. Capability packages may adapt richer audit records to it. */\nexport interface RunInputCommand {\n  readonly kind: \"steering\" | \"follow-up\";\n  readonly input: Prompt.RawInput;\n}\n\n/**\n * Dependency-neutral input seam used by the interpreter.\n *\n * A capability adapter owns queue bounds and Scope finalization. The engine calls\n * `start` before the first drain, `drain` only at safe Turn seams, and `end`\n * exactly once when the Run leaves its Scope.\n */\nexport interface RunInputHook<Error = never, Requirements = never> {\n  readonly start?: (() => Effect.Effect<void, Error, Requirements>) | undefined;\n  readonly drain: (\n    policy: CommandDrainPolicy,\n  ) => Effect.Effect<ReadonlyArray<RunInputCommand>, Error, Requirements>;\n  readonly end?: (() => Effect.Effect<void, never, Requirements>) | undefined;\n}\n\n/** Decision returned by an ephemeral approval adapter. */\nexport type RunApprovalDecision =\n  | {\n      readonly _tag: \"approved\";\n      readonly reason?: string | undefined;\n    }\n  | {\n      readonly _tag: \"denied\";\n      readonly reason?: string | undefined;\n    }\n  | {\n      readonly _tag: \"unresolved\";\n      readonly reason?: string | undefined;\n    };\n\n/** Native Effect AI approval request enriched with stable Run identities. */\nexport interface RunApprovalRequest {\n  readonly request: Response.ToolApprovalRequestPart;\n  readonly threadId: ThreadId;\n  readonly runId: RunId;\n  readonly turnId: TurnId;\n  readonly toolCallId: ToolCallId;\n  readonly toolName: string;\n  readonly parameters: unknown;\n}\n\n/** Dependency-neutral approval decision hook. */\nexport interface RunApprovalHook<Error = never, Requirements = never> {\n  readonly request: (\n    request: RunApprovalRequest,\n  ) => Effect.Effect<RunApprovalDecision, Error, Requirements>;\n}\n\n/** Input passed to ordered context transformation and compaction adapters. */\nexport interface RunContextRequest {\n  readonly threadId: ThreadId;\n  readonly runId: RunId;\n  readonly turnId: TurnId;\n  readonly turn: number;\n  /**\n   * Official engine history for this Attempt before context preparation. The\n   * engine never replaces or mutates this value. Durable prompt\n   * reconstruction can produce a different model-visible basis afterward, so\n   * adapters that need canonical retrieval should key it by the supplied Run\n   * identities rather than infer durable state from this Prompt alone.\n   */\n  readonly source: Prompt.Prompt;\n  /**\n   * The exact model-visible final-output contract the engine appends to the\n   * prepared prompt after this hook returns (RUN-028), or\n   * undefined when the definition's output Schema cannot render to JSON\n   * Schema. Exposed so a limit-targeting adapter can reserve the contract's\n   * overhead in its own window calculation; the hook can size for the\n   * contract but cannot remove or alter it.\n   */\n  readonly outputContract?: string | undefined;\n}\n\n/**\n * One captured provider configuration and its context bounds. Build the native Model Layer\n * from the same resolved values as context; do not defer route selection inside its requests.\n * Capture provider requirements in the preparation Layer. The engine acquires this closed\n * Layer once per Turn and keeps it through compaction, dispatch, accounting, and overflow retry.\n */\nexport interface ResolvedModelCall {\n  readonly model: Layer.Layer<LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName>;\n  readonly context: ModelCallContext;\n  /**\n   * The selected provider's native Tool schema transformer, such as toCodecOpenAI or\n   * toCodecAnthropic. Omission uses generic JSON Schema and is suitable only when the provider\n   * does not rewrite schemas. Select it from the same captured configuration as the Model Layer.\n   * Provider-defined Tools count their native name/configuration arguments instead; their\n   * provider-generated call parameter schemas are never transformed into function declarations.\n   */\n  readonly toolSchemaTransformer?: LanguageModel.CodecTransformer | undefined;\n  /**\n   * Replace the entire estimate of a message, including its framing, with a non-negative finite\n   * integer. Undefined uses the native structural estimate for that message. Capture any model\n   * or content-specific reservation before returning this callback; it must be deterministic for\n   * copied message content and same-Turn retries, without consulting mutable provider state.\n   * The engine shares it across admission, built-in compaction sizing, and default summaries.\n   * Do not also charge a replaced message through uncountedOverheadTokens.\n   */\n  readonly estimateMessageTokens?: ContextMessageTokenEstimator | undefined;\n}\n\n/** Prepared model-only context returned by a context adapter. */\nexport interface PreparedRunContext {\n  /** Replace non-pinned registered native Tools at this Turn boundary. */\n  readonly toolSelection?: Selection | undefined;\n  readonly prompt: Prompt.Prompt;\n  /** Resolves actual model selection and admission together, once at this Turn boundary. */\n  readonly modelCall?: ResolvedModelCall | undefined;\n  /**\n   * Start a fresh native context window even below capacity. Coverage must map to a complete\n   * canonical prefix for durable Runs and cannot discard protected input or split Tool pairs.\n   * Omit through to select prior history before this Run's protected instructions/input; this\n   * is a no-op when no prior prefix remains, including after a committed reset is recovered.\n   * Leave the source prefix intact; the engine commits and applies the selected rollover.\n   */\n  readonly rollover?: ContextRolloverSelection | undefined;\n}\n\n/**\n * Model-only prompt transformation. Compaction requires a safely mapped original\n * instruction/input block and content-equivalent covered prefixes across Turns.\n * Incompatible changes fail with CompactionError before compaction or model I/O.\n */\nexport interface RunContextHook<Error = never, Requirements = never> {\n  /**\n   * Resources acquired by `prepare` belong to the current Turn and close before\n   * the next Turn starts. Acquire resources shared across Turns in a surrounding\n   * Run Layer or Scope instead.\n   */\n  readonly prepare: (\n    request: RunContextRequest,\n  ) => Effect.Effect<PreparedRunContext, Error, Requirements>;\n}\n\n/**\n * Supplies model-visible reference context for one Turn without changing the\n * prompt that compaction covers or the history that the engine commits.\n *\n * The engine treats the returned input as untrusted, validates it before\n * provider I/O, and includes it in the Turn's context and completion-reserve\n * admission. It never passes this input to the compaction summary Model. A\n * same-Turn provider-overflow retry reuses the loaded snapshot. Return an\n * empty Prompt when the Turn needs no references.\n */\nexport interface RunTransientContextHook<Error = never, Requirements = never> {\n  readonly load: (\n    request: RunContextRequest,\n  ) => Effect.Effect<Prompt.RawInput, Error, Requirements>;\n}\n\n/** Context service failures retain their concrete tags and structured fields. */\nexport type RunContextPreparationError = AgentInputError | MemoryRecallError | CompactionError;\n\n/**\n * One usage delta. Turn-boundary consumption charges `modelCalls: 1` after a\n * complete response and before any Tool starts; the programmatic Tool broker\n * charges `modelCalls: 0, toolCalls: 1` before each inner handler starts\n * (RUN-017).\n */\nexport interface RunUsageDelta {\n  readonly modelCalls: 0 | 1;\n  readonly inputTokens: number;\n  readonly outputTokens: number;\n  readonly totalTokens: number;\n  readonly toolCalls: number;\n  readonly costMicrousd: number;\n  readonly usage: Response.Usage;\n  /** Present for model-call deltas; absent for programmatic Tool-only charges. */\n  readonly modelUsage?: ModelCallUsage | undefined;\n}\n\n/** Stable pricing identity returned alongside a host's microdollar estimate. */\nexport interface RunCostEstimate {\n  readonly costMicrousd: number;\n  readonly serviceTier?: string | undefined;\n  readonly pricingVersion?: string | undefined;\n  /** Unknown estimates do not prove a free call and fail an explicit cost budget after usage is retained. */\n  readonly pricingStatus?: \"estimated\" | \"unknown\" | undefined;\n}\n\n/** A number preserves the original estimator API; the object form adds pricing provenance. */\nexport type RunCostEstimateValue = number | RunCostEstimate;\n\n/** Model identity presented beside the legacy raw-usage estimator argument. */\nexport interface RunCostEstimateRequest {\n  readonly provider: string;\n  /** Configured binding identity; only response.model identifies the returned model. */\n  readonly model: string;\n  readonly usage: Response.Usage;\n  /** Actual provider response fields, never the configured binding name. */\n  readonly response?:\n    | {\n        readonly id?: string | undefined;\n        readonly model?: string | undefined;\n      }\n    | undefined;\n  /** Native Effect AI provider metadata, runtime-only; HTTP details are excluded. */\n  readonly finishMetadata?: Response.FinishPart[\"metadata\"] | undefined;\n  readonly purpose?: \"turn\" | \"summary\" | undefined;\n}\n\n/**\n * Host-owned price lookup; durable hosts close every dependency before installing it. Raw usage\n * remains the first argument for source and runtime compatibility with the original estimator API.\n */\nexport type RunCostEstimator<Error = never, Requirements = never> = (\n  usage: Response.Usage,\n  request: RunCostEstimateRequest,\n) => Effect.Effect<RunCostEstimateValue, Error, Requirements>;\n\n/**\n * Dependency-neutral hierarchical budget hook. A typed failure at a Turn-seam\n * consumption or a stream-guard pull stops the Run. A mid-pass programmatic\n * consumption failure instead becomes that call's outcome (RUN-017 —\n * exhaustion prevents the call): the Run still stops at the next Turn seam,\n * because the following model call's `consume` and the guarded stream pulls\n * re-enforce the same budget.\n */\nexport interface RunBudgetHook<Error = never, Requirements = never> {\n  /**\n   * Guard one active model or Tool stream pull. Hierarchical budget adapters\n   * use an absolute deadline so repeated pulls share one duration allowance.\n   */\n  readonly guard: <A, E, R>(\n    effect: Effect.Effect<A, E, R>,\n  ) => Effect.Effect<A, E | Error, R | Requirements>;\n  readonly consume: (delta: RunUsageDelta) => Effect.Effect<void, Error, Requirements>;\n}\n\n/**\n * One application Tool Call of a completed Turn as the durable runtime sees\n * it: stable identity, the encoded (wire-form) parameters exactly as official\n * history carries them, and the Tool's declared execution class (fail-closed\n * `\"uncertain\"` for unannotated Tools).\n */\nexport interface RunToolCallDescriptor {\n  readonly toolCallId: ToolCallId;\n  readonly toolName: string;\n  /** Encoded JSON parameters — the same value official history and canonical records carry. */\n  readonly parameters: unknown;\n  readonly executionClass: ToolExecutionClassValue;\n  /** Definition-owned classification; never inferred from the Tool name. */\n  readonly executionKind: ToolExecutionKind;\n}\n\n/** Decision returned by a host's action-time Tool authorization policy. */\nexport type RunToolAuthorizationDecision =\n  | { readonly _tag: \"allowed\" }\n  | { readonly _tag: \"denied\"; readonly reason: string };\n\n/**\n * Exact authority presented before one application Tool Handler may start.\n *\n * `input` is the Agent Schema's encoded Run input. Durable coordinators replace it with the exact\n * canonical Submission input admitted for the logical Run on every Attempt.\n * `call` is the exact still-executable call being authorized. Recorded settled calls are never\n * reauthorized because no Handler can start for them.\n */\nexport interface RunToolAuthorizationRequest {\n  readonly frameworkMessage?: FrameworkMessage;\n  readonly threadId: ThreadId;\n  readonly runId: RunId;\n  readonly turnId: TurnId;\n  readonly turn: number;\n  readonly input: unknown;\n  readonly call: RunToolCallDescriptor;\n  /** Present for an ephemeral inner invocation; the outer Tool's approval grants no inner authority. */\n  readonly programmatic?:\n    | {\n        readonly parentToolCallId: ToolCallId;\n        readonly sequenceIndex: number;\n      }\n    | undefined;\n}\n\n/** Host policy invoked before each executable native or programmatic application call. */\nexport interface RunToolAuthorizationHook<Error = never, Requirements = never> {\n  readonly authorize: (\n    request: RunToolAuthorizationRequest,\n  ) => Effect.Effect<RunToolAuthorizationDecision, Error, Requirements>;\n}\n\n/**\n * Host-owned model-context preparation, independent of action-time Tool authorization.\n *\n * Runs use this service when provided; durable coordinators capture it while their runtime\n * Layer is acquired. Implementations acquire dependencies in their Layer and preserve the\n * declared error tags. Layer acquisition failures belong to the providing Effect, not this union.\n * Without this service, Runs apply no host context loading. Provide `ContextCompactor`\n * separately to select native compaction; neither service replaces `RunToolAuthorization`.\n */\nexport class RunContextPreparation extends Context.Service<\n  RunContextPreparation,\n  {\n    /** Optional transformation of the model-visible prompt. */\n    readonly hook?: RunContextHook<RunContextPreparationError, never> | undefined;\n    /** Optional per-Turn reference context, excluded from history and compaction coverage. */\n    readonly transientContext?:\n      | RunTransientContextHook<RunContextPreparationError, never>\n      | undefined;\n  }\n>()(\"@effect-agent/engine/RunContextPreparation\") {}\n\n/** Explicit no-preparer Layer used by compatible runtime assemblies. */\nexport const RunContextPreparationPassthrough: Layer.Layer<RunContextPreparation> = Layer.succeed(\n  RunContextPreparation,\n)({});\n\n/**\n * Host action-time authority for native and programmatic application Tools. Implementations close over\n * their dependencies at Layer construction and return a denial when execution is not authorized.\n * Durable coordinators capture this service once and retain it across replacement Attempts.\n * Ephemeral Runs also resolve this service at their Run boundary. A typed per-run\n * `RunOptions.toolAuthorization` overrides it while retaining its own error and requirement channel.\n */\nexport class RunToolAuthorization extends Context.Service<\n  RunToolAuthorization,\n  RunToolAuthorizationHook\n>()(\"@effect-agent/engine/RunToolAuthorization\") {\n  /** Explicit compatibility policy: Tool execution requires no additional host authorization. */\n  static readonly allowAll: Layer.Layer<RunToolAuthorization> = Layer.succeed(\n    RunToolAuthorization,\n    { authorize: () => Effect.succeed({ _tag: \"allowed\" }) },\n  );\n}\n\n/**\n * Payload of one durable response commit: the completed Turn's identity, its\n * response messages in official (encoded) form, and every application Tool\n * Call it declared. The engine invokes it only for Turns that declare\n * application Tool Calls; no-tool Turns keep their late single-batch commit.\n */\nexport interface RunTurnResponseCommit {\n  readonly toolExposure?: Snapshot | undefined;\n  readonly turn: number;\n  readonly turnId: TurnId;\n  /** The Turn's response messages in official history form (encoded Tool parameters). */\n  readonly responseMessages: Prompt.Prompt;\n  readonly calls: ReadonlyArray<RunToolCallDescriptor>;\n}\n\n/**\n * One compaction decision the engine applied to its model-visible view\n * (RUN-026). The durable coordinator maps the covered source prefix to complete canonical\n * records, including settled current-Run batches for rollover. It must never infer a wider cutoff\n * from policy or token estimates.\n */\nexport interface RunCompactionCommit {\n  readonly turn: number;\n  /** Exact pre-compaction source and exclusive message bound; live values, never persisted. */\n  readonly source: Prompt.Prompt;\n  readonly through: number;\n  readonly kind: \"clear-tool-results\" | \"summarize\" | \"rollover\";\n  /** Present exactly when `kind` is `\"summarize\"`. */\n  readonly summary?: string | undefined;\n  /** Optional continuation state for a rollover; never a generated summary. */\n  readonly handoff?: string | undefined;\n  readonly tokensBeforeEstimate: number;\n  readonly tokensAfterEstimate: number;\n}\n\n/** One completed model call's provider-reported usage, staged for the Turn's canonical commit. */\nexport interface RunTurnUsage {\n  readonly turn: number;\n  readonly usage: ModelCallUsage;\n}\n\n/**\n * Attempt-local accounting for provider invocations without retained usage.\n * Staging is infallible and does not itself persist records. Durable runtime\n * composition supplies the canonical Turn accumulator; ephemeral entry points\n * explicitly supply the no-op implementation.\n */\nexport class ModelUsageAccounting extends Context.Service<\n  ModelUsageAccounting,\n  { readonly noteIncompleteUsage: (turn: number) => Effect.Effect<void> }\n>()(\"@effect-agent/engine/ModelUsageAccounting\") {\n  static readonly layerEphemeral = Layer.succeed(ModelUsageAccounting, {\n    noteIncompleteUsage: () => Effect.void,\n  });\n}\n\n/**\n * Accepts an interpreter-validated update before semantic publication. Durable hosts bind this\n * port to the emitting Attempt and return its canonical identity and sequence. Infrastructure\n * failures must also halt that Attempt before any subsequent event is committed.\n * Ephemeral entry points explicitly accept only into their Run-local event stream.\n */\nexport class AgentUpdateAcceptance extends Context.Service<\n  AgentUpdateAcceptance,\n  { readonly accept: (update: Update) => Effect.Effect<Update, UpdateError> }\n>()(\"@effect-agent/engine/AgentUpdateAcceptance\") {\n  static readonly layerEphemeral = Layer.succeed(AgentUpdateAcceptance, {\n    accept: (update) => Effect.succeed(update),\n  });\n}\n\n/**\n * Dependency-neutral durability seam implemented by a durable coordinator.\n *\n * Invocation ordering inside one Tool-declaring Turn is normative:\n * `commitResponse` fires after the finish part's continuation validations and staged canonical\n * provider/Turn events have been emitted, but before approval preflight (making the response\n * canonical before any Tool work — the provably-safe resume window); `prepareToolCalls` fires after\n * every approval and host authorization resolved allowed and before any handler acquires a\n * scheduler permit, with all delegations and non-`readonly` ordinary calls (it is skipped\n * entirely when no call needs preparation); `step` persists Durable Step\n * results mid-flight. When the hook is absent the engine behaves exactly as\n * the ephemeral runtime always has.\n */\nexport interface RunDurabilityHook<Error = never, Requirements = never> {\n  /** Stage the exact request declarations for the existing canonical response append. */\n  readonly noteToolExposure?:\n    | ((turn: number, snapshot: Snapshot) => Effect.Effect<void, Error, Requirements>)\n    | undefined;\n  /**\n   * Reserve cumulative programmatic calls and grace finalization before external execution.\n   * Calls are serialized across the Run. A committed reservation\n   * is never refunded, even if ownership is lost before the Handler or model starts.\n   * Coordinators must append fenced, schema-backed records before returning.\n   */\n  readonly reservePolicyUsage?:\n    | ((\n        usage: Pick<RunPolicyUsage, \"programmaticToolCalls\" | \"finalizationUsed\">,\n      ) => Effect.Effect<void, Error, Requirements>)\n    | undefined;\n  /** After validated staged response events are emitted, before approval preflight. */\n  readonly commitResponse: (\n    commit: RunTurnResponseCommit,\n  ) => Effect.Effect<void, Error, Requirements>;\n  /** After every approval and host authorization resolved allowed, before any handler starts. */\n  readonly prepareToolCalls: (\n    calls: ReadonlyArray<RunToolCallDescriptor>,\n  ) => Effect.Effect<void, Error, Requirements>;\n  readonly step: RunStepHook<Error, Requirements>;\n  /**\n   * RUN-026: called at the pre-Turn seam BEFORE the engine applies a\n   * compaction to its model-visible view or starts the model call whose\n   * prompt reflects it, so a crash between the two resumes onto the compacted\n   * projection. Required by the durability protocol: a coordinator that\n   * silently dropped the record would let the engine use a compacted prompt\n   * that recovery cannot reproduce. Reject unpersistable decisions in the typed\n   * error channel; success means the same replacement and coverage are durable.\n   */\n  readonly commitCompaction: (\n    commit: RunCompactionCommit,\n  ) => Effect.Effect<void, Error, Requirements>;\n  /**\n   * RUN-023: stage one completed model call's usage for the Turn's canonical\n   * commit (the response record carries it for resume re-seeding). Staging is\n   * not itself a durable mutation, but the member is required by the\n   * durability protocol: dropping it writes response records without the\n   * usage a later Attempt needs, so ownership changes would silently reset\n   * token budgets instead of failing closed.\n   */\n  readonly noteTurnUsage: (usage: RunTurnUsage) => Effect.Effect<void, Error, Requirements>;\n}\n\n/**\n * `DefinitionDigests`-shaped digests of one child Agent Binding in plain\n * string form. The durable coordinator's thread-owned digest Schema never\n * crosses inward: the coordinator resolves these digests from the exact\n * registered target and stores and verifies them\n * byte-for-byte (SUB-023 exact-digest binding resolution).\n */\nexport interface RunSubagentDigests {\n  readonly agent: string;\n  readonly model: string;\n  readonly tools: string;\n}\n\n/**\n * Establishment request assembled by a delegation Tool handler for the\n * durable coordinator, expressed strictly\n * in core/engine vocabulary. The coordinator derives everything else\n * deterministically: reservation identity from `(parentRunId, toolCallId)`,\n * child Thread/Submission identity and the admission idempotency key\n * from the parent Run and Tool Call pair, the child principal from the parent\n * Submission, and digests of the encoded input/grant/allocation values (it\n * owns the canonical digest authority). Establishment is idempotent by\n * construction (SUB-016): replaying the identical request converges on the\n * one existing child.\n */\nexport interface RunSubagentEstablishRequest {\n  /** Resolved child defaults and ceilings, fixed before admission and restored on recovery. */\n  readonly policy?: AgentPolicy | undefined;\n  readonly budget?: SubagentBudgetReservation | undefined;\n  readonly toolCallId: ToolCallId;\n  readonly delegationId: DelegationId;\n  readonly targetAgentId: AgentId;\n  /** The child Run's root-relative delegation depth (S2 fixes the ceiling at 1). */\n  readonly depth: DelegationDepth;\n  /** Exact target Definition from the capability; the host resolves its existing registration. */\n  readonly target?: AnyDefinition | undefined;\n  /** Explicit low-level binding override. If a target is supplied, this must match its registration. */\n  readonly targetDigests?: RunSubagentDigests | undefined;\n  /** The prepared child input in encoded (wire) form; it rides the canonical request record so recovery admission never needs a live handler. */\n  readonly encodedChildInput: unknown;\n  /** The delegation's authority ceiling in encoded form. */\n  readonly encodedGrant: unknown;\n  /** The per-invocation budget allocation in encoded form (opaque to the engine and to storage adapters). */\n  readonly encodedAllocation: unknown;\n  /** Tightening-only child Tool Call bound, clamped to the reservation and Definition by the caller. */\n  readonly toolCallAllowance?: number | undefined;\n}\n\n/** Durable identity of one established attached child, in core vocabulary. */\nexport interface RunSubagentChildIdentity {\n  readonly childThreadId: ThreadId;\n  readonly childSubmissionId: SubmissionId;\n  readonly childRunId: RunId;\n  /** The child Receipt: establishment is never durable-visible before it exists (SUB-017). */\n  readonly receiptId: ReceiptId;\n}\n\n/** The established child has not settled; the parent must suspend, never poll or respawn (SUB-018). */\nexport interface ChildEstablishWaiting extends RunSubagentChildIdentity {\n  readonly _tag: \"waiting\";\n}\n\n/**\n * The established child already has a verified canonical Settlement. The\n * coordinator verified Parent Link, target, digests, and settlement identity\n * fail-closed before returning it; `encodedResult` is the Schema-encoded\n * child terminal output for `completed` and the coordinator's bounded\n * `{errorTag, message}` failure projection otherwise — never a raw Cause.\n */\nexport interface ChildEstablishSettled extends RunSubagentChildIdentity {\n  readonly _tag: \"settled\";\n  /** Verified canonical usage; absence denotes legacy or unavailable evidence. */\n  readonly usage?: RunTotals;\n  readonly delegatedUsage?: RunTotals;\n  readonly outcome: \"completed\" | \"failed\" | \"aborted\";\n  readonly encodedResult: unknown;\n  /**\n   * Present when the child's durable Settlement carries the honest\n   * exhaustion marker (RUN-011/RUN-018): the child completed through the\n   * final-answer resolution, so its output is a budget-truncated partial.\n   */\n  readonly finishReason?: \"budget-exhausted\" | undefined;\n}\n\n/**\n * Establishment was refused or failed verification fail-closed (typed, bounded;\n * never a raw Cause). No further establishment attempt is made for this call.\n */\nexport interface ChildEstablishDenied {\n  readonly _tag: \"denied\";\n  readonly errorTag: string;\n  readonly message: string;\n}\n\n/** Result of one idempotent durable child establishment attempt. */\nexport type ChildEstablishStatus =\n  | ChildEstablishWaiting\n  | ChildEstablishSettled\n  | ChildEstablishDenied;\n\n/**\n * One settlement join handed back to the coordinator by the delegation\n * handler after it decoded the verified child output and applied its bounded\n * result/failure projection. The coordinator appends `SubagentJoined` and the\n * parent `ToolCallSettled` as ONE atomic canonical batch (SUB-019) and then\n * applies the accounting decision through the idempotent reservation-release\n * transitions.\n */\nexport interface RunSubagentJoinRequest {\n  readonly toolCallId: ToolCallId;\n  /** The encoded parent Tool result exactly as the Tool message will carry it. */\n  readonly encodedResult: unknown;\n  readonly isFailure: boolean;\n  /** Final consumed/released accounting decision per budget dimension (opaque encoded policy math owned by the delegation capability). */\n  readonly encodedAccounting: unknown;\n}\n\n/**\n * Dependency-neutral durable-Subagent seam implemented by a durable\n * coordinator (S2 plan §2 option c) and consumed by the delegation Tool\n * handler through the engine-provided per-batch `SubagentDurability` service.\n *\n * `establish` performs (or replays) child establishment\n * under the parent's ownership fence and reports where\n * the one child stands; `join` atomically commits the verified settlement\n * join. When the hook is absent the engine provides the explicit\n * ephemeral-mode service and the S1 in-process spawn semantics apply honestly\n * — absence means no durable claim is being made.\n */\nexport interface RunSubagentHook<Error = never, Requirements = never> {\n  readonly establish: (\n    request: RunSubagentEstablishRequest,\n  ) => Effect.Effect<ChildEstablishStatus, Error, Requirements>;\n  readonly join: (request: RunSubagentJoinRequest) => Effect.Effect<void, Error, Requirements>;\n}\n\n/** One declared Tool Call of a Turn being resumed, in canonical encoded form. */\nexport interface RunTurnResumeCall {\n  readonly id: string;\n  readonly name: string;\n  /** Canonical encoded parameters; re-validated through the Tool's parameter Schema before anything executes. */\n  readonly params: unknown;\n  /** Provider calls must have a canonical settled result and are never dispatched locally. */\n  readonly providerExecuted?: boolean;\n}\n\n/**\n * One already-settled Tool Call of a Turn being resumed; injected without execution.\n *\n * The engine decodes this Schema at the recovery boundary before the value can\n * enter official history. The result remains the exact canonical JSON value\n * carried by the Tool message.\n */\nexport const RunTurnResumeSettledCallSchema = Schema.Struct({\n  toolSelection: Schema.optionalKey(Selection),\n  id: Schema.NonEmptyString,\n  result: Schema.Json,\n  isFailure: Schema.Boolean,\n  /** Engine-owned rejection evidence; never inferred from the encoded result. */\n  budgetRejected: Schema.optionalKey(Schema.Literal(true)),\n});\n\nexport type RunTurnResumeSettledCall = typeof RunTurnResumeSettledCallSchema.Type;\n\n/**\n * Canonical cumulative usage and Stop Policy accounting restored from prior Attempts.\n * Turns and declared Tool calls include a pending resumed batch. The failure\n * streak excludes that entire batch, whose terminal outcomes the engine folds once.\n * Programmatic reservations include pending work and are never refunded.\n *\n * Counts and microdollars are non-negative safe integers. The most recent\n * call cannot exceed its cumulative total. Every committed Turn has a model\n * call, and a failure streak cannot exceed the declared Tool call count.\n */\nexport const RunResumeUsageSchema = Schema.Struct({\n  ...RunPolicyUsage.fields,\n  modelCalls: Schema.Natural,\n  inputTokens: Schema.Natural,\n  outputTokens: Schema.Natural,\n  lastInputTokens: Schema.Natural,\n  lastOutputTokens: Schema.Natural,\n  costMicrousd: Schema.Natural,\n  usageStatus: Schema.optionalKey(UsageCompleteness),\n  pricingStatus: Schema.optionalKey(UsageCompleteness),\n  unobservedModelCalls: Schema.optionalKey(Schema.Natural),\n  /** Verified direct-child reports, deduplicated by Run ID across Attempts. */\n  children: Schema.optionalKey(Schema.Array(ChildRunUsage)),\n}).check(\n  Schema.makeFilter(\n    (usage) =>\n      usage.lastInputTokens <= usage.inputTokens && usage.lastOutputTokens <= usage.outputTokens,\n    {\n      expected: \"last-call token usage no greater than cumulative token usage\",\n    },\n  ),\n  Schema.makeFilter(\n    (usage) =>\n      usage.modelCalls >= usage.committedTurns && usage.consecutiveToolFailures <= usage.toolCalls,\n    {\n      expected:\n        \"model calls covering committed Turns and a failure streak within declared Tool calls\",\n    },\n  ),\n);\n\nexport type RunResumeUsage = typeof RunResumeUsageSchema.Type;\n\n/**\n * Resume one canonically declared Tool batch without re-invoking the model.\n *\n * When present, the engine's first Turn skips the model request entirely: the\n * declared calls are re-validated through their Tool parameter Schemas (a\n * decode failure executes nothing), approval preflight runs against recorded\n * decisions, host Tool authorization is re-evaluated, `prepareToolCalls` replays the full\n * prepared batch idempotently,\n * calls listed in `settled` are injected as final results without starting\n * their handlers, and only the remaining open calls execute. The Run then\n * proceeds through the normal continuation.\n */\nexport interface RunTurnResume {\n  readonly toolExposure?: Snapshot | undefined;\n  readonly turn: number;\n  readonly turnId: TurnId;\n  readonly calls: ReadonlyArray<RunTurnResumeCall>;\n  readonly settled: ReadonlyArray<RunTurnResumeSettledCall>;\n  /**\n   * The pending Turn's committed LEADING messages — the messages the durable\n   * coordinator committed inside the pending Turn's canonical response record\n   * BEFORE the assistant tool-call message (Turn-1 evaluated instructions +\n   * input, or steering drained at the prior seam). A resumed Attempt's\n   * canonical prompt boundary excludes the pending Turn entirely, so without\n   * this field those messages would be absent from the resumed Run's live\n   * model context. When present the engine threads them into official history\n   * between the re-evaluated initial prompt and the rebuilt assistant\n   * tool-call message. Optional: absent keeps the prior behavior byte-for-byte.\n   */\n  readonly leadingMessages?: Prompt.Prompt | undefined;\n  /**\n   * The pending Turn's canonical assistant response, including text, reasoning and provider\n   * options. Durable hosts pass the decoded response after its leading messages. Execution\n   * still uses the independently validated `calls`; this exact response enters history instead\n   * of reconstructing it from call descriptors that cannot preserve every provider field.\n   */\n  readonly responseMessages?: Prompt.Prompt | undefined;\n}\n\n/** Run-level scheduler override; it may only make the Agent's finite bound stricter. */\nexport const RunSchedulingOverride = Schema.Union([\n  Schema.Struct({\n    mode: Schema.Literal(\"bounded\"),\n    concurrency: Schema.Int.check(Schema.isGreaterThan(0)),\n  }),\n  Schema.Struct({ mode: Schema.Literal(\"sequential\") }),\n]);\n\nexport type RunSchedulingOverride = typeof RunSchedulingOverride.Type;\n\n/** Dependency-neutral scheduling policy surrounding native Effect AI Tool handlers. */\nexport interface RunSchedulingHook {\n  readonly runOverride?: RunSchedulingOverride | undefined;\n  readonly toolRequiresSequential?: ((toolName: string) => boolean) | undefined;\n}\n\n/**\n * Host Tool scheduling, captured by durable runtimes across replacement Attempts.\n * The Agent's admitted concurrency remains the upper bound. A sequential Tool\n * forms a barrier around neighboring parallel batches, including on recovery.\n * Ephemeral Runs may override this reference with `RunOptions.scheduling`.\n */\nexport const RunToolScheduling = Context.Reference<RunSchedulingHook>(\n  \"@effect-agent/engine/RunToolScheduling\",\n  { defaultValue: () => ({}) },\n);\n\n/**\n * Tightening-only memory limits for one Run. The engine supplies finite ceilings for every field;\n * callers may lower them for a deployment or test but cannot widen the engine defaults.\n */\nexport interface RunBufferLimits {\n  /** Maximum decoded response parts retained from one model call, including compaction calls. */\n  readonly maxModelResponseParts?: number | undefined;\n  /** Maximum conservative retained-byte estimate for one model response. */\n  readonly maxModelResponseBytes?: number | undefined;\n  /** Maximum semantic Run events, including the reserved terminal event. */\n  readonly maxRunEvents?: number | undefined;\n  /**\n   * Maximum cumulative UTF-8 JSON bytes in published ToolProgress results, including provider\n   * progress and detached replay. Defaults to 8 MiB. Invalid or oversized application progress\n   * fails with ModelProtocolError; terminal Tool results use the Agent's toolResultBounds.\n   */\n  readonly maxToolProgressBytes?: number | undefined;\n  /** Maximum Subagent lifecycle payloads queued by one Tool batch. */\n  readonly maxSubagentEventsPerBatch?: number | undefined;\n}\n\n/**\n * Per-Run values and advanced integration hooks. ThreadHistory.layer retains history\n * incrementally in memory, including completed updates before a failure or interruption.\n * PersistentHistory.layer commits only successful Runs to a ThreadStore. Hook failures and\n * requirements stay visible in the returned Stream / Effect through the generic parameters.\n */\nexport interface RunOptions<HookError = never, HookRequirements = never> {\n  /** Finite per-Run limits: accepted update count and cumulative UTF-8 JSON value bytes. Defaults: 32 and 16384. */\n  readonly updates?: { readonly maxCount?: number; readonly maxBytes?: number };\n\n  /** Host-validated worker message; application input still supplies instructions and policy context. */\n  readonly frameworkMessage?: FrameworkMessage;\n\n  /** Initial or canonically restored run-scoped native selection. */\n  readonly toolSelection?: Selection | undefined;\n  /**\n   * Host preparation boundary before each new model Turn, including its context preparation\n   * and compaction calls. The preceding Tool batch and history advance have finished. A resumed\n   * canonical Tool batch bypasses this hook until it continues to a new Turn. This hook does not\n   * reset the Run deadline or change prompt protection, and is not automatically inherited by spawned children.\n   * Resources acquired here close with the current Turn, before the next Turn starts.\n   */\n  readonly beforeTurn?: (() => Effect.Effect<void, HookError, HookRequirements>) | undefined;\n  /** Reuse a Thread identity, including retained history, instead of allocating one. */\n  readonly threadId?: ThreadId | undefined;\n  /**\n   * Preallocated Run identity used instead of `IdGenerator` when supplied.\n   * The S1 Subagent seam preallocates child Run identity through this option\n   * so `SubagentRequested` can carry the intended child identity.\n   */\n  readonly runId?: RunId | undefined;\n  /** Canonically reconstructed window identity for a resumed durable Run. */\n  readonly initialContextWindowId?: string | undefined;\n  /** Last unconsumed, settled singleton application Tool in this Run; the engine verifies its control annotation. */\n  readonly pendingContextToolCallId?: string | undefined;\n  /** Canonical instruction/input block for durable recovery; not re-evaluated Attempt input. */\n  readonly protectedContext?: Prompt.Prompt | undefined;\n  /**\n   * Non-model-visible Parent Link for a delegated child Run (S1 seam). It\n   * never enters the model prompt or the Run's event payloads directly; the\n   * engine uses it only to fix the Run's delegation depth (`parentLink.depth`\n   * for a child, `0` when absent) exposed through the locally provided\n   * `AgentSpawner`, and future durable work persists it as child lineage.\n   */\n  readonly parentLink?: SubagentParentLink | undefined;\n  /** Durable background provenance supplies depth independently of attached parent linkage. */\n  readonly delegationDepth?: number | undefined;\n  /** Immutable narrowed authority restored for every delegated Attempt. */\n  readonly subagentGrant?: SubagentGrant | undefined;\n  /** Reserved subtree frame; descendants may spend only the residual after this Run's own ceiling. */\n  readonly subagentBudget?: SubagentBudgetReservation | undefined;\n  /** Native host funding provenance; never inferred from absent allocation amounts. */\n  readonly subagentBudgetScope?: WorkerBudgetScope | undefined;\n  /**\n   * Seed or append-only extension for an in-memory Thread. ThreadHistory.layer retains this\n   * prefix before execution and rejects replacement of existing messages. The engine appends\n   * this Run's evaluated instructions and rendered input. PersistentHistory rejects this option;\n   * durable hosts supply the history reconstructed from their journal.\n   */\n  readonly history?: Prompt.Prompt | undefined;\n  readonly commandDrainPolicy?: CommandDrainPolicy | undefined;\n  readonly input?: RunInputHook<HookError, HookRequirements> | undefined;\n  readonly approval?: RunApprovalHook<HookError, HookRequirements> | undefined;\n  /** Per-Run override of RunContextPreparation.hook, preserving application-specific E/R. */\n  readonly context?: RunContextHook<HookError, HookRequirements> | undefined;\n  /**\n   * Per-Run override of RunContextPreparation.transientContext. Use the service\n   * for host configuration; this generic hook preserves application-specific E/R.\n   * Model-visible reference context is loaded for each Turn, including a grace\n   * finalization Turn and a Turn reconstructed by durable recovery. The engine\n   * validates and budgets the result but never adds it to official history or\n   * compaction coverage. A same-Turn provider-overflow retry reuses the Turn's\n   * loaded snapshot.\n   */\n  readonly transientContext?: RunTransientContextHook<HookError, HookRequirements> | undefined;\n  readonly budget?: RunBudgetHook<HookError, HookRequirements> | undefined;\n  /**\n   * Host-owned action-time authorization for model-declared application Tool batches. The engine\n   * uses this per-Run override when present, otherwise the provided RunToolAuthorization service.\n   * It invokes the policy for every still-executable call after complete-batch validation and approval, but\n   * before durable preparation or any Handler permit. A resumed durable batch invokes it again\n   * with the same canonical Run/Turn/input authority and Tool Call identity. Programmatic\n   * `ToolBroker` calls invoke it after schema/visibility checks and before budget reservation or\n   * execution, with their parent identity in `programmatic`. Inner denials become catchable\n   * outcomes; other independent calls may already have completed.\n   */\n  readonly toolAuthorization?: RunToolAuthorizationHook<HookError, HookRequirements> | undefined;\n  /**\n   * Actual wall-clock start of the logical Run, used for elapsed-time status.\n   * Durable coordinators supply the canonical `RunStarted` record timestamp on\n   * every replacement Attempt. It is independent from `durationDeadline`,\n   * which may tighten the remaining allowance without changing how long the\n   * Run has existed (RUN-024/RUN-030).\n   */\n  readonly runStartedAt?: DateTime.Utc | undefined;\n  /**\n   * Optional absolute deadline for the Run's `maxDuration` rail. The engine\n   * uses the earlier of this value and the fresh policy deadline, so callers\n   * may preserve or tighten an existing Run allowance but can never widen it.\n   * Durable coordinators derive this value from the canonical `RunStarted`\n   * record timestamp and stored duration so replacement Attempts share one\n   * wall-clock allowance (RUN-030).\n   */\n  readonly durationDeadline?: DateTime.Utc | undefined;\n  /**\n   * Durable turn-commit seam (P5). When absent the engine behaves exactly as\n   * the ephemeral runtime: no response/prepared commits, and `DurableStep`\n   * executes pass-through.\n   */\n  readonly durability?: RunDurabilityHook<HookError, HookRequirements> | undefined;\n  /**\n   * Durable-Subagent establishment/join seam (S2). When present the engine's\n   * per-batch `SubagentDurability` service runs in durable mode over this\n   * hook; when absent the service is the explicit ephemeral-mode default and\n   * delegation Tools keep their S1 in-process spawn semantics unchanged.\n   */\n  readonly subagent?: RunSubagentHook<HookError, HookRequirements> | undefined;\n  /**\n   * Resume a declared, canonically committed Tool batch without re-invoking\n   * the model (durable batch-resume seam). Consumed by the Run's first Turn.\n   * Requires `resumeUsage`; missing or contradictory accounting fails with\n   * `ModelProtocolError` before input, model, or Tool execution.\n   */\n  readonly resume?: RunTurnResume | undefined;\n  /**\n   * Cumulative usage and Stop Policy accounting of the Run's prior Attempts,\n   * projected from canonical records. A fresh continuation starts at\n   * `committedTurns + 1`; a pending batch uses the already-counted declarations\n   * and folds its terminal outcomes onto the prior failure streak once.\n   * Omit only for fresh Runs. Incomplete or invalid seeds fail typed before execution.\n   * For a pending batch, `committedTurns` must equal `resume.turn`, `toolCalls`\n   * must include every pending declaration, and the failure streak cannot\n   * exceed the declared calls before that batch.\n   */\n  readonly resumeUsage?: RunResumeUsage | undefined;\n  /**\n   * Per-Run Tool Call allowance (RUN-021): a TIGHTENING-ONLY bound below the\n   * Agent Policy's `maxToolCalls` — the effective limit is\n   * `min(policy.maxToolCalls, max(1, floor(toolCallAllowance)))`, so an\n   * allowance can never widen the Definition's ceiling. The `onExhaustion`\n   * resolution (RUN-018) keys off the effective limit, which is how an\n   * orchestrator grants a delegated child a budget extension by re-invoking\n   * with a larger allowance up to the child Definition's policy.\n   */\n  readonly toolCallAllowance?: number | undefined;\n  /**\n   * Per-Run Turn allowance (RUN-021): tightening-only below the Agent\n   * Policy's `maxTurns`, with the same normalization and the same\n   * `onExhaustion` resolution (RUN-019 grace) at the effective limit.\n   */\n  readonly turnAllowance?: number | undefined;\n  /** Required when the core policy declares `costBudgetMicrousd`. */\n  readonly estimateCostMicrousd?: RunCostEstimator<HookError, HookRequirements> | undefined;\n  readonly scheduling?: RunSchedulingHook | undefined;\n  /** Optional tightening-only overrides for the engine's finite in-memory buffer ceilings. */\n  readonly bufferLimits?: RunBufferLimits | undefined;\n  /**\n   * Incremental history observer. ThreadHistory.layer retains each complete update first.\n   * Invoked inline with the full Prompt whenever official history advances, including initial\n   * instructions/input before the first model call. It can write before the Run succeeds or its\n   * resources close. Failure stops execution through HookError; defects and interruption propagate.\n   * Earlier callback writes are caller-owned and are not rolled back if this or a later step fails.\n   * PersistentHistory's on-success adapter rejects this hook;\n   * the durable coordinator uses it for live Prompt state while its journal owns durable commits.\n   */\n  readonly onHistory?:\n    | ((history: Prompt.Prompt) => Effect.Effect<void, HookError, HookRequirements>)\n    | undefined;\n}\n\nexport type RunOptionsError<Options> =\n  Options extends RunOptions<infer Error, infer _Requirements> ? Error : never;\n\nexport type RunOptionsRequirements<Options> =\n  Options extends RunOptions<infer _Error, infer Requirements> ? Requirements : never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAkIA,MAAa,6BAA6B,QAAQ,UAChD,mDACA,EAAE,oBAAoB,KAAA,EAAU,CAClC;;AAGA,MAAa,4BAA4B,aACvC,MAAM,QAAQ,0BAA0B,CAAC,CAAC,QAAQ;;AAGpD,MAAa,qBAAqB,OAAO,SAAS,CAAC,OAAO,KAAK,CAAC;;;;;;;;;;AA4ShE,IAAa,wBAAb,cAA2C,QAAQ,QAUjD,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC;;AAGnD,MAAa,mCAAuE,MAAM,QACxF,qBACF,CAAC,CAAC,CAAC,CAAC;;;;;;;;AASJ,IAAa,uBAAb,MAAa,6BAA6B,QAAQ,QAGhD,CAAC,CAAC,2CAA2C,CAAC,CAAC;;CAE/C,OAAgB,WAA8C,MAAM,QAClE,sBACA,EAAE,iBAAiB,OAAO,QAAQ,EAAE,MAAM,UAAU,CAAC,EAAE,CACzD;AACF;;;;;;;AAiDA,IAAa,uBAAb,MAAa,6BAA6B,QAAQ,QAGhD,CAAC,CAAC,2CAA2C,CAAC,CAAC;CAC/C,OAAgB,iBAAiB,MAAM,QAAQ,sBAAsB,EACnE,2BAA2B,OAAO,KACpC,CAAC;AACH;;;;;;;AAQA,IAAa,wBAAb,MAAa,8BAA8B,QAAQ,QAGjD,CAAC,CAAC,4CAA4C,CAAC,CAAC;CAChD,OAAgB,iBAAiB,MAAM,QAAQ,uBAAuB,EACpE,SAAS,WAAW,OAAO,QAAQ,MAAM,EAC3C,CAAC;AACH;;;;;;;;AAwNA,MAAa,iCAAiC,OAAO,OAAO;CAC1D,eAAe,OAAO,YAAY,SAAS;CAC3C,IAAI,OAAO;CACX,QAAQ,OAAO;CACf,WAAW,OAAO;;CAElB,gBAAgB,OAAO,YAAY,OAAO,QAAQ,IAAI,CAAC;AACzD,CAAC;;;;;;;;;;;AAcD,MAAa,uBAAuB,OAAO,OAAO;CAChD,GAAG,eAAe;CAClB,YAAY,OAAO;CACnB,aAAa,OAAO;CACpB,cAAc,OAAO;CACrB,iBAAiB,OAAO;CACxB,kBAAkB,OAAO;CACzB,cAAc,OAAO;CACrB,aAAa,OAAO,YAAY,iBAAiB;CACjD,eAAe,OAAO,YAAY,iBAAiB;CACnD,sBAAsB,OAAO,YAAY,OAAO,OAAO;;CAEvD,UAAU,OAAO,YAAY,OAAO,MAAM,aAAa,CAAC;AAC1D,CAAC,CAAC,CAAC,MACD,OAAO,YACJ,UACC,MAAM,mBAAmB,MAAM,eAAe,MAAM,oBAAoB,MAAM,cAChF,EACE,UAAU,+DACZ,CACF,GACA,OAAO,YACJ,UACC,MAAM,cAAc,MAAM,kBAAkB,MAAM,2BAA2B,MAAM,WACrF,EACE,UACE,uFACJ,CACF,CACF;;AA4CA,MAAa,wBAAwB,OAAO,MAAM,CAChD,OAAO,OAAO;CACZ,MAAM,OAAO,QAAQ,SAAS;CAC9B,aAAa,OAAO,IAAI,MAAM,OAAO,cAAc,CAAC,CAAC;AACvD,CAAC,GACD,OAAO,OAAO,EAAE,MAAM,OAAO,QAAQ,YAAY,EAAE,CAAC,CACtD,CAAC;;;;;;;AAgBD,MAAa,oBAAoB,QAAQ,UACvC,0CACA,EAAE,qBAAqB,CAAC,GAAG,CAC7B"}

package/dist/engine/SubagentHost.d.mts

@@ -0,0 +1,2 @@
+import { c as WorkerReportPreparationFailure, i as SubagentHost, l as WorkerReporting, n as FollowUpWorkerRequest, o as WorkerObservation, r as StartWorkerRequest, s as WorkerReceiptRequest, t as BackgroundReporting, u as WorkerRunReport } from "../SubagentHost-CJUBQlcc.mjs";
+export { BackgroundReporting, FollowUpWorkerRequest, StartWorkerRequest, SubagentHost, WorkerObservation, WorkerReceiptRequest, WorkerReportPreparationFailure, WorkerReporting, WorkerRunReport };

package/dist/engine/SubagentHost.mjs

@@ -0,0 +1,72 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { WorkerError } from "../core/Worker.mjs";
+import { Context, Schema, Stream } from "effect";
+//#region src/engine/SubagentHost.ts
+var SubagentHost_exports = /* @__PURE__ */ __exportAll({
+	BackgroundReporting: () => BackgroundReporting,
+	SubagentHost: () => SubagentHost,
+	WorkerReportPreparationFailure: () => WorkerReportPreparationFailure
+});
+/** A bounded projection failure; raw application errors never enter durable report records. */
+var WorkerReportPreparationFailure = class extends Schema.TaggedError()("WorkerReportPreparationFailure", { stage: Schema.Literals([
+	"projection",
+	"input",
+	"preparation"
+]) }) {};
+/** Descriptor carried by background tools; registration discovers it without an app handoff. */
+const BackgroundReporting = Context.Reference("@effect-agent/engine/BackgroundReporting", { defaultValue: () => void 0 });
+/**
+* Trusted, caller-bound host port. The interpreter supplies a fresh facet for each Tool Call;
+* programmatic callers acquire a separately authorized Thread facet. Request values cannot
+* choose the source identity, replace worker provenance or expand its authority and budgets.
+*/
+var SubagentHost = class SubagentHost extends Context.Service()("@effect-agent/engine/SubagentHost") {
+	static unavailable = {
+		context: WorkerError.make({
+			operation: "context",
+			reason: "unavailable"
+		}),
+		resolveTargetPolicy: () => WorkerError.make({
+			operation: "start",
+			reason: "unavailable"
+		}),
+		start: () => WorkerError.make({
+			operation: "start",
+			reason: "unavailable"
+		}),
+		followUp: () => WorkerError.make({
+			operation: "followUp",
+			reason: "unavailable"
+		}),
+		inspect: () => WorkerError.make({
+			operation: "inspect",
+			reason: "unavailable"
+		}),
+		summary: () => WorkerError.make({
+			operation: "inspect",
+			reason: "unavailable"
+		}),
+		observe: () => Stream.fail(WorkerError.make({
+			operation: "observe",
+			reason: "unavailable"
+		})),
+		await: () => WorkerError.make({
+			operation: "await",
+			reason: "unavailable"
+		}),
+		list: () => WorkerError.make({
+			operation: "list",
+			reason: "unavailable"
+		}),
+		cancel: () => WorkerError.make({
+			operation: "cancel",
+			reason: "unavailable"
+		})
+	};
+	/** Runtime-owned per-call binding. Unconfigured Runs deny background operations. */
+	static forTool = Context.Reference("@effect-agent/engine/SubagentHost/forTool", { defaultValue: () => () => SubagentHost.unavailable });
+};
+//#endregion
+export { BackgroundReporting, SubagentHost, WorkerReportPreparationFailure, SubagentHost_exports as t };
+
+//# sourceMappingURL=SubagentHost.mjs.map

package/dist/engine/SubagentHost.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubagentHost.mjs","names":[],"sources":["../../src/engine/SubagentHost.ts"],"sourcesContent":["import type { Effect, Option } from \"effect\";\nimport { Context, Schema, Stream } from \"effect\";\n\nimport type * as Agent from \"../core/Agent.ts\";\nimport type { AgentPolicy } from \"../core/AgentPolicy.ts\";\nimport type { DelegationId, RunId, SettlementId, ThreadId } from \"../core/Identifiers.ts\";\nimport { type IdempotencyKey, type JoinedToHost, type Receipt } from \"../core/Receipt.ts\";\nimport type { SubagentBudgetReservation } from \"../core/SubagentContract.ts\";\nimport {\n  WorkerError,\n  type WorkerCompletion,\n  type WorkerHistoryEntry,\n  type WorkerContext,\n  type WorkerBudgetScope,\n  type WorkerSource,\n  type WorkerPage,\n  type WorkerRef,\n  type WorkerStarted,\n  type WorkerSummary,\n} from \"../core/Worker.ts\";\n\n/** Prepared values cross this port only to be Schema-decoded before durable storage. */\nexport interface StartWorkerRequest {\n  readonly delegationId: DelegationId;\n  readonly target: Agent.AnyDefinition;\n  readonly idempotencyKey: IdempotencyKey;\n  readonly encodedInput: unknown;\n  readonly encodedParameters: unknown;\n  readonly policy: AgentPolicy;\n  readonly budget: SubagentBudgetReservation;\n  readonly encodedGrant: unknown;\n  readonly toolCallAllowance?: number;\n  /** Author-owned request; the durable host must separately authorize worker-run funding. */\n  readonly budgetScope?: WorkerBudgetScope;\n}\n\nexport interface FollowUpWorkerRequest {\n  readonly worker: WorkerRef;\n  readonly target: Agent.AnyDefinition;\n  readonly idempotencyKey: IdempotencyKey;\n  readonly encodedInput: unknown;\n  readonly encodedParameters: unknown;\n}\n\nexport interface WorkerReceiptRequest {\n  readonly worker: WorkerRef;\n  readonly target: Agent.AnyDefinition;\n  readonly receipt: Receipt;\n}\n\n/**\n * Canonical terminal values remain encoded until the capability decodes the saved parameters\n * and target output and applies its declared result projection. Child E does not survive settlement.\n */\nexport type WorkerObservation =\n  | { readonly _tag: \"Pending\"; readonly receipt: Receipt }\n  | {\n      readonly _tag: \"Settled\";\n      readonly receipt: Receipt;\n      /** Absent when an input failed or was cancelled before any Run started. */\n      readonly runId?: RunId;\n      readonly settlementId: SettlementId;\n      readonly outcome: \"completed\" | \"failed\" | \"aborted\";\n      readonly encodedParameters: unknown;\n      readonly encodedResult: unknown;\n      readonly budgetExhausted: boolean;\n    };\n\n/** One actual canonical Run, independent of how many input Receipts joined it. */\nexport interface WorkerRunReport {\n  readonly worker: WorkerRef;\n  readonly context: WorkerContext;\n  readonly observation: Extract<WorkerObservation, { readonly _tag: \"Settled\" }> & {\n    readonly runId: RunId;\n  };\n}\n\n/** A bounded projection failure; raw application errors never enter durable report records. */\nexport class WorkerReportPreparationFailure extends Schema.TaggedError<WorkerReportPreparationFailure>()(\n  \"WorkerReportPreparationFailure\",\n  { stage: Schema.Literals([\"projection\", \"input\", \"preparation\"]) },\n) {}\n\n/**\n * Source-owned projection discovered from background tools or supplied by a custom registration.\n * The concrete descriptor retains its E/R; durable registration captures R and records\n * bounded preparation failure rather than serializing arbitrary application errors.\n */\nexport interface WorkerReporting<E = never, R = never> {\n  readonly delegationId: DelegationId;\n  readonly target: Agent.AnyDefinition;\n  /** Standard messages retain the parent's original application input. */\n  readonly mode?: \"standard\";\n  readonly input?: Schema.Top;\n  /** Required for custom mapping when the receiving coordinator is itself an established worker. */\n  readonly destination?: {\n    readonly delegationId: DelegationId;\n    readonly target: Agent.AnyDefinition;\n  };\n  readonly prepare: (report: WorkerRunReport) => Effect.Effect<\n    {\n      readonly encodedInput: Schema.Json;\n      readonly encodedParameters?: Schema.Json;\n      readonly message?: WorkerCompletion;\n    },\n    E | WorkerReportPreparationFailure,\n    R\n  >;\n}\n\n/** Descriptor carried by background tools; registration discovers it without an app handoff. */\nexport const BackgroundReporting = Context.Reference<\n  WorkerReporting<WorkerReportPreparationFailure> | undefined\n>(\"@effect-agent/engine/BackgroundReporting\", { defaultValue: () => undefined });\n\n/**\n * Trusted, caller-bound host port. The interpreter supplies a fresh facet for each Tool Call;\n * programmatic callers acquire a separately authorized Thread facet. Request values cannot\n * choose the source identity, replace worker provenance or expand its authority and budgets.\n */\nexport class SubagentHost extends Context.Service<\n  SubagentHost,\n  {\n    readonly context: Effect.Effect<WorkerContext, WorkerError>;\n    /** Resolve prepared input through host authority; None retains legacy target inheritance. */\n    readonly resolveTargetPolicy: (request: {\n      readonly target: Agent.AnyDefinition;\n      readonly encodedInput: unknown;\n    }) => Effect.Effect<Option.Option<AgentPolicy>, WorkerError>;\n    readonly start: (request: StartWorkerRequest) => Effect.Effect<WorkerStarted, WorkerError>;\n    readonly followUp: (request: FollowUpWorkerRequest) => Effect.Effect<Receipt, WorkerError>;\n    readonly inspect: (\n      request: WorkerReceiptRequest,\n    ) => Effect.Effect<WorkerObservation, WorkerError>;\n    /** Inspect the continuing worker using the same summary contract as discovery. */\n    readonly summary: (request: {\n      readonly worker: WorkerRef;\n      readonly target: Agent.AnyDefinition;\n    }) => Effect.Effect<WorkerSummary, WorkerError>;\n    /** A finite snapshot through the captured tail; resume with the last sequence as `after`. */\n    readonly observe: (request: {\n      readonly worker: WorkerRef;\n      readonly target: Agent.AnyDefinition;\n      readonly after?: number;\n    }) => Stream.Stream<WorkerHistoryEntry, WorkerError>;\n    /** Interrupting this wait never requests cancellation of accepted work. */\n    readonly await: (\n      request: WorkerReceiptRequest,\n    ) => Effect.Effect<WorkerObservation, WorkerError>;\n    readonly list: (request: {\n      readonly delegationId: DelegationId;\n      readonly target: Agent.AnyDefinition;\n      readonly limit: number;\n      readonly after?: ThreadId;\n    }) => Effect.Effect<WorkerPage, WorkerError>;\n    /** Cancel exactly this Receipt; preserve JoinedToHost without broadening its target. */\n    readonly cancel: (\n      request: WorkerReceiptRequest,\n    ) => Effect.Effect<void, WorkerError | JoinedToHost>;\n  }\n>()(\"@effect-agent/engine/SubagentHost\") {\n  static readonly unavailable: SubagentHost[\"Service\"] = {\n    context: WorkerError.make({ operation: \"context\", reason: \"unavailable\" }),\n    resolveTargetPolicy: () => WorkerError.make({ operation: \"start\", reason: \"unavailable\" }),\n    start: () => WorkerError.make({ operation: \"start\", reason: \"unavailable\" }),\n    followUp: () => WorkerError.make({ operation: \"followUp\", reason: \"unavailable\" }),\n    inspect: () => WorkerError.make({ operation: \"inspect\", reason: \"unavailable\" }),\n    summary: () => WorkerError.make({ operation: \"inspect\", reason: \"unavailable\" }),\n    observe: () => Stream.fail(WorkerError.make({ operation: \"observe\", reason: \"unavailable\" })),\n    await: () => WorkerError.make({ operation: \"await\", reason: \"unavailable\" }),\n    list: () => WorkerError.make({ operation: \"list\", reason: \"unavailable\" }),\n    cancel: () => WorkerError.make({ operation: \"cancel\", reason: \"unavailable\" }),\n  };\n\n  /** Runtime-owned per-call binding. Unconfigured Runs deny background operations. */\n  static readonly forTool = Context.Reference<\n    (source: Extract<WorkerSource, { readonly _tag: \"tool\" }>) => SubagentHost[\"Service\"]\n  >(\"@effect-agent/engine/SubagentHost/forTool\", {\n    defaultValue: () => () => SubagentHost.unavailable,\n  });\n}\n"],"mappings":";;;;;;;;;;AA8EA,IAAa,iCAAb,cAAoD,OAAO,YAA4C,CAAC,CACtG,kCACA,EAAE,OAAO,OAAO,SAAS;CAAC;CAAc;CAAS;AAAa,CAAC,EAAE,CACnE,CAAC,CAAC,CAAC;;AA8BH,MAAa,sBAAsB,QAAQ,UAEzC,4CAA4C,EAAE,oBAAoB,KAAA,EAAU,CAAC;;;;;;AAO/E,IAAa,eAAb,MAAa,qBAAqB,QAAQ,QAwCxC,CAAC,CAAC,mCAAmC,CAAC,CAAC;CACvC,OAAgB,cAAuC;EACrD,SAAS,YAAY,KAAK;GAAE,WAAW;GAAW,QAAQ;EAAc,CAAC;EACzE,2BAA2B,YAAY,KAAK;GAAE,WAAW;GAAS,QAAQ;EAAc,CAAC;EACzF,aAAa,YAAY,KAAK;GAAE,WAAW;GAAS,QAAQ;EAAc,CAAC;EAC3E,gBAAgB,YAAY,KAAK;GAAE,WAAW;GAAY,QAAQ;EAAc,CAAC;EACjF,eAAe,YAAY,KAAK;GAAE,WAAW;GAAW,QAAQ;EAAc,CAAC;EAC/E,eAAe,YAAY,KAAK;GAAE,WAAW;GAAW,QAAQ;EAAc,CAAC;EAC/E,eAAe,OAAO,KAAK,YAAY,KAAK;GAAE,WAAW;GAAW,QAAQ;EAAc,CAAC,CAAC;EAC5F,aAAa,YAAY,KAAK;GAAE,WAAW;GAAS,QAAQ;EAAc,CAAC;EAC3E,YAAY,YAAY,KAAK;GAAE,WAAW;GAAQ,QAAQ;EAAc,CAAC;EACzE,cAAc,YAAY,KAAK;GAAE,WAAW;GAAU,QAAQ;EAAc,CAAC;CAC/E;;CAGA,OAAgB,UAAU,QAAQ,UAEhC,6CAA6C,EAC7C,0BAA0B,aAAa,YACzC,CAAC;AACH"}

package/dist/engine/ThreadHistory.d.mts

@@ -0,0 +1,2 @@
+import { a as layer, n as ThreadHistoryError, r as ThreadHistoryRun, t as ThreadHistory } from "../ThreadHistory-tS1KwxHR.mjs";
+export { ThreadHistory, ThreadHistoryError, ThreadHistoryRun, layer };

package/dist/engine/ThreadHistory.mjs

@@ -0,0 +1,67 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { ThreadId } from "../core/Identifiers.mjs";
+import { Store, layerMemory, toPrompt } from "../core/Thread.mjs";
+import { Context, Effect, Layer, Schema } from "effect";
+//#region src/engine/ThreadHistory.ts
+var ThreadHistory_exports = /* @__PURE__ */ __exportAll({
+	ThreadHistory: () => ThreadHistory,
+	ThreadHistoryError: () => ThreadHistoryError,
+	layer: () => layer
+});
+/** A history adapter rejected a read, staged value, or completed Run commit. */
+var ThreadHistoryError = class extends Schema.TaggedError()("ThreadHistoryError", {
+	threadId: ThreadId,
+	reason: Schema.Literals([
+		"not-found",
+		"conflict",
+		"fenced",
+		"incompatible",
+		"limit",
+		"encoding",
+		"storage"
+	]),
+	message: Schema.String,
+	cause: Schema.optionalKey(Schema.Defect())
+}) {};
+/**
+* History shared by Runs with the same Thread ID. The default layer retains native messages
+* incrementally in memory for its application Scope, including completed updates before a failure.
+* PersistentHistory.layer from effect-agent/persistent-history instead commits successful
+* Runs to an explicit ThreadStore. Durable hosts retain history through their journal hooks.
+* No implementation may retry model or Tool execution or claim interrupted-work recovery.
+*/
+var ThreadHistory = class ThreadHistory extends Context.Service()("@effect-agent/engine/ThreadHistory") {
+	/**
+	* Retain bounded in-memory history across Runs. Provide once around the application so
+	* all Runs share the same store. The underlying Thread.Store service is exposed for
+	* snapshots and interactive hooks; separate Layer builds own separate stores.
+	*/
+	static layer = Layer.effect(ThreadHistory, Effect.gen(function* () {
+		const threads = yield* Store;
+		const historyError = (cause) => ThreadHistoryError.make({
+			threadId: cause.threadId,
+			reason: cause._tag === "ThreadNotFound" ? "not-found" : cause._tag === "ThreadLimitExceeded" ? "limit" : cause._tag === "ThreadHistoryDiverged" ? "conflict" : "encoding",
+			message: cause._tag === "ThreadNotFound" ? "Thread history is not present in this application Scope" : cause._tag === "ThreadLimitExceeded" ? `In-memory history exceeds the ${cause.limit} limit of ${cause.limitValue}` : cause.message,
+			cause
+		});
+		return ThreadHistory.of({
+			retention: "incremental",
+			load: (threadId) => threads.snapshot(threadId).pipe(Effect.map(toPrompt), Effect.mapError(historyError)),
+			open: Effect.fn("ThreadHistory.open")(function* ({ threadId, runId }) {
+				const snapshot = yield* threads.create(threadId).pipe(Effect.mapError(historyError));
+				return {
+					prompt: toPrompt(snapshot),
+					stageInput: () => Effect.void,
+					stageHistory: (history) => threads.recordHistory(threadId, runId, history).pipe(Effect.asVoid, Effect.mapError(historyError)),
+					commit: () => Effect.void
+				};
+			})
+		});
+	})).pipe(Layer.provideMerge(layerMemory));
+};
+/** Retain in-memory conversation history for the application Scope. */
+const layer = ThreadHistory.layer;
+//#endregion
+export { ThreadHistory, ThreadHistoryError, layer, ThreadHistory_exports as t };
+
+//# sourceMappingURL=ThreadHistory.mjs.map

package/dist/engine/ThreadHistory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThreadHistory.mjs","names":["ConversationStore"],"sources":["../../src/engine/ThreadHistory.ts"],"sourcesContent":["import { Context, Effect, Layer, Schema } from \"effect\";\nimport type { Prompt } from \"effect/unstable/ai\";\n\nimport { ThreadId, type RunId } from \"../core/Identifiers.ts\";\nimport { type RunCompleted } from \"../core/RunEvent.ts\";\nimport {\n  Store as ConversationStore,\n  layerMemory,\n  toPrompt,\n  type ThreadError,\n} from \"../core/Thread.ts\";\n\n/** A history adapter rejected a read, staged value, or completed Run commit. */\nexport class ThreadHistoryError extends Schema.TaggedError<ThreadHistoryError>()(\n  \"ThreadHistoryError\",\n  {\n    threadId: ThreadId,\n    reason: Schema.Literals([\n      \"not-found\",\n      \"conflict\",\n      \"fenced\",\n      \"incompatible\",\n      \"limit\",\n      \"encoding\",\n      \"storage\",\n    ]),\n    message: Schema.String,\n    cause: Schema.optionalKey(Schema.Defect()),\n  },\n) {}\n\n/**\n * One Run's history owner. Incremental adapters retain each stageHistory update; on-success\n * adapters stage privately until commit. Before commit, the interpreter\n * finishes run-owned work and closes resources acquired for that Run, then validates the result\n * for run/start.await. Shared model, provider, and client services supplied by an enclosing\n * application Layer remain owned by that application's Scope and may outlive multiple Runs.\n * Commit must succeed before RunCompleted becomes observable. Schema-encoded input is opaque\n * here; the adapter owns its persistence boundary. A failed commit may have reached storage;\n * callers must inspect history before retrying external execution.\n */\nexport interface ThreadHistoryRun {\n  readonly prompt: Prompt.Prompt;\n  readonly stageInput: (input: unknown) => Effect.Effect<void, ThreadHistoryError>;\n  readonly stageHistory: (history: Prompt.Prompt) => Effect.Effect<void, ThreadHistoryError>;\n  readonly commit: (completed: RunCompleted) => Effect.Effect<void, ThreadHistoryError>;\n}\n\n/**\n * History shared by Runs with the same Thread ID. The default layer retains native messages\n * incrementally in memory for its application Scope, including completed updates before a failure.\n * PersistentHistory.layer from effect-agent/persistent-history instead commits successful\n * Runs to an explicit ThreadStore. Durable hosts retain history through their journal hooks.\n * No implementation may retry model or Tool execution or claim interrupted-work recovery.\n */\nexport class ThreadHistory extends Context.Service<\n  ThreadHistory,\n  {\n    readonly retention: \"incremental\" | \"on-success\";\n    readonly open: (request: {\n      readonly threadId: ThreadId;\n      readonly runId: RunId;\n    }) => Effect.Effect<ThreadHistoryRun, ThreadHistoryError>;\n    readonly load: (threadId: ThreadId) => Effect.Effect<Prompt.Prompt, ThreadHistoryError>;\n  }\n>()(\"@effect-agent/engine/ThreadHistory\") {\n  /**\n   * Retain bounded in-memory history across Runs. Provide once around the application so\n   * all Runs share the same store. The underlying Thread.Store service is exposed for\n   * snapshots and interactive hooks; separate Layer builds own separate stores.\n   */\n  static readonly layer = Layer.effect(\n    ThreadHistory,\n    Effect.gen(function* () {\n      const threads = yield* ConversationStore;\n\n      const historyError = (cause: ThreadError): ThreadHistoryError =>\n        ThreadHistoryError.make({\n          threadId: cause.threadId,\n          reason:\n            cause._tag === \"ThreadNotFound\"\n              ? \"not-found\"\n              : cause._tag === \"ThreadLimitExceeded\"\n                ? \"limit\"\n                : cause._tag === \"ThreadHistoryDiverged\"\n                  ? \"conflict\"\n                  : \"encoding\",\n          message:\n            cause._tag === \"ThreadNotFound\"\n              ? \"Thread history is not present in this application Scope\"\n              : cause._tag === \"ThreadLimitExceeded\"\n                ? `In-memory history exceeds the ${cause.limit} limit of ${cause.limitValue}`\n                : cause.message,\n          cause,\n        });\n\n      return ThreadHistory.of({\n        retention: \"incremental\",\n        load: (threadId) =>\n          threads.snapshot(threadId).pipe(Effect.map(toPrompt), Effect.mapError(historyError)),\n        open: Effect.fn(\"ThreadHistory.open\")(function* ({ threadId, runId }) {\n          const snapshot = yield* threads.create(threadId).pipe(Effect.mapError(historyError));\n\n          return {\n            prompt: toPrompt(snapshot),\n            stageInput: () => Effect.void,\n            stageHistory: (history: Prompt.Prompt) =>\n              threads\n                .recordHistory(threadId, runId, history)\n                .pipe(Effect.asVoid, Effect.mapError(historyError)),\n            commit: () => Effect.void,\n          };\n        }),\n      });\n    }),\n  ).pipe(Layer.provideMerge(layerMemory));\n}\n\n/** Retain in-memory conversation history for the application Scope. */\nexport const layer = ThreadHistory.layer;\n"],"mappings":";;;;;;;;;;;AAaA,IAAa,qBAAb,cAAwC,OAAO,YAAgC,CAAC,CAC9E,sBACA;CACE,UAAU;CACV,QAAQ,OAAO,SAAS;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,SAAS,OAAO;CAChB,OAAO,OAAO,YAAY,OAAO,OAAO,CAAC;AAC3C,CACF,CAAC,CAAC,CAAC;;;;;;;;AA0BH,IAAa,gBAAb,MAAa,sBAAsB,QAAQ,QAUzC,CAAC,CAAC,oCAAoC,CAAC,CAAC;;;;;;CAMxC,OAAgB,QAAQ,MAAM,OAC5B,eACA,OAAO,IAAI,aAAa;EACtB,MAAM,UAAU,OAAOA;EAEvB,MAAM,gBAAgB,UACpB,mBAAmB,KAAK;GACtB,UAAU,MAAM;GAChB,QACE,MAAM,SAAS,mBACX,cACA,MAAM,SAAS,wBACb,UACA,MAAM,SAAS,0BACb,aACA;GACV,SACE,MAAM,SAAS,mBACX,4DACA,MAAM,SAAS,wBACb,iCAAiC,MAAM,MAAM,YAAY,MAAM,eAC/D,MAAM;GACd;EACF,CAAC;EAEH,OAAO,cAAc,GAAG;GACtB,WAAW;GACX,OAAO,aACL,QAAQ,SAAS,QAAQ,CAAC,CAAC,KAAK,OAAO,IAAI,QAAQ,GAAG,OAAO,SAAS,YAAY,CAAC;GACrF,MAAM,OAAO,GAAG,oBAAoB,CAAC,CAAC,WAAW,EAAE,UAAU,SAAS;IACpE,MAAM,WAAW,OAAO,QAAQ,OAAO,QAAQ,CAAC,CAAC,KAAK,OAAO,SAAS,YAAY,CAAC;IAEnF,OAAO;KACL,QAAQ,SAAS,QAAQ;KACzB,kBAAkB,OAAO;KACzB,eAAe,YACb,QACG,cAAc,UAAU,OAAO,OAAO,CAAC,CACvC,KAAK,OAAO,QAAQ,OAAO,SAAS,YAAY,CAAC;KACtD,cAAc,OAAO;IACvB;GACF,CAAC;EACH,CAAC;CACH,CAAC,CACH,CAAC,CAAC,KAAK,MAAM,aAAa,WAAW,CAAC;AACxC;;AAGA,MAAa,QAAQ,cAAc"}

package/dist/engine/ToolBroker.d.mts

@@ -0,0 +1,2 @@
+import { a as ProgrammaticCallSuccess, c as ToolBrokerConfigurationError, d as ToolBrokerService, f as ToolBrokerUnavailableError, i as ProgrammaticCallRecord, l as ToolBrokerPass, n as ProgrammaticCallFailure, o as ProgrammaticToolInput, r as ProgrammaticCallOutcome, s as ToolBroker, t as ProgrammaticCallError, u as ToolBrokerPassOptions } from "../ToolBroker-DWs4tZra.mjs";
+export { ProgrammaticCallError, ProgrammaticCallFailure, ProgrammaticCallOutcome, ProgrammaticCallRecord, ProgrammaticCallSuccess, ProgrammaticToolInput, ToolBroker, ToolBrokerConfigurationError, ToolBrokerPass, ToolBrokerPassOptions, ToolBrokerService, ToolBrokerUnavailableError };

package/dist/engine/ToolBroker.mjs

@@ -0,0 +1,42 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { Context, Schema } from "effect";
+//#region src/engine/ToolBroker.ts
+var ToolBroker_exports = /* @__PURE__ */ __exportAll({
+	ProgrammaticCallRecord: () => ProgrammaticCallRecord,
+	ToolBroker: () => ToolBroker,
+	ToolBrokerConfigurationError: () => ToolBrokerConfigurationError,
+	ToolBrokerUnavailableError: () => ToolBrokerUnavailableError
+});
+/**
+* Ephemeral execution evidence, ordered by invocation rather than completion. No arguments or
+* results are copied into this diagnostic. A started call without a confirmed result is uncertain;
+* a failed call is a confirmed failure, not a promise that external effects were rolled back.
+*/
+const ProgrammaticCallRecord = Schema.Struct({
+	sequenceIndex: Schema.Natural,
+	toolName: Schema.String,
+	status: Schema.Literals([
+		"not-started",
+		"succeeded",
+		"failed",
+		"uncertain"
+	]),
+	errorTag: Schema.optionalKey(Schema.String)
+});
+/** The broker was used outside a live Tool batch; there is nothing to bind to. */
+var ToolBrokerUnavailableError = class extends Schema.TaggedError()("ToolBrokerUnavailableError", { message: Schema.String }) {};
+/**
+* The pass options are invalid — for example a `maxResultBytes` that is not
+* a positive safe integer, which would make the size comparison fail open.
+*/
+var ToolBrokerConfigurationError = class extends Schema.TaggedError()("ToolBrokerConfigurationError", { message: Schema.String }) {};
+/**
+* Engine-provided programmatic Tool broker (RUN-016, RUN-017). Declare it
+* with `.addDependency(ToolBroker)` on a Tool that performs programmatic
+* invocation; the interpreter supplies it, and an application Layer must not.
+*/
+var ToolBroker = class extends Context.Service()("@effect-agent/engine/ToolBroker") {};
+//#endregion
+export { ProgrammaticCallRecord, ToolBroker, ToolBrokerConfigurationError, ToolBrokerUnavailableError, ToolBroker_exports as t };
+
+//# sourceMappingURL=ToolBroker.mjs.map

package/dist/engine/ToolBroker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolBroker.mjs","names":[],"sources":["../../src/engine/ToolBroker.ts"],"sourcesContent":["import type { Effect } from \"effect\";\nimport { Context, Schema } from \"effect\";\nimport type { Tool, Toolkit } from \"effect/unstable/ai\";\n\n/**\n * Programmatic Tool invocation seam for Code Mode (runtime spec §12.1,\n * ADR-0017 decision 3). The interpreter provides `ToolBroker` locally in the\n * same pattern as `AgentSpawner` and `DurableStep`: a fail-closed Run-level\n * default shadowed by a live per-outer-Tool-Call service, excluded from\n * `AgentRuntimeRequirements`. The live service is bound to the outer Tool\n * Call's identity, the Run's policy context, and the already-held scheduling\n * permit; per-call input from generated code is data only, and the broker\n * allocates every sequence index from its own monotonic per-pass state.\n */\n\n/** One programmatic invocation request. Data only: the broker owns identity. */\nexport interface ProgrammaticToolInput {\n  /** The exact Effect AI Tool name resolved by the capability's namespace map. */\n  readonly toolName: string;\n  /** Schema-encoded (wire-form) parameters, exactly as they cross the sandbox. */\n  readonly encodedArguments: unknown;\n}\n\n/** The handler ran and settled with an owned JSON snapshot of its encoded success value. */\nexport interface ProgrammaticCallSuccess {\n  readonly _tag: \"ProgrammaticCallSuccess\";\n  /** Broker-owned invocation index within the pass; rejected calls leave gaps. */\n  readonly index: number;\n  readonly encodedResult: unknown;\n}\n\n/**\n * The handler settled with the Tool's declared, Schema-encoded typed failure\n * (an Effect AI `failureMode: \"return\"` result). The program may catch and\n * branch on it.\n */\nexport interface ProgrammaticCallFailure {\n  readonly _tag: \"ProgrammaticCallFailure\";\n  readonly index: number;\n  readonly encodedResult: unknown;\n}\n\n/**\n * The call never produced a settled handler result: a broker preflight\n * rejected it (authorization, budget, unknown Tool, approval-requiring Tool,\n * invalid parameters), the handler failed in its typed error channel, or the\n * result failed encoding or the broker-owned size bound. `errorTag` and\n * `message` are the same bounded projection the direct path uses for\n * `ToolCallFailed` events; `index` is present only when the handler was\n * actually started (preflight rejections consume no identity and no budget).\n */\nexport interface ProgrammaticCallError {\n  readonly _tag: \"ProgrammaticCallError\";\n  readonly index: number | undefined;\n  readonly errorTag: string;\n  readonly message: string;\n}\n\n/**\n * Total outcome of one programmatic invocation; defects stay defects. Trusted applications may\n * install `CurrentToolFailureObserver` to receive non-propagating failures before the outcome\n * returns, with the live Cause retained before projection. Neither Causes nor observation values\n * cross the broker boundary.\n */\nexport type ProgrammaticCallOutcome =\n  | ProgrammaticCallSuccess\n  | ProgrammaticCallFailure\n  | ProgrammaticCallError;\n\n/**\n * Ephemeral execution evidence, ordered by invocation rather than completion. No arguments or\n * results are copied into this diagnostic. A started call without a confirmed result is uncertain;\n * a failed call is a confirmed failure, not a promise that external effects were rolled back.\n */\nexport const ProgrammaticCallRecord = Schema.Struct({\n  sequenceIndex: Schema.Natural,\n  toolName: Schema.String,\n  status: Schema.Literals([\"not-started\", \"succeeded\", \"failed\", \"uncertain\"]),\n  errorTag: Schema.optionalKey(Schema.String),\n});\n\nexport type ProgrammaticCallRecord = typeof ProgrammaticCallRecord.Type;\n\n/** Broker-owned per-pass policy for results crossing back into the sandbox. */\nexport interface ToolBrokerPassOptions {\n  /** Maximum active invocations in this pass, from one through 64. Defaults to four. */\n  readonly concurrency?: number | undefined;\n  /**\n   * Maximum UTF-8 byte size of one encoded success result at the sandbox\n   * boundary. The returned value is decoded from the exact JSON representation\n   * admitted by this bound, after redaction. Later handler or redactor mutations\n   * cannot change it. The executor enforces its own transport bound independently.\n   */\n  readonly maxResultBytes: number;\n  /**\n   * Optional broker-owned redaction pass applied to every encoded success\n   * result before the size bound. It must be total; a defect stays a defect.\n   */\n  readonly redactResult?: ((encodedResult: unknown) => Effect.Effect<unknown>) | undefined;\n}\n\n/**\n * One open programmatic pass, bound to one outer Tool Call. A finite Effect Semaphore bounds\n * execution. The caller owns invocation fibers and must join or interrupt them before leaving\n * its Scope. Results return as soon as they settle, without waiting for unrelated earlier calls.\n */\nexport interface ToolBrokerPass {\n  readonly invoke: (input: ProgrammaticToolInput) => Effect.Effect<ProgrammaticCallOutcome>;\n  /** Owned snapshot in invocation order, including interrupted and rejected calls. Never replay it. */\n  readonly snapshot: Effect.Effect<ReadonlyArray<ProgrammaticCallRecord>>;\n}\n\n/** The broker was used outside a live Tool batch; there is nothing to bind to. */\nexport class ToolBrokerUnavailableError extends Schema.TaggedError<ToolBrokerUnavailableError>()(\n  \"ToolBrokerUnavailableError\",\n  {\n    message: Schema.String,\n  },\n) {}\n\n/**\n * The pass options are invalid — for example a `maxResultBytes` that is not\n * a positive safe integer, which would make the size comparison fail open.\n */\nexport class ToolBrokerConfigurationError extends Schema.TaggedError<ToolBrokerConfigurationError>()(\n  \"ToolBrokerConfigurationError\",\n  {\n    message: Schema.String,\n  },\n) {}\n\n/**\n * The engine-owned broker service. `openPass` fixes the capability-supplied\n * Toolkit and per-pass result policy once for the whole pass and captures the\n * handler services present at the call site, so nothing inside business\n * execution — least of all generated code — can substitute handlers, policy,\n * or identity afterwards.\n */\nexport interface ToolBrokerService {\n  readonly openPass: <Tools extends Record<string, Tool.Any>>(\n    toolkit: Toolkit.WithHandler<Tools>,\n    options: ToolBrokerPassOptions,\n  ) => Effect.Effect<\n    ToolBrokerPass,\n    ToolBrokerUnavailableError | ToolBrokerConfigurationError,\n    Tool.HandlerServices<Tools[keyof Tools]>\n  >;\n}\n\n/**\n * Engine-provided programmatic Tool broker (RUN-016, RUN-017). Declare it\n * with `.addDependency(ToolBroker)` on a Tool that performs programmatic\n * invocation; the interpreter supplies it, and an application Layer must not.\n */\nexport class ToolBroker extends Context.Service<ToolBroker, ToolBrokerService>()(\n  \"@effect-agent/engine/ToolBroker\",\n) {}\n"],"mappings":";;;;;;;;;;;;;;AA0EA,MAAa,yBAAyB,OAAO,OAAO;CAClD,eAAe,OAAO;CACtB,UAAU,OAAO;CACjB,QAAQ,OAAO,SAAS;EAAC;EAAe;EAAa;EAAU;CAAW,CAAC;CAC3E,UAAU,OAAO,YAAY,OAAO,MAAM;AAC5C,CAAC;;AAkCD,IAAa,6BAAb,cAAgD,OAAO,YAAwC,CAAC,CAC9F,8BACA,EACE,SAAS,OAAO,OAClB,CACF,CAAC,CAAC,CAAC;;;;;AAMH,IAAa,+BAAb,cAAkD,OAAO,YAA0C,CAAC,CAClG,gCACA,EACE,SAAS,OAAO,OAClB,CACF,CAAC,CAAC,CAAC;;;;;;AAyBH,IAAa,aAAb,cAAgC,QAAQ,QAAuC,CAAC,CAC9E,iCACF,CAAC,CAAC,CAAC"}

package/dist/foreign-diagnostic-DBQ1XHKh.mjs

@@ -0,0 +1,37 @@
+import { Option, Schema } from "effect";
+//#region src/durable/internal/foreign-diagnostic.ts
+const ErrorMessage = Schema.Struct({ message: Schema.String });
+const ErrorTag = Schema.Struct({ _tag: Schema.NonEmptyString });
+const decodeErrorMessage = Schema.decodeUnknownOption(ErrorMessage);
+const decodeErrorTag = Schema.decodeUnknownOption(ErrorTag);
+/**
+* Inspect a foreign failure without trusting its property accessors. Schema owns the accepted
+* fields, while the guards around each decode keep hostile proxies and getters from escaping as
+* defects during diagnostic projection.
+*/
+const inspectForeignDiagnostic = (value) => {
+	let tag;
+	let message;
+	try {
+		tag = Option.getOrUndefined(decodeErrorTag(value))?._tag;
+	} catch {}
+	try {
+		message = Option.getOrUndefined(decodeErrorMessage(value))?.message;
+	} catch {}
+	return {
+		...tag === void 0 ? {} : { tag },
+		...message === void 0 ? {} : { message }
+	};
+};
+/** Render an opaque foreign value without allowing its coercion hooks to escape. */
+const safeUnknownString = (value, fallback) => {
+	try {
+		return String(value);
+	} catch {
+		return fallback;
+	}
+};
+//#endregion
+export { safeUnknownString as n, inspectForeignDiagnostic as t };
+
+//# sourceMappingURL=foreign-diagnostic-DBQ1XHKh.mjs.map

package/dist/foreign-diagnostic-DBQ1XHKh.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreign-diagnostic-DBQ1XHKh.mjs","names":[],"sources":["../src/durable/internal/foreign-diagnostic.ts"],"sourcesContent":["import { Option, Schema } from \"effect\";\n\nconst ErrorMessage = Schema.Struct({ message: Schema.String });\nconst ErrorTag = Schema.Struct({ _tag: Schema.NonEmptyString });\nconst decodeErrorMessage = Schema.decodeUnknownOption(ErrorMessage);\nconst decodeErrorTag = Schema.decodeUnknownOption(ErrorTag);\n\ninterface ForeignDiagnostic {\n  readonly tag?: string | undefined;\n  readonly message?: string | undefined;\n}\n\n/**\n * Inspect a foreign failure without trusting its property accessors. Schema owns the accepted\n * fields, while the guards around each decode keep hostile proxies and getters from escaping as\n * defects during diagnostic projection.\n */\nexport const inspectForeignDiagnostic = (value: unknown): ForeignDiagnostic => {\n  let tag: string | undefined;\n  let message: string | undefined;\n\n  try {\n    tag = Option.getOrUndefined(decodeErrorTag(value))?._tag;\n  } catch {\n    // A diagnostic is best effort. The caller supplies the stable fallback classification.\n  }\n\n  try {\n    message = Option.getOrUndefined(decodeErrorMessage(value))?.message;\n  } catch {\n    // A hostile message accessor must not replace the original failure with a defect.\n  }\n\n  return {\n    ...(tag === undefined ? {} : { tag }),\n    ...(message === undefined ? {} : { message }),\n  };\n};\n\n/** Render an opaque foreign value without allowing its coercion hooks to escape. */\nexport const safeUnknownString = (value: unknown, fallback: string): string => {\n  try {\n    return String(value);\n  } catch {\n    return fallback;\n  }\n};\n"],"mappings":";;AAEA,MAAM,eAAe,OAAO,OAAO,EAAE,SAAS,OAAO,OAAO,CAAC;AAC7D,MAAM,WAAW,OAAO,OAAO,EAAE,MAAM,OAAO,eAAe,CAAC;AAC9D,MAAM,qBAAqB,OAAO,oBAAoB,YAAY;AAClE,MAAM,iBAAiB,OAAO,oBAAoB,QAAQ;;;;;;AAY1D,MAAa,4BAA4B,UAAsC;CAC7E,IAAI;CACJ,IAAI;CAEJ,IAAI;EACF,MAAM,OAAO,eAAe,eAAe,KAAK,CAAC,CAAC,EAAE;CACtD,QAAQ,CAER;CAEA,IAAI;EACF,UAAU,OAAO,eAAe,mBAAmB,KAAK,CAAC,CAAC,EAAE;CAC9D,QAAQ,CAER;CAEA,OAAO;EACL,GAAI,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,IAAI;EACnC,GAAI,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ;CAC7C;AACF;;AAGA,MAAa,qBAAqB,OAAgB,aAA6B;CAC7E,IAAI;EACF,OAAO,OAAO,KAAK;CACrB,QAAQ;EACN,OAAO;CACT;AACF"}