effect-agent 0.1.0-beta.15 → 0.1.0-beta.151

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

@@ -0,0 +1,306 @@
+import { Clock, Crypto, DateTime, Effect, Option, Schema } from "effect";
+
+import { Update, UpdateError } from "../../core/AgentUpdates.ts";
+import type { RunId, ThreadId } from "../../core/Identifiers.ts";
+import { utf8ByteLength } from "../../core/internal/utf8.ts";
+import { IdempotencyKey } from "../../core/Receipt.ts";
+import { digestJson } from "../Digest.ts";
+import { DurableRuntimeFailpoint } from "../DurableFailpoint.ts";
+import {
+  MessageDeliveryStore,
+  MessageDeliveryRecord,
+  messageDeliveryCapacity,
+  messageDeliveryUsesCapacity,
+  prepareMessageDelivery,
+} from "../MessageDelivery.ts";
+import {
+  AgentUpdateEmitted,
+  BatchId,
+  CanonicalBatch,
+  type CanonicalRecordEnvelope,
+  DefinitionDigests,
+  type DeploymentId,
+  PersistedJson,
+  type ProducerEpoch,
+  type ProducerId,
+  RecordEnvelope,
+  RecordId,
+} from "../Records.ts";
+import { LedgerError, type SubmissionSnapshot } from "../SubmissionLedger.ts";
+import { PreparedInput } from "../Subscription.ts";
+import {
+  FencedAppendRequest,
+  ThreadExportRequest,
+  ThreadStore,
+  ThreadTailRequest,
+} from "../ThreadStore.ts";
+import { WakeScheduler } from "../WakeScheduler.ts";
+import { WorkerRuntime } from "./worker-runtime.ts";
+
+export const lastWorkerReportMessageId = (records: ReadonlyArray<CanonicalRecordEnvelope>) => {
+  for (let index = records.length - 1; index >= 0; index--) {
+    const payload = records[index]?.record.payload;
+
+    if (payload?._tag === "WorkerReportPrepared") return payload.messageId;
+    if (payload?._tag === "AgentUpdateEmitted" && payload.delivery !== undefined)
+      return payload.delivery.messageId;
+  }
+
+  return undefined;
+};
+
+type Delivery = NonNullable<AgentUpdateEmitted["delivery"]>;
+
+const storage = () =>
+  LedgerError.make({ operation: "agent-update", message: "Durable update persistence failed" });
+
+const rejected = (reason: UpdateError["reason"]) => UpdateError.make({ reason });
+
+/** Acceptance is fenced by the actual emitting Attempt; recovery only recreates frozen outbox rows. */
+export const makeAgentUpdateRuntime = Effect.fn("AgentUpdates.makeDurable")(function* (options: {
+  readonly deploymentId: DeploymentId;
+  readonly producerId: ProducerId;
+}) {
+  const store = yield* ThreadStore;
+  const workers = yield* WorkerRuntime;
+  const wake = yield* WakeScheduler;
+  const deliveries = yield* Effect.serviceOption(MessageDeliveryStore);
+  const crypto = yield* Crypto.Crypto;
+  const failpoint = yield* DurableRuntimeFailpoint;
+
+  const read = (threadId: ThreadId) =>
+    store.export(ThreadExportRequest.make({ threadId })).pipe(Effect.mapError(storage));
+
+  const prepareDelivery = Effect.fn("AgentUpdates.prepareDelivery")(function* (
+    update: Update,
+    delivery: Delivery,
+  ) {
+    const envelope = yield* Schema.decodeUnknownEffect(PreparedInput)(delivery.envelope).pipe(
+      Effect.mapError(storage),
+    );
+
+    return yield* prepareMessageDelivery({
+      key: { ownerThreadId: update.threadId, messageId: delivery.messageId },
+      envelope,
+      createdAtMillis: delivery.createdAtMillis,
+      deadlineAtMillis: delivery.deadlineAtMillis,
+      ...(delivery.predecessor === undefined ? {} : { predecessor: delivery.predecessor }),
+    }).pipe(Effect.provideService(Crypto.Crypto, crypto), Effect.mapError(storage));
+  });
+
+  const insert = Effect.fn("AgentUpdates.restoreDelivery")(function* (record: AgentUpdateEmitted) {
+    const delivery = record.delivery;
+
+    if (delivery === undefined) return;
+    if (Option.isNone(deliveries)) return yield* storage();
+    const prepared = yield* prepareDelivery(record.update, delivery);
+
+    yield* failpoint.hit("update:before-delivery-insert");
+    yield* deliveries.value.insert(prepared).pipe(Effect.mapError(storage));
+    yield* failpoint.hit("update:after-delivery-insert");
+  });
+
+  const repair = Effect.fn("AgentUpdates.repair")(function* (threadId: ThreadId) {
+    const history = yield* read(threadId);
+
+    for (const { record } of history.records) {
+      if (record.payload._tag === "AgentUpdateEmitted" && record.payload.delivery !== undefined)
+        yield* insert(record.payload);
+    }
+  });
+
+  const emit = Effect.fn("AgentUpdates.accept")(function* (request: {
+    readonly submission: SubmissionSnapshot;
+    readonly runId: RunId;
+    readonly producerEpoch: ProducerEpoch;
+    readonly definitions: DefinitionDigests;
+    readonly updateId: IdempotencyKey;
+    readonly value: Schema.Json;
+    readonly maxCount?: number;
+    readonly maxBytes?: number;
+  }) {
+    const value = yield* Schema.encodeEffect(Schema.fromJsonString(PersistedJson))(
+      request.value,
+    ).pipe(
+      Effect.flatMap(Schema.decodeEffect(Schema.fromJsonString(PersistedJson))),
+      Effect.mapError(() => rejected("validation")),
+    );
+
+    const updateId = yield* Schema.decodeEffect(IdempotencyKey)(request.updateId).pipe(
+      Effect.mapError(() => rejected("validation")),
+    );
+
+    const digest = yield* digestJson([request.submission.threadId, request.runId, updateId]).pipe(
+      Effect.provideService(Crypto.Crypto, crypto),
+      Effect.mapError(storage),
+    );
+
+    const id = `agent-update:${digest}`;
+    const messageId = Schema.decodeSync(IdempotencyKey)(`worker-update:${digest}`);
+    const maxCount = request.maxCount ?? 32;
+    const maxBytes = request.maxBytes ?? 16_384;
+
+    if (
+      !Number.isSafeInteger(maxCount) ||
+      maxCount < 1 ||
+      !Number.isSafeInteger(maxBytes) ||
+      maxBytes < 1
+    )
+      return yield* rejected("validation");
+
+    for (let attempt = 0; attempt < 32; attempt++) {
+      const history = yield* read(request.submission.threadId);
+
+      const updates = history.records.flatMap(({ record }) =>
+        record.payload._tag === "AgentUpdateEmitted" ? [record.payload] : [],
+      );
+
+      const existing = updates.find(
+        (entry) => entry.update.runId === request.runId && entry.update.updateId === updateId,
+      );
+
+      if (existing !== undefined) {
+        if (
+          existing.update.agentId !== request.submission.agentId ||
+          !Schema.toEquivalence(PersistedJson)(existing.update.value, value) ||
+          !Schema.toEquivalence(DefinitionDigests)(existing.definitions, request.definitions)
+        )
+          return yield* rejected("conflict");
+        yield* insert(existing);
+
+        return existing.update;
+      }
+      const own = updates.filter((entry) => entry.update.runId === request.runId);
+
+      if (
+        own.length >= maxCount ||
+        own.reduce(
+          (total, entry) => total + utf8ByteLength(JSON.stringify(entry.update.value)),
+          0,
+        ) +
+          utf8ByteLength(JSON.stringify(value)) >
+          maxBytes
+      )
+        return yield* rejected("capacity");
+      if (
+        history.records.some(
+          ({ record }) =>
+            record.payload._tag === "SubmissionSettled" && record.payload.runId === request.runId,
+        ) ||
+        !history.records.some(
+          ({ record }) =>
+            record.payload._tag === "RunStarted" && record.payload.runId === request.runId,
+        )
+      )
+        return yield* rejected("identity");
+
+      const update = Update.make({
+        schemaVersion: 1,
+        agentId: request.submission.agentId,
+        threadId: request.submission.threadId,
+        runId: request.runId,
+        updateId,
+        sequence: (updates.at(-1)?.update.sequence ?? 0) + 1,
+        value,
+      });
+
+      const prepared = yield* workers.prepareUpdate(update, request.submission, messageId);
+      let delivery: Delivery | undefined;
+
+      if (prepared !== undefined) {
+        if (Option.isNone(deliveries)) return yield* rejected("unavailable");
+        const retained = updates.filter((entry) => entry.delivery !== undefined);
+        const capacity = messageDeliveryCapacity(deliveries.value.limits, true);
+
+        if (
+          retained.length >= capacity.retained ||
+          utf8ByteLength(JSON.stringify(prepared.envelope)) >
+            deliveries.value.limits.maxEnvelopeBytes
+        )
+          return yield* rejected("capacity");
+        let pending = 0;
+
+        for (const accepted of retained) {
+          if (accepted.delivery === undefined) continue;
+
+          const row = yield* deliveries.value
+            .get({
+              ownerThreadId: request.submission.threadId,
+              messageId: accepted.delivery.messageId,
+            })
+            .pipe(Effect.mapError(storage));
+
+          if (row === null || messageDeliveryUsesCapacity(row)) pending++;
+        }
+        if (pending >= capacity.pending) return yield* rejected("capacity");
+        const predecessor = lastWorkerReportMessageId(history.records);
+
+        delivery = { ...prepared, ...(predecessor === undefined ? {} : { predecessor }) };
+        const deliveryRecord = yield* prepareDelivery(update, delivery);
+
+        const stored = yield* Schema.encodeEffect(Schema.fromJsonString(MessageDeliveryRecord))(
+          deliveryRecord,
+        ).pipe(Effect.mapError(storage));
+
+        if (utf8ByteLength(stored) > deliveries.value.maxStoredValueBytes)
+          return yield* rejected("capacity");
+      }
+
+      const payload = AgentUpdateEmitted.make({
+        update,
+        definitions: request.definitions,
+        ...(delivery === undefined ? {} : { delivery }),
+      });
+
+      const tail = yield* store
+        .inspectTail(ThreadTailRequest.make({ threadId: request.submission.threadId }))
+        .pipe(Effect.mapError(storage));
+
+      if (tail.producerEpoch !== request.producerEpoch) return yield* storage();
+      if (tail.tailSequence !== history.tailSequence || tail.tailDigest !== history.tailDigest)
+        continue;
+      yield* failpoint.hit("update:before-canonical-append");
+
+      const appended = yield* store
+        .append(
+          FencedAppendRequest.make({
+            threadId: request.submission.threadId,
+            producerEpoch: request.producerEpoch,
+            expectedTailSequence: history.tailSequence,
+            expectedTailDigest: history.tailDigest,
+            batch: CanonicalBatch.make({
+              batchId: Schema.decodeSync(BatchId)(id),
+              producerId: options.producerId,
+              records: [
+                RecordEnvelope.make({
+                  recordId: Schema.decodeSync(RecordId)(id),
+                  family: "thread",
+                  schemaVersion: 1,
+                  createdAt: DateTime.makeUnsafe(yield* Clock.currentTimeMillis),
+                  deploymentId: options.deploymentId,
+                  payload,
+                }),
+              ],
+            }),
+          }),
+        )
+        .pipe(
+          Effect.as(true),
+          Effect.catchTag("AppendConflict", () => Effect.succeed(false)),
+          Effect.mapError(storage),
+        );
+
+      if (!appended) continue;
+      yield* failpoint.hit("update:after-canonical-append");
+      // Canonical progress is observable even when no parent report is selected.
+      yield* wake.notify(request.submission.threadId);
+      yield* insert(payload);
+
+      return update;
+    }
+
+    return yield* storage();
+  });
+
+  return { emit, repair };
+});

