effect-agent 0.1.0-beta.84 → 0.1.0-beta.86

package/src/engine/SubagentHost.ts

@@ -0,0 +1,181 @@
+import type { Effect, Option } from "effect";
+import { Context, Schema, Stream } from "effect";
+
+import type * as Agent from "../core/Agent.ts";
+import type { AgentPolicy } from "../core/AgentPolicy.ts";
+import type { DelegationId, RunId, SettlementId, ThreadId } from "../core/Identifiers.ts";
+import { type IdempotencyKey, type JoinedToHost, type Receipt } from "../core/Receipt.ts";
+import type { SubagentBudgetReservation } from "../core/SubagentContract.ts";
+import {
+  WorkerError,
+  type WorkerCompletion,
+  type WorkerHistoryEntry,
+  type WorkerContext,
+  type WorkerBudgetScope,
+  type WorkerSource,
+  type WorkerPage,
+  type WorkerRef,
+  type WorkerStarted,
+  type WorkerSummary,
+} from "../core/Worker.ts";
+
+/** Prepared values cross this port only to be Schema-decoded before durable storage. */
+export interface StartWorkerRequest {
+  readonly delegationId: DelegationId;
+  readonly target: Agent.AnyDefinition;
+  readonly idempotencyKey: IdempotencyKey;
+  readonly encodedInput: unknown;
+  readonly encodedParameters: unknown;
+  readonly policy: AgentPolicy;
+  readonly budget: SubagentBudgetReservation;
+  readonly encodedGrant: unknown;
+  readonly toolCallAllowance?: number;
+  /** Author-owned request; the durable host must separately authorize worker-run funding. */
+  readonly budgetScope?: WorkerBudgetScope;
+}
+
+export interface FollowUpWorkerRequest {
+  readonly worker: WorkerRef;
+  readonly target: Agent.AnyDefinition;
+  readonly idempotencyKey: IdempotencyKey;
+  readonly encodedInput: unknown;
+  readonly encodedParameters: unknown;
+}
+
+export interface WorkerReceiptRequest {
+  readonly worker: WorkerRef;
+  readonly target: Agent.AnyDefinition;
+  readonly receipt: Receipt;
+}
+
+/**
+ * Canonical terminal values remain encoded until the capability decodes the saved parameters
+ * and target output and applies its declared result projection. Child E does not survive settlement.
+ */
+export type WorkerObservation =
+  | { readonly _tag: "Pending"; readonly receipt: Receipt }
+  | {
+      readonly _tag: "Settled";
+      readonly receipt: Receipt;
+      /** Absent when an input failed or was cancelled before any Run started. */
+      readonly runId?: RunId;
+      readonly settlementId: SettlementId;
+      readonly outcome: "completed" | "failed" | "aborted";
+      readonly encodedParameters: unknown;
+      readonly encodedResult: unknown;
+      readonly budgetExhausted: boolean;
+    };
+
+/** One actual canonical Run, independent of how many input Receipts joined it. */
+export interface WorkerRunReport {
+  readonly worker: WorkerRef;
+  readonly context: WorkerContext;
+  readonly observation: Extract<WorkerObservation, { readonly _tag: "Settled" }> & {
+    readonly runId: RunId;
+  };
+}
+
+/** A bounded projection failure; raw application errors never enter durable report records. */
+export class WorkerReportPreparationFailure extends Schema.TaggedError<WorkerReportPreparationFailure>()(
+  "WorkerReportPreparationFailure",
+  { stage: Schema.Literals(["projection", "input", "preparation"]) },
+) {}
+
+/**
+ * Source-owned projection discovered from background tools or supplied by a custom registration.
+ * The concrete descriptor retains its E/R; durable registration captures R and records
+ * bounded preparation failure rather than serializing arbitrary application errors.
+ */
+export interface WorkerReporting<E = never, R = never> {
+  readonly delegationId: DelegationId;
+  readonly target: Agent.AnyDefinition;
+  /** Standard messages retain the parent's original application input. */
+  readonly mode?: "standard";
+  readonly input?: Schema.Top;
+  /** Required for custom mapping when the receiving coordinator is itself an established worker. */
+  readonly destination?: {
+    readonly delegationId: DelegationId;
+    readonly target: Agent.AnyDefinition;
+  };
+  readonly prepare: (report: WorkerRunReport) => Effect.Effect<
+    {
+      readonly encodedInput: Schema.Json;
+      readonly encodedParameters?: Schema.Json;
+      readonly message?: WorkerCompletion;
+    },
+    E | WorkerReportPreparationFailure,
+    R
+  >;
+}
+
+/** Descriptor carried by background tools; registration discovers it without an app handoff. */
+export const BackgroundReporting = Context.Reference<
+  WorkerReporting<WorkerReportPreparationFailure> | undefined
+>("@effect-agent/engine/BackgroundReporting", { defaultValue: () => undefined });
+
+/**
+ * Trusted, caller-bound host port. The interpreter supplies a fresh facet for each Tool Call;
+ * programmatic callers acquire a separately authorized Thread facet. Request values cannot
+ * choose the source identity, replace worker provenance or expand its authority and budgets.
+ */
+export class SubagentHost extends Context.Service<
+  SubagentHost,
+  {
+    readonly context: Effect.Effect<WorkerContext, WorkerError>;
+    /** Resolve prepared input through host authority; None retains legacy target inheritance. */
+    readonly resolveTargetPolicy: (request: {
+      readonly target: Agent.AnyDefinition;
+      readonly encodedInput: unknown;
+    }) => Effect.Effect<Option.Option<AgentPolicy>, WorkerError>;
+    readonly start: (request: StartWorkerRequest) => Effect.Effect<WorkerStarted, WorkerError>;
+    readonly followUp: (request: FollowUpWorkerRequest) => Effect.Effect<Receipt, WorkerError>;
+    readonly inspect: (
+      request: WorkerReceiptRequest,
+    ) => Effect.Effect<WorkerObservation, WorkerError>;
+    /** Inspect the continuing worker using the same summary contract as discovery. */
+    readonly summary: (request: {
+      readonly worker: WorkerRef;
+      readonly target: Agent.AnyDefinition;
+    }) => Effect.Effect<WorkerSummary, WorkerError>;
+    /** A finite snapshot through the captured tail; resume with the last sequence as `after`. */
+    readonly observe: (request: {
+      readonly worker: WorkerRef;
+      readonly target: Agent.AnyDefinition;
+      readonly after?: number;
+    }) => Stream.Stream<WorkerHistoryEntry, WorkerError>;
+    /** Interrupting this wait never requests cancellation of accepted work. */
+    readonly await: (
+      request: WorkerReceiptRequest,
+    ) => Effect.Effect<WorkerObservation, WorkerError>;
+    readonly list: (request: {
+      readonly delegationId: DelegationId;
+      readonly target: Agent.AnyDefinition;
+      readonly limit: number;
+      readonly after?: ThreadId;
+    }) => Effect.Effect<WorkerPage, WorkerError>;
+    /** Cancel exactly this Receipt; preserve JoinedToHost without broadening its target. */
+    readonly cancel: (
+      request: WorkerReceiptRequest,
+    ) => Effect.Effect<void, WorkerError | JoinedToHost>;
+  }
+>()("@effect-agent/engine/SubagentHost") {
+  static readonly unavailable: SubagentHost["Service"] = {
+    context: WorkerError.make({ operation: "context", reason: "unavailable" }),
+    resolveTargetPolicy: () => WorkerError.make({ operation: "start", reason: "unavailable" }),
+    start: () => WorkerError.make({ operation: "start", reason: "unavailable" }),
+    followUp: () => WorkerError.make({ operation: "followUp", reason: "unavailable" }),
+    inspect: () => WorkerError.make({ operation: "inspect", reason: "unavailable" }),
+    summary: () => WorkerError.make({ operation: "inspect", reason: "unavailable" }),
+    observe: () => Stream.fail(WorkerError.make({ operation: "observe", reason: "unavailable" })),
+    await: () => WorkerError.make({ operation: "await", reason: "unavailable" }),
+    list: () => WorkerError.make({ operation: "list", reason: "unavailable" }),
+    cancel: () => WorkerError.make({ operation: "cancel", reason: "unavailable" }),
+  };
+
+  /** Runtime-owned per-call binding. Unconfigured Runs deny background operations. */
+  static readonly forTool = Context.Reference<
+    (source: Extract<WorkerSource, { readonly _tag: "tool" }>) => SubagentHost["Service"]
+  >("@effect-agent/engine/SubagentHost/forTool", {
+    defaultValue: () => () => SubagentHost.unavailable,
+  });
+}

