effect-agent 0.1.0-beta.103 → 0.1.0-beta.106

package/src/durable/MessageDelivery.ts

@@ -1,5 +1,6 @@
 import { Clock, Context, Crypto, Effect, Layer, Result, Schema, Semaphore } from "effect";
 
+import * as FailureDiagnostic from "../core/FailureDiagnostic.ts";
 import { ThreadId } from "../core/Identifiers.ts";
 import { Receipt } from "../core/Receipt.ts";
 import { WorkerUpdate } from "../core/Worker.ts";
@@ -86,6 +87,8 @@ export const MessageDeliveryRecord = Schema.Struct({
   parkReason: Schema.NullOr(ParkReason),
   leaseUntilMillis: Schema.NullOr(ScheduleInstant),
   retry: ScheduleRetry,
+  /** Last failed admission/status check, retained across retries and successful recovery. */
+  lastFailureDiagnostic: Schema.optionalKey(FailureDiagnostic.Diagnostic),
 }).check(
   Schema.makeFilter(
     (record) =>
@@ -117,6 +120,8 @@ export type MessageDeliveryRecord = typeof MessageDeliveryRecord.Type;
 export class MessageDeliveryError extends Schema.TaggedError<MessageDeliveryError>()(
   "MessageDeliveryError",
   {
+    cause: Schema.optionalKey(FailureDiagnostic.Value),
+    stack: Schema.optionalKey(Schema.String),
     reason: Schema.Literals([
       "validation",
       "conflict",
@@ -151,9 +156,24 @@ export const MessageDeliveryChange = Schema.Union([
   Schema.Struct({ _tag: Schema.Literal("Accept"), ...fence, receipt: Receipt }),
   Schema.Struct({ _tag: Schema.Literal("Process"), ...fence, settlement: Settlement }),
   Schema.Struct({ _tag: Schema.Literal("ObservePending"), ...fence }),
-  Schema.Struct({ _tag: Schema.Literal("Refuse"), ...fence, code: BoundedName }),
-  Schema.Struct({ _tag: Schema.Literal("Retry"), ...fence, reason: ScheduleRetryReason }),
-  Schema.Struct({ _tag: Schema.Literal("Park"), ...fence, reason: ParkReason }),
+  Schema.Struct({
+    _tag: Schema.Literal("Refuse"),
+    ...fence,
+    code: BoundedName,
+    diagnostic: Schema.optionalKey(FailureDiagnostic.Diagnostic),
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal("Retry"),
+    ...fence,
+    reason: ScheduleRetryReason,
+    diagnostic: Schema.optionalKey(FailureDiagnostic.Diagnostic),
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal("Park"),
+    ...fence,
+    reason: ParkReason,
+    diagnostic: Schema.optionalKey(FailureDiagnostic.Diagnostic),
+  }),
   Schema.Struct({ _tag: Schema.Literal("Recover"), ...fence, deadlineAtMillis: ScheduleInstant }),
   /** Waiting for earlier admission never spends an automatic transport attempt. */
   Schema.Struct({ _tag: Schema.Literal("Defer"), ...fence, untilMillis: ScheduleInstant }),
@@ -292,8 +312,8 @@ export const sameMessageDeliveryIdentity = (
   left.createdAtMillis === right.createdAtMillis &&
   left.initialDeadlineAtMillis === right.initialDeadlineAtMillis;
 
-const error = (reason: MessageDeliveryError["reason"], operation: string) =>
-  MessageDeliveryError.make({ reason, operation });
+const error = (reason: MessageDeliveryError["reason"], operation: string, cause?: unknown) =>
+  MessageDeliveryError.make({ reason, operation, ...(cause === undefined ? {} : { cause }) });
 
 export const validateMessageDelivery = <A, I>(
   schema: Schema.Codec<A, I>,
@@ -328,23 +348,23 @@ export const prepareMessageDelivery = Effect.fn("MessageDelivery.prepare")(funct
     policy: options.policy ?? defaultMessageDeliveryPolicy,
   }).pipe(
     Effect.flatMap(Schema.decodeEffect(Schema.fromJsonString(MessageDeliveryPreparation))),
-    Effect.mapError(() => error("validation", "prepare")),
+    Effect.mapError((cause) => error("validation", "prepare", cause)),
   );
 
   const envelope = snapshot.envelope;
 
   const encoded = yield* Schema.encodeEffect(PreparedInput)(envelope).pipe(
-    Effect.mapError(() => error("validation", "prepare")),
+    Effect.mapError((cause) => error("validation", "prepare", cause)),
   );
 
   const inputDigest = yield* digestJson(encoded.input).pipe(
-    Effect.mapError(() => error("storage", "digest")),
+    Effect.mapError((cause) => error("storage", "digest", cause)),
   );
 
   if (inputDigest !== envelope.inputDigest) return yield* error("corrupt", "input-digest");
 
   const envelopeDigest = yield* digestJson(encoded).pipe(
-    Effect.mapError(() => error("storage", "digest")),
+    Effect.mapError((cause) => error("storage", "digest", cause)),
   );
 
   return yield* validateMessageDelivery(
@@ -390,7 +410,14 @@ export const applyMessageDeliveryChange = (
   if (record.version !== change.expectedVersion) return conflict();
   if (record.status === "processed" || record.status === "refused") return conflict();
   const now = change.nowMillis;
-  const base = { ...record, version: record.version + 1 };
+
+  const base = {
+    ...record,
+    version: record.version + 1,
+    ...("diagnostic" in change && change.diagnostic !== undefined
+      ? { lastFailureDiagnostic: change.diagnostic }
+      : {}),
+  };
 
   const parked = (reason: typeof ParkReason.Type): MessageDeliveryRecord => ({
     ...base,
@@ -636,12 +663,12 @@ export class MessageDeliveryDriver extends Context.Service<
                 if (claimed.status === "parked") return claimed;
 
                 const envelope = yield* Schema.encodeEffect(PreparedInput)(claimed.envelope).pipe(
-                  Effect.mapError(() => error("corrupt", "envelope")),
+                  Effect.mapError((cause) => error("corrupt", "envelope", cause)),
                 );
 
                 const digest = yield* digestJson(envelope).pipe(
                   Effect.provideService(Crypto.Crypto, crypto),
-                  Effect.mapError(() => error("storage", "digest")),
+                  Effect.mapError((cause) => error("storage", "digest", cause)),
                 );
 
                 if (digest !== claimed.envelopeDigest)
@@ -675,15 +702,23 @@ export class MessageDeliveryDriver extends Context.Service<
                   const outcome = yield* admitPreparedInput(
                     admission.submit(claimed.envelope),
                     timeout,
-                  ).pipe(Effect.mapError(() => error("corrupt", "admission")));
+                  ).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 === "Refused")
-                    return yield* commit({ _tag: "Refuse", code: outcome.error.code });
+                    return yield* commit({
+                      _tag: "Refuse",
+                      code: outcome.error.code,
+                      diagnostic: FailureDiagnostic.capture(outcome.error),
+                    });
 
-                  return yield* commit({ _tag: "Retry", reason: outcome.reason });
+                  return yield* commit({
+                    _tag: "Retry",
+                    reason: outcome.reason,
+                    diagnostic: outcome.diagnostic,
+                  });
                 }
                 if (claimed.receipt === null) return yield* error("corrupt", "receipt");
                 if (admission.submissionStatus === undefined)
@@ -693,28 +728,51 @@ export class MessageDeliveryDriver extends Context.Service<
                   Effect.timeout(timeout),
                   Effect.map((status) => ({ _tag: "Status" as const, status })),
                   Effect.catchTag("ScheduledInputRetryable", (failure) =>
-                    Effect.succeed({ _tag: "Retry" as const, reason: failure.reason }),
+                    Effect.succeed({
+                      _tag: "Retry" as const,
+                      reason: failure.reason,
+                      diagnostic: FailureDiagnostic.capture(failure),
+                    }),
                   ),
-                  Effect.catchTag("ScheduledInputRefused", () =>
-                    Effect.succeed({ _tag: "Unavailable" as const }),
+                  Effect.catchTag("ScheduledInputRefused", (failure) =>
+                    Effect.succeed({
+                      _tag: "Unavailable" as const,
+                      diagnostic: FailureDiagnostic.capture(failure),
+                    }),
                   ),
-                  Effect.catchTag("TimeoutError", () =>
-                    Effect.succeed({ _tag: "Retry" as const, reason: "timeout" as const }),
+                  Effect.catchTag("TimeoutError", (failure) =>
+                    Effect.succeed({
+                      _tag: "Retry" as const,
+                      reason: "timeout" as const,
+                      diagnostic: FailureDiagnostic.capture(failure),
+                    }),
                   ),
                   Effect.catchTag("ScheduleStorageError", (failure) =>
                     failure.reason === "unavailable"
-                      ? Effect.succeed({ _tag: "Retry" as const, reason: "storage" as const })
-                      : Effect.fail(error("corrupt", "status")),
+                      ? Effect.succeed({
+                          _tag: "Retry" as const,
+                          reason: "storage" as const,
+                          diagnostic: FailureDiagnostic.capture(failure),
+                        })
+                      : Effect.fail(error("corrupt", "status", failure)),
                   ),
                 );
 
                 if (status._tag === "Unavailable")
-                  return yield* commit({ _tag: "Park", reason: "status-unavailable" });
+                  return yield* commit({
+                    _tag: "Park",
+                    reason: "status-unavailable",
+                    diagnostic: status.diagnostic,
+                  });
                 if (status._tag === "Status" && status.status._tag === "settled")
                   return yield* commit({ _tag: "Process", settlement: status.status.settlement });
                 if (status._tag === "Status") return yield* commit({ _tag: "ObservePending" });
 
-                return yield* commit({ _tag: "Retry", reason: status.reason });
+                return yield* commit({
+                  _tag: "Retry",
+                  reason: status.reason,
+                  diagnostic: status.diagnostic,
+                });
               }),
             )
             .pipe(

package/src/durable/PreparedInputAdmission.ts

@@ -1,5 +1,6 @@
 import { Context, Effect } from "effect";
 
+import * as FailureDiagnostic from "../core/FailureDiagnostic.ts";
 import type { Receipt } from "./DurableAgentRuntime.ts";
 import { type ScheduledInputFailure, ScheduleStorageError } from "./Schedule.ts";
 import type { SubmissionStatus } from "./SubmissionStatus.ts";
@@ -30,14 +31,26 @@ export const admitPreparedInput = Effect.fn("Thread.admitPreparedInput")(
         Effect.succeed({ _tag: "Refused" as const, error }),
       ),
       Effect.catchTag("ScheduledInputRetryable", (error) =>
-        Effect.succeed({ _tag: "Retry" as const, reason: error.reason }),
+        Effect.succeed({
+          _tag: "Retry" as const,
+          reason: error.reason,
+          diagnostic: FailureDiagnostic.capture(error),
+        }),
       ),
-      Effect.catchTag("TimeoutError", () =>
-        Effect.succeed({ _tag: "Retry" as const, reason: "timeout" as const }),
+      Effect.catchTag("TimeoutError", (error) =>
+        Effect.succeed({
+          _tag: "Retry" as const,
+          reason: "timeout" as const,
+          diagnostic: FailureDiagnostic.capture(error),
+        }),
       ),
       Effect.catchTag("ScheduleStorageError", (error) =>
         error.reason === "unavailable"
-          ? Effect.succeed({ _tag: "Retry" as const, reason: "storage" as const })
+          ? Effect.succeed({
+              _tag: "Retry" as const,
+              reason: "storage" as const,
+              diagnostic: FailureDiagnostic.capture(error),
+            })
           : Effect.fail(ScheduleStorageError.make(error)),
       ),
     ),

package/src/durable/Records.ts

@@ -5,6 +5,7 @@ import { InputMessage } from "../capabilities/Messaging.ts";
 import { PolicyLimit } from "../core/AgentError.ts";
 import { AgentPolicy } from "../core/AgentPolicy.ts";
 import { Update } from "../core/AgentUpdates.ts";
+import * as FailureDiagnostic from "../core/FailureDiagnostic.ts";
 import {
   AgentId,
   AttemptId,
@@ -17,7 +18,6 @@ import {
   ToolCallId,
   TurnId,
 } from "../core/Identifiers.ts";
-import { strictSchema } from "../core/internal/strict-schema.ts";
 import { utf8ByteLength } from "../core/internal/utf8.ts";
 import { IdempotencyKey, Principal } from "../core/Receipt.ts";
 import { ExhaustedLimit } from "../core/RunEvent.ts";
@@ -82,22 +82,12 @@ export type ProducerEpoch = typeof ProducerEpoch.Type;
 const BoundedText = Schema.String.check(Schema.isMaxLength(64 * 1024));
 const BoundedName = Schema.NonEmptyString.check(Schema.isMaxLength(256));
 
-/** Stable, non-empty failure classification carried by a failed durable Settlement. */
-const SettlementFailureTag = Schema.NonEmptyString.check(Schema.isMaxLength(256));
-
-/** Diagnostic text is bounded independently from the broader persisted JSON envelope. */
-const SettlementFailureMessage = Schema.String.check(Schema.isMaxLength(16 * 1024));
-
 /**
- * The complete generic diagnostic allowed on a failed durable Settlement. It deliberately has
- * no raw Cause, stack, provider payload, or application-specific fields; those values can carry
- * secrets and do not form a stable cross-process contract.
+ * Private failed-Settlement evidence. The summary remains the safe public projection; diagnostic
+ * and context preserve structured causal evidence for authorized operators, never model context.
+ * Optional fields allow reading supported Settlements written before causal capture was available.
  */
-export const SettlementFailureDiagnostic = Schema.Struct({
-  errorTag: SettlementFailureTag,
-  message: SettlementFailureMessage,
-}).pipe(
-  strictSchema,
+export const SettlementFailureDiagnostic = FailureDiagnostic.Failure.pipe(
   Schema.annotate({
     identifier: "@effect-agent/thread/SettlementFailureDiagnostic",
   }),

package/src/durable/Schedule.ts

@@ -1,5 +1,6 @@
 import { Context, Effect, Schema } from "effect";
 
+import * as FailureDiagnostic from "../core/FailureDiagnostic.ts";
 import { AgentId, ThreadId } from "../core/Identifiers.ts";
 import { Receipt } from "../core/Receipt.ts";
 import { DefinitionDigests, Digest, PersistedJson } from "./Records.ts";
@@ -269,13 +270,21 @@ export class ScheduleStorageError extends Schema.TaggedError<ScheduleStorageErro
 /** Only when the unchanged envelope was not admitted and cannot succeed, including on replay. */
 export class ScheduledInputRefused extends Schema.TaggedError<ScheduledInputRefused>()(
   "ScheduledInputRefused",
-  { code: Name },
+  {
+    code: Name,
+    cause: Schema.optionalKey(FailureDiagnostic.Value),
+    stack: Schema.optionalKey(Schema.String),
+  },
 ) {}
 
 /** Includes lost replies: admission may already have committed. */
 export class ScheduledInputRetryable extends Schema.TaggedError<ScheduledInputRetryable>()(
   "ScheduledInputRetryable",
-  { reason: ScheduleRetryReason },
+  {
+    reason: ScheduleRetryReason,
+    cause: Schema.optionalKey(FailureDiagnostic.Value),
+    stack: Schema.optionalKey(Schema.String),
+  },
 ) {}
 
 export type ScheduledInputFailure =

package/src/durable/SqlMessageDeliveryStore.ts

@@ -59,11 +59,23 @@ const Scan = Schema.Struct({
 
 const codec = Schema.fromJsonString(MessageDeliveryRecord);
 const bytes = (text: string): number => new TextEncoder().encode(text).byteLength;
-const storage = (operation: string) => MessageDeliveryError.make({ reason: "storage", operation });
-const corrupt = (operation: string) => MessageDeliveryError.make({ reason: "corrupt", operation });
+
+const storage = (operation: string, cause?: unknown) =>
+  MessageDeliveryError.make({
+    reason: "storage",
+    operation,
+    ...(cause === undefined ? {} : { cause }),
+  });
+
+const corrupt = (operation: string, cause?: unknown) =>
+  MessageDeliveryError.make({
+    reason: "corrupt",
+    operation,
+    ...(cause === undefined ? {} : { cause }),
+  });
 
 const query = <A>(operation: string, effect: Effect.Effect<A, SqlError>) =>
-  effect.pipe(Effect.mapError(() => storage(operation)));
+  effect.pipe(Effect.mapError((cause) => storage(operation, cause)));
 
 /**
  * Shared SQL implementation over the adapter-owned effect_agent_message_deliveries table.
@@ -92,7 +104,7 @@ export const makeSqlMessageDeliveryStore = Effect.fn("SqlMessageDeliveryStore.ma
     record: MessageDeliveryRecord,
   ) {
     const text = yield* Schema.encodeEffect(codec)(record).pipe(
-      Effect.mapError(() => corrupt("encode")),
+      Effect.mapError((cause) => corrupt("encode", cause)),
     );
 
     if (bytes(text) > maxStoredValueBytes)
@@ -108,7 +120,7 @@ export const makeSqlMessageDeliveryStore = Effect.fn("SqlMessageDeliveryStore.ma
     if (bytes(row.record_json) > maxStoredValueBytes) return yield* corrupt("stored-value-bytes");
 
     const record = yield* Schema.decodeEffect(codec)(row.record_json).pipe(
-      Effect.mapError(() => corrupt("decode")),
+      Effect.mapError((cause) => corrupt("decode", cause)),
     );
 
     if (
@@ -126,7 +138,7 @@ export const makeSqlMessageDeliveryStore = Effect.fn("SqlMessageDeliveryStore.ma
 
   const decodeRows = (rows: unknown) =>
     Schema.decodeUnknownEffect(Schema.Array(Row))(rows).pipe(
-      Effect.mapError(() => corrupt("rows")),
+      Effect.mapError((cause) => corrupt("rows", cause)),
       Effect.flatMap((rows) => Effect.forEach(rows, decode)),
     );
 
@@ -149,7 +161,7 @@ export const makeSqlMessageDeliveryStore = Effect.fn("SqlMessageDeliveryStore.ma
     const text = yield* encode(record);
 
     const input = yield* Schema.decodeEffect(codec)(text).pipe(
-      Effect.mapError(() => corrupt("insert")),
+      Effect.mapError((cause) => corrupt("insert", cause)),
     );
 
     if (
@@ -190,7 +202,7 @@ export const makeSqlMessageDeliveryStore = Effect.fn("SqlMessageDeliveryStore.ma
         );
 
         const count = (yield* Schema.decodeUnknownEffect(Schema.Array(Count))(counts).pipe(
-          Effect.mapError(() => corrupt("count")),
+          Effect.mapError((cause) => corrupt("count", cause)),
         ))[0];
 
         if (count === undefined) return yield* corrupt("count");
@@ -293,7 +305,7 @@ export const makeSqlMessageDeliveryStore = Effect.fn("SqlMessageDeliveryStore.ma
       );
 
       const decoded = yield* Schema.decodeUnknownEffect(Schema.Array(Deadline))(rows).pipe(
-        Effect.mapError(() => corrupt("next-deadline")),
+        Effect.mapError((cause) => corrupt("next-deadline", cause)),
       );
 
       return decoded[0]?.deadline ?? null;

package/src/durable/SubmissionLedger.ts

@@ -2,6 +2,7 @@ import type { Option, Stream } from "effect";
 import { Context, Duration, Effect, Schema } from "effect";
 
 import { InputMessage } from "../capabilities/Messaging.ts";
+import * as FailureDiagnostic from "../core/FailureDiagnostic.ts";
 import {
   AgentId,
   AttemptId,
@@ -133,6 +134,8 @@ export class AdmissionPolicyError extends Schema.TaggedError<AdmissionPolicyErro
   {
     reason: Schema.Literals(["refused", "unavailable", "occupied"]),
     code: Schema.NonEmptyString.check(Schema.isMaxLength(128)),
+    cause: Schema.optionalKey(FailureDiagnostic.Value),
+    stack: Schema.optionalKey(Schema.String),
   },
 ) {}
 
@@ -916,7 +919,7 @@ export class ChildReservationConflict extends Schema.TaggedError<ChildReservatio
 export class LedgerError extends Schema.TaggedError<LedgerError>()("LedgerError", {
   operation: Schema.String,
   message: Schema.String,
-  cause: Schema.optionalKey(Schema.Defect()),
+  cause: Schema.optionalKey(FailureDiagnostic.Value),
 }) {}
 
 export type SubmissionLedgerFailure =

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

@@ -1,4 +1,14 @@
-import { type Crypto, type Option, type Scope, Context, Effect, Layer, Schema } from "effect";
+import {
+  type Crypto,
+  type Option,
+  type Scope,
+  Context,
+  Effect,
+  Layer,
+  References,
+  Schema,
+  Tracer,
+} from "effect";
 import { Tool } from "effect/unstable/ai";
 
 import type * as Agent from "../../core/Agent.ts";
@@ -229,20 +239,40 @@ type ReportRequirements<Reports> =
         : never
     : never;
 
+// Registrations outlive their construction span. Dependencies remain captured,
+// while every attempt/report inherits the invoking fiber's tracing state.
+const omitTraceContext = Context.omit(
+  Tracer.ParentSpan,
+  Tracer.Tracer,
+  Tracer.MinimumTraceLevel,
+  Tracer.CurrentTraceLevel,
+  References.TracerEnabled,
+  References.TracerTimingEnabled,
+  References.TracerSpanAnnotations,
+  References.TracerSpanLinks,
+);
+
+// R describes captured application services; ParentSpan is supplied by the
+// live invocation rather than stored as a registration dependency.
+const withoutTraceContext = <R>(context: Context.Context<R>): Context.Context<R> =>
+  omitTraceContext(context) as Context.Context<R>;
+
 const captureReporting = <R>(reports: ReadonlyArray<WorkerReporting<unknown, R>>) =>
-  Effect.map(Effect.context<Exclude<R, Scope.Scope>>(), (context) =>
-    reports.map((report): WorkerReporting<WorkerReportPreparationFailure> => ({
-      ...report,
-      prepare: (value) =>
-        Effect.scoped(Effect.suspend(() => report.prepare(value))).pipe(
-          Effect.provide(context),
-          Effect.mapError((error) =>
-            Schema.is(WorkerReportPreparationFailure)(error)
-              ? error
-              : WorkerReportPreparationFailure.make({ stage: "preparation" }),
+  Effect.map(
+    Effect.context<Exclude<R, Scope.Scope>>().pipe(Effect.map(withoutTraceContext)),
+    (context) =>
+      reports.map((report): WorkerReporting<WorkerReportPreparationFailure> => ({
+        ...report,
+        prepare: (value) =>
+          Effect.scoped(Effect.suspend(() => report.prepare(value))).pipe(
+            Effect.provide(context),
+            Effect.mapError((error) =>
+              Schema.is(WorkerReportPreparationFailure)(error)
+                ? error
+                : WorkerReportPreparationFailure.make({ stage: "preparation" }),
+            ),
           ),
-        ),
-    })),
+      })),
   );
 
 const backgroundReports = (definition: Agent.AnyDefinition) => [
@@ -276,7 +306,9 @@ const capture = <A extends ExecutableAgentBinding, Provides = never, Requires =
   Exclude<DurableWorkerRequirements<A>, Provides> | Requires
 > =>
   Effect.map(
-    Effect.context<Exclude<DurableWorkerRequirements<A>, Provides> | Requires>(),
+    Effect.context<Exclude<DurableWorkerRequirements<A>, Provides> | Requires>().pipe(
+      Effect.map(withoutTraceContext),
+    ),
     (context): CapturedBinding => ({
       agentId: agent.definition.id,
       definition: agent.definition,