package/src/durable/internal/foreign-diagnostic.ts

@@ -0,0 +1,47 @@
+import { Option, Schema } from "effect";
+
+const ErrorMessage = Schema.Struct({ message: Schema.String });
+const ErrorTag = Schema.Struct({ _tag: Schema.NonEmptyString });
+const decodeErrorMessage = Schema.decodeUnknownOption(ErrorMessage);
+const decodeErrorTag = Schema.decodeUnknownOption(ErrorTag);
+
+interface ForeignDiagnostic {
+  readonly tag?: string | undefined;
+  readonly message?: string | undefined;
+}
+
+/**
+ * Inspect a foreign failure without trusting its property accessors. Schema owns the accepted
+ * fields, while the guards around each decode keep hostile proxies and getters from escaping as
+ * defects during diagnostic projection.
+ */
+export const inspectForeignDiagnostic = (value: unknown): ForeignDiagnostic => {
+  let tag: string | undefined;
+  let message: string | undefined;
+
+  try {
+    tag = Option.getOrUndefined(decodeErrorTag(value))?._tag;
+  } catch {
+    // A diagnostic is best effort. The caller supplies the stable fallback classification.
+  }
+
+  try {
+    message = Option.getOrUndefined(decodeErrorMessage(value))?.message;
+  } catch {
+    // A hostile message accessor must not replace the original failure with a defect.
+  }
+
+  return {
+    ...(tag === undefined ? {} : { tag }),
+    ...(message === undefined ? {} : { message }),
+  };
+};
+
+/** Render an opaque foreign value without allowing its coercion hooks to escape. */
+export const safeUnknownString = (value: unknown, fallback: string): string => {
+  try {
+    return String(value);
+  } catch {
+    return fallback;
+  }
+};