package/src/engine/ThreadHistory.ts

@@ -0,0 +1,120 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import type { Prompt } from "effect/unstable/ai";
+
+import { ThreadId, type RunId } from "../core/Identifiers.ts";
+import { type RunCompleted } from "../core/RunEvent.ts";
+import {
+  Store as ConversationStore,
+  layerMemory,
+  toPrompt,
+  type ThreadError,
+} from "../core/Thread.ts";
+
+/** A history adapter rejected a read, staged value, or completed Run commit. */
+export class ThreadHistoryError extends Schema.TaggedError<ThreadHistoryError>()(
+  "ThreadHistoryError",
+  {
+    threadId: ThreadId,
+    reason: Schema.Literals([
+      "not-found",
+      "conflict",
+      "fenced",
+      "incompatible",
+      "limit",
+      "encoding",
+      "storage",
+    ]),
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {}
+
+/**
+ * One Run's history owner. Incremental adapters retain each stageHistory update; on-success
+ * adapters stage privately until commit. Before commit, the interpreter
+ * finishes run-owned work and closes resources acquired for that Run, then validates the result
+ * for run/start.await. Shared model, provider, and client services supplied by an enclosing
+ * application Layer remain owned by that application's Scope and may outlive multiple Runs.
+ * Commit must succeed before RunCompleted becomes observable. Schema-encoded input is opaque
+ * here; the adapter owns its persistence boundary. A failed commit may have reached storage;
+ * callers must inspect history before retrying external execution.
+ */
+export interface ThreadHistoryRun {
+  readonly prompt: Prompt.Prompt;
+  readonly stageInput: (input: unknown) => Effect.Effect<void, ThreadHistoryError>;
+  readonly stageHistory: (history: Prompt.Prompt) => Effect.Effect<void, ThreadHistoryError>;
+  readonly commit: (completed: RunCompleted) => Effect.Effect<void, ThreadHistoryError>;
+}
+
+/**
+ * History shared by Runs with the same Thread ID. The default layer retains native messages
+ * incrementally in memory for its application Scope, including completed updates before a failure.
+ * PersistentHistory.layer from effect-agent/persistent-history instead commits successful
+ * Runs to an explicit ThreadStore. Durable hosts retain history through their journal hooks.
+ * No implementation may retry model or Tool execution or claim interrupted-work recovery.
+ */
+export class ThreadHistory extends Context.Service<
+  ThreadHistory,
+  {
+    readonly retention: "incremental" | "on-success";
+    readonly open: (request: {
+      readonly threadId: ThreadId;
+      readonly runId: RunId;
+    }) => Effect.Effect<ThreadHistoryRun, ThreadHistoryError>;
+    readonly load: (threadId: ThreadId) => Effect.Effect<Prompt.Prompt, ThreadHistoryError>;
+  }
+>()("@effect-agent/engine/ThreadHistory") {
+  /**
+   * Retain bounded in-memory history across Runs. Provide once around the application so
+   * all Runs share the same store. The underlying Thread.Store service is exposed for
+   * snapshots and interactive hooks; separate Layer builds own separate stores.
+   */
+  static readonly layer = Layer.effect(
+    ThreadHistory,
+    Effect.gen(function* () {
+      const threads = yield* ConversationStore;
+
+      const historyError = (cause: ThreadError): ThreadHistoryError =>
+        ThreadHistoryError.make({
+          threadId: cause.threadId,
+          reason:
+            cause._tag === "ThreadNotFound"
+              ? "not-found"
+              : cause._tag === "ThreadLimitExceeded"
+                ? "limit"
+                : cause._tag === "ThreadHistoryDiverged"
+                  ? "conflict"
+                  : "encoding",
+          message:
+            cause._tag === "ThreadNotFound"
+              ? "Thread history is not present in this application Scope"
+              : cause._tag === "ThreadLimitExceeded"
+                ? `In-memory history exceeds the ${cause.limit} limit of ${cause.limitValue}`
+                : cause.message,
+          cause,
+        });
+
+      return ThreadHistory.of({
+        retention: "incremental",
+        load: (threadId) =>
+          threads.snapshot(threadId).pipe(Effect.map(toPrompt), Effect.mapError(historyError)),
+        open: Effect.fn("ThreadHistory.open")(function* ({ threadId, runId }) {
+          const snapshot = yield* threads.create(threadId).pipe(Effect.mapError(historyError));
+
+          return {
+            prompt: toPrompt(snapshot),
+            stageInput: () => Effect.void,
+            stageHistory: (history: Prompt.Prompt) =>
+              threads
+                .recordHistory(threadId, runId, history)
+                .pipe(Effect.asVoid, Effect.mapError(historyError)),
+            commit: () => Effect.void,
+          };
+        }),
+      });
+    }),
+  ).pipe(Layer.provideMerge(layerMemory));
+}
+
+/** Retain in-memory conversation history for the application Scope. */
+export const layer = ThreadHistory.layer;

package/src/engine/ToolBroker.ts

@@ -0,0 +1,157 @@
+import type { Effect } from "effect";
+import { Context, Schema } from "effect";
+import type { Tool, Toolkit } from "effect/unstable/ai";
+
+/**
+ * Programmatic Tool invocation seam for Code Mode (runtime spec §12.1,
+ * ADR-0017 decision 3). The interpreter provides `ToolBroker` locally in the
+ * same pattern as `AgentSpawner` and `DurableStep`: a fail-closed Run-level
+ * default shadowed by a live per-outer-Tool-Call service, excluded from
+ * `AgentRuntimeRequirements`. The live service is bound to the outer Tool
+ * Call's identity, the Run's policy context, and the already-held scheduling
+ * permit; per-call input from generated code is data only, and the broker
+ * allocates every sequence index from its own monotonic per-pass state.
+ */
+
+/** One programmatic invocation request. Data only: the broker owns identity. */
+export interface ProgrammaticToolInput {
+  /** The exact Effect AI Tool name resolved by the capability's namespace map. */
+  readonly toolName: string;
+  /** Schema-encoded (wire-form) parameters, exactly as they cross the sandbox. */
+  readonly encodedArguments: unknown;
+}
+
+/** The handler ran and settled with an owned JSON snapshot of its encoded success value. */
+export interface ProgrammaticCallSuccess {
+  readonly _tag: "ProgrammaticCallSuccess";
+  /** Broker-owned invocation index within the pass; rejected calls leave gaps. */
+  readonly index: number;
+  readonly encodedResult: unknown;
+}
+
+/**
+ * The handler settled with the Tool's declared, Schema-encoded typed failure
+ * (an Effect AI `failureMode: "return"` result). The program may catch and
+ * branch on it.
+ */
+export interface ProgrammaticCallFailure {
+  readonly _tag: "ProgrammaticCallFailure";
+  readonly index: number;
+  readonly encodedResult: unknown;
+}
+
+/**
+ * The call never produced a settled handler result: a broker preflight
+ * rejected it (authorization, budget, unknown Tool, approval-requiring Tool,
+ * invalid parameters), the handler failed in its typed error channel, or the
+ * result failed encoding or the broker-owned size bound. `errorTag` and
+ * `message` are the same bounded projection the direct path uses for
+ * `ToolCallFailed` events; `index` is present only when the handler was
+ * actually started (preflight rejections consume no identity and no budget).
+ */
+export interface ProgrammaticCallError {
+  readonly _tag: "ProgrammaticCallError";
+  readonly index: number | undefined;
+  readonly errorTag: string;
+  readonly message: string;
+}
+
+/**
+ * Total outcome of one programmatic invocation; defects stay defects. Trusted applications may
+ * install `CurrentToolFailureObserver` to receive non-propagating failures before the outcome
+ * returns, with the live Cause retained before projection. Neither Causes nor observation values
+ * cross the broker boundary.
+ */
+export type ProgrammaticCallOutcome =
+  | ProgrammaticCallSuccess
+  | ProgrammaticCallFailure
+  | ProgrammaticCallError;
+
+/**
+ * Ephemeral execution evidence, ordered by invocation rather than completion. No arguments or
+ * results are copied into this diagnostic. A started call without a confirmed result is uncertain;
+ * a failed call is a confirmed failure, not a promise that external effects were rolled back.
+ */
+export const ProgrammaticCallRecord = Schema.Struct({
+  sequenceIndex: Schema.Natural,
+  toolName: Schema.String,
+  status: Schema.Literals(["not-started", "succeeded", "failed", "uncertain"]),
+  errorTag: Schema.optionalKey(Schema.String),
+});
+
+export type ProgrammaticCallRecord = typeof ProgrammaticCallRecord.Type;
+
+/** Broker-owned per-pass policy for results crossing back into the sandbox. */
+export interface ToolBrokerPassOptions {
+  /** Maximum active invocations in this pass, from one through 64. Defaults to four. */
+  readonly concurrency?: number | undefined;
+  /**
+   * Maximum UTF-8 byte size of one encoded success result at the sandbox
+   * boundary. The returned value is decoded from the exact JSON representation
+   * admitted by this bound, after redaction. Later handler or redactor mutations
+   * cannot change it. The executor enforces its own transport bound independently.
+   */
+  readonly maxResultBytes: number;
+  /**
+   * Optional broker-owned redaction pass applied to every encoded success
+   * result before the size bound. It must be total; a defect stays a defect.
+   */
+  readonly redactResult?: ((encodedResult: unknown) => Effect.Effect<unknown>) | undefined;
+}
+
+/**
+ * One open programmatic pass, bound to one outer Tool Call. A finite Effect Semaphore bounds
+ * execution. The caller owns invocation fibers and must join or interrupt them before leaving
+ * its Scope. Results return as soon as they settle, without waiting for unrelated earlier calls.
+ */
+export interface ToolBrokerPass {
+  readonly invoke: (input: ProgrammaticToolInput) => Effect.Effect<ProgrammaticCallOutcome>;
+  /** Owned snapshot in invocation order, including interrupted and rejected calls. Never replay it. */
+  readonly snapshot: Effect.Effect<ReadonlyArray<ProgrammaticCallRecord>>;
+}
+
+/** The broker was used outside a live Tool batch; there is nothing to bind to. */
+export class ToolBrokerUnavailableError extends Schema.TaggedError<ToolBrokerUnavailableError>()(
+  "ToolBrokerUnavailableError",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * The pass options are invalid — for example a `maxResultBytes` that is not
+ * a positive safe integer, which would make the size comparison fail open.
+ */
+export class ToolBrokerConfigurationError extends Schema.TaggedError<ToolBrokerConfigurationError>()(
+  "ToolBrokerConfigurationError",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * The engine-owned broker service. `openPass` fixes the capability-supplied
+ * Toolkit and per-pass result policy once for the whole pass and captures the
+ * handler services present at the call site, so nothing inside business
+ * execution — least of all generated code — can substitute handlers, policy,
+ * or identity afterwards.
+ */
+export interface ToolBrokerService {
+  readonly openPass: <Tools extends Record<string, Tool.Any>>(
+    toolkit: Toolkit.WithHandler<Tools>,
+    options: ToolBrokerPassOptions,
+  ) => Effect.Effect<
+    ToolBrokerPass,
+    ToolBrokerUnavailableError | ToolBrokerConfigurationError,
+    Tool.HandlerServices<Tools[keyof Tools]>
+  >;
+}
+
+/**
+ * Engine-provided programmatic Tool broker (RUN-016, RUN-017). Declare it
+ * with `.addDependency(ToolBroker)` on a Tool that performs programmatic
+ * invocation; the interpreter supplies it, and an application Layer must not.
+ */
+export class ToolBroker extends Context.Service<ToolBroker, ToolBrokerService>()(
+  "@effect-agent/engine/ToolBroker",
+) {}

package/src/engine/ToolExposure.ts

@@ -0,0 +1,48 @@
+import { Context, type Effect } from "effect";
+import type { Tool } from "effect/unstable/ai";
+
+import type { RunId, ThreadId } from "../core/Identifiers.ts";
+
+export type CatalogEntry =
+  | {
+      readonly kind: "native";
+      readonly tool: Tool.Any;
+      readonly namespace?: string | undefined;
+      readonly nativeToolName: string;
+    }
+  | {
+      readonly kind: "code-mode";
+      readonly tool: Tool.Any;
+      readonly namespace: string;
+      readonly method: string;
+      readonly nativeToolName: string;
+    };
+
+/** Engine-owned per-Turn snapshot. All candidates passed host visibility and inherited grants. */
+export class CurrentToolCatalog extends Context.Service<
+  CurrentToolCatalog,
+  {
+    readonly entries: ReadonlyArray<CatalogEntry>;
+  }
+>()("@effect-agent/engine/ToolExposure/CurrentToolCatalog") {}
+
+/** Host visibility is checked before a discovery Handler may inspect candidate documentation. */
+export interface VisibilityRequest {
+  readonly threadId: ThreadId;
+  readonly runId: RunId;
+  readonly turn: number;
+  readonly input: unknown;
+  /** Includes registered native names and explicitly advertised programmatic names. */
+  readonly toolNames: ReadonlyArray<string>;
+}
+
+/** Resolve host dependencies when constructing the policy Layer. */
+export interface VisibilityHook {
+  readonly visible: (request: VisibilityRequest) => Effect.Effect<ReadonlyArray<string>>;
+}
+
+/** Optional host policy captured by durable runtimes; action authorization remains independent. */
+export const RunToolVisibility = Context.Reference<VisibilityHook | undefined>(
+  "@effect-agent/engine/ToolExposure/RunToolVisibility",
+  { defaultValue: () => undefined },
+);