effect-agent 0.1.0-beta.9 → 0.1.0-beta.91

package/src/durable/SubscriptionTools.ts

@@ -0,0 +1,327 @@
+import type { Layer } from "effect";
+import { Crypto, Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+import { type AgentId, type ThreadId } from "../core/Identifiers.ts";
+import { DurableStep, ToolExecutionClass } from "../engine/DurableStep.ts";
+import type { DefinitionDigests, PersistedJson } from "./Records.ts";
+import type { ScheduleDestination } from "./Schedule.ts";
+import type { Principal } from "./SubmissionLedger.ts";
+import {
+  type EventSourceVersion,
+  SubscriptionError,
+  SubscriptionFailpointError,
+  SubscriptionName,
+  SubscriptionSnapshot,
+  SubscriptionSourceError,
+  type SubscriptionScope,
+} from "./Subscription.ts";
+import { Subscriptions } from "./Subscriptions.ts";
+
+export const SubscriptionToolRegistration = Schema.Struct({
+  subscriptionId: SubscriptionName,
+  source: Schema.Struct({ name: SubscriptionName, version: SubscriptionName }),
+  mode: Schema.Literals(["once", "continuous"]),
+  state: Schema.Literals(["active", "paused", "consumed", "cancelled", "expired"]),
+  createdAtMillis: Schema.Int,
+  expiresAtMillis: Schema.NullOr(Schema.Int),
+  recovery: SubscriptionSnapshot.fields.recovery,
+});
+
+export type SubscriptionToolRegistration = typeof SubscriptionToolRegistration.Type;
+
+export const SubscribeToEventParameters = Schema.Struct({
+  source: Schema.Struct({ name: SubscriptionName, version: SubscriptionName }),
+  parameters: Schema.Json,
+  mode: Schema.Literals(["once", "continuous"]),
+  expiresAtMillis: Schema.NullOr(Schema.Int).annotate({
+    description:
+      "Absolute Unix epoch milliseconds, or null to remain active until cancelled; retain the same value on retries",
+  }),
+  context: Schema.Json,
+});
+
+export const ListEventSubscriptionsParameters = Schema.Struct({
+  after: Schema.optionalKey(Schema.Natural),
+  limit: Schema.optionalKey(
+    Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(100)),
+  ),
+});
+
+export const CancelEventSubscriptionParameters = Schema.Struct({
+  subscriptionId: SubscriptionName,
+});
+
+export const SubscriptionToolSourceCatalogEntry = Schema.Struct({
+  source: Schema.Struct({ name: SubscriptionName, version: SubscriptionName }),
+  description: Schema.NonEmptyString.check(Schema.isMaxLength(2_048)),
+  parametersJsonSchema: Schema.Json,
+  contextJsonSchema: Schema.Json,
+});
+
+export type SubscriptionToolSourceCatalogEntry = typeof SubscriptionToolSourceCatalogEntry.Type;
+
+const SubscriptionToolFailure = Schema.Union([
+  SubscriptionError,
+  SubscriptionSourceError,
+  SubscriptionFailpointError,
+]);
+
+export const ListEventSources = Tool.make("list_event_sources", {
+  description:
+    "List the exact event source versions this host permits, with their parameter and continuation-context JSON Schemas. Inspect this catalog before subscribing.",
+  parameters: Schema.Struct({}),
+  success: Schema.Array(SubscriptionToolSourceCatalogEntry),
+  failure: SubscriptionError,
+  failureMode: "return",
+})
+  .annotate(Tool.Readonly, true)
+  .annotate(ToolExecutionClass, "readonly");
+
+export const SubscribeToEvent = Tool.make("subscribe_to_event", {
+  description:
+    "Register a durable event subscription from the host-permitted source catalog. The destination, Agent, authority, and delivery principal are fixed by the host.",
+  parameters: SubscribeToEventParameters,
+  success: SubscriptionToolRegistration,
+  failure: SubscriptionToolFailure,
+  failureMode: "return",
+  dependencies: [DurableStep],
+})
+  .annotate(Tool.Readonly, false)
+  .annotate(ToolExecutionClass, "idempotent");
+
+export const ListEventSubscriptions = Tool.make("list_event_subscriptions", {
+  description: "List redacted durable event subscriptions in the current host-bound owner scope.",
+  parameters: ListEventSubscriptionsParameters,
+  success: Schema.Struct({
+    items: Schema.Array(SubscriptionToolRegistration),
+    next: Schema.NullOr(Schema.Natural),
+  }),
+  failure: SubscriptionError,
+  failureMode: "return",
+})
+  .annotate(Tool.Readonly, true)
+  .annotate(ToolExecutionClass, "readonly");
+
+export const CancelEventSubscription = Tool.make("cancel_event_subscription", {
+  description: "Cancel one durable event subscription in the current host-bound owner scope.",
+  parameters: CancelEventSubscriptionParameters,
+  success: SubscriptionToolRegistration,
+  failure: Schema.Union([SubscriptionError, SubscriptionFailpointError]),
+  failureMode: "return",
+  dependencies: [DurableStep],
+})
+  .annotate(Tool.Readonly, false)
+  .annotate(ToolExecutionClass, "idempotent");
+
+export const SubscriptionTools = Toolkit.make(
+  ListEventSources,
+  SubscribeToEvent,
+  ListEventSubscriptions,
+  CancelEventSubscription,
+);
+
+export interface PermittedSubscriptionToolSource {
+  readonly source: EventSourceVersion;
+  /** The source's input Schema must be the input Schema of this exact host Agent identity. */
+  readonly agentId: AgentId;
+  readonly description: string;
+  readonly parameters: Schema.Top;
+  readonly context: Schema.Top;
+}
+
+export interface SubscriptionToolsOptions {
+  readonly scope: SubscriptionScope;
+  readonly currentThreadId: ThreadId;
+  readonly deliveryPrincipal: Principal;
+  readonly agentId: AgentId;
+  readonly definitions: DefinitionDigests;
+  readonly permittedSources: ReadonlyArray<PermittedSubscriptionToolSource>;
+  /** Defaults to the current Thread; a host may instead bind deterministic fresh delivery. */
+  readonly destination?: ScheduleDestination | undefined;
+}
+
+const sameSource = (left: EventSourceVersion, right: EventSourceVersion): boolean =>
+  left.name === right.name && left.version === right.version;
+
+const registration = (
+  snapshot: typeof SubscriptionSnapshot.Type,
+): SubscriptionToolRegistration => ({
+  subscriptionId: snapshot.key.subscriptionId,
+  source: snapshot.source,
+  mode: snapshot.mode,
+  state: snapshot.state,
+  createdAtMillis: snapshot.createdAtMillis,
+  expiresAtMillis: snapshot.expiresAtMillis,
+  recovery: snapshot.recovery,
+});
+
+const toolFailure = (reason: SubscriptionError["reason"], code: string): SubscriptionError =>
+  SubscriptionError.make({ reason, code });
+
+/**
+ * Bind management authority before exposing Tools to a model. The model can select only an exact
+ * source/version and source-defined parameters; it cannot choose another tenant, owner,
+ * Thread, Agent, definition digest, principal, destination policy, or credential.
+ */
+export const subscriptionToolsLayer = (
+  options: SubscriptionToolsOptions,
+): Layer.Layer<
+  Tool.HandlersFor<Toolkit.Tools<typeof SubscriptionTools>>,
+  SubscriptionError,
+  Subscriptions | Crypto.Crypto
+> => {
+  const destination: ScheduleDestination = options.destination ?? {
+    _tag: "ExistingThread",
+    threadId: options.currentThreadId,
+  };
+
+  const build = Effect.gen(function* () {
+    const duplicate = options.permittedSources.find(
+      (candidate, index, all) =>
+        all.findIndex((item) => sameSource(item.source, candidate.source)) !== index,
+    );
+
+    if (duplicate !== undefined) {
+      return yield* toolFailure("validation", "duplicate-source-catalog-entry");
+    }
+
+    const mismatched = options.permittedSources.find(
+      (candidate) => candidate.agentId !== options.agentId,
+    );
+
+    if (mismatched !== undefined) {
+      return yield* toolFailure("validation", "source-agent-mismatch");
+    }
+
+    const catalog = yield* Effect.forEach(options.permittedSources, (candidate) =>
+      Effect.gen(function* () {
+        const description = yield* Schema.decodeEffect(
+          SubscriptionToolSourceCatalogEntry.fields.description,
+        )(candidate.description).pipe(
+          Effect.mapError(() => toolFailure("validation", "source-catalog-description")),
+        );
+
+        return SubscriptionToolSourceCatalogEntry.make({
+          source: candidate.source,
+          description,
+          parametersJsonSchema: yield* Effect.try({
+            try: () => Tool.getJsonSchemaFromSchema(candidate.parameters),
+            catch: () => toolFailure("validation", "source-parameters-schema"),
+          }),
+          contextJsonSchema: yield* Effect.try({
+            try: () => Tool.getJsonSchemaFromSchema(candidate.context),
+            catch: () => toolFailure("validation", "source-context-schema"),
+          }),
+        });
+      }),
+    );
+
+    const subscriptions = yield* Subscriptions;
+    const crypto = yield* Crypto.Crypto;
+
+    const permitted = (source: EventSourceVersion) =>
+      options.permittedSources.some((candidate) => sameSource(candidate.source, source));
+
+    const subscribe = Effect.fn("SubscriptionTools.subscribe")(function* (parameters: {
+      readonly source: EventSourceVersion;
+      readonly parameters: PersistedJson;
+      readonly mode: "once" | "continuous";
+      readonly expiresAtMillis: number | null;
+      readonly context: PersistedJson;
+    }) {
+      if (!permitted(parameters.source)) {
+        return yield* toolFailure("unauthorized", "source-catalog");
+      }
+      const step = yield* DurableStep;
+
+      // The first committed Step creates one identity per Tool Call. Re-entry observes the same
+      // value, while a separate identical call receives a distinct identity.
+      const subscriptionId = yield* step
+        .do(
+          "subscription-identity",
+          SubscriptionName,
+          crypto.randomUUIDv7.pipe(
+            Effect.map((id) => `tool:${id}`),
+            Effect.mapError(() => toolFailure("storage", "creation-identity")),
+          ),
+        )
+        .pipe(
+          Effect.catchTag("DurableStepError", (error) =>
+            Effect.fail(toolFailure("storage", `durable-step-${error.reason}`)),
+          ),
+        );
+
+      return yield* step
+        .do(
+          "register-subscription",
+          SubscriptionToolRegistration,
+          subscriptions
+            .subscribe(options.scope, {
+              subscriptionId,
+              source: parameters.source,
+              parameters: parameters.parameters,
+              context: parameters.context,
+              mode: parameters.mode,
+              expiresAtMillis: parameters.expiresAtMillis,
+              destination,
+              deliveryPrincipal: options.deliveryPrincipal,
+              agentId: options.agentId,
+              definitions: options.definitions,
+            })
+            .pipe(Effect.map(registration)),
+        )
+        .pipe(
+          Effect.catchTag("DurableStepError", (error) =>
+            Effect.fail(toolFailure("storage", `durable-step-${error.reason}`)),
+          ),
+        );
+    });
+
+    const list = Effect.fn("SubscriptionTools.list")(function* (parameters: {
+      readonly after?: number | undefined;
+      readonly limit?: number | undefined;
+    }) {
+      const page = yield* subscriptions.listSubscriptions(
+        options.scope,
+        parameters.after,
+        parameters.limit,
+      );
+
+      return { items: page.items.map(registration), next: page.next };
+    });
+
+    const cancel = Effect.fn("SubscriptionTools.cancel")(function* (parameters: {
+      readonly subscriptionId: string;
+    }) {
+      const step = yield* DurableStep;
+
+      return yield* step
+        .do(
+          "cancel-subscription",
+          SubscriptionToolRegistration,
+          subscriptions
+            .cancelSubscription(options.scope, {
+              partition: options.scope.partition,
+              ownerId: options.scope.ownerId,
+              subscriptionId: parameters.subscriptionId,
+            })
+            .pipe(Effect.map(registration)),
+        )
+        .pipe(
+          Effect.catchTag("DurableStepError", (error) =>
+            Effect.fail(toolFailure("storage", `durable-step-${error.reason}`)),
+          ),
+        );
+    });
+
+    return SubscriptionTools.of({
+      list_event_sources: () => Effect.succeed(catalog),
+      subscribe_to_event: subscribe,
+      list_event_subscriptions: list,
+      cancel_event_subscription: cancel,
+    });
+  });
+
+  return SubscriptionTools.toLayer(build);
+};

