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

package/src/durable/internal/worker-runtime.ts

@@ -0,0 +1,9 @@
+import { Context, type Effect } from "effect";
+
+import type { makeWorkerRuntime } from "./worker-host.ts";
+
+/** Canonical worker operations constructed once by the durable coordinator. */
+export class WorkerRuntime extends Context.Service<
+  WorkerRuntime,
+  Effect.Success<ReturnType<typeof makeWorkerRuntime>>
+>()("@effect-agent/thread/internal/WorkerRuntime") {}

package/src/engine/AgentRuntime.ts

@@ -0,0 +1,37 @@
+/** Public AgentRuntime API. Implementation helpers remain private. */
+export {
+  decodeFinalOutput,
+  encodeRunDisposition,
+  projectCompletionOutput,
+  projectCompletionFromToolOutput,
+  run,
+  runUnknown,
+  start,
+  startUnknown,
+  stream,
+  streamUnknown,
+  streamWithUsageAccountingUnknown,
+  AgentResultSchema,
+  AgentChildPending,
+  AgentSpawner,
+  SubagentDurability,
+  SubagentDurabilityError,
+  ToolCallWaiting,
+  renderInputPrompt,
+  withTerminalDefectEvent,
+  type AgentResult,
+  type AgentRuntimeFailure,
+  type AgentRuntimeRequirements,
+  type AgentCompletionProjectionRequirements,
+  type AgentSpawnerParent,
+  type AgentSpawnerService,
+  type DetachedRun,
+  type EngineProvidedToolServices,
+  type RuntimeBinding,
+  type SpawnDelegation,
+  type SpawnedChildRun,
+  type SpawnRunOptions,
+  type SubagentDurabilityDurable,
+  type SubagentDurabilityEphemeral,
+  type SubagentDurabilityService,
+} from "./internal/agent-runtime.ts";

package/src/engine/Compaction.ts

@@ -0,0 +1,11 @@
+/** Public Compaction API. Implementation helpers remain private. */
+export {
+  CLEARED_TOOL_RESULT,
+  COMPACTION_SUMMARY_PREFIX,
+  CONTEXT_ROLLOVER_PREFIX,
+  contextWindowId,
+  contextWindowMessage,
+  estimateMessageTokens,
+  estimatePromptTokens,
+  type ContextCompactionState,
+} from "./internal/compaction.ts";

package/src/engine/ContextCompactor.ts

