effect-agent 0.1.0-beta.156 → 0.1.0-beta.158

package/src/durable/DurableAgentRuntime.ts

@@ -167,6 +167,7 @@ import { makeMessagingRuntime } from "./internal/messaging-host.ts";
 import * as ThreadInitialization from "./internal/thread-initialization.ts";
 import { makeWorkerRuntime, WorkerInputControl } from "./internal/worker-host.ts";
 import { WorkerRuntime } from "./internal/worker-runtime.ts";
+import { MessageDeliveryStore } from "./MessageDelivery.ts";
 import {
   OperationAuthorizationRequest,
   OperationAuthorizer,
@@ -1266,6 +1267,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
   const ledger = yield* SubmissionLedger;
   const submissionScheduling = yield* SubmissionScheduling;
   const store = yield* ThreadStore;
+  const deliveries = yield* Effect.serviceOption(MessageDeliveryStore);
 
   // Disposable: canonical tail and owner identify the exact projection, never ownership.
   // Retain only the most recent view; persisted checkpoints still govern cold recovery.
@@ -3112,7 +3114,75 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
    */
   const notifyParentOfChildSettlement = Effect.fn(
     "DurableAgentRuntime.notifyParentOfChildSettlement",
-  )(function* (submission: SubmissionSnapshot): Effect.fn.Return<void, LedgerError> {
+  )(function* (
+    submission: SubmissionSnapshot,
+    record: RecordEnvelope,
+  ): Effect.fn.Return<void, LedgerError> {
+    const admission = submission.messageAdmission;
+    const worker = submission.workerAdmission;
+
+    const key =
+      admission === undefined
+        ? worker === undefined
+          ? undefined
+          : {
+              ownerThreadId: worker.origin.source.threadId,
+              messageId: worker.messageId,
+            }
+        : Schema.is(MessageAdmission)(admission)
+          ? admission.message
+          : {
+              ownerThreadId:
+                admission._tag === "WorkerCompletion"
+                  ? admission.report.worker.threadId
+                  : admission.worker.threadId,
+              messageId: submission.idempotencyKey,
+            };
+
+    // Commit the destination's exact canonical acknowledgement at the source before
+    // making the ledger terminal. A failed/lost response is replayed during recovery.
+    if (key !== undefined && Option.isSome(deliveries)) {
+      const settled = yield* settlementPayloadFromRecord(record, submission.submissionId);
+
+      yield* deliveries.value
+        .change(key, {
+          _tag: "Complete",
+          nowMillis: yield* Clock.currentTimeMillis,
+          admissionKey: submission.idempotencyKey,
+          inputDigest: submission.inputDigest,
+          receipt: Receipt.make({
+            threadId: submission.threadId,
+            submissionId: submission.submissionId,
+            receiptId: submission.receiptId,
+            queueSequence: submission.queueSequence,
+          }),
+          settlement: Settlement.make({
+            submissionId: settled.submissionId,
+            receiptId: settled.receiptId,
+            settlementId: settled.settlementId,
+            outcome: settled.outcome,
+            settledAt: record.createdAt,
+            ...(settled.outcome === "failed" ? { failure: settled.result } : {}),
+            ...(settled.usageSummary === undefined ? {} : { usageSummary: settled.usageSummary }),
+            ...(settled.runDisposition === undefined
+              ? {}
+              : { runDisposition: settled.runDisposition }),
+          }),
+        })
+        .pipe(
+          Effect.catchCause((cause) =>
+            Effect.failCause(
+              Cause.map(cause, (error) =>
+                LedgerError.make({
+                  operation: "delivery-completion",
+                  message: "Destination acknowledgement remains pending",
+                  cause: error,
+                }),
+              ),
+            ),
+          ),
+        );
+    }
     if (submission.workerAdmission?.origin.reporting?.mode === "standard")
       yield* updateRuntime.repair(submission.threadId).pipe(
         Effect.mapError(() =>
@@ -3227,14 +3297,14 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
       Effect.asVoid,
     );
     yield* hit("terminalize:after-canonical-append");
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, record);
 
     const settlement = yield* ledger.finalizeSettlement(
       SettlementFinalization.make({ submissionId, settlementId }),
     );
 
     yield* wake.notify(submission.threadId);
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, record);
 
     return settlement;
   });
@@ -3349,7 +3419,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
       Effect.asVoid,
     );
     yield* hit("terminalize:after-canonical-append");
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, reserved.record);
 
     const settlement = yield* ledger.finalizeSettlement(
       SettlementFinalization.make({ submissionId, settlementId }),
@@ -3358,7 +3428,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
     const canonicalSettlement = yield* settlementPayloadFromRecord(reserved.record, submissionId);
 
     yield* wake.notify(submission.threadId);
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, reserved.record);
     yield* settleJoinedSubmissions(ctx, canonicalSettlement);
 
     return materializeSettlement(settlement, reserved.record);