package/src/durable/SubscriptionTransition.ts

@@ -0,0 +1,302 @@
+import { Result, Schema } from "effect";
+
+import { Receipt } from "./DurableAgentRuntime.ts";
+import { DefinitionDigests } from "./Records.ts";
+import { AdmissionFence } from "./SubmissionLedger.ts";
+import {
+  type AcceptedEvent,
+  type DeliveryChange,
+  type SubscriptionChange,
+  type SubscriptionLimits,
+  type SourcePartition,
+  SubscriptionDelivery,
+  SubscriptionConfiguration,
+  type SubscriptionDelivery as SubscriptionDeliveryType,
+  type SubscriptionRecord,
+  SubscriptionError,
+} from "./Subscription.ts";
+
+const conflict = (code: string) => SubscriptionError.make({ reason: "conflict", code });
+const sameDefinitions = Schema.toEquivalence(DefinitionDigests);
+const sameReceipt = Schema.toEquivalence(Receipt);
+
+export const sameSourcePartition = (left: SourcePartition, right: SourcePartition): boolean =>
+  left.tenantId === right.tenantId && left.address === right.address;
+
+/** The retained event is authoritative. An absent historical occurrence stays unknown on replay. */
+export const sameAcceptedEventIdentity = (left: AcceptedEvent, right: AcceptedEvent): boolean =>
+  sameSourcePartition(left.partition, right.partition) &&
+  left.eventId === right.eventId &&
+  left.source.name === right.source.name &&
+  left.source.version === right.source.version &&
+  left.matchingKey === right.matchingKey &&
+  left.payloadDigest === right.payloadDigest &&
+  (left.occurredAtMillis === undefined || left.occurredAtMillis === right.occurredAtMillis);
+
+export const subscriptionMatchesEvent = (
+  subscription: SubscriptionRecord,
+  event: AcceptedEvent,
+): boolean =>
+  subscription.configuration.source.name === event.source.name &&
+  subscription.configuration.source.version === event.source.version &&
+  subscription.configuration.matchingKey === event.matchingKey;
+
+export const subscriptionCanSelect = (
+  subscription: SubscriptionRecord,
+  event: AcceptedEvent,
+  nowMillis: number,
+  bypassCutoff: boolean,
+): boolean =>
+  subscriptionMatchesEvent(subscription, event) &&
+  subscription.state === "active" &&
+  (subscription.configuration.expiresAtMillis === null ||
+    subscription.configuration.expiresAtMillis > nowMillis) &&
+  (bypassCutoff || subscription.ordinal <= event.cutoff);
+
+export const subscriptionDeliveryCanSelect = (
+  delivery: SubscriptionDeliveryType,
+  subscription: SubscriptionRecord,
+  event: AcceptedEvent,
+): boolean => {
+  const expectedThread =
+    subscription.configuration.destination._tag === "ExistingThread"
+      ? subscription.configuration.destination.threadId
+      : `subscription:${delivery.deliveryId}`;
+
+  return (
+    event.tombstone !== true &&
+    delivery.key.eventId === event.eventId &&
+    delivery.key.subscription.partition.tenantId === subscription.key.partition.tenantId &&
+    delivery.key.subscription.partition.address === subscription.key.partition.address &&
+    delivery.key.subscription.ownerId === subscription.key.ownerId &&
+    delivery.key.subscription.subscriptionId === subscription.key.subscriptionId &&
+    delivery.source.name === event.source.name &&
+    delivery.source.version === event.source.version &&
+    delivery.subscriptionFingerprint === subscription.configurationFingerprint &&
+    delivery.configurationRevision === subscription.configurationRevision &&
+    Schema.toEquivalence(SubscriptionConfiguration)(
+      delivery.configuration,
+      subscription.configuration,
+    ) &&
+    delivery.eventDigest === event.payloadDigest &&
+    delivery.threadId === expectedThread &&
+    delivery.admissionKey === `subscription:${delivery.deliveryId}` &&
+    delivery.state === "selected" &&
+    delivery.envelope === null &&
+    delivery.envelopeDigest === null &&
+    delivery.receipt === null &&
+    delivery.refusal === null
+  );
+};
+
+export const sameSubscriptionDelivery = (
+  left: SubscriptionDeliveryType,
+  right: SubscriptionDeliveryType,
+): boolean =>
+  Schema.encodeSync(Schema.fromJsonString(SubscriptionDelivery))(left) ===
+  Schema.encodeSync(Schema.fromJsonString(SubscriptionDelivery))(right);
+
+/** Pure lifecycle transition used inside each adapter's local atomic mutation. */
+export const applySubscriptionDeliveryChange = (
+  existing: SubscriptionDeliveryType,
+  subscription: SubscriptionRecord,
+  deliveryId: string,
+  change: DeliveryChange,
+): Result.Result<SubscriptionDeliveryType, SubscriptionError> => {
+  if (existing.deliveryId !== deliveryId) return Result.fail(conflict("stale-delivery"));
+
+  const configuration = existing.configuration;
+
+  switch (change._tag) {
+    case "ObserveSettlement":
+      if (
+        existing.state !== "delivered" ||
+        existing.receipt === null ||
+        !sameReceipt(existing.receipt, change.receipt)
+      )
+        return Result.fail(conflict("settlement-receipt"));
+      if (existing.settledAtMillis !== undefined) return Result.succeed(existing);
+
+      return Result.succeed({
+        ...existing,
+        observeSettlement: !change.settled,
+        ...(change.settled ? { settledAtMillis: change.nowMillis } : {}),
+        retry: { ...existing.retry, nextAttemptAtMillis: change.nextAttemptAtMillis },
+      });
+    case "Recover":
+      if (existing.retry.generation !== change.expectedGeneration) return Result.succeed(existing);
+      if (existing.state === "delivered" || existing.state === "refused")
+        return Result.succeed(existing);
+
+      return Result.succeed({
+        ...existing,
+        retry: {
+          ...existing.retry,
+          generation: existing.retry.generation + 1,
+          automaticAttempts: 0,
+          parked: false,
+          nextAttemptAtMillis: change.nowMillis,
+        },
+      });
+    case "Prepare": {
+      if (existing.state === "prepared") {
+        return existing.envelope !== null &&
+          existing.envelopeDigest === change.envelopeDigest &&
+          Schema.encodeSync(Schema.fromJsonString(SubscriptionDelivery.fields.envelope))(
+            existing.envelope,
+          ) ===
+            Schema.encodeSync(Schema.fromJsonString(SubscriptionDelivery.fields.envelope))(
+              change.envelope,
+            )
+          ? Result.succeed(existing)
+          : Result.fail(conflict("prepared-envelope"));
+      }
+      if (existing.state !== "selected") return Result.fail(conflict("delivery-state"));
+      if (
+        subscription.state === "cancelled" ||
+        (configuration.expiresAtMillis !== null &&
+          configuration.expiresAtMillis <= change.nowMillis)
+      ) {
+        return Result.succeed({
+          ...existing,
+          state: "refused",
+          refusal: {
+            phase: "preparation",
+            code: subscription.state === "cancelled" ? "cancelled" : "expired",
+          },
+        });
+      }
+      if (
+        change.envelope.threadId !== existing.threadId ||
+        change.envelope.admissionKey !== existing.admissionKey ||
+        change.envelope.deliveryPrincipal !== configuration.deliveryPrincipal ||
+        change.envelope.agentId !== configuration.agentId ||
+        change.envelope.admissionGroup !== configuration.admissionGroup ||
+        !Schema.toEquivalence(Schema.optional(AdmissionFence))(
+          change.envelope.admissionFence,
+          configuration.admissionFence,
+        ) ||
+        !sameDefinitions(change.envelope.definitions, configuration.definitions)
+      )
+        return Result.fail(conflict("prepared-identity"));
+
+      return Result.succeed({
+        ...existing,
+        state: "prepared",
+        envelope: change.envelope,
+        envelopeDigest: change.envelopeDigest,
+      });
+    }
+    case "Complete":
+      if (change.receipt.threadId !== existing.threadId)
+        return Result.fail(conflict("receipt-thread"));
+      if (existing.state === "delivered")
+        return existing.receipt !== null && sameReceipt(existing.receipt, change.receipt)
+          ? Result.succeed(existing)
+          : Result.fail(conflict("receipt"));
+
+      return existing.state === "prepared"
+        ? Result.succeed({
+            ...existing,
+            state: "delivered",
+            receipt: change.receipt,
+            completedAtMillis: change.nowMillis,
+          })
+        : Result.fail(conflict("delivery-state"));
+    case "Refuse":
+      if (existing.state === "refused")
+        return existing.refusal?.phase === change.refusal.phase &&
+          existing.refusal.code === change.refusal.code
+          ? Result.succeed(existing)
+          : Result.fail(conflict("refusal"));
+      if (
+        (change.refusal.phase === "preparation" && existing.state !== "selected") ||
+        (change.refusal.phase === "admission" && existing.state !== "prepared")
+      )
+        return Result.fail(conflict("refusal-phase"));
+
+      return existing.state === "delivered"
+        ? Result.fail(conflict("delivery-state"))
+        : Result.succeed({
+            ...existing,
+            state: "refused",
+            refusal: change.refusal,
+            completedAtMillis: change.nowMillis,
+          });
+    case "Retry":
+      if (existing.state === "delivered" || existing.state === "refused")
+        return Result.fail(conflict("delivery-state"));
+      if (
+        change.retry.generation !== existing.retry.generation ||
+        change.retry.attempts <= existing.retry.attempts ||
+        change.retry.nextAttemptAtMillis < existing.retry.nextAttemptAtMillis
+      )
+        return Result.succeed(existing);
+
+      return Result.succeed({ ...existing, retry: change.retry });
+  }
+};
+
+/** CAS management never mutates a selected or prepared delivery. */
+export const applySubscriptionChange = (
+  existing: SubscriptionRecord,
+  expectedRevision: number,
+  change: SubscriptionChange,
+): Result.Result<SubscriptionRecord, SubscriptionError> => {
+  const revision = existing.configurationRevision;
+
+  if (revision !== expectedRevision)
+    return Result.fail(
+      SubscriptionError.make({
+        reason: "conflict",
+        code: "configuration-revision",
+        currentRevision: revision,
+        currentState: existing.state,
+      }),
+    );
+  if (existing.state === "cancelled" || existing.state === "consumed")
+    return Result.fail(conflict("subscription-state"));
+  if (change._tag === "Pause" && existing.state !== "active")
+    return Result.fail(conflict("subscription-state"));
+  if (change._tag === "Resume" && existing.state !== "paused")
+    return Result.fail(conflict("subscription-state"));
+
+  return Result.succeed({
+    ...existing,
+    creationConfiguration: existing.creationConfiguration,
+    configurationRevision: revision + 1,
+    ...(change._tag === "Update"
+      ? {
+          configuration: change.configuration,
+          configurationFingerprint: change.configurationFingerprint,
+          recovery: change.recovery,
+        }
+      : change._tag === "Recover"
+        ? {
+            recovery:
+              existing.recovery === null
+                ? null
+                : { ...existing.recovery, nextAttemptAtMillis: change.nowMillis },
+          }
+        : { state: change._tag === "Pause" ? ("paused" as const) : ("active" as const) }),
+  });
+};
+
+/** Called only after retained identity lookup: unfinished work remains replayable past the horizon. */
+export const validateEventRetention = (
+  event: AcceptedEvent,
+  limits: SubscriptionLimits,
+  nowMillis: number,
+): Result.Result<void, SubscriptionError> => {
+  if (limits.retention === undefined) return Result.void;
+  if (
+    event.occurredAtMillis === undefined ||
+    event.occurredAtMillis > nowMillis ||
+    event.occurredAtMillis <= nowMillis - limits.retention.replayHorizonMillis
+  )
+    return Result.fail(
+      SubscriptionError.make({ reason: "validation", code: "event-replay-horizon" }),
+    );
+
+  return Result.void;
+};