@@ -0,0 +1,277 @@
+import { Context, Effect, Layer, Option, Schema, Stream } from "effect";
+import { type LanguageModel, type Model, Prompt } from "effect/unstable/ai";
+
+import { type CompactionPolicy } from "../core/AgentPolicy.ts";
+import { type RunId, type ThreadId } from "../core/Identifiers.ts";
+import { ContextHandoff, type ContextRolloverRequest } from "./ContextWindow.ts";
+import {
+  buildCompactedView,
+  buildRolloverHandoff,
+  choosePruneBound,
+  chooseSummarizeCut,
+  collectCoveredMessages,
+  estimatePromptTokens,
+  evaluateMessageTokenEstimates,
+  renderForSummary,
+  SUMMARY_MAX_LENGTH,
+  SUMMARY_REQUEST_PREFIX,
+  SUMMARY_REQUEST_SUFFIX,
+  type ContextCompactionState,
+} from "./internal/compaction.ts";
+
+/**
+ * A proposed view change. Source indices are exclusive prefix bounds, never record sequences.
+ * Summaries contain at most 65,536 characters; the interpreter rejects oversized decisions
+ * before committing or changing coverage.
+ */
+export const CompactionDecision = Schema.Union([
+  Schema.Struct({
+    kind: Schema.Literal("rollover"),
+    through: Schema.Natural,
+    handoff: Schema.optionalKey(ContextHandoff),
+  }),
+  Schema.Struct({ kind: Schema.Literal("clear-tool-results"), through: Schema.Natural }),
+  Schema.Struct({
+    kind: Schema.Literal("summarize"),
+    through: Schema.Natural,
+    summary: Schema.NonEmptyString.check(
+      Schema.isMaxLength(SUMMARY_MAX_LENGTH),
+      Schema.isPattern(/\S/),
+    ),
+  }),
+]);
+
+export type CompactionDecision = typeof CompactionDecision.Type;
+
+/** Expected strategy or decision-validation failure. Causes stay in the live Effect only. */
+export class CompactionError extends Schema.TaggedError<CompactionError>()("CompactionError", {
+  message: Schema.String.check(Schema.isMaxLength(4_096)),
+  cause: Schema.optionalKey(Schema.Defect()),
+}) {}
+
+/** Upstream Model.captureRequirements returns this closed Layer. */
+export type CompactionModelLayer = Layer.Layer<
+  LanguageModel.LanguageModel | Model.ProviderName | Model.ModelName
+>;
+
+/** A full message estimate, or undefined to use the native structural estimate. */
+export type ContextMessageTokenEstimator = (message: Prompt.Message) => number | undefined;
+
+/**
+ * One bounded pass over an immutable source snapshot. A harness owns state, metering, and
+ * application of decisions. The interpreter permits at most one prune followed by one replacement
+ * (summary or rollover), and one call to summarize per Turn, shared across every trigger.
+ * All model work must use summarize so it is metered.
+ * Callback failures and requirements pass through unchanged; strategy dependencies belong to
+ * its construction Layer. Protected messages cannot be removed and Tool pairs cannot be split by a decision.
+ */
+export interface CompactionRequest<E, R> {
+  readonly threadId: ThreadId;
+  readonly runId: RunId;
+  readonly turn: number;
+  readonly source: Prompt.Prompt;
+  readonly state: Readonly<ContextCompactionState>;
+  readonly policy: CompactionPolicy;
+  readonly targetTokens: number | undefined;
+  readonly trigger: "pressure" | "overflow" | "requested";
+  /** Budget admission may prohibit a separate model call while still allowing a rollover. */
+  readonly modelCallAllowed: boolean;
+  /** The current captured Model's message accounting, including native fallback. */
+  readonly estimateMessageTokens?: ContextMessageTokenEstimator | undefined;
+  /** Present for a successful, singleton context rollover Tool; through excludes later steering. */
+  readonly requested?: (ContextRolloverRequest & { readonly through: number }) | undefined;
+  readonly summarize: (
+    prompt: Prompt.Prompt,
+    model?: CompactionModelLayer,
+  ) => Effect.Effect<string, E, R>;
+}
+
+export interface ContextCompaction {
+  /** Non-negative finite integer estimate, used for admission and derived prompt overhead too. */
+  readonly estimate: (messages: ReadonlyArray<Prompt.Message>) => number;
+  /** Emit decisions sequentially; the consumer commits each before pulling the next. */
+  readonly compact: <E, R>(
+    request: CompactionRequest<E, R>,
+  ) => Stream.Stream<CompactionDecision, E | CompactionError, R>;
+}
+
+const evaluateEstimates = <A>(
+  override: ContextMessageTokenEstimator | undefined,
+  operation: (estimate: (message: Prompt.Message) => number) => A,
+): Effect.Effect<A, CompactionError> =>
+  Effect.suspend(() => {
+    const result = evaluateMessageTokenEstimates(override, operation);
+
+    return Option.isSome(result)
+      ? Effect.succeed(result.value)
+      : CompactionError.make({
+          message: "Message token estimator returned an invalid token count",
+        });
+  });
+
+const defaultCompactor = (model?: CompactionModelLayer): ContextCompaction => ({
+  estimate: estimatePromptTokens,
+  compact: <E, R>(request: CompactionRequest<E, R>) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const { source, policy, targetTokens, trigger, modelCallAllowed } = request;
+
+        if (request.requested !== undefined) {
+          return Stream.succeed({ kind: "rollover", ...request.requested });
+        }
+        const forceSummarize = trigger === "overflow";
+        const state = { ...request.state };
+
+        const keepRecentTokens =
+          targetTokens === undefined
+            ? policy.keepRecentTokens
+            : Math.max(1, Math.min(policy.keepRecentTokens, targetTokens));
+
+        const decisions: Array<CompactionDecision> = [];
+
+        if (!forceSummarize && policy.mode !== "summarize") {
+          const through = yield* evaluateEstimates(request.estimateMessageTokens, (estimate) =>
+            choosePruneBound(source.content, state, keepRecentTokens, targetTokens, estimate),
+          );
+
+          if (through > state.clearedThrough) {
+            state.clearedThrough = through;
+            decisions.push({ kind: "clear-tool-results", through });
+            if (
+              targetTokens !== undefined &&
+              (yield* evaluateEstimates(request.estimateMessageTokens, (estimate) =>
+                estimatePromptTokens(buildCompactedView(source.content, state), estimate),
+              )) <= targetTokens
+            ) {
+              return Stream.fromIterable(decisions);
+            }
+          }
+        }
+        const prune = Stream.fromIterable(decisions);
+
+        if ((!modelCallAllowed || policy.mode === "prune") && !forceSummarize) return prune;
+
+        return prune.pipe(
+          Stream.concat(
+            Stream.unwrap(
+              Effect.gen(function* () {
+                const through = yield* evaluateEstimates(
+                  request.estimateMessageTokens,
+                  (estimate) =>
+                    chooseSummarizeCut(source.content, state, keepRecentTokens, estimate),
+                );
+
+                const covered = collectCoveredMessages(source.content, state, through);
+
+                if (covered.length === 0) return Stream.empty;
+
+                const transcript = renderForSummary(
+                  covered,
+                  state.replacement?.kind === "summarize"
+                    ? state.replacement.summary
+                    : state.replacement?.handoff,
+                );
+
+                if (transcript === undefined) {
+                  return yield* CompactionError.make({
+                    message: `Previous compaction summary exceeds ${SUMMARY_MAX_LENGTH} characters`,
+                  });
+                }
+
+                const prompt = Prompt.fromMessages([
+                  Prompt.userMessage({
+                    content: [
+                      Prompt.textPart({
+                        text: `${SUMMARY_REQUEST_PREFIX}${transcript}${SUMMARY_REQUEST_SUFFIX}`,
+                      }),
+                    ],
+                  }),
+                ]);
+
+                const text = yield* request.summarize(prompt, model);
+
+                return Stream.succeed({
+                  kind: "summarize",
+                  through,
+                  summary: text.trim(),
+                } satisfies CompactionDecision);
+              }),
+            ),
+          ),
+        );
+      }),
+    ),
+});
+
+/**
+ * The sole interpreter compaction port. Runs without an installed service provide layer at their
+ * composition boundary. Decorators yield this service during construction and receive their
+ * underlying implementation through Layer.provide. Direct harnesses use the same Layer contract.
+ */
+export class ContextCompactor extends Context.Service<ContextCompactor, ContextCompaction>()(
+  "@effect-agent/engine/ContextCompactor",
+) {
+  static readonly layer = Layer.succeed(ContextCompactor, defaultCompactor());
+
+  /**
+   * Start fresh windows without a summarizer call. The engine retains instructions/input and
+   * commits each boundary; a bounded emergency handoff preserves user inputs and unseen results.
+   * Applications provide notes/history tools alongside this strategy.
+   */
+  static readonly layerRollover = Layer.succeed(ContextCompactor, {
+    estimate: estimatePromptTokens,
+    compact: <E, R>(request: CompactionRequest<E, R>) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          if (request.requested !== undefined) {
+            return Stream.succeed({
+              kind: "rollover",
+              ...request.requested,
+            } satisfies CompactionDecision);
+          }
+
+          // Trailing user steering may not be canonical until the next response. Keep it verbatim.
+          const through =
+            request.source.content.findLastIndex(
+              (message) => message.role === "assistant" || message.role === "tool",
+            ) + 1;
+
+          if (collectCoveredMessages(request.source.content, request.state, through).length === 0) {
+            return Stream.empty;
+          }
+
+          const handoff = yield* evaluateEstimates(request.estimateMessageTokens, (estimate) =>
+            buildRolloverHandoff(
+              request.source.content,
+              request.state,
+              request.targetTokens,
+              through,
+              estimate,
+            ),
+          );
+
+          if (handoff === undefined)
+            return Stream.fail(
+              CompactionError.make({
+                message: "Insufficient context capacity for an automatic rollover handoff",
+              }),
+            );
+
+          return Stream.succeed({
+            kind: "rollover",
+            through,
+            handoff,
+          } satisfies CompactionDecision);
+        }),
+      ),
+  });
+
+  /** Use the bounded default algorithm with a separate upstream Effect AI Model. */
+  static readonly layerWithModel = <Provider, Requirements>(
+    model: Model.Model<Provider, LanguageModel.LanguageModel, Requirements>,
+  ): Layer.Layer<ContextCompactor, never, Requirements> =>
+    Layer.effect(
+      ContextCompactor,
+      Effect.map(model.captureRequirements, (captured) => defaultCompactor(captured)),
+    );
+}