@@ -3385,7 +3455,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
       );
       yield* hit("terminalize:after-canonical-append");
     }
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, reservation.record);
 
     const settlement = yield* ledger.finalizeSettlement(
       SettlementFinalization.make({
@@ -3400,7 +3470,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
     );
 
     yield* wake.notify(submission.threadId);
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, reservation.record);
     yield* settleJoinedSubmissions(ctx, canonicalSettlement);
 
     return materializeSettlement(settlement, reservation.record);
@@ -3413,7 +3483,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
   ): Effect.fn.Return<Settlement, LedgerError | SettlementConflict> {
     const canonicalSettlement = yield* settlementPayloadFromRecord(record, submission.submissionId);
 
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, record);
 
     const settlement = yield* ledger.finalizeSettlement(
       SettlementFinalization.make({
@@ -3427,7 +3497,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
     );
 
     yield* wake.notify(submission.threadId);
-    yield* notifyParentOfChildSettlement(submission);
+    yield* notifyParentOfChildSettlement(submission, record);
 
     return materializeSettlement(settlement, snapshot.reservation?.record);
   });
@@ -4559,6 +4629,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
     ctx: AttemptAppendContext,
     submission: SubmissionSnapshot,
     tokenRef: Ref.Ref<OwnershipToken>,
+    renewAtRef: Ref.Ref<number>,
     records: ReadonlyArray<CanonicalRecordEnvelope>,
     canonical: Stream.Stream<CanonicalRecordEnvelope, ThreadStoreError | ThreadNotMaterialized>,
     canonicalThrough: CanonicalSequence,
