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

package/dist/AgentRuntime-uxR_a4VM.d.mts

@@ -0,0 +1,346 @@
+import { d as ToolCallId, r as DelegationId, s as RunId, t as AgentId, u as ThreadId } from "./Identifiers-CN2s30fF.mjs";
+import { i as SubagentBudgetReservation, l as SubagentGrant, u as SubagentParentLink } from "./SubagentContract-DdT7Cqe6.mjs";
+import { i as UpdateError, n as Emitter } from "./AgentUpdates-DMJ-_xow.mjs";
+import { c as RunUsageReport, s as RunTotals } from "./Usage-Dx0aknfk.mjs";
+import { l as RunEvent } from "./RunEvent-DIrzkjLr.mjs";
+import { n as ThreadHistoryError, t as ThreadHistory } from "./ThreadHistory-tS1KwxHR.mjs";
+import { n as CurrentToolCatalog } from "./ToolExposure-UCN12eCd.mjs";
+import { s as ToolBroker } from "./ToolBroker-DWs4tZra.mjs";
+import { a as AgentInputError, c as AgentPolicyError, d as ContextBudgetError, f as ContextOverflowError, n as AgentApprovalPending, p as ModelProtocolError, s as AgentOutputError, t as AgentApprovalDenied, u as AgentToolAuthorizationDenied } from "./AgentError-CggcAQ7V.mjs";
+import { t as AgentPolicy } from "./AgentPolicy-CetmQrf3.mjs";
+import { C as Requirements, D as RunDispositionSchema, E as RunDispositionFailure, M as UpdatesSchema, S as OutputSchema, T as RunDispositionDeclaration, _ as InstructionSource, a as CompletionFromToolDeclaration, c as Definition, d as EncodedInput, f as Failure, k as ToolUnion, m as InputPromptSource, n as Any, r as AnyDefinition, s as CompletionToolDeclaration, x as Output } from "./Agent-CN0EWRsR.mjs";
+import { n as WorkerBudgetScope } from "./Worker-CaPYykpe.mjs";
+import { a as ContextWindow } from "./ContextWindow-DRQ5Mbm2.mjs";
+import { n as CompactionError } from "./ContextCompactor-Dxu5zhOL.mjs";
+import { t as DurableStep } from "./DurableStep-Cry_iol4.mjs";
+import { B as RunSubagentChildIdentity, H as RunSubagentEstablishRequest, M as RunOptions, S as RunContextPreparationError, W as RunSubagentJoinRequest, i as ChildEstablishStatus, l as ModelUsageAccounting, t as AgentUpdateAcceptance, x as RunContextPreparation } from "./RunOptions-g1aigcKI.mjs";
+import { t as MessagingHost } from "./MessagingHost-CRk0kXzT.mjs";
+import { i as SubagentHost } from "./SubagentHost-CJUBQlcc.mjs";
+import { t as RunEventSink } from "./RunEventSink-D5aVhISG.mjs";
+import { AiError, LanguageModel, Model, Prompt, Tool, Toolkit } from "effect/unstable/ai";
+import { Cause, Context, Effect, Layer, Option, Schema, Scope, Stream, Tracer } from "effect";
+//#region src/engine/internal/tool-telemetry.d.ts
+interface ToolSpanTelemetryService {
+  /** Measure one Tool handler attempt while isolating every host span-lifecycle defect. */
+  readonly isolateSpanLifecycle: <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<A, E, R>;
+  /** Effect counterpart used by programmatic Tool handlers nested inside an outer Tool stream. */
+  readonly isolateEffectSpanLifecycle: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+  /** Keep Effect AI implementation annotations local while preserving host-owned handler spans. */
+  readonly isolateToolkitHandle: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+declare const ToolSpanTelemetry_base: Context.ServiceClass<ToolSpanTelemetry, "@effect-agent/engine/ToolSpanTelemetry", ToolSpanTelemetryService>;
+/**
+ * @internal Engine-owned span-lifecycle policy. The AgentRuntime composition boundary builds this
+ * capability from the host's ambient Tracer; Tool execution consumes it without selecting,
+ * decorating, or locally providing a Tracer implementation.
+ */
+declare class ToolSpanTelemetry extends ToolSpanTelemetry_base {
+  static readonly layer: Layer.Layer<ToolSpanTelemetry>;
+}
+//#endregion
+//#region src/engine/internal/agent-runtime.d.ts
+type RuntimeProgram<InputSchema extends Schema.Top, OutputSchema extends Schema.Top, Instructions, Tools extends Record<string, Tool.Any>, InstructionError = InstructionErrorOf<Instructions, InputSchema["Type"]>, InstructionRequirements = InstructionRequirementsOf<Instructions, InputSchema["Type"]>, RunDispositionValue extends RunDispositionDeclaration<OutputSchema["Type"], Schema.Top> | undefined = undefined, InputPromptValue extends InputPromptSource<InputSchema["Type"], unknown, unknown> | undefined = undefined, UpdatesSchema extends Schema.Top | undefined = undefined> = {
+  readonly definition: Definition<InputSchema, OutputSchema, Instructions, Toolkit.Toolkit<Tools>, RunDispositionValue, InputPromptValue, UpdatesSchema> & {
+    readonly instructions: InstructionSource<InputSchema["Type"], NoInfer<InstructionError>, NoInfer<InstructionRequirements>>;
+    readonly inputPrompt?: InputPromptValue | undefined;
+  };
+};
+/**
+ * Structural shape of an Agent Binding accepted by the interpreter and by
+ * `AgentSpawner.spawn`: a model-agnostic Definition paired with an explicit
+ * native model Layer whose requirements stay visible. The Layer must provide
+ * LanguageModel, ProviderName, and ModelName, including after requirement capture.
+ */
+type RuntimeBinding<InputSchema extends Schema.Top, OutputSchema extends Schema.Top, Instructions, Tools extends Record<string, Tool.Any>, _Provider, ModelProvides, ModelRequires, InstructionError = InstructionErrorOf<Instructions, InputSchema["Type"]>, InstructionRequirements = InstructionRequirementsOf<Instructions, InputSchema["Type"]>, RunDispositionValue extends RunDispositionDeclaration<OutputSchema["Type"], Schema.Top> | undefined = undefined, InputPromptValue extends InputPromptSource<InputSchema["Type"], unknown, unknown> | undefined = undefined, UpdatesSchema extends Schema.Top | undefined = undefined> = RuntimeProgram<InputSchema, OutputSchema, Instructions, Tools, InstructionError, InstructionRequirements, RunDispositionValue, InputPromptValue, UpdatesSchema> & {
+  readonly model: Layer.Layer<LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName | ModelProvides, never, ModelRequires>;
+};
+type InstructionResultOf<Instructions, Input> = Instructions extends ((input: Input) => infer Result) ? Result : Instructions;
+type InstructionErrorOf<Instructions, Input> = InstructionResultOf<Instructions, Input> extends Effect.Effect<infer _Success, infer Error, infer _Requirements> ? Error : never;
+type InstructionRequirementsOf<Instructions, Input> = InstructionResultOf<Instructions, Input> extends Effect.Effect<infer _Success, infer _Error, infer Requirements> ? Requirements : never;
+type InputPromptErrorOf<InputPromptValue, Input> = InputPromptValue extends ((input: Input) => infer Result) ? Result extends Effect.Effect<infer _Success, infer Error, infer _Requirements> ? Error : never : never;
+type InputPromptRequirementsOf<InputPromptValue, Input> = InputPromptValue extends ((input: Input) => infer Result) ? Result extends Effect.Effect<infer _Success, infer _Error, infer Requirements> ? Requirements : never : never;
+/** Schema factory for the terminal value produced by reducing a completed agent event stream. */
+declare const AgentResultSchema: <Output extends Schema.Top>(output: Output) => Schema.Struct<{
+  readonly output: Output;
+  readonly threadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
+  readonly runId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/RunId">;
+  readonly turns: Schema.Int;
+  readonly finishReason: Schema.Literals<readonly ["completed", "model-stop", "budget-exhausted"]>;
+  /** Dimension that bound when the Run settled budget-exhausted (RUN-025; the grant-flow marker). */
+  readonly exhausted: Schema.optionalKey<Schema.Literals<readonly ["tokens", "tool-calls", "turns"]>>;
+  /** Schema-encoded application disposition declared for an ordinary completed Run. */
+  readonly runDisposition: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+  /** Cumulative spend for the Run, as reported on its terminal event. */
+  readonly usage: Schema.optionalKey<typeof RunTotals>;
+  /** Disjoint usage of attached descendants, including nested and failed children. */
+  readonly delegatedUsage: Schema.optionalKey<typeof RunTotals>;
+}>;
+/** Decoded terminal value produced by reducing a completed agent event stream. */
+type AgentResult<Output> = ReturnType<typeof AgentResultSchema<Schema.Schema<Output>>>["Type"];
+/** Expected agent, policy, and model-protocol failures exposed by the runtime. */
+type AgentRuntimeFailure<AgentValue extends AnyDefinition | Any, HookError = never, InstructionError = never> = Failure<AgentValue> | ([UpdatesSchema<AgentValue>] extends [never] ? never : UpdateError) | AgentPolicyError | ContextBudgetError | ContextOverflowError | CompactionError | RunContextPreparationError | ModelProtocolError | AgentApprovalDenied | AgentToolAuthorizationDenied | AgentApprovalPending | AgentChildPending | ThreadHistoryError | HookError | InstructionError;
+/**
+ * Services the engine itself provides locally to every Run: `AgentSpawner`
+ * bound to the Run's immutable identity and delegation depth, `RunEventSink`
+ * and `SubagentDurability` bound to the active Tool batch, `DurableStep`
+ * bound to the active Tool Call, and `ToolSpanTelemetry` bound at the Run
+ * composition edge. They are excluded from the runtime's public
+ * requirements and MUST NOT be satisfied from an application Layer.
+ */
+type EngineProvidedToolServices = Emitter | AgentSpawner | RunEventSink | DurableStep | SubagentDurability | SubagentHost | MessagingHost | ToolBroker | ToolSpanTelemetry | ContextWindow | CurrentToolCatalog;
+/** Schema services needed to reconstruct a completion Tool's canonical Agent output. */
+type AgentCompletionProjectionRequirements<AgentValue extends AnyDefinition | Any> = OutputSchema<AgentValue>["DecodingServices"] | OutputSchema<AgentValue>["EncodingServices"] | Tool.ParametersSchema<ToolUnion<AgentValue>>["DecodingServices"] | Tool.SuccessSchema<ToolUnion<AgentValue>>["DecodingServices"];
+/**
+ * Inferred agent services plus the runtime's identity and Thread history authorities.
+ * Engine-provided Tool handler services are excluded because the interpreter
+ * supplies them itself, bound to the current Run's identity. Tool parameter
+ * encoding, output decoding, and completion-projection Schema services stay
+ * listed unexcluded: the interpreter records canonical parameters before the
+ * handler boundary, `run`/`start` re-decode terminal output, and durable recovery
+ * re-decodes canonical completion Tool parameters/results.
+ */
+type AgentRuntimeRequirements<AgentValue extends AnyDefinition | Any, HookRequirements = never, InstructionRequirements = never> = Exclude<Requirements<AgentValue>, EngineProvidedToolServices> | Tool.ParametersSchema<ToolUnion<AgentValue>>["EncodingServices"] | AgentCompletionProjectionRequirements<AgentValue> | OutputSchema<AgentValue>["DecodingServices"] | ThreadHistory | HookRequirements | InstructionRequirements;
+/** Render decoded Agent input for model visibility, preserving the legacy JSON default. */
+declare function renderInputPrompt<Input, InputPromptValue extends InputPromptSource<NoInfer<Input>, unknown, unknown> | undefined>(inputPrompt: InputPromptValue, decodedInput: Input, encodedInput: unknown): Effect.Effect<Prompt.RawInput, AgentInputError | InputPromptErrorOf<InputPromptValue, Input>, InputPromptRequirementsOf<InputPromptValue, Input>>;
+declare const decodeFinalOutput: <AgentValue extends Any>(agent: AgentValue, text: string) => Effect.Effect<{
+  readonly encoded: Schema.Json;
+  readonly decoded: Output<AgentValue>;
+}, AgentOutputError, OutputSchema<AgentValue>["DecodingServices"]>;
+declare const projectCompletionOutput: <AgentValue extends Any>(agent: AgentValue, declaration: CompletionToolDeclaration<unknown, unknown, unknown>, parameters: unknown, result: unknown) => Effect.Effect<{
+  encoded: Schema.Json;
+  decoded: unknown;
+}, AgentOutputError | ModelProtocolError, unknown>;
+/** Reconstruct optional action completion identically for live execution and canonical recovery. */
+declare const projectCompletionFromToolOutput: <AgentValue extends Any>(agent: AgentValue, declaration: CompletionFromToolDeclaration<unknown, unknown, unknown>, parameters: unknown, result: unknown) => Effect.Effect<Option.None<{
+  encoded: Schema.Json;
+  decoded: unknown;
+}> | Option.Some<{
+  encoded: Schema.Json;
+  decoded: unknown;
+}>, AgentOutputError | ModelProtocolError, unknown>;
+declare function encodeRunDisposition<AgentValue extends Any>(agent: AgentValue, output: Output<AgentValue>): Effect.Effect<Schema.Json | undefined, RunDispositionFailure<AgentValue>, RunDispositionSchema<AgentValue>["EncodingServices"]>;
+/**
+ * Scoped detached execution whose observers cannot backpressure Run
+ * completion.
+ *
+ * `observe` is a live multicast subscription: each subscription replays every
+ * event the Run has already emitted, follows subsequent events as they occur,
+ * and ends once the Run settles. The finite Run event ceiling sizes the replay
+ * buffer so events are never dropped for a slow subscriber and publishing
+ * never blocks the Run. `events` remains the complete bounded replay,
+ * available after settlement. Both belong to the `start` Scope; observing
+ * after that Scope closes interrupts the observer.
+ */
+interface DetachedRun<Output, Error> {
+  readonly await: Effect.Effect<AgentResult<Output>, Error>;
+  readonly events: Effect.Effect<ReadonlyArray<RunEvent>>;
+  readonly observe: Stream.Stream<RunEvent>;
+  /** Snapshot of observed usage, also available after failure, defect, or interruption. Read after
+   * await settles (or the owning Scope closes) for a final report. In-flight work may be unpriced. */
+  readonly usageReport: Effect.Effect<RunUsageReport>;
+}
+/** Executable definitions or explicit per-agent model Layers for registration and delegation. */
+type ExecutableDefinition = AnyDefinition & {
+  readonly instructions: InstructionSource<never, unknown, unknown>;
+};
+type ExecutableAgent = ExecutableDefinition | {
+  readonly definition: ExecutableDefinition;
+  readonly model: Layer.Layer<LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName, never, unknown>;
+};
+/** Decode external input before instructions or model execution. */
+declare const streamUnknown: <A extends ExecutableAgent, H = never, R = never>(agent: A, input: unknown, options?: RunOptions<H, R>) => Stream.Stream<RunEvent, AgentRuntimeFailure<A, H>, AgentRuntimeRequirements<A, R>>;
+/**
+ * Host interpreter entry point with Attempt-local usage accounting and update acceptance in R.
+ * Durable coordinators provide these services alongside their recovery hooks;
+ * ordinary callers use streamUnknown's explicit ephemeral composition.
+ */
+declare const streamWithUsageAccountingUnknown: <A extends ExecutableAgent, H = never, R = never>(agent: A, input: unknown, options?: RunOptions<H, R>) => Stream.Stream<RunEvent, AgentRuntimeFailure<A, H>, AgentRuntimeRequirements<A, R> | ModelUsageAccounting | AgentUpdateAcceptance>;
+/** Accept schema-encoded input, retaining runtime validation. Use streamUnknown for external data. */
+declare const stream: <A extends ExecutableAgent, H = never, R = never>(agent: A, input: NoInfer<EncodedInput<A>>, options?: RunOptions<H, R>) => Stream.Stream<RunEvent, AgentRuntimeFailure<A, H>, AgentRuntimeRequirements<A, R>>;
+/** Decode external input before instructions or model execution. */
+declare function runUnknown<A extends ExecutableAgent, H = never, R = never>(agent: A, input: unknown, options?: RunOptions<H, R>): Effect.Effect<AgentResult<Output<A>>, AgentRuntimeFailure<A, H>, AgentRuntimeRequirements<A, R>>;
+/** Accept schema-encoded input, retaining runtime validation. Use runUnknown for external data. */
+declare const run: <A extends ExecutableAgent, H = never, R = never>(agent: A, input: NoInfer<EncodedInput<A>>, options?: RunOptions<H, R>) => Effect.Effect<AgentResult<Output<A>>, AgentRuntimeFailure<A, H>, AgentRuntimeRequirements<A, R>>;
+/** Decode external input before instructions or model execution. */
+declare function startUnknown<A extends ExecutableAgent, H = never, R = never>(agent: A, input: unknown, options?: RunOptions<H, R>): Effect.Effect<DetachedRun<Output<A>, AgentRuntimeFailure<A, H>>, never, AgentRuntimeRequirements<A, R> | Scope.Scope>;
+/** Accept schema-encoded input, retaining runtime validation. Use startUnknown for external data. */
+declare const start: <A extends ExecutableAgent, H = never, R = never>(agent: A, input: NoInfer<EncodedInput<A>>, options?: RunOptions<H, R>) => Effect.Effect<DetachedRun<Output<A>, AgentRuntimeFailure<A, H>>, never, AgentRuntimeRequirements<A, R> | Scope.Scope>;
+/**
+ * Immutable parent Run identity carried by the locally provided
+ * `AgentSpawner`. It exposes no mutable engine state and no Layer Context.
+ */
+interface AgentSpawnerParent {
+  readonly agentId: AgentId;
+  readonly threadId: ThreadId;
+  readonly runId: RunId;
+}
+declare const ToolCallWaiting_base: Schema.Class<ToolCallWaiting, Schema.TaggedStruct<"ToolCallWaiting", {
+  readonly toolCallId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ToolCallId">;
+  readonly childThreadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
+  readonly childSubmissionId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/SubmissionId">;
+  readonly childRunId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/RunId">;
+  readonly receiptId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ReceiptId">;
+  readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * Typed engine-owned suspension signal raised by a delegation Tool handler
+ * through the per-batch `SubagentDurability` service when its durable child
+ * is established but not settled (S2 plan §2). It is NOT a Tool failure: the
+ * batch executor treats the raising call as "stays open" — no terminal
+ * result, no `ToolCallFailed`, no batch failure policy, no sibling
+ * interruption — and terminates the Run with `AgentChildPending` after every
+ * non-waiting sibling handler settled.
+ */
+declare class ToolCallWaiting extends ToolCallWaiting_base {}
+declare const AgentChildPending_base: Schema.Class<AgentChildPending, Schema.TaggedStruct<"AgentChildPending", {
+  readonly children: Schema.NonEmptyArray<Schema.Struct<{
+    readonly toolCallId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ToolCallId">;
+    readonly childThreadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
+    readonly childSubmissionId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/SubmissionId">;
+    readonly childRunId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/RunId">;
+  }>>;
+  readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * The Run suspended `waitingForChild`: at least one durable delegation call
+ * of the last Tool batch is waiting on its attached child.
+ * Mirrors `AgentApprovalPending`: the engine emits
+ * `RunSuspended` and then fails the Run stream with this error; the durable
+ * coordinator catches it and ends the Attempt's ownership period without
+ * settling. `children` is listed in declaration order, deterministically.
+ */
+declare class AgentChildPending extends AgentChildPending_base {}
+declare const SubagentDurabilityError_base: Schema.Class<SubagentDurabilityError, Schema.TaggedStruct<"SubagentDurabilityError", {
+  readonly operation: Schema.Literals<readonly ["establish", "join", "waiting"]>;
+  readonly reason: Schema.Literals<readonly ["hook-failed", "no-active-tool-batch"]>;
+  readonly message: Schema.String;
+  readonly toolCallId: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ToolCallId">>;
+  /** Diagnostic cause for the live Effect only; Run events retain the fixed public message. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, Cause.YieldableError>;
+/**
+ * Typed failure of the engine-provided `SubagentDurability` operations.
+ * `hook-failed` wraps a coordinator hook failure without leaking the hook's
+ * error type into handler signatures (the `DurableStepError` precedent);
+ * `no-active-tool-batch` is the fail-closed Run-level default — establishment
+ * outside an active Tool batch never silently degrades to ephemeral spawning.
+ */
+declare class SubagentDurabilityError extends SubagentDurabilityError_base {}
+/**
+ * Explicit ephemeral mode: no durable coordinator supplied
+ * `RunOptions.subagent`, so no durable claim is being made and the delegation
+ * handler keeps the S1 in-process spawn semantics honestly.
+ */
+interface SubagentDurabilityEphemeral {
+  readonly mode: "ephemeral";
+}
+/**
+ * Durable mode: establishment and join run through the coordinator's
+ * `RunSubagentHook` under the parent's ownership fence, and `waiting` raises
+ * the engine-owned suspension signal for a still-running child.
+ */
+interface SubagentDurabilityDurable {
+  readonly mode: "durable";
+  /** Idempotent durable child establishment under the parent ownership fence. */
+  readonly establish: (request: RunSubagentEstablishRequest) => Effect.Effect<ChildEstablishStatus, SubagentDurabilityError>;
+  /** Atomic settlement join: `SubagentJoined` + parent `ToolCallSettled` in one canonical batch (SUB-019). */
+  readonly join: (request: RunSubagentJoinRequest) => Effect.Effect<void, SubagentDurabilityError>;
+  /**
+   * Raise the waiting suspension signal for one delegation call whose
+   * established child has not settled. Never returns: the handler ends here,
+   * siblings run to completion, the Run suspends, and the resumed batch
+   * re-executes the handler idempotently.
+   */
+  readonly waiting: (toolCallId: ToolCallId, child: RunSubagentChildIdentity) => Effect.Effect<never, ToolCallWaiting | SubagentDurabilityError>;
+}
+/**
+ * Mode-dispatched service value seen by delegation Tool handlers: an explicit
+ * ephemeral default when the Run carries no durable coordinator, the durable
+ * establish/join/waiting surface otherwise.
+ */
+type SubagentDurabilityService = SubagentDurabilityEphemeral | SubagentDurabilityDurable;
+declare const SubagentDurability_base: Context.ServiceClass<SubagentDurability, "@effect-agent/engine/SubagentDurability", SubagentDurabilityService>;
+/**
+ * Engine-owned durable-Subagent seam provided locally to every Tool batch,
+ * constructed from `RunOptions.subagent` when present and the explicit
+ * ephemeral-mode default when absent. Like the other engine-provided Tool
+ * services it is excluded from the runtime's public requirements and MUST NOT
+ * be satisfied from an application Layer; handlers resolve it per call (the
+ * S1 innermost re-provide pattern) so a Layer built inside another Run's
+ * batch never captures a stale mode.
+ */
+declare class SubagentDurability extends SubagentDurability_base {}
+/** Stable delegation identity supplied by the invoking delegation Tool handler. */
+interface SpawnDelegation {
+  readonly delegationId: DelegationId;
+  readonly parentToolCallId: ToolCallId;
+}
+/**
+ * Child Run options accepted by `AgentSpawner.spawn`. Child Thread/Run
+ * identity and the Parent Link are spawner-owned and cannot be overridden.
+ */
+interface SpawnRunOptions<HookError = never, HookRequirements = never> extends Omit<RunOptions<HookError, HookRequirements>, "threadId" | "runId" | "parentLink"> {}
+/**
+ * Handle to one spawned Attached Child: its preallocated child identity, its
+ * immutable Parent Link, and the same observation surface as `DetachedRun`.
+ * The child fiber belongs to the Scope the caller provided to `spawn`.
+ */
+interface SpawnedChildRun<Output, Error> extends DetachedRun<Output, Error> {
+  readonly threadId: ThreadId;
+  readonly runId: RunId;
+  readonly parentLink: SubagentParentLink;
+}
+/**
+ * Narrow parent execution value visible to Tool handlers. `depth` is the
+ * current Run's root-relative delegation depth: `0` for a root Run and
+ * `parentLink.depth` for a child, which the delegation preflight uses to
+ * enforce inherited nesting ceilings and conserved subtree allocations.
+ */
+interface AgentSpawnerService {
+  /** Resolved defaults for this parent Run; never includes its tools or handlers. */
+  readonly policy: AgentPolicy;
+  readonly depth: number;
+  readonly grant?: SubagentGrant;
+  readonly budget?: SubagentBudgetReservation;
+  readonly budgetScope?: WorkerBudgetScope;
+  readonly parent: AgentSpawnerParent;
+  readonly spawn: <InputSchema extends Schema.Top, OutputSchema extends Schema.Top, Instructions, Tools extends Record<string, Tool.Any>, Provider, ModelProvides, ModelRequires, HookError = never, HookRequirements = never, InstructionError = InstructionErrorOf<Instructions, InputSchema["Type"]>, InstructionRequirements = InstructionRequirementsOf<Instructions, InputSchema["Type"]>, RunDispositionValue extends RunDispositionDeclaration<OutputSchema["Type"], Schema.Top> | undefined = undefined, InputPromptValue extends InputPromptSource<InputSchema["Type"], unknown, unknown> | undefined = undefined, UpdatesSchema extends Schema.Top | undefined = undefined>(binding: RuntimeBinding<InputSchema, OutputSchema, Instructions, Tools, Provider, ModelProvides, ModelRequires, InstructionError, InstructionRequirements, RunDispositionValue, InputPromptValue, UpdatesSchema>, input: unknown, delegation: SpawnDelegation, options?: SpawnRunOptions<HookError, HookRequirements>) => Effect.Effect<SpawnedChildRun<OutputSchema["Type"], AgentRuntimeFailure<RuntimeBinding<InputSchema, OutputSchema, Instructions, Tools, Provider, ModelProvides, ModelRequires, InstructionError, InstructionRequirements, RunDispositionValue, InputPromptValue, UpdatesSchema>, HookError, InstructionError>>, never, Scope.Scope | Exclude<AgentRuntimeRequirements<RuntimeBinding<InputSchema, OutputSchema, Instructions, Tools, Provider, ModelProvides, ModelRequires, InstructionError, InstructionRequirements, RunDispositionValue, InputPromptValue, UpdatesSchema>, HookRequirements, InstructionRequirements>, ThreadHistory | RunContextPreparation>>;
+}
+declare const AgentSpawner_base: Context.ServiceClass<AgentSpawner, "@effect-agent/engine/AgentSpawner", AgentSpawnerService>;
+/**
+ * Engine-owned service contract through which a declared delegation Tool
+ * runs an Attached Child on the same interpreter.
+ *
+ * The engine provides this service locally to every Run, bound to the Run's
+ * immutable identity and delegation depth; it is never satisfied from an
+ * application Layer, is excluded from the runtime's public requirements, and
+ * exposes neither the engine's mutable Run state nor any root Layer Context.
+ */
+declare class AgentSpawner extends AgentSpawner_base {}
+/**
+ * Opt-in boundary combinator (P7 §7(h), decision point 8): the engine keeps defects as
+ * defects — `RunFailed` covers EXPECTED failures only, and a defect still fails the event
+ * stream with its full Cause (AGENTS.md: errors are never silently widened, and a defect is
+ * never converted into a typed failure by default). A host boundary that forwards Run Events
+ * to a UI or transport can wrap the stream with this helper to append ONE bounded terminal
+ * `RunFailed { errorTag: "Defect" }` event before the original cause is rethrown, so a viewer
+ * always observes a terminal event even when the Run dies.
+ *
+ * Event contract:
+ *
+ * - typed failures and interruptions pass through untouched — the engine already emitted
+ *   their terminal event, so nothing is duplicated;
+ * - a cause carrying a defect first emits `RunFailed` with `errorTag: "Defect"` and a
+ *   bounded string rendering of the defect (never the raw value; hosts owning stricter
+ *   redaction apply it downstream), then RETHROWS the original cause unchanged;
+ * - identity fields come from the last event already streamed (`sequence` advances by one);
+ *   a defect BEFORE the first event has no Run identity to attribute, so it is rethrown
+ *   without an event — the helper never fabricates identities.
+ */
+declare const withTerminalDefectEvent: <E, R>(events: Stream.Stream<RunEvent, E, R>) => Stream.Stream<RunEvent, E, R>;
+declare namespace AgentRuntime_d_exports {
+  export { AgentChildPending, AgentCompletionProjectionRequirements, AgentResult, AgentResultSchema, AgentRuntimeFailure, AgentRuntimeRequirements, AgentSpawner, AgentSpawnerParent, AgentSpawnerService, DetachedRun, EngineProvidedToolServices, RuntimeBinding, SpawnDelegation, SpawnRunOptions, SpawnedChildRun, SubagentDurability, SubagentDurabilityDurable, SubagentDurabilityEphemeral, SubagentDurabilityError, SubagentDurabilityService, ToolCallWaiting, decodeFinalOutput, encodeRunDisposition, projectCompletionFromToolOutput, projectCompletionOutput, renderInputPrompt, run, runUnknown, start, startUnknown, stream, streamUnknown, streamWithUsageAccountingUnknown, withTerminalDefectEvent };
+}
+//#endregion
+export { start as A, decodeFinalOutput as C, renderInputPrompt as D, projectCompletionOutput as E, withTerminalDefectEvent as F, stream as M, streamUnknown as N, run as O, streamWithUsageAccountingUnknown as P, ToolCallWaiting as S, projectCompletionFromToolOutput as T, SubagentDurability as _, AgentResultSchema as a, SubagentDurabilityError as b, AgentSpawner as c, DetachedRun as d, EngineProvidedToolServices as f, SpawnedChildRun as g, SpawnRunOptions as h, AgentResult as i, startUnknown as j, runUnknown as k, AgentSpawnerParent as l, SpawnDelegation as m, AgentChildPending as n, AgentRuntimeFailure as o, RuntimeBinding as p, AgentCompletionProjectionRequirements as r, AgentRuntimeRequirements as s, AgentRuntime_d_exports as t, AgentSpawnerService as u, SubagentDurabilityDurable as v, encodeRunDisposition as w, SubagentDurabilityService as x, SubagentDurabilityEphemeral as y };
+//# sourceMappingURL=AgentRuntime-uxR_a4VM.d.mts.map

package/dist/AgentUpdates-DMJ-_xow.d.mts

@@ -0,0 +1,53 @@
+import { t as AgentId } from "./Identifiers-CN2s30fF.mjs";
+import { t as IdempotencyKey } from "./Receipt-BAHyigAF.mjs";
+import { Context, Effect, Schema, Stream } from "effect";
+declare namespace AgentUpdates_d_exports {
+  export { Emitter, Update, UpdateError, decode, emit, observe };
+}
+declare const Update_base: Schema.Class<Update, Schema.Struct<{
+  readonly schemaVersion: Schema.Literal<1>;
+  readonly agentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/AgentId">;
+  readonly threadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
+  readonly runId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/RunId">;
+  readonly updateId: Schema.brand<Schema.NonEmptyString, "@effect-agent/thread/IdempotencyKey">;
+  readonly sequence: Schema.Int;
+  readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, {}>;
+/** Canonical schema-encoded intermediate output, scoped to one logical Run. */
+declare class Update extends Update_base {}
+declare const UpdateError_base: Schema.Class<UpdateError, Schema.TaggedStruct<"AgentUpdateError", {
+  readonly reason: Schema.Literals<readonly ["validation", "unavailable", "conflict", "capacity", "storage", "identity", "denied"]>;
+}>, import("effect/Cause").YieldableError>;
+/** Fail-closed update acceptance and decoding errors; payloads are never included. */
+declare class UpdateError extends UpdateError_base {}
+declare const Emitter_base: Context.ServiceClass<Emitter, "@effect-agent/core/AgentUpdates/Emitter", {
+  readonly emit: (request: {
+    readonly target: {
+      readonly id: AgentId;
+      readonly updates?: Schema.Top | undefined;
+    };
+    readonly updateId: IdempotencyKey;
+    readonly value: Schema.Json;
+  }) => Effect.Effect<Update, UpdateError>;
+}>;
+/** Engine-owned invocation port. The Agent ID and exact update Schema must match the executing definition. */
+declare class Emitter extends Emitter_base {}
+/** Structural schema boundary accepted by definitions and their model bindings. */
+type Source<S extends Schema.Top> = {
+  readonly id: AgentId;
+  readonly updates?: S | undefined;
+};
+type BoundSource<S extends Schema.Top> = Source<S> | {
+  readonly definition: Source<S>;
+};
+/** Emit a decoded update under an explicit stable key. Retries cannot replace accepted values. */
+declare const emit: <S extends Schema.Top>(agent: BoundSource<S>, value: NoInfer<S["Type"]>, options: {
+  readonly idempotencyKey: IdempotencyKey;
+}) => Effect.Effect<Update, UpdateError, Emitter | S["EncodingServices"]>;
+/** Decode canonical update data through its declaring Agent Schema. */
+declare const decode: <S extends Schema.Top>(agent: BoundSource<S>, update: Update) => Effect.Effect<S["Type"], UpdateError, S["DecodingServices"]>;
+/** Decode an encoded update stream without hiding its failures or requirements. */
+declare const observe: <S extends Schema.Top, E, R>(agent: BoundSource<S>, updates: Stream.Stream<Update, E, R>) => Stream.Stream<S["Type"], E | UpdateError, R | S["DecodingServices"]>;
+//#endregion
+export { decode as a, UpdateError as i, Emitter as n, emit as o, Update as r, observe as s, AgentUpdates_d_exports as t };
+//# sourceMappingURL=AgentUpdates-DMJ-_xow.d.mts.map

package/dist/ContextCompactor-Dxu5zhOL.d.mts

@@ -0,0 +1,161 @@
+import { s as RunId, u as ThreadId } from "./Identifiers-CN2s30fF.mjs";
+import { i as CompactionPolicy } from "./AgentPolicy-CetmQrf3.mjs";
+import { n as ContextRolloverRequest } from "./ContextWindow-DRQ5Mbm2.mjs";
+import { LanguageModel, Model, Prompt } from "effect/unstable/ai";
+import { Context, Effect, Layer, Option, Schema, Stream } from "effect";
+//#region src/engine/internal/compaction.d.ts
+/**
+ * Pure helpers for engine-native context compaction (RUN-026/RUN-027). Everything here is deterministic and side-effect free:
+ * the engine's turn loop owns the state transitions, the durable coordinator
+ * owns the canonical record, and this module owns the arithmetic.
+ *
+ * Compaction is a VIEW over official history, never a mutation of it. The
+ * durable commit machinery slices official history by length
+ * (`lastCommitLen` in the coordinator), so official history must stay
+ * append-only within an Attempt; only the outgoing model prompt is rebuilt.
+ */
+/** Model-visible replacement for a tool result cleared by prune compaction. */
+declare const CLEARED_TOOL_RESULT = "[tool result cleared by compaction]";
+/** Prefix of the user message that carries a compaction summary into the prompt. */
+declare const COMPACTION_SUMMARY_PREFIX = "The prior thread was compacted into this summary:\n\n";
+/** Rollover text is recovery evidence; it never asserts that an external action succeeded. */
+declare const CONTEXT_ROLLOVER_PREFIX = "A fresh context window has started. Earlier conversation has left this model view. Restore relevant notes and use available history tools to retrieve evidence; verify live state before repeating an action.\n\n";
+/** Stable across Attempts; the initial window uses turn zero. */
+declare const contextWindowId: (runId: string, turn: number) => string;
+/** Shared by the live interpreter and canonical journal projection. */
+declare const contextWindowMessage: (windowId: string, handoff?: string) => Prompt.Message;
+/**
+ * Deterministic UTF-8 bytes/4 token estimate over one message's structural JSON.
+ * Conservative for prose, slightly generous for dense JSON — the estimate
+ * only gates WHEN to compact, never what is preserved.
+ */
+declare const estimateMessageTokens: (message: Prompt.Message) => number;
+/** Sum of `estimateMessageTokens` over a message array. */
+declare const estimatePromptTokens: (messages: ReadonlyArray<Prompt.Message>, estimate?: (message: Prompt.Message) => number) => number;
+/**
+ * Mutable per-Run compaction state held on the engine's RunContext. Indices
+ * are positions in the SOURCE prompt (the official-history basis handed to
+ * each Turn). Ordinary history grows append-only. Prepared history must retain
+ * content-equivalent covered prefixes or the engine rejects the next Turn.
+ */
+interface ContextCompactionState {
+  /**
+   * Source-index bounds `[start, end)` of the protected instruction/input
+   * block, mapped to prepared indices when necessary. `-1` before mapping;
+   * an unmappable protected block fails before any compaction decision.
+   */
+  protectedStart: number;
+  protectedEnd: number;
+  /** Prepared prompts also retain application-added system instructions. */
+  protectSystemMessages?: boolean;
+  /** Tool messages at source index below this bound render as cleared. */
+  clearedThrough: number;
+  /**
+   * Source messages below this bound (outside the protected block) are
+   * replaced by a summary or a fresh-window marker. Absent before the first replacement.
+   */
+  replacement: {
+    readonly kind: "summarize";
+    readonly through: number;
+    readonly summary: string;
+  } | {
+    readonly kind: "rollover";
+    readonly through: number;
+    readonly windowId: string;
+    readonly handoff?: string;
+  } | undefined;
+  /** Loop guard: at most one threshold compaction per Turn. */
+  lastCompactionTurn: number;
+  /** RUN-027 guard: at most one overflow compact-and-retry per Turn. */
+  overflowRetryTurn: number;
+  /**
+   * View length at the last model call, the base of the provider-anchored
+   * estimate. `-1` invalidates it (fresh Run or just compacted), forcing a
+   * full-view estimate.
+   */
+  lastViewLength: number;
+}
+declare namespace ContextCompactor_d_exports {
+  export { CompactionDecision, CompactionError, CompactionModelLayer, CompactionRequest, ContextCompaction, ContextCompactor, ContextMessageTokenEstimator };
+}
+/**
+ * A proposed view change. Source indices are exclusive prefix bounds, never record sequences.
+ * Summaries contain at most 65,536 characters; the interpreter rejects oversized decisions
+ * before committing or changing coverage.
+ */
+declare const CompactionDecision: Schema.Union<readonly [Schema.Struct<{
+  readonly kind: Schema.Literal<"rollover">;
+  readonly through: Schema.Natural;
+  readonly handoff: Schema.optionalKey<Schema.NonEmptyString>;
+}>, Schema.Struct<{
+  readonly kind: Schema.Literal<"clear-tool-results">;
+  readonly through: Schema.Natural;
+}>, Schema.Struct<{
+  readonly kind: Schema.Literal<"summarize">;
+  readonly through: Schema.Natural;
+  readonly summary: Schema.NonEmptyString;
+}>]>;
+type CompactionDecision = typeof CompactionDecision.Type;
+declare const CompactionError_base: Schema.Class<CompactionError, Schema.TaggedStruct<"CompactionError", {
+  readonly message: Schema.String;
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/** Expected strategy or decision-validation failure. Causes stay in the live Effect only. */
+declare class CompactionError extends CompactionError_base {}
+/** Upstream Model.captureRequirements returns this closed Layer. */
+type CompactionModelLayer = Layer.Layer<LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName>;
+/** A full message estimate, or undefined to use the native structural estimate. */
+type ContextMessageTokenEstimator = (message: Prompt.Message) => number | undefined;
+/**
+ * One bounded pass over an immutable source snapshot. A harness owns state, metering, and
+ * application of decisions. The interpreter permits at most one prune followed by one replacement
+ * (summary or rollover), and one call to summarize per Turn, shared across every trigger.
+ * All model work must use summarize so it is metered.
+ * Callback failures and requirements pass through unchanged; strategy dependencies belong to
+ * its construction Layer. Protected messages cannot be removed and Tool pairs cannot be split by a decision.
+ */
+interface CompactionRequest<E, R> {
+  readonly threadId: ThreadId;
+  readonly runId: RunId;
+  readonly turn: number;
+  readonly source: Prompt.Prompt;
+  readonly state: Readonly<ContextCompactionState>;
+  readonly policy: CompactionPolicy;
+  readonly targetTokens: number | undefined;
+  readonly trigger: "pressure" | "overflow" | "requested";
+  /** Budget admission may prohibit a separate model call while still allowing a rollover. */
+  readonly modelCallAllowed: boolean;
+  /** The current captured Model's message accounting, including native fallback. */
+  readonly estimateMessageTokens?: ContextMessageTokenEstimator | undefined;
+  /** Present for a successful, singleton context rollover Tool; through excludes later steering. */
+  readonly requested?: (ContextRolloverRequest & {
+    readonly through: number;
+  }) | undefined;
+  readonly summarize: (prompt: Prompt.Prompt, model?: CompactionModelLayer) => Effect.Effect<string, E, R>;
+}
+interface ContextCompaction {
+  /** Non-negative finite integer estimate, used for admission and derived prompt overhead too. */
+  readonly estimate: (messages: ReadonlyArray<Prompt.Message>) => number;
+  /** Emit decisions sequentially; the consumer commits each before pulling the next. */
+  readonly compact: <E, R>(request: CompactionRequest<E, R>) => Stream.Stream<CompactionDecision, E | CompactionError, R>;
+}
+declare const ContextCompactor_base: Context.ServiceClass<ContextCompactor, "@effect-agent/engine/ContextCompactor", ContextCompaction>;
+/**
+ * The sole interpreter compaction port. Runs without an installed service provide layer at their
+ * composition boundary. Decorators yield this service during construction and receive their
+ * underlying implementation through Layer.provide. Direct harnesses use the same Layer contract.
+ */
+declare class ContextCompactor extends ContextCompactor_base {
+  static readonly layer: Layer.Layer<ContextCompactor, never, never>;
+  /**
+   * Start fresh windows without a summarizer call. The engine retains instructions/input and
+   * commits each boundary; a bounded emergency handoff preserves user inputs and unseen results.
+   * Applications provide notes/history tools alongside this strategy.
+   */
+  static readonly layerRollover: Layer.Layer<ContextCompactor, never, never>;
+  /** Use the bounded default algorithm with a separate upstream Effect AI Model. */
+  static readonly layerWithModel: <Provider, Requirements>(model: Model.Model<Provider, LanguageModel.LanguageModel, Requirements>) => Layer.Layer<ContextCompactor, never, Requirements>;
+}
+//#endregion
+export { ContextCompaction as a, ContextMessageTokenEstimator as c, CONTEXT_ROLLOVER_PREFIX as d, ContextCompactionState as f, estimatePromptTokens as g, estimateMessageTokens as h, CompactionRequest as i, CLEARED_TOOL_RESULT as l, contextWindowMessage as m, CompactionError as n, ContextCompactor as o, contextWindowId as p, CompactionModelLayer as r, ContextCompactor_d_exports as s, CompactionDecision as t, COMPACTION_SUMMARY_PREFIX as u };
+//# sourceMappingURL=ContextCompactor-Dxu5zhOL.d.mts.map

package/dist/ContextWindow-DRQ5Mbm2.d.mts

@@ -0,0 +1,58 @@
+import { Context, Effect, Schema } from "effect";
+declare namespace ContextWindow_d_exports {
+  export { ContextHandoff, ContextRolloverRequest, ContextRolloverSelection, ContextRolloverTool, ContextWindow, ContextWindowStatus, ModelCallContext };
+}
+/** Model-authored continuation state; fuller notes belong in an application-owned memory store. */
+declare const ContextHandoff: Schema.NonEmptyString;
+/** Successful output of an explicitly designated context-window Tool. */
+declare const ContextRolloverRequest: Schema.Struct<{
+  readonly handoff: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+type ContextRolloverRequest = typeof ContextRolloverRequest.Type;
+/**
+ * Host-selected exclusive source-message boundary, applied at the next safe model seam.
+ * Omit through to reset the prefix before the protected current instructions/input. The
+ * engine resolves that prefix after preparation; an empty prior prefix needs no new window.
+ */
+declare const ContextRolloverSelection: Schema.Struct<{
+  readonly handoff: Schema.optionalKey<Schema.NonEmptyString>;
+  readonly through: Schema.optionalKey<Schema.Natural>;
+}>;
+type ContextRolloverSelection = typeof ContextRolloverSelection.Type;
+declare const ModelCallContext_base: Schema.Class<ModelCallContext, Schema.Struct<{
+  readonly contextCapacity: Schema.Int;
+  readonly maxInputTokens: Schema.optionalKey<Schema.Int>;
+  readonly outputReserveTokens: Schema.Natural;
+  readonly uncountedOverheadTokens: Schema.Natural;
+}>, {}>;
+/**
+ * Bounds resolved alongside the native model for one Turn. Output reserve must match the
+ * selected provider configuration. Uncounted overhead includes only provider framing or image
+ * token costs absent from the prompt estimate; prompt text, output contracts, and native Tool
+ * schemas are counted by the engine. These are live-context bounds, not cumulative Run budgets.
+ */
+declare class ModelCallContext extends ModelCallContext_base {}
+/**
+ * Definition-owned control annotation. A successful singleton application Tool carrying this
+ * annotation returns ContextRolloverRequest. The engine applies it at the next Turn seam,
+ * including after durable Tool-result replay. A Tool name alone never grants this authority.
+ */
+declare const ContextRolloverTool: Context.Reference<boolean>;
+declare const ContextWindowStatus_base: Schema.Class<ContextWindowStatus, Schema.Struct<{
+  readonly threadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
+  readonly runId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/RunId">;
+  readonly windowId: Schema.NonEmptyString;
+  readonly estimatedTokens: Schema.Natural;
+  readonly contextTokenLimit: Schema.NullOr<Schema.Natural>;
+  readonly remainingTokens: Schema.NullOr<Schema.Natural>;
+}>, {}>;
+/** Best available live-context estimate, independent of cumulative Run budgets. */
+declare class ContextWindowStatus extends ContextWindowStatus_base {}
+declare const ContextWindow_base: Context.ServiceClass<ContextWindow, "@effect-agent/engine/ContextWindow", {
+  readonly status: Effect.Effect<ContextWindowStatus>;
+}>;
+/** Engine-owned identity and context accounting for the current Run. */
+declare class ContextWindow extends ContextWindow_base {}
+//#endregion
+export { ContextWindow as a, ModelCallContext as c, ContextRolloverTool as i, ContextRolloverRequest as n, ContextWindowStatus as o, ContextRolloverSelection as r, ContextWindow_d_exports as s, ContextHandoff as t };
+//# sourceMappingURL=ContextWindow-DRQ5Mbm2.d.mts.map