package/src/engine/ContextHistory.ts

@@ -0,0 +1,73 @@
+import { Context, type Effect, Schema } from "effect";
+
+import { ThreadId } from "../core/Identifiers.ts";
+
+/** Canonical transcript lookup failure. Access to a Thread remains a host authorization decision. */
+export class ContextHistoryError extends Schema.TaggedError<ContextHistoryError>()(
+  "ContextHistoryError",
+  {
+    reason: Schema.Literals(["unavailable", "not-found", "invalid-input", "limit"]),
+    message: Schema.String.check(Schema.isMaxLength(4_096)),
+  },
+) {}
+
+export class ContextHistoryHit extends Schema.Class<ContextHistoryHit>("ContextHistoryHit")({
+  recordId: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  windowId: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  text: Schema.String.check(Schema.isMaxLength(2_000)),
+}) {}
+
+/**
+ * Newest-first literal substring search, trimmed and JavaScript case-folded (not FTS or regex).
+ * `beforeRecordId` excludes that record and every newer canonical position. Use the last hit
+ * from the previous page with the same query; fewer than `limit` hits (including zero) ends
+ * pagination. A full final page requires one more request to observe the empty page.
+ *
+ * The anchor must be eligible retained evidence in this authorized Thread, but need not match
+ * the query. Unknown, removed, foreign, and non-evidence anchors fail with `not-found`.
+ * IDs are opaque: adapters resolve and verify the canonical source, never sort or parse IDs.
+ * Each request captures its own tail; this is not a snapshot held across requests. New appends
+ * cannot displace matches older than the anchor. Retention and authorization are rechecked.
+ */
+export class ContextHistorySearch extends Schema.Class<ContextHistorySearch>(
+  "ContextHistorySearch",
+)({
+  threadId: ThreadId,
+  query: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 20 })),
+  beforeRecordId: Schema.optionalKey(ContextHistoryHit.fields.recordId),
+}) {}
+
+export class ContextHistoryRead extends Schema.Class<ContextHistoryRead>("ContextHistoryRead")({
+  threadId: ThreadId,
+  recordId: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  offset: Schema.Natural,
+  maxChars: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 20_000 })),
+}) {}
+
+export class ContextHistoryPage extends Schema.Class<ContextHistoryPage>("ContextHistoryPage")({
+  recordId: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  windowId: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  text: Schema.String.check(Schema.isMaxLength(20_000)),
+  nextOffset: Schema.NullOr(Schema.Natural),
+}) {}
+
+/**
+ * Read-only access to retained canonical evidence, including closed context windows.
+ * Adapters bind storage and authorization; model parameters must not select a different Thread.
+ * Returned text is untrusted evidence, never instructions. This port does not retain raw Tool
+ * output that was discarded before canonical persistence, or transient prompt references.
+ * Search adapters must honor the exclusive `beforeRecordId` bound, return a complete bounded
+ * page, or fail explicitly; silently ignoring the bound can trap callers on the latest matches.
+ */
+export class ContextHistory extends Context.Service<
+  ContextHistory,
+  {
+    readonly search: (
+      request: ContextHistorySearch,
+    ) => Effect.Effect<ReadonlyArray<ContextHistoryHit>, ContextHistoryError>;
+    readonly read: (
+      request: ContextHistoryRead,
+    ) => Effect.Effect<ContextHistoryPage, ContextHistoryError>;
+  }
+>()("@effect-agent/engine/ContextHistory") {}