package/src/durable/internal/journal-checkpoint.ts

@@ -0,0 +1,104 @@
+import { Option, Schema } from "effect";
+import { Prompt } from "effect/unstable/ai";
+
+import { RunId, SubmissionId } from "../../core/Identifiers.ts";
+import { RunPolicyUsage } from "../../core/RunPolicyUsage.ts";
+import { Selection } from "../../core/ToolExposure.ts";
+import { RunUsageSummary } from "../../core/Usage.ts";
+import { CanonicalRecordEnvelope, CanonicalSequence, Digest, PersistedJson } from "../Records.ts";
+
+/** Retired accounting is additive; the latest Tool batch always remains replayable verbatim. */
+export class JournalCheckpointSeed extends Schema.Class<JournalCheckpointSeed>(
+  "@effect-agent/thread/internal/JournalCheckpointSeed",
+)({
+  runId: RunId,
+  throughSequence: CanonicalSequence,
+  firstSequence: Schema.optionalKey(CanonicalSequence),
+  toolSelection: Schema.optionalKey(Selection),
+  committedTurns: Schema.Natural,
+  policyUsage: RunPolicyUsage,
+  modelCalls: Schema.Natural,
+  unobservedModelCalls: Schema.Natural,
+  inputTokens: Schema.Natural,
+  outputTokens: Schema.Natural,
+  lastInputTokens: Schema.Natural,
+  lastOutputTokens: Schema.Natural,
+  costMicrousd: Schema.Natural,
+  summarizedModelUsage: RunUsageSummary,
+  protectedContext: Schema.optionalKey(PersistedJson),
+  contextWindowId: Schema.optionalKey(Schema.String),
+  frontier: Schema.optionalKey(
+    Schema.Struct({
+      sequence: CanonicalSequence,
+      tag: Schema.Literals(["ModelResponseRecorded", "ToolCallSettled"]),
+    }),
+  ),
+  /** Canonical replacement whose covered batches were validated before retirement. */
+  compaction: CanonicalRecordEnvelope,
+}) {}
+
+/** A bounded sparse projection, never a canonical log or a submission-ownership record. */
+export class RecoveryCheckpointState extends Schema.Class<RecoveryCheckpointState>(
+  "@effect-agent/thread/internal/RecoveryCheckpointState",
+)({
+  schemaVersion: Schema.Literal(1),
+  policyAccountingVersion: Schema.Literal(1),
+  submissionId: SubmissionId,
+  submissionIds: Schema.Array(SubmissionId).check(Schema.isMaxLength(4_096)),
+  seed: JournalCheckpointSeed,
+  records: Schema.Array(CanonicalRecordEnvelope).check(Schema.isMaxLength(4_096)),
+}) {}
+
+export class RecoveryCheckpointContents extends Schema.Class<RecoveryCheckpointContents>(
+  "@effect-agent/thread/internal/RecoveryCheckpointContents",
+)({
+  state: RecoveryCheckpointState,
+  digest: Digest,
+}) {}
+
+export const RECOVERY_ENGINE_VERSION = "effect-agent/recovery@2";
+
+/**
+ * Late evidence can invalidate an old compaction. Such histories use full canonical replay;
+ * an omitted run/turn must never be treated as proven absent by a sparse projection.
+ */
+export const checkpointSuffixCompatible = (
+  seed: JournalCheckpointSeed,
+  records: ReadonlyArray<CanonicalRecordEnvelope>,
+  retained: ReadonlyArray<CanonicalRecordEnvelope>,
+): boolean =>
+  records.every(({ sequence, record: { payload } }) => {
+    if ("runId" in payload && payload.runId !== undefined && payload.runId !== seed.runId)
+      return false;
+    if ("turn" in payload && payload.turn <= seed.committedTurns) return false;
+    if (payload._tag === "ToolCallSettled" || payload._tag === "ToolCallResolved") {
+      // These records have no turn. The retained declaration/preparation proves their scope.
+      return [...retained, ...records].some(
+        ({ sequence: declarationSequence, record: { payload: candidate } }) => {
+          if (
+            candidate._tag !== "ModelResponseRecorded" ||
+            candidate.runId !== payload.runId ||
+            candidate.turn <= seed.committedTurns ||
+            seed.compaction.record.payload._tag !== "CompactionCreated" ||
+            declarationSequence <= seed.compaction.record.payload.coversThrough ||
+            declarationSequence >= sequence
+          )
+            return false;
+          const decoded = Schema.decodeUnknownOption(Prompt.Prompt)(candidate.messages);
+
+          return (
+            Option.isSome(decoded) &&
+            decoded.value.content.some(
+              (message) =>
+                message.role === "assistant" &&
+                message.content.some(
+                  (part) => part.type === "tool-call" && part.id === payload.toolCallId,
+                ),
+            )
+          );
+        },
+      );
+    }
+
+    return payload._tag !== "CompactionCreated" || payload.coversThrough >= seed.throughSequence;
+  });

