effect-agent 0.1.0-beta.85 → 0.1.0-beta.87

package/src/durable/ToolReconciler.ts

@@ -0,0 +1,105 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+import { ThreadId, RunId, SubmissionId, ToolCallId } from "../core/Identifiers.ts";
+import { Digest, PersistedJson, ToolCallPrepared } from "./Records.ts";
+
+/**
+ * Everything a reconciliation policy can consult about one prepared-but-unsettled ordinary Tool
+ * Call (durability §10): deterministic identities for supplier-side lookup plus the exact
+ * Schema-encoded parameters and their digest. Built from the canonical `ToolCallPrepared` record
+ * and the owning Submission's identities — never from in-memory Attempt state.
+ */
+export class PreparedToolCallEvidence extends Schema.Class<PreparedToolCallEvidence>(
+  "@effect-agent/thread/PreparedToolCallEvidence",
+)({
+  threadId: ThreadId,
+  submissionId: SubmissionId,
+  runId: RunId,
+  turn: ToolCallPrepared.fields.turn,
+  toolCallId: ToolCallId,
+  toolName: ToolCallPrepared.fields.toolName,
+  parameters: PersistedJson,
+  parametersDigest: Digest,
+}) {}
+
+/** Proof that the external execution never started: the call may re-execute on resume. */
+export class ReconciliationNeverStarted extends Schema.TaggedClass<ReconciliationNeverStarted>(
+  "@effect-agent/thread/ReconciliationNeverStarted",
+)("NeverStarted", {}) {}
+
+/**
+ * Proof that the external execution completed: `result` is the recovered supplier truth, which
+ * becomes canonical (`ToolCallSettled` + `ToolCallResolved`) WITHOUT executing anything.
+ */
+export class ReconciliationCompleted extends Schema.TaggedClass<ReconciliationCompleted>(
+  "@effect-agent/thread/ReconciliationCompleted",
+)("CompletedWithResult", {
+  result: PersistedJson,
+  isFailure: Schema.Boolean,
+}) {}
+
+/** The call is safe to repeat under a stable external idempotency contract. */
+export class ReconciliationSafeToRetry extends Schema.TaggedClass<ReconciliationSafeToRetry>(
+  "@effect-agent/thread/ReconciliationSafeToRetry",
+)("SafeToRetry", {}) {}
+
+/** No proof either way: the outcome is Unknown and requires authorized resolution (DUR-017). */
+export class ReconciliationUncertain extends Schema.TaggedClass<ReconciliationUncertain>(
+  "@effect-agent/thread/ReconciliationUncertain",
+)("Uncertain", {
+  reason: Schema.String,
+}) {}
+
+/**
+ * What a reconciliation policy can prove about one prepared-but-unsettled ordinary Tool Call
+ * (durability §10): execution never started, execution completed with a recoverable result,
+ * execution is safe to repeat, or nothing — in which case the Run enters Unknown. The engine
+ * never manufactures an error result and continues.
+ */
+export const ReconciliationDecision = Schema.Union([
+  ReconciliationNeverStarted,
+  ReconciliationCompleted,
+  ReconciliationSafeToRetry,
+  ReconciliationUncertain,
+]);
+
+export type ReconciliationDecision = typeof ReconciliationDecision.Type;
+
+/** The reconciliation policy itself failed (supplier unreachable, corrupt lookup, ...). The
+ * caller treats this as no proof: the call stays open and the pass may retry. */
+export class ToolReconcilerError extends Schema.TaggedError<ToolReconcilerError>()(
+  "ToolReconcilerError",
+  {
+    toolCallId: ToolCallId,
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {}
+
+/**
+ * Application-registered reconciliation policy consulted by recovery for every open ordinary
+ * Tool Call before an Unknown Outcome is recorded (durability §10, DUR-009). A decision is a
+ * claim about EXTERNAL truth — typically an idempotency-keyed supplier lookup — never a guess
+ * from canonical state alone.
+ *
+ * `ToolReconciler.uncertain` is the fail-closed default (AGENTS rule 11): with no registered
+ * policy, every open call stays Unknown and routes to the authorized DUR-017 resolution path.
+ */
+export class ToolReconciler extends Context.Service<
+  ToolReconciler,
+  {
+    readonly reconcile: (
+      evidence: PreparedToolCallEvidence,
+    ) => Effect.Effect<ReconciliationDecision, ToolReconcilerError>;
+  }
+>()("@effect-agent/thread/ToolReconciler") {
+  /** Fail-closed default: no proof is ever asserted, every open call stays Unknown. */
+  static readonly uncertain: Layer.Layer<ToolReconciler> = Layer.succeed(this)({
+    reconcile: () =>
+      Effect.succeed(
+        ReconciliationUncertain.make({
+          reason: "No reconciliation policy is registered; the outcome stays unknown",
+        }),
+      ),
+  });
+}

package/src/durable/WakeScheduler.ts

@@ -0,0 +1,134 @@
+import type { Scope } from "effect";
+import { Context, Deferred, Effect, Layer, Ref, Stream } from "effect";
+
+import { type ThreadId } from "../core/Identifiers.ts";
+
+/**
+ * Incarnation-local, thread-keyed wake registrations. A registration is installed before
+ * its returned Effect can be awaited, which lets a caller subscribe, check durable authority,
+ * and then park without a lost-wakeup window.
+ */
+export interface WakeSubscriptionHub {
+  /** Register one Scope-owned waiter and return its one-shot wake Effect. */
+  readonly subscribe: (
+    threadId: ThreadId,
+  ) => Effect.Effect<Effect.Effect<void>, never, Scope.Scope>;
+  /** Wake every currently registered waiter for exactly this Thread. */
+  readonly notify: (threadId: ThreadId) => Effect.Effect<void>;
+}
+
+interface WakeRegistration {
+  readonly id: number;
+  readonly deferred: Deferred.Deferred<void>;
+}
+
+type WakeRegistrations = ReadonlyMap<ThreadId, ReadonlyMap<number, Deferred.Deferred<void>>>;
+
+/**
+ * Build the shared per-incarnation registration primitive used by host WakeSchedulers. The hub
+ * contains hints only: eviction may discard it, while a reconnecting caller re-subscribes and
+ * rechecks canonical storage. Scope finalizers remove cancelled waiters, and notify broadcasts
+ * instead of consuming a signal that belongs to another waiter.
+ */
+export const makeWakeSubscriptionHub: Effect.Effect<WakeSubscriptionHub> = Effect.gen(function* () {
+  const registrations = yield* Ref.make<WakeRegistrations>(new Map());
+  const nextId = yield* Ref.make(0);
+
+  const remove = (threadId: ThreadId, id: number) =>
+    Ref.update(registrations, (current) => {
+      const existing = current.get(threadId);
+
+      if (existing === undefined || !existing.has(id)) return current;
+      const next = new Map(current);
+      const thread = new Map(existing);
+
+      thread.delete(id);
+      if (thread.size === 0) {
+        next.delete(threadId);
+      } else {
+        next.set(threadId, thread);
+      }
+
+      return next;
+    });
+
+  const subscribe = Effect.fn("WakeSubscriptionHub.subscribe")(
+    (threadId: ThreadId): Effect.Effect<Effect.Effect<void>, never, Scope.Scope> =>
+      Effect.gen(function* () {
+        const deferred = yield* Deferred.make<void>();
+        const id = yield* Ref.getAndUpdate(nextId, (current) => current + 1);
+        const registration: WakeRegistration = { id, deferred };
+
+        yield* Effect.addFinalizer(() => remove(threadId, registration.id));
+        yield* Ref.update(registrations, (current) => {
+          const next = new Map(current);
+          const thread = new Map(current.get(threadId) ?? []);
+
+          thread.set(registration.id, registration.deferred);
+          next.set(threadId, thread);
+
+          return next;
+        });
+
+        return registration.deferred;
+      }).pipe(Effect.map((deferred) => Deferred.await(deferred))),
+  );
+
+  const notify = Effect.fn("WakeSubscriptionHub.notify")(function* (threadId: ThreadId) {
+    const waiters = yield* Ref.modify(registrations, (current) => {
+      const thread = current.get(threadId);
+
+      if (thread === undefined) return [[], current] as const;
+      const next = new Map(current);
+
+      next.delete(threadId);
+
+      return [[...thread.values()], next] as const;
+    });
+
+    yield* Effect.forEach(waiters, (waiter) => Deferred.succeed(waiter, undefined), {
+      discard: true,
+    });
+  });
+
+  return { subscribe, notify };
+});
+
+/**
+ * Liveness hint channel for durable schedulers. `notify` announces that a Thread lane may
+ * have claimable, canonical, or settled work; `wakes` is the all-lanes subscription surface for
+ * workers, while `subscribe` installs an efficient one-Thread wait registration.
+ *
+ * Correctness must NEVER depend on delivery: notifications may be dropped, coalesced, duplicated,
+ * or observed by no subscriber (a notify before any subscription is simply lost). Every consumer
+ * must pair a wake with durable authority: workers use periodic SubmissionLedger scans, while a
+ * public progress waiter subscribes before its canonical read and reconnects/rechecks after an
+ * incarnation loss (persistence §14).
+ *
+ * Each run of `wakes` creates its own subscription whose resources live in that run's Scope and
+ * are released when the consuming stream ends or is interrupted. Implementations must not spawn
+ * daemon fibers.
+ */
+export class WakeScheduler extends Context.Service<
+  WakeScheduler,
+  {
+    /** Best-effort hint that `threadId` may have claimable or settled work. Never fails. */
+    readonly notify: (threadId: ThreadId) => Effect.Effect<void>;
+    /** Scope-owned one-shot registration for exactly one Thread. */
+    readonly subscribe: (
+      threadId: ThreadId,
+    ) => Effect.Effect<Effect.Effect<void>, never, Scope.Scope>;
+    /** Scope-owned subscription to wake hints, starting at subscription time. */
+    readonly wakes: Stream.Stream<ThreadId>;
+  }
+>()("@effect-agent/thread/WakeScheduler") {
+  /**
+   * Discards every notification and never wakes anyone. Valid because WakeScheduler is only a
+   * liveness hint: consumers relying on ledger scans stay correct, merely slower.
+   */
+  static readonly layerNoop: Layer.Layer<WakeScheduler> = Layer.succeed(WakeScheduler, {
+    notify: () => Effect.void,
+    subscribe: () => Effect.succeed(Effect.never),
+    wakes: Stream.never,
+  });
+}

package/src/durable/WorkerHost.ts

@@ -0,0 +1,171 @@
+import { Context, Effect, Option, Schema } from "effect";
+
+import type * as Agent from "../core/Agent.ts";
+import type { AgentPolicy } from "../core/AgentPolicy.ts";
+import type { SubmissionId, ThreadId } from "../core/Identifiers.ts";
+import type { SubagentBudgetReservation } from "../core/SubagentContract.ts";
+import { WorkerError, type WorkerRef, type WorkerSource } from "../core/Worker.ts";
+import type { DefinitionDigests, Digest, PersistedJson, WorkerOrigin } from "./Records.ts";
+import type { Principal, SubmissionSnapshot } from "./SubmissionLedger.ts";
+
+/** Host-verified source input; absence never means the latest input in the Thread. */
+export interface WorkerPolicySource {
+  readonly threadId: ThreadId;
+  readonly definition: Agent.AnyDefinition;
+  readonly definitions: DefinitionDigests;
+  readonly submission?: SubmissionSnapshot;
+}
+
+/** Initial input is validated again at destination admission, including idempotent replay. */
+export type WorkerPolicyTarget = {
+  readonly definition: Agent.AnyDefinition;
+  readonly definitions: DefinitionDigests;
+  readonly source: WorkerSource;
+} & (
+  | {
+      readonly _tag: "InitialInput";
+      readonly sourceSubmission?: SubmissionSnapshot;
+      readonly input: PersistedJson;
+      readonly inputDigest: Digest;
+    }
+  | {
+      readonly _tag: "RetainedWorker";
+      /** Verified against canonical source history before this request reaches the resolver. */
+      readonly origin: WorkerOrigin;
+    }
+);
+
+/**
+ * Opt-in host authority for policies captured in immutable application input. None preserves
+ * the registered Definition's existing policy/override semantics. Some is a complete policy,
+ * never merged with static overrides. Decode and authorize the exact captured revision; do not
+ * read mutable settings or substitute a current capture for missing historical authority.
+ * RetainedWorker may affirm only origin.policy, never replace a continuing worker's allowance.
+ * Return WorkerError(unavailable) for temporarily unavailable authority so delivery can retry.
+ * Implementations are acquired through Effect Layers; capture their dependencies in Layer R.
+ */
+export const WorkerPolicyResolver = Context.Reference<{
+  readonly resolveSource: (
+    request: WorkerPolicySource,
+  ) => Effect.Effect<Option.Option<AgentPolicy>, WorkerError>;
+  readonly resolveTarget: (
+    request: WorkerPolicyTarget,
+  ) => Effect.Effect<Option.Option<AgentPolicy>, WorkerError>;
+}>("@effect-agent/thread/WorkerPolicyResolver", {
+  defaultValue: () => ({
+    resolveSource: () => Effect.succeed(Option.none()),
+    resolveTarget: () => Effect.succeed(Option.none()),
+  }),
+});
+
+const Positive = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** A host-authorized ceiling on active background workers, not retained workers or Run usage. */
+export const WorkerConcurrencyLimit = Schema.Struct({
+  maxActiveWorkersPerSource: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type WorkerConcurrencyLimit = typeof WorkerConcurrencyLimit.Type;
+
+/**
+ * Optional source-aware operational authority. Resolution occurs inside every new source
+ * reservation attempt, against the same canonical history used for the append CAS. None
+ * preserves WorkerHostConfig; Some can only narrow it. The selected submission is exact,
+ * never the latest input. Implementations must authorize that immutable capture and retain
+ * construction dependencies in Layer R. Unavailable authority must return WorkerError(unavailable).
+ *
+ * One worker occupies a slot while any of its inputs remain unacknowledged. Steering an active
+ * worker does not acquire another slot. Decreases (including zero) do not cancel incumbents;
+ * an idle worker needs a slot again. Idempotent retained reservations do not reacquire slots.
+ */
+export const WorkerConcurrencyResolver = Context.Reference<{
+  readonly resolve: (request: {
+    readonly source: WorkerSource;
+    readonly sourceSubmission?: SubmissionSnapshot;
+    readonly worker: WorkerRef;
+    readonly principal: Principal;
+  }) => Effect.Effect<Option.Option<WorkerConcurrencyLimit>, WorkerError>;
+}>("@effect-agent/thread/WorkerConcurrencyResolver", {
+  defaultValue: () => ({ resolve: () => Effect.succeed(Option.none()) }),
+});
+
+/** Host ceilings apply across all declarations owned by one source Thread. */
+export const WorkerHostLimits = Schema.Struct({
+  maxWorkersPerSource: Positive.check(Schema.isLessThanOrEqualTo(100)),
+  /** Active background workers across declarations; omission retains source Tool concurrency. */
+  maxActiveWorkersPerSource: Schema.optionalKey(Positive.check(Schema.isLessThanOrEqualTo(100))),
+  maxInputsPerWorker: Positive.check(Schema.isLessThanOrEqualTo(1_000)),
+  maxPendingInputsPerWorker: Positive.check(Schema.isLessThanOrEqualTo(100)),
+  maxUpdateInputsPerWorker: Schema.optionalKey(Positive.check(Schema.isLessThanOrEqualTo(1_000))),
+  maxPendingUpdateInputsPerWorker: Schema.optionalKey(
+    Positive.check(Schema.isLessThanOrEqualTo(100)),
+  ),
+  lifetimeMillis: Positive.check(Schema.isLessThanOrEqualTo(604_800_000)),
+  /** Preparation may repeat after loss before its decision commits; keep callbacks side-effect free. */
+  reportPreparationTimeoutMillis: Schema.optionalKey(
+    Positive.check(Schema.isLessThanOrEqualTo(30_000)),
+  ),
+});
+
+export type WorkerHostLimits = typeof WorkerHostLimits.Type;
+
+export const WorkerHostConfig = Context.Reference<WorkerHostLimits>(
+  "@effect-agent/thread/WorkerHostConfig",
+  {
+    defaultValue: () => ({
+      maxWorkersPerSource: 32,
+      maxInputsPerWorker: 64,
+      maxPendingInputsPerWorker: 8,
+      lifetimeMillis: 86_400_000,
+    }),
+  },
+);
+
+/**
+ * Authenticate every acquisition/operation and authorize its exact source Thread. A returned
+ * Principal is host-owned admission identity. Context access authenticates source metadata;
+ * read, send and control remain separate grants. WorkerRefs and caller-supplied Thread
+ * identifiers alone never confer any of them.
+ */
+export interface WorkerHostAuthorizationRequest {
+  readonly sourceThreadId: ThreadId;
+  /** An explicitly selected owner input; authorize this locator as well as the Thread. */
+  readonly sourceSubmissionId?: SubmissionId;
+  readonly principal: Principal;
+  readonly operation: WorkerError["operation"];
+  readonly access: "context" | "read" | "send" | "control";
+  readonly worker?: WorkerRef;
+}
+
+export const WorkerHostAuthorizer = Context.Reference<{
+  readonly authorize: (
+    request: WorkerHostAuthorizationRequest,
+  ) => Effect.Effect<Principal, WorkerError>;
+}>("@effect-agent/thread/WorkerHostAuthorizer", {
+  defaultValue: () => ({
+    authorize: (request) =>
+      WorkerError.make({
+        operation: request.operation,
+        reason: "denied",
+      }),
+  }),
+});
+
+/**
+ * Deployment-owned permission to fund a root's background worker independently. The decision
+ * covers the exact immutable origin and is checked again before each input admission. It never
+ * changes delegation depth or Tool authority. Omission denies independent funding.
+ */
+export const WorkerBudgetAuthorizer = Context.Reference<{
+  readonly authorize: (request: {
+    readonly source: WorkerSource;
+    readonly principal: Principal;
+    readonly worker: WorkerRef;
+    readonly policy: AgentPolicy;
+    readonly budget: SubagentBudgetReservation;
+  }) => Effect.Effect<void, WorkerError>;
+}>("@effect-agent/thread/WorkerBudgetAuthorizer", {
+  defaultValue: () => ({
+    authorize: () => WorkerError.make({ operation: "start", reason: "denied" }),
+  }),
+});