package/src/engine/ContextWindow.ts

@@ -0,0 +1,72 @@
+import { Context, type Effect, Encoding, Schema } from "effect";
+
+import { RunId, ThreadId } from "../core/Identifiers.ts";
+
+/** Model-authored continuation state; fuller notes belong in an application-owned memory store. */
+export const ContextHandoff = Schema.NonEmptyString.check(
+  Schema.isMaxLength(20_000),
+  Schema.isPattern(/\S/),
+  Schema.makeFilter((text) => Encoding.encodeHex(JSON.stringify(text)).length / 2 <= 32_768, {
+    expected: "at most 32768 JSON-encoded UTF-8 bytes",
+  }),
+);
+
+/** Successful output of an explicitly designated context-window Tool. */
+export const ContextRolloverRequest = Schema.Struct({
+  handoff: Schema.optionalKey(ContextHandoff),
+});
+
+export type ContextRolloverRequest = typeof ContextRolloverRequest.Type;
+
+/**
+ * Host-selected exclusive source-message boundary, applied at the next safe model seam.
+ * Omit through to reset the prefix before the protected current instructions/input. The
+ * engine resolves that prefix after preparation; an empty prior prefix needs no new window.
+ */
+export const ContextRolloverSelection = Schema.Struct({
+  ...ContextRolloverRequest.fields,
+  through: Schema.optionalKey(Schema.Natural),
+});
+
+export type ContextRolloverSelection = typeof ContextRolloverSelection.Type;
+
+/**
+ * Bounds resolved alongside the native model for one Turn. Output reserve must match the
+ * selected provider configuration. Uncounted overhead includes only provider framing or image
+ * token costs absent from the prompt estimate; prompt text, output contracts, and native Tool
+ * schemas are counted by the engine. These are live-context bounds, not cumulative Run budgets.
+ */
+export class ModelCallContext extends Schema.Class<ModelCallContext>("ModelCallContext")({
+  contextCapacity: Schema.Int.check(Schema.isGreaterThan(0)),
+  maxInputTokens: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0))),
+  outputReserveTokens: Schema.Natural,
+  uncountedOverheadTokens: Schema.Natural,
+}) {}
+
+/**
+ * Definition-owned control annotation. A successful singleton application Tool carrying this
+ * annotation returns ContextRolloverRequest. The engine applies it at the next Turn seam,
+ * including after durable Tool-result replay. A Tool name alone never grants this authority.
+ */
+export const ContextRolloverTool = Context.Reference<boolean>(
+  "@effect-agent/engine/ContextRolloverTool",
+  { defaultValue: () => false },
+);
+
+/** Best available live-context estimate, independent of cumulative Run budgets. */
+export class ContextWindowStatus extends Schema.Class<ContextWindowStatus>("ContextWindowStatus")({
+  threadId: ThreadId,
+  runId: RunId,
+  windowId: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  estimatedTokens: Schema.Natural,
+  contextTokenLimit: Schema.NullOr(Schema.Natural),
+  remainingTokens: Schema.NullOr(Schema.Natural),
+}) {}
+
+/** Engine-owned identity and context accounting for the current Run. */
+export class ContextWindow extends Context.Service<
+  ContextWindow,
+  {
+    readonly status: Effect.Effect<ContextWindowStatus>;
+  }
+>()("@effect-agent/engine/ContextWindow") {}