@@ -5258,6 +5329,9 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
           );
 
           return RunUsageSummary.make({
+            ...(legacyCalls === 0 && detailed.webSearchCalls !== undefined
+              ? { webSearchCalls: detailed.webSearchCalls }
+              : {}),
             modelCalls,
             inputTokens: InputTokenUsage.make({
               total: inputTokens,
@@ -7798,18 +7872,33 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
       // Liveness only: the lease keeps the claim visible; correctness stays with the epoch fence.
       // OwnershipLost ends the race and interrupts the Run fiber cleanly.
       const renewal = halt(
-        Effect.repeat(
-          Effect.gen(function* () {
-            const ownershipToken = yield* Ref.get(tokenRef);
+        Effect.gen(function* () {
+          // Binding selection and preparation consume the acquired lease too. Carry the next
+          // deadline across model continuations; an overdue first renewal must run immediately.
+          const renewAt = yield* Ref.get(renewAtRef);
+          const now = yield* Clock.currentTimeMillis;
 
-            const renewal = yield* ledger.renewOwnership(
-              RenewOwnershipRequest.make({ submissionId, ownershipToken }),
-            );
+          yield* Effect.sleep(Math.max(0, renewAt - now));
+          yield* Effect.repeat(
+            Effect.gen(function* () {
+              const ownershipToken = yield* Ref.get(tokenRef);
+              const renewingAt = yield* Clock.currentTimeMillis;
 
-            yield* Ref.set(tokenRef, renewal.ownershipToken);
-          }).pipe(Effect.uninterruptible),
-          { schedule: Schedule.spaced(config.leaseRenewalInterval) },
-        ).pipe(Effect.andThen(Effect.never)),
+              const renewal = yield* ledger.renewOwnership(
+                RenewOwnershipRequest.make({ submissionId, ownershipToken }),
+              );
+
+              yield* Ref.set(tokenRef, renewal.ownershipToken);
+              yield* Ref.set(
+                renewAtRef,
+                renewingAt + Duration.toMillis(config.leaseRenewalInterval),
+              );
+            }).pipe(Effect.uninterruptible),
+            { schedule: Schedule.spaced(config.leaseRenewalInterval) },
+          );
+
+          return yield* Effect.never;
+        }),
       );
 
       const execution = Effect.raceFirst(consume, Effect.raceFirst(abortWatcher, renewal));
@@ -8031,6 +8120,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
     threadId: ThreadId,
     claim: Claim,
     tokenRef: Ref.Ref<OwnershipToken>,
+    renewAtRef: Ref.Ref<number>,
     resumeAfterRetention: () => void,
     onHandoff: (nextSubmissionId: SubmissionId) => void,
     yieldAfter?: DateTime.Utc,
@@ -8467,6 +8557,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
           ctx,
           submission,
           tokenRef,
+          renewAtRef,
           currentRecords,
           canonical,
           tail.tailSequence,
@@ -8647,6 +8738,8 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
     threadId: ThreadId,
     handoff?: ClaimHandoff,
   ) {
+    const acquiringAt = yield* Clock.currentTimeMillis;
+
     const claimed = yield* ledger.claim(
       ClaimRequest.make({
         threadId,
@@ -8659,6 +8752,10 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
     const claim = claimed.value;
     const tokenRef = yield* Ref.make(claim.ownershipToken);
 
+    const renewAtRef = yield* Ref.make(
+      acquiringAt + Duration.toMillis(config.leaseRenewalInterval),
+    );
+
     yield* Effect.addFinalizer(() =>
       Ref.get(tokenRef).pipe(
         Effect.flatMap((ownershipToken) =>
@@ -8681,7 +8778,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
         message: "The submission adapter did not honor the requested handoff",
       });
 
-    return Option.some({ claim, tokenRef });
+    return Option.some({ claim, tokenRef, renewAtRef });
   }, Effect.uninterruptible);
 
   const processThreadHead = (
@@ -8701,7 +8798,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
           const claimed = yield* acquireClaim(threadId, handoff);
 
           if (Option.isNone(claimed)) return Option.none();
-          const { claim, tokenRef } = claimed.value;
+          const { claim, tokenRef, renewAtRef } = claimed.value;
 
           const attributes = {
             threadId,
@@ -8781,6 +8878,7 @@ const make = Effect.fn("DurableAgentRuntime.make")(function* (
                 attemptThreadId,
                 attemptClaim,
                 tokenRef,
+                renewAtRef,
                 () => {
                   resumeAfterRetention = true;
                 },

package/src/durable/LifecyclePublication.ts

@@ -146,10 +146,13 @@ export type LifecyclePublicationBatch = typeof LifecyclePublicationBatch.Type;
 
 /** Native recovery state, independent of Attempts. Hosts serialize drains per storage owner. */
 export interface LifecyclePublicationStorage {
-  /** Select up to `limit` due owners, with a bounded pending prefix for each selected owner. */
+  /** Select up to `limit` due owners, with a bounded pending prefix for each selected owner.
+   * `retainedOnly` excludes unmaterialized source facts, for a precommitted start prefix.
+   */
   readonly pending: (
     nowMillis: number,
     limit: number,
+    options?: { readonly retainedOnly?: boolean },
   ) => Effect.Effect<ReadonlyArray<LifecyclePublicationBatch>, LifecyclePublicationError>;
   /** Atomically acknowledge the exact batch, retaining its identities and fingerprints. */
   readonly acknowledge: (
@@ -166,6 +169,15 @@ export interface LifecyclePublicationStorage {
     timeoutMillis: number,
   ) => Effect.Effect<boolean, LifecyclePublicationError>;
   readonly pendingDeadline: Effect.Effect<Option.Option<number>, LifecyclePublicationError>;
+  /**
+   * Deadline for `pending(..., { retainedOnly: true })`, excluding unmaterialized source facts.
+   * Source-backed stores provide this when `pendingDeadline` also includes source intent.
+   * Otherwise `pendingDeadline` already describes retained work.
+   */
+  readonly retainedPendingDeadline?: Effect.Effect<
+    Option.Option<number>,
+    LifecyclePublicationError
+  >;
   /** Explicit operator retry after repairing a parked owner's destination. */
   readonly retryParked: (
     ownerThreadId: ThreadId,
@@ -259,9 +271,10 @@ export const drainLifecyclePublications = Effect.fn("LifecyclePublication.drain"
   storage: LifecyclePublicationStorage,
   timeoutMillis = 10_000,
   limit = 4,
+  options?: { readonly retainedOnly?: boolean },
 ) {
   const handler = yield* LifecyclePublicationHandler;
-  const pending = yield* storage.pending(yield* Clock.currentTimeMillis, limit);
+  const pending = yield* storage.pending(yield* Clock.currentTimeMillis, limit, options);
 
   let failures: Cause.Cause<LifecyclePublicationError> = Cause.empty;
 

package/src/durable/MessageDelivery.ts

@@ -14,6 +14,8 @@ import { PreparedInput } from "./Subscription.ts";
 
 const Positive = Schema.Int.check(Schema.isGreaterThan(0));
 const BoundedName = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+const receiptsEqual = Schema.toEquivalence(Receipt);
+const settlementsEqual = Schema.toEquivalence(Settlement);
 
 /** An owner is always a source Thread. Destination admission has its own frozen key. */
 export const MessageDeliveryKey = Schema.Struct({
@@ -66,7 +68,12 @@ export const defaultMessageDeliveryStoreLimits: MessageDeliveryStoreLimits = {
   maxRetainedUpdatesPerOwner: 256,
 };
 
-const ParkReason = Schema.Literals(["exhausted", "deadline", "status-unavailable"]);
+const ParkReason = Schema.Literals([
+  "exhausted",
+  "deadline",
+  "status-unavailable",
+  "awaiting-settlement",
+]);
 
 export const MessageDeliveryRecord = Schema.Struct({
   schemaVersion: Schema.Literal(1),
@@ -152,7 +159,20 @@ export const MessageDeliveryFailpoint = Context.Reference<{
 
 const fence = { expectedVersion: Positive, nowMillis: ScheduleInstant };
 
+/** Terminal destination evidence, independent of an expiring source transport claim. */
+export const MessageDeliveryCompletion = Schema.Struct({
+  receipt: Receipt,
+  settlement: Settlement,
+  admissionKey: IdempotencyKey,
+  inputDigest: Digest,
+});
+
 export const MessageDeliveryChange = Schema.Union([
+  Schema.Struct({
+    _tag: Schema.Literal("Complete"),
+    nowMillis: ScheduleInstant,
+    ...MessageDeliveryCompletion.fields,
+  }),
   Schema.Struct({ _tag: Schema.Literal("Claim"), ...fence }),
   Schema.Struct({ _tag: Schema.Literal("Accept"), ...fence, receipt: Receipt }),
   Schema.Struct({ _tag: Schema.Literal("Process"), ...fence, settlement: Settlement }),
@@ -424,6 +444,34 @@ export const applyMessageDeliveryChange = (
 ): Result.Result<MessageDeliveryRecord, MessageDeliveryError> => {
   const conflict = () => Result.fail(error("conflict", change._tag));
 
+  if (change._tag === "Complete") {
+    if (
+      change.admissionKey !== record.envelope.admissionKey ||
+      change.inputDigest !== record.envelope.inputDigest ||
+      change.receipt.threadId !== record.envelope.threadId ||
+      change.settlement.submissionId !== change.receipt.submissionId ||
+      change.settlement.receiptId !== change.receipt.receiptId ||
+      (record.receipt !== null && !receiptsEqual(record.receipt, change.receipt))
+    )
+      return Result.fail(error("corrupt", "completion-identity"));
+    if (record.status === "refused") return conflict();
+    if (record.status === "processed")
+      return record.settlement !== null && settlementsEqual(record.settlement, change.settlement)
+        ? Result.succeed(record)
+        : Result.fail(error("corrupt", "completion-identity"));
+
+    return Result.succeed({
+      ...record,
+      version: record.version + 1,
+      status: "processed",
+      receipt: change.receipt,
+      settlement: change.settlement,
+      leaseUntilMillis: null,
+      parkReason: null,
+      retry: { ...record.retry, parked: false },
+    });
+  }
+
   if (record.version !== change.expectedVersion) return conflict();
   if (record.status === "processed" || record.status === "refused") return conflict();
   const now = change.nowMillis;
@@ -540,21 +588,8 @@ export const applyMessageDeliveryChange = (
   }
   if (change._tag === "ObservePending") {
     if (record.status !== "accepted") return conflict();
-    if (now >= record.deadlineAtMillis) return Result.succeed(parked("deadline"));
 
-    return Result.succeed({
-      ...base,
-      leaseUntilMillis: null,
-      retry: {
-        ...record.retry,
-        automaticAttempts: 0,
-        lastFailure: null,
-        nextAttemptAtMillis: Math.min(
-          now + record.policy.settlementPollMillis,
-          record.deadlineAtMillis,
-        ),
-      },
-    });
+    return Result.succeed(parked("awaiting-settlement"));
   }
   if (change._tag === "Refuse") {
     if (record.status !== "pending") return conflict();
@@ -700,9 +735,10 @@ export class MessageDeliveryDriver extends Context.Service<
                 // Digest computation cannot extend this claim's admission authority.
                 if (timeout <= 0) return claimed;
 
-                type WithoutFence<T> = T extends MessageDeliveryChange
-                  ? Omit<T, "expectedVersion" | "nowMillis">
-                  : never;
+                type WithoutFence<T> =
+                  T extends Exclude<MessageDeliveryChange, { _tag: "Complete" }>
+                    ? Omit<T, "expectedVersion" | "nowMillis">
+                    : never;
 
                 const commit = (change: WithoutFence<MessageDeliveryChange>) =>
                   Clock.currentTimeMillis.pipe(
@@ -722,8 +758,16 @@ export class MessageDeliveryDriver extends Context.Service<
                   ).pipe(Effect.mapError((cause) => error("corrupt", "admission", cause)));
 
                   yield* failpoint.hit("message-delivery:admission:after");
-                  if (outcome._tag === "Receipt")
-                    return yield* commit({ _tag: "Accept", receipt: outcome.receipt });
+                  if (outcome._tag === "Receipt") {
+                    const accepted = yield* commit({ _tag: "Accept", receipt: outcome.receipt });
+
+                    return yield* store.change(key, {
+                      _tag: "Park",
+                      reason: "awaiting-settlement",
+                      expectedVersion: accepted.version,
+                      nowMillis: yield* Clock.currentTimeMillis,
+                    });
+                  }
                   if (outcome._tag === "Refused")
                     return yield* commit({
                       _tag: "Refuse",

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

@@ -111,6 +111,17 @@ export const toolReplayContracts = Effect.fn("AgentRegistration.toolReplayContra
           name: tool.name,
           contract: {
             version,
+            ...(Tool.isProviderDefined(tool)
+              ? {
+                  provider: {
+                    id: tool.id,
+                    providerName: tool.providerName,
+                    args: Schema.decodeUnknownSync(Schema.Json)(tool.args ?? null),
+                    requiresHandler: tool.requiresHandler,
+                  },
+                  readonly: Context.get(tool.annotations, Tool.Readonly),
+                }
+              : {}),
             parameters: jsonSchema(tool.parametersSchema),
             success: jsonSchema(tool.successSchema),
             failure: jsonSchema(tool.failureSchema),

package/src/engine/RunOptions.ts

@@ -348,6 +348,8 @@ export type RunCostEstimateValue = number | RunCostEstimate;
 
 /** Model identity presented beside the legacy raw-usage estimator argument. */
 export interface RunCostEstimateRequest {
+  /** Observed hosted web search calls, separately billed from tokens. */
+  readonly webSearchCalls?: number | undefined;
   readonly provider: string;
   /** Configured binding identity; only response.model identifies the returned model. */
   readonly model: string;
@@ -816,6 +818,7 @@ export type RunTurnResumeSettledCall = typeof RunTurnResumeSettledCallSchema.Typ
 export const RunResumeUsageSchema = Schema.Struct({
   ...RunPolicyUsage.fields,
   modelCalls: Schema.Natural,
+  webSearchCalls: Schema.optionalKey(Schema.Natural),
   inputTokens: Schema.Natural,
   outputTokens: Schema.Natural,
   lastInputTokens: Schema.Natural,