effect-agent 0.1.0-beta.152 → 0.1.0-beta.153

package/src/durable/Records.ts

@@ -498,6 +498,17 @@ export class ModelResponseInterrupted extends Schema.TaggedClass<ModelResponseIn
   reason: BoundedText,
 }) {}
 
+/** Disposable call cancellation: no response or Tool declaration is canonical. */
+export class ModelCallAborted extends Schema.TaggedClass<ModelCallAborted>()("ModelCallAborted", {
+  runId: RunId,
+  turnId: TurnId,
+  turn: TurnNumber,
+  restart: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 2 })),
+  reason: Schema.Literal("joined-input"),
+  modelUsage: Schema.Array(ModelCallUsage),
+  unobservedModelCalls: Schema.Natural,
+}) {}
+
 /**
  * One engine-native compaction committed before the pre-Turn view changes (RUN-026).
  * `coversThrough` is a Thread record sequence: the projection
@@ -1020,6 +1031,7 @@ export const CanonicalRecordPayload = Schema.Union([
   ToolApprovalRequested,
   ToolApprovalDecided,
   ModelResponseInterrupted,
+  ModelCallAborted,
   CompactionCreated,
   RunFailed,
   RunCompleted,

package/src/durable/RunJournal.ts

@@ -1,4 +1,4 @@
-import { type Crypto, Effect, Schema, Stream, type DateTime } from "effect";
+import { type Crypto, Effect, Predicate, Schema, Stream, type DateTime } from "effect";
 import { Prompt } from "effect/unstable/ai";
 
 import { ThreadId, RunId, ToolCallId, TurnId, type SubmissionId } from "../core/Identifiers.ts";
@@ -330,14 +330,34 @@ export const childIdempotencyKeyFor = (
   toolCallId: ToolCallId,
 ): IdempotencyKey => decodeIdempotencyKey(`subagent:${parentRunId}:${toolCallId}`);
 
-const decodePromptMessages = Effect.fn("RunJournal.decodePromptMessages")(
-  (messages: PersistedJson): Effect.Effect<Prompt.Prompt, RunJournalError> =>
-    Schema.decodeUnknownEffect(Prompt.Prompt)(messages).pipe(
-      Effect.mapError((cause) =>
-        journalError("Canonical messages are not Schema-encoded Prompt messages", cause),
-      ),
+const decodePersistedPrompt = (
+  messages: PersistedJson,
+): Effect.Effect<Prompt.Prompt, RunJournalError> =>
+  Schema.decodeUnknownEffect(Prompt.Prompt)(messages).pipe(
+    Effect.mapError((cause) =>
+      journalError("Canonical messages are not Schema-encoded Prompt messages", cause),
     ),
-);
+  );
+
+// Canonical payloads are immutable. Weak keys let retained storage rows own the lifetime
+// while repeated projections of an advancing tail reuse their validated Prompt values.
+const decodedMessages = new WeakMap<object, Prompt.Prompt>();
+
+const decodePromptMessages = (messages: PersistedJson) =>
+  Effect.suspend(() => {
+    if (!Predicate.isObject(messages)) return decodePersistedPrompt(messages);
+    const cached = decodedMessages.get(messages);
+
+    return cached === undefined
+      ? decodePersistedPrompt(messages).pipe(
+          Effect.tap((prompt) =>
+            Effect.sync(() => {
+              decodedMessages.set(messages, prompt);
+            }),
+          ),
+        )
+      : Effect.succeed(cached);
+  });
 
 interface PendingSettledTool {
   readonly record: ToolCallSettled;
@@ -345,24 +365,24 @@ interface PendingSettledTool {
   readonly cleared: boolean;
 }
 
-const toolMessageFromSettled = Effect.fn("RunJournal.toolMessageFromSettled")(
-  (settled: ReadonlyArray<PendingSettledTool>): Effect.Effect<Prompt.Message, RunJournalError> =>
-    Effect.try({
-      try: () =>
-        Prompt.makeMessage("tool", {
-          content: settled.map(({ record, cleared }) =>
-            Prompt.makePart("tool-result", {
-              id: record.toolCallId,
-              name: record.toolName,
-              result: cleared ? CLEARED_TOOL_RESULT : record.result,
-              isFailure: record.isFailure,
-              providerExecuted: false,
-            }),
-          ),
-        }),
-      catch: (cause) => journalError("Unable to rebuild Tool message from ToolCallSettled", cause),
-    }),
-);
+const toolMessageFromSettled = (
+  settled: ReadonlyArray<PendingSettledTool>,
+): Effect.Effect<Prompt.Message, RunJournalError> =>
+  Effect.try({
+    try: () =>
+      Prompt.makeMessage("tool", {
+        content: settled.map(({ record, cleared }) =>
+          Prompt.makePart("tool-result", {
+            id: record.toolCallId,
+            name: record.toolName,
+            result: cleared ? CLEARED_TOOL_RESULT : record.result,
+            isFailure: record.isFailure,
+            providerExecuted: false,
+          }),
+        ),
+      }),
+    catch: (cause) => journalError("Unable to rebuild Tool message from ToolCallSettled", cause),
+  });
 
 /**
  * Pure canonical projection of one Run's durable execution state.
@@ -525,6 +545,7 @@ const PROMPT_TRANSPARENT_TAGS: ReadonlySet<string> = new Set([
   "ToolApprovalRequested",
   "ToolApprovalDecided",
   "ModelResponseInterrupted",
+  "ModelCallAborted",
   "SubagentRequested",
   "SubagentStarted",
   "SubagentJoined",
@@ -892,6 +913,7 @@ export const projectRunJournalStream = Effect.fn("RunJournal.projectRunJournalSt
     programmaticToolCalls: seed?.policyUsage.programmaticToolCalls ?? 0,
     consecutiveToolFailures: seed?.policyUsage.consecutiveToolFailures ?? 0,
     finalizationUsed: seed?.policyUsage.finalizationUsed ?? false,
+    modelRestarts: seed?.policyUsage.modelRestarts ?? 0,
   };
 
   const accountResponse = Effect.fn("RunJournal.accountResponse")(function* (
@@ -1020,7 +1042,7 @@ export const projectRunJournalStream = Effect.fn("RunJournal.projectRunJournalSt
 
   let pendingToolOrder = new Map<string, number>();
 
-  const flushTools = Effect.fn("RunJournal.flushTools")(function* (
+  const flushTools = Effect.fnUntraced(function* (
     current: FoldState,
   ): Effect.fn.Return<FoldState, RunJournalError> {
     if (current.pendingTools.length === 0) return current;
@@ -1068,6 +1090,45 @@ export const projectRunJournalStream = Effect.fn("RunJournal.projectRunJournalSt
         policyUsage.programmaticToolCalls = payload.programmaticToolCalls;
         policyUsage.finalizationUsed = payload.finalizationUsed;
       }
+      if (payload._tag === "ModelCallAborted" && payload.runId === ownerRunId) {
+        if (seed !== undefined && envelope.sequence <= seed.throughSequence) return;
+        if (payload.restart !== policyUsage.modelRestarts + 1)
+          return yield* journalError("Model restart reservations must advance once");
+        policyUsage.modelRestarts = payload.restart;
+
+        const summary = yield* summarizeModelUsage(payload.modelUsage).pipe(
+          Effect.mapError((cause) =>
+            journalError("Aborted model usage exceeds accounting bounds", cause),
+          ),
+        );
+
+        usage.modelCalls = yield* addProjectedUsage(
+          "modelCalls",
+          usage.modelCalls,
+          summary.modelCalls,
+        );
+        usage.inputTokens = yield* addProjectedUsage(
+          "inputTokens",
+          usage.inputTokens,
+          summary.inputTokens.total,
+        );
+        usage.outputTokens = yield* addProjectedUsage(
+          "outputTokens",
+          usage.outputTokens,
+          summary.outputTokens.total,
+        );
+        usage.costMicrousd = yield* addProjectedUsage(
+          "costMicrousd",
+          usage.costMicrousd,
+          summary.costMicrousd,
+        );
+        usage.modelUsage.push(...payload.modelUsage);
+        unobservedModelCalls = yield* addProjectedUsage(
+          "unobservedModelCalls",
+          unobservedModelCalls,
+          payload.unobservedModelCalls,
+        );
+      }
       if (PROMPT_TRANSPARENT_TAGS.has(payload._tag)) return;
       // The compaction record governs the fold (pre-scan) and contributes no
       // message of its own; records at or below the summarize bound render as

package/src/durable/internal/agent-registration.ts

@@ -39,7 +39,7 @@ import { digestDefinitions, digestJson, DigestError } from "../Digest.ts";
 import type { DurableWorkerFailure, DurableWorkerRequirements } from "../DurableAgentRuntime.ts";
 import type { DefinitionDigestInput, PersistedJson } from "../Records.ts";
 import { DefinitionDigests, ReplayContract } from "../Records.ts";
-import type { Claim, Settlement } from "../SubmissionLedger.ts";
+import type { Claim, Settlement, SubmissionSnapshot } from "../SubmissionLedger.ts";
 
 /** No unique current executable is registered for the stable Agent identity. */
 export class BindingUnavailable extends Schema.TaggedError<BindingUnavailable>()(
@@ -49,6 +49,29 @@ export class BindingUnavailable extends Schema.TaggedError<BindingUnavailable>()
 
 export type DurableBindingFailure = BindingUnavailable;
 
+/**
+ * Submission execution/recovery routing for stable identities shared by current Definitions.
+ * Worker declarations and peer-messaging endpoints still require unique Agent identities.
+ */
+export interface BindingSelection {
+  /** Change when routing changes, so hosts can retry parked work without rewriting admission. */
+  readonly key: string;
+  /**
+   * Select an exact registered Definition using the canonical Submission and authoritative host
+   * state. Undefined retains unique-identity resolution. Never grant authority or mutate here;
+   * input decoding, replay contracts and current Tool authorization still apply after selection.
+   */
+  readonly select: (
+    submission: SubmissionSnapshot,
+  ) => Effect.Effect<Agent.AnyDefinition | undefined, DurableWorkerFailure | BindingUnavailable>;
+}
+
+/** Captured at runtime construction; callers cannot replace routing during an Attempt. */
+export const CurrentBindingSelection = Context.Reference<BindingSelection | undefined>(
+  "@effect-agent/thread/CurrentBindingSelection",
+  { defaultValue: () => undefined },
+);
+
 /** Exact immutable admission, lineage and delivery evidence; never an executable-code gate. */
 export const definitionDigestsEqual = (
   left: DefinitionDigests,
@@ -358,50 +381,50 @@ export const DurableWorkerBinding = {
 /** INTERNAL identity-only capture retained for the legacy direct worker path. */
 export const makeLegacyWorkerBinding = capture;
 
-export const resolveWorkerBinding = (
+export const resolveWorkerBinding = Effect.fnUntraced(function* (
   bindings: ReadonlyArray<ResolvedBinding>,
-  agentId: AgentId,
-): Effect.Effect<ResolvedBinding, BindingUnavailable> => {
-  const registered = bindings.filter((binding) => binding.agentId === agentId);
+  submission: SubmissionSnapshot,
+) {
+  const selection = yield* CurrentBindingSelection;
+  const definition = selection === undefined ? undefined : yield* selection.select(submission);
+
+  const registered = bindings.filter(
+    (binding) =>
+      binding.agentId === submission.agentId &&
+      (definition === undefined || Object.is(binding.definition, definition)),
+  );
+
   const binding = registered[0];
 
-  return registered.length === 1 && binding !== undefined
-    ? Effect.succeed(binding)
-    : Effect.fail(
-        BindingUnavailable.make({
-          agentId,
-          message: `Exactly one current Agent Binding must be registered for ${agentId}`,
-        }),
-      );
-};
+  if (registered.length !== 1 || binding === undefined)
+    return yield* BindingUnavailable.make({
+      agentId: submission.agentId,
+      message: "Exactly one current Agent Binding must match the accepted Submission",
+    });
+
+  return binding;
+});
 
-/** Resolve authoring-time admission through the one exact host registration, never by identity alone. */
+/** Resolve authoring-time admission through exact host registration, never by identity alone. */
 export const resolveDefinitionBinding = (
   bindings: ReadonlyArray<ResolvedBinding>,
   definition: Pick<Agent.AnyDefinition, "id">,
 ): Effect.Effect<ResolvedBinding, BindingUnavailable> => {
-  const candidates = bindings.filter((binding) => binding.agentId === definition.id);
-  const binding = candidates[0];
+  const candidates = bindings.filter(
+    (binding) => binding.agentId === definition.id && Object.is(binding.definition, definition),
+  );
 
-  if (candidates.length !== 1 || binding === undefined) {
-    return Effect.fail(
-      BindingUnavailable.make({
-        agentId: definition.id,
-        message: "Registered admission requires exactly one binding for the Agent identity",
-      }),
-    );
-  }
-
-  if (!Object.is(binding.definition, definition)) {
-    return Effect.fail(
-      BindingUnavailable.make({
-        agentId: definition.id,
-        message: "Registered admission requires the exact Agent Definition used in registration",
-      }),
-    );
-  }
+  const binding = candidates[0];
 
-  return Effect.succeed(binding);
+  return candidates.length === 1 && binding !== undefined
+    ? Effect.succeed(binding)
+    : Effect.fail(
+        BindingUnavailable.make({
+          agentId: definition.id,
+          message:
+            "Registered admission requires exactly one registration of the exact Agent Definition",
+        }),
+      );
 };
 
 /** Application versions and a model Layer, supplied directly or through an existing Binding. */

package/src/engine/RunOptions.ts

@@ -152,10 +152,17 @@ export interface RunInputCommand {
  * Dependency-neutral input seam used by the interpreter.
  *
  * A capability adapter owns queue bounds and Scope finalization. The engine calls
- * `start` before the first drain, `drain` only at safe Turn seams, and `end`
+ * `start` before the first drain, `drain` only at safe Turn seams (including after
+ * cancellation of a disposable model call), and `end`
  * exactly once when the Run leaves its Scope.
  */
 export interface RunInputHook<Error = never, Requirements = never> {
+  /**
+   * Wait for an eligible join without appending it to history. Must register before checking
+   * authority and retain any claimed input for `drain`, even when this wait is interrupted.
+   * Used only with `restartOnJoinedInput`; each wait belongs to the model stream's Scope.
+   */
+  readonly awaitJoin?: Effect.Effect<void, Error, Requirements> | undefined;
   readonly start?: (() => Effect.Effect<void, Error, Requirements>) | undefined;
   readonly drain: (
     policy: CommandDrainPolicy,
@@ -577,6 +584,14 @@ export class AgentUpdateAcceptance extends Context.Service<
  * the ephemeral runtime always has.
  */
 export interface RunDurabilityHook<Error = never, Requirements = never> {
+  /** Persist replacement count and staged usage after cancellation, before starting its successor. */
+  readonly commitModelRestart?:
+    | ((restart: {
+        readonly turn: number;
+        readonly turnId: TurnId;
+        readonly restart: number;
+      }) => Effect.Effect<void, Error, Requirements>)
+    | undefined;
   /** Stage the exact request declarations for the existing canonical response append. */
   readonly noteToolExposure?:
     | ((turn: number, snapshot: Snapshot) => Effect.Effect<void, Error, Requirements>)
@@ -948,7 +963,7 @@ export interface RunOptions<HookError = never, HookRequirements = never> {
   /** Initial or canonically restored run-scoped native selection. */
   readonly toolSelection?: Selection | undefined;
   /**
-   * Host preparation boundary before each new model Turn, including its context preparation
+   * Host preparation boundary before each new or replacement model call, including context preparation
    * and compaction calls. The preceding Tool batch and history advance have finished. A resumed
    * canonical Tool batch bypasses this hook until it continues to a new Turn. This hook does not
    * reset the Run deadline or change prompt protection, and is not automatically inherited by spawned children.

package/src/engine/internal/agent-runtime.ts

@@ -78,6 +78,7 @@ import {
   BudgetWarning,
   CompactionPerformed,
   ModelStarted,
+  ModelRestarted,
   ReasoningDelta,
   RunCompleted,
   RunFailed,
@@ -555,6 +556,7 @@ interface RunContext {
   readonly durationDeadlineMillis: number;
   history: Prompt.Prompt;
   modelCalls: number;
+  modelRestarts: number;
   usageStatus: typeof UsageCompleteness.Type;
   pricingStatus: typeof UsageCompleteness.Type;
   unobservedModelCalls: number;
@@ -1430,7 +1432,15 @@ const decodeResumeUsage = Effect.fn("AgentRuntime.decodeResumeUsage")((input: un
         };
 
         const optional = Object.fromEntries(
-          (["usageStatus", "pricingStatus", "unobservedModelCalls", "children"] as const)
+          (
+            [
+              "usageStatus",
+              "pricingStatus",
+              "unobservedModelCalls",
+              "children",
+              "modelRestarts",
+            ] as const
+          )
             .map((key) => [key, read(key, true)])
             .filter(([, value]) => value !== undefined),
         );
@@ -1893,7 +1903,11 @@ const agentTelemetryAttributes = (context: RunContext) => ({
 });
 
 /** Label Effect AI's existing span, preserving provider usage, sampling and host async context. */
-const modelTelemetryTracer = Effect.fnUntraced(function* (context: RunContext, turnId?: TurnId) {
+const modelTelemetryTracer = Effect.fnUntraced(function* (
+  context: RunContext,
+  turnId?: TurnId,
+  onSpan?: (span: Tracer.Span) => void,
+) {
   const delegate = yield* Tracer.Tracer;
   const model = yield* Model.ModelName;
   const provider = yield* Model.ProviderName;
@@ -1904,6 +1918,8 @@ const modelTelemetryTracer = Effect.fnUntraced(function* (context: RunContext, t
 
       const span = delegate.span({ ...options, name: `chat ${model}` });
 
+      onSpan?.(span);
+
       const attributes = {
         ...agentTelemetryAttributes(context),
         "gen_ai.operation.name": "chat",
@@ -5343,6 +5359,7 @@ function decodeRunDisposition<DispositionSchema extends Schema.Top>(
 /** Internal control output consumed by the driver before RunEvent publication. */
 interface NextTurn {
   readonly _tag: "NextTurn";
+  readonly restarting?: boolean;
   readonly prompt: Prompt.Prompt;
   readonly turn: number;
   readonly toolCalls: number;
@@ -5388,6 +5405,7 @@ const makeTurn = <
   turn: number,
   priorToolCalls: number,
   options: RunOptions<HookError, HookRequirements>,
+  restarting = false,
 ): Stream.Stream<
   TurnOutput,
   AgentRuntimeFailure<typeof agent, HookError, InstructionError>,
@@ -5416,7 +5434,7 @@ const makeTurn = <
           }),
         );
       }
-      if (context.finalizationUsed) {
+      if (context.finalizationUsed && !restarting) {
         return failRunEventStream(
           AgentPolicyError.make({
             limit:
@@ -5591,6 +5609,9 @@ const makeTurn = <
         }
       }
 
+      let restartRequested = false;
+      let activeModelSpan: Tracer.Span | undefined;
+
       const trace: TurnTrace = {
         responsePartCount: 0,
         responsePartBytes: 0,
@@ -6206,6 +6227,10 @@ const makeTurn = <
           );
         });
 
+      let failedUsageCause:
+        | Cause.Cause<AgentRuntimeFailure<typeof agent, HookError, InstructionError>>
+        | undefined;
+
       // Failure accounting observes the already-selected failure; a secondary
       // budget/estimator failure must not replace that native outcome.
       const retainFailedUsage = Effect.fn("AgentRuntime.retainFailedUsage")(function* () {
@@ -6214,7 +6239,9 @@ const makeTurn = <
         if (trace.usage === undefined) {
           return yield* noteIncompleteUsage(context, turn);
         }
-        yield* consumeTurnUsage(0).pipe(Effect.exit);
+        const exit = yield* consumeTurnUsage(0).pipe(Effect.exit);
+
+        if (Exit.isFailure(exit)) failedUsageCause = exit.cause;
       });
 
       const attempt = (basis: Prompt.Prompt) =>
@@ -6337,7 +6364,9 @@ const makeTurn = <
                           : stream,
                       Stream.provideServiceEffect(
                         Tracer.Tracer,
-                        modelTelemetryTracer(context, turnId),
+                        modelTelemetryTracer(context, turnId, (span) => {
+                          activeModelSpan = span;
+                        }),
                       ),
                       Stream.onStart(
                         Effect.sync(() => {
@@ -6365,7 +6394,9 @@ const makeTurn = <
                         ),
                       ),
                       Stream.flatMap(Stream.fromIterable),
-                      Stream.tapCause(() => retainFailedUsage()),
+                      Stream.onExit((exit) =>
+                        Exit.isFailure(exit) ? retainFailedUsage() : Effect.void,
+                      ),
                     ),
                   ),
                 );
@@ -7059,10 +7090,83 @@ const makeTurn = <
         }),
       );
 
+      // Only the model stream is cancellable. It resolves no application Tools and
+      // closes its waiter before continuation can commit a response or start a Handler.
+      // Provider-defined Tools may execute remotely before reporting a part: fail closed
+      // for the whole call when any are exposed.
+      const restartSignal =
+        policy.restartOnJoinedInput === true &&
+        context.modelRestarts < 2 &&
+        (options.durability === undefined || options.durability.commitModelRestart !== undefined) &&
+        !Object.values(modelToolkit.tools).some(Tool.isProviderDefined)
+          ? options.input?.awaitJoin
+          : undefined;
+
+      const disposableResponse =
+        restartSignal !== undefined
+          ? response.pipe(
+              Stream.interruptWhen(
+                restartSignal.pipe(
+                  Effect.tap(() =>
+                    Effect.sync(() => {
+                      restartRequested = true;
+                      activeModelSpan?.attribute("effect_agent.model.outcome", "aborted");
+                      activeModelSpan?.attribute("effect_agent.model.abort_reason", "joined-input");
+                    }),
+                  ),
+                ),
+              ),
+            )
+          : response;
+
+      const afterResponse = Stream.unwrap(
+        Effect.gen(function* () {
+          if (!restartRequested)
+            return continuation.pipe(Stream.tapCause(() => retainFailedUsage()));
+
+          const discarded = ModelRestarted.make({
+            ...(yield* eventBase(context)),
+            turnId,
+            turn,
+            reason: "joined-input",
+          });
+
+          // Publish invalidation before any fallible persistence, input rendering or budget check.
+          return Stream.succeed(discarded).pipe(
+            Stream.concat(
+              Stream.unwrap(
+                Effect.gen(function* () {
+                  yield* retainFailedUsage();
+                  context.modelRestarts++;
+                  if (options.durability?.commitModelRestart !== undefined)
+                    yield* options.durability.commitModelRestart({
+                      turn,
+                      turnId,
+                      restart: context.modelRestarts,
+                    });
+                  if (failedUsageCause !== undefined)
+                    return yield* Effect.failCause(failedUsageCause);
+                  const inputs = yield* drainInputs(context, options);
+                  const nextPrompt = yield* appendInputs(context, prompt, inputs, options);
+
+                  return Stream.succeed<TurnOutput>({
+                    _tag: "NextTurn",
+                    prompt: nextPrompt,
+                    turn,
+                    toolCalls: priorToolCalls,
+                    restarting: true,
+                  });
+                }),
+              ),
+            ),
+          );
+        }),
+      );
+
       const events = Stream.fromIterable(preEvents).pipe(
         Stream.concat(started),
-        Stream.concat(response),
-        Stream.concat(continuation.pipe(Stream.tapCause(() => retainFailedUsage()))),
+        Stream.concat(disposableResponse),
+        Stream.concat(afterResponse),
       );
 
       return modelServices === undefined ? events : Stream.provideContext(events, modelServices);
@@ -8144,6 +8248,7 @@ function streamWithCompletion<
             // canonical response records so token budgets and the compaction
             // trigger keep accounting across ownership changes.
             modelCalls: resumeUsage?.modelCalls ?? 0,
+            modelRestarts: resumeUsage?.modelRestarts ?? 0,
             usageStatus:
               resumeUsage?.usageStatus ?? (resumeUsage === undefined ? "complete" : "unknown"),
             pricingStatus:
@@ -8379,6 +8484,7 @@ function streamWithCompletion<
                     readonly turn: number;
                     readonly toolCalls: number;
                     readonly resume?: RunTurnResume;
+                    readonly restarting?: boolean;
                   }
                 | undefined;
 
@@ -8425,6 +8531,7 @@ function streamWithCompletion<
                         request.turn,
                         request.toolCalls,
                         options,
+                        request.restarting,
                       )
                     : makeResumeTurn(
                         agent,