package/src/engine/DurableStep.ts

@@ -0,0 +1,132 @@
+import { Context, Schema } from "effect";
+import type { Effect, Option } from "effect";
+import type { Tool } from "effect/unstable/ai";
+
+import { ToolCallId } from "../core/Identifiers.ts";
+
+/**
+ * Declared external execution class of one Tool, used by the durable runtime
+ * to decide which Tool Calls need the prepared/settled uncertainty protocol:
+ *
+ * - `"readonly"`: the handler performs no external mutation. A crash between
+ *   start and settlement is a free re-run; no prepared record is written.
+ * - `"idempotent"`: the handler declares an external idempotency contract
+ *   (it owns key derivation). Prepared/settled records are written and
+ *   recovery may re-execute without reconciliation proof.
+ * - `"uncertain"`: no external contract is declared. Prepared/settled records
+ *   are written and recovery must reconcile or record an Unknown Outcome.
+ */
+export type ToolExecutionClassValue = "readonly" | "idempotent" | "uncertain";
+
+/**
+ * Effect AI Tool annotation key declaring a Tool's execution class, applied
+ * with `Tool.annotate(ToolExecutionClass, "...")`.
+ *
+ * Unannotated Tools default to `"uncertain"`: security and durability
+ * decisions are fail-closed, so the framework never infers a safer class
+ * from a Tool's shape.
+ */
+export const ToolExecutionClass = Context.Reference<ToolExecutionClassValue>(
+  "@effect-agent/engine/ToolExecutionClass",
+  { defaultValue: () => "uncertain" },
+);
+
+/** Read a Tool's declared execution class, falling back to the fail-closed `"uncertain"` default. */
+export const getToolExecutionClass = (tool: Tool.Any): ToolExecutionClassValue =>
+  Context.get(tool.annotations, ToolExecutionClass);
+
+/** Stable identity of one Step within one Tool Call: `(toolCallId, stepName)`. */
+export interface RunStepKey {
+  readonly toolCallId: ToolCallId;
+  readonly stepName: string;
+}
+
+/** A previously committed Step result in its canonical encoded form. */
+export interface PersistedStepResult {
+  readonly encodedOutput: unknown;
+}
+
+/**
+ * Dependency-neutral Step persistence seam implemented by a durable
+ * coordinator and consumed by the engine-provided `DurableStep` service.
+ *
+ * `lookup` returns the committed result for a Step identity when one exists;
+ * `commit` durably records one successful encoded output. Only success is
+ * ever committed — recording failures would replay a transient failure
+ * forever. Both operations are keyed by the deterministic `RunStepKey`, so
+ * replays and racing writers dedupe on record identity in the adapter.
+ */
+export interface RunStepHook<Error = never, Requirements = never> {
+  readonly lookup: (
+    key: RunStepKey,
+  ) => Effect.Effect<Option.Option<PersistedStepResult>, Error, Requirements>;
+  readonly commit: (
+    key: RunStepKey,
+    encodedOutput: unknown,
+  ) => Effect.Effect<void, Error, Requirements>;
+}
+
+/**
+ * Typed failure of one `DurableStep.do` call.
+ *
+ * `duplicate-step-name` is an identity conflict: Step names must be
+ * deterministic and unique within one Tool Call, and reuse would silently
+ * replay another Step's recorded result. `recorded-result-invalid` is the
+ * replay-with-different-content conflict: a committed result that no longer
+ * decodes through the declared output Schema is never silently accepted.
+ */
+export class DurableStepError extends Schema.TaggedError<DurableStepError>()("DurableStepError", {
+  stepName: Schema.String,
+  reason: Schema.Literals([
+    "duplicate-step-name",
+    "lookup-failed",
+    "recorded-result-invalid",
+    "output-encoding-failed",
+    "commit-failed",
+    "no-active-tool-call",
+  ]),
+  message: Schema.String.check(Schema.isMaxLength(4_096)),
+  toolCallId: Schema.optionalKey(ToolCallId),
+  /** Diagnostic cause for the live Effect only; Run events retain the fixed public message. */
+  cause: Schema.optionalKey(Schema.Defect()),
+}) {}
+
+/**
+ * Service value provided locally by the engine to each Tool Call's handler.
+ *
+ * `do` runs one named Step with exactly-once-recorded, at-least-once-executed
+ * semantics: a committed result decodes through `output` and returns without
+ * executing the body; otherwise the body runs (a crash mid-body re-executes
+ * on the next Attempt), the success is encoded through `output`, and only
+ * then committed. The Schema argument is the canonical codec for the recorded
+ * result, not decoration. A Step never makes a non-idempotent external API
+ * exactly-once — the body must use the external system's idempotency key,
+ * reconciliation API, or compensating workflow.
+ */
+export interface DurableStepService {
+  readonly do: <Output extends Schema.Top, BodyError, BodyServices>(
+    name: string,
+    output: Output,
+    execute: Effect.Effect<Output["Type"], BodyError, BodyServices>,
+  ) => Effect.Effect<
+    Output["Type"],
+    DurableStepError | BodyError,
+    BodyServices | Output["DecodingServices"] | Output["EncodingServices"]
+  >;
+}
+
+/**
+ * Engine-owned Durable Step seam.
+ *
+ * Declaring this service in `Tool.make({ dependencies: [DurableStep] })` is
+ * what makes a Tool a Durable Tool: its handler divides external effects into
+ * named Steps and may be re-entered after interruption. The engine provides
+ * the service locally to every Tool Call, bound to that call's identity; it
+ * is never satisfied from an application Layer and is excluded from the
+ * runtime's public requirements. Without a durable runtime the engine
+ * provides an ephemeral pass-through that executes each Step once and
+ * records nothing — the durable claim attaches to the runtime, not the Tool.
+ */
+export class DurableStep extends Context.Service<DurableStep, DurableStepService>()(
+  "@effect-agent/engine/DurableStep",
+) {}