package/src/durable/internal/journal-metadata.ts

@@ -0,0 +1,124 @@
+import { type RunId } from "../../core/Identifiers.ts";
+import {
+  type CanonicalRecordEnvelope,
+  type CompactionCreated,
+  type ToolCallPrepared,
+  type ToolCallSettled,
+} from "../Records.ts";
+import { type JournalCheckpointSeed } from "./journal-checkpoint.ts";
+
+/** Metadata for one exact canonical prefix, including the same optional checkpoint seed. */
+export interface JournalMetadata {
+  readonly ownerRunId: RunId | undefined;
+  readonly seed: JournalCheckpointSeed | undefined;
+  readonly firstSequenceByRun: ReadonlyMap<string, number>;
+  readonly lastResponseSequenceByRun: ReadonlyMap<string, number>;
+  readonly terminalSequenceByRun: ReadonlyMap<string, number>;
+  readonly settledSpans: ReadonlyArray<{
+    readonly from: number;
+    readonly to: number;
+    readonly runId: RunId;
+  }>;
+  readonly toolExecutionEvidence: ReadonlySet<string>;
+  readonly settledToolCallRecordIds: ReadonlySet<string>;
+  readonly settledById: ReadonlyMap<
+    string,
+    Pick<ToolCallSettled, "isFailure" | "budgetRejected" | "toolSelection">
+  >;
+  readonly compactions: ReadonlyArray<{
+    readonly payload: CompactionCreated;
+    readonly sequence: number;
+  }>;
+}
+
+export const toolExecutionKey = (
+  call: Pick<ToolCallPrepared, "runId" | "turn" | "toolCallId">,
+): string => JSON.stringify([call.runId, call.turn, call.toolCallId]);
+
+/**
+ * Attempt-local metadata collector. Feed every validated record exactly once, in canonical order,
+ * including records omitted from the control view. A snapshot is independent of later suffix
+ * additions and may only accompany a replay stream bounded at that same captured tail.
+ */
+export const makeJournalMetadata = (
+  ownerRunId: RunId | undefined,
+  seed?: JournalCheckpointSeed,
+) => {
+  const firstSequenceByRun = new Map<string, number>();
+
+  if (seed?.firstSequence !== undefined) firstSequenceByRun.set(seed.runId, seed.firstSequence);
+  const lastResponseSequenceByRun = new Map<string, number>();
+  const terminalSequenceByRun = new Map<string, number>();
+
+  const settledSpans: Array<{ readonly from: number; readonly to: number; readonly runId: RunId }> =
+    [];
+
+  const toolExecutionEvidence = new Set<string>();
+  const settledToolCallRecordIds = new Set<string>();
+
+  const settledById = new Map<
+    string,
+    Pick<ToolCallSettled, "isFailure" | "budgetRejected" | "toolSelection">
+  >();
+
+  const compactions: Array<{ readonly payload: CompactionCreated; readonly sequence: number }> = [];
+
+  return {
+    add: (envelope: CanonicalRecordEnvelope): void => {
+      const payload = envelope.record.payload;
+
+      if (
+        (payload._tag === "RunCompleted" ||
+          payload._tag === "RunFailed" ||
+          payload._tag === "SubmissionSettled") &&
+        payload.runId !== undefined &&
+        !terminalSequenceByRun.has(payload.runId)
+      )
+        terminalSequenceByRun.set(payload.runId, envelope.sequence);
+      if (payload._tag === "CompactionCreated") {
+        compactions.push({ payload, sequence: envelope.sequence });
+
+        return;
+      }
+      if (
+        "runId" in payload &&
+        typeof payload.runId === "string" &&
+        !firstSequenceByRun.has(payload.runId)
+      )
+        firstSequenceByRun.set(payload.runId, envelope.sequence);
+      if (payload._tag === "ModelResponseRecorded") {
+        lastResponseSequenceByRun.set(payload.runId, envelope.sequence);
+      } else if (payload._tag === "ToolCallPrepared" || payload._tag === "ToolCallUnknown") {
+        toolExecutionEvidence.add(toolExecutionKey(payload));
+      } else if (payload._tag === "ToolCallSettled") {
+        settledToolCallRecordIds.add(envelope.record.recordId);
+        if (payload.runId === ownerRunId)
+          settledById.set(envelope.record.recordId, {
+            isFailure: payload.isFailure,
+            ...(payload.toolSelection === undefined
+              ? {}
+              : { toolSelection: payload.toolSelection }),
+            ...(payload.budgetRejected === undefined
+              ? {}
+              : { budgetRejected: payload.budgetRejected }),
+          });
+        const from = lastResponseSequenceByRun.get(payload.runId);
+
+        if (from !== undefined && from < envelope.sequence)
+          settledSpans.push({ from, to: envelope.sequence, runId: payload.runId });
+      }
+    },
+    snapshot: (): JournalMetadata => ({
+      ownerRunId,
+      seed,
+      firstSequenceByRun: new Map(firstSequenceByRun),
+      lastResponseSequenceByRun: new Map(lastResponseSequenceByRun),
+      terminalSequenceByRun: new Map(terminalSequenceByRun),
+      settledSpans: [...settledSpans],
+      toolExecutionEvidence: new Set(toolExecutionEvidence),
+      settledToolCallRecordIds: new Set(settledToolCallRecordIds),
+      settledById: new Map(settledById),
+      compactions: [...compactions],
+    }),
+  };
+};

package/src/durable/internal/message-status.ts

@@ -0,0 +1,20 @@
+import { Schema } from "effect";
+
+import { MessageStatus } from "../../core/Messaging.ts";
+import type { MessageDeliveryRecord } from "../MessageDelivery.ts";
+
+/** Share the bounded projection across peer and worker delivery; diagnostics stay in storage. */
+export const messageStatus = (row: MessageDeliveryRecord) =>
+  Schema.decodeUnknownEffect(MessageStatus)({
+    message: row.key,
+    status: row.status,
+    receipt: row.receipt,
+    settlement:
+      row.settlement === null
+        ? null
+        : { settlementId: row.settlement.settlementId, outcome: row.settlement.outcome },
+    reason:
+      row.refusal ??
+      row.parkReason ??
+      (row.status === "pending" || row.status === "accepted" ? row.retry.lastFailure : null),
+  });