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

package/src/core/AgentError.ts

@@ -0,0 +1,152 @@
+import { Schema } from "effect";
+
+import { ToolCallId } from "./Identifiers.ts";
+
+/** Run input failed to decode through the agent definition's input Schema. */
+export class AgentInputError extends Schema.TaggedError<AgentInputError>()("AgentInputError", {
+  message: Schema.String,
+}) {}
+
+/** Final model output failed to decode through the agent definition's output Schema. */
+export class AgentOutputError extends Schema.TaggedError<AgentOutputError>()("AgentOutputError", {
+  message: Schema.String,
+}) {}
+
+/** An application-selected run disposition failed its definition-owned Schema boundary. */
+export class AgentRunDispositionError extends Schema.TaggedError<AgentRunDispositionError>()(
+  "AgentRunDispositionError",
+  {
+    cause: Schema.Defect(),
+    message: Schema.String,
+  },
+) {}
+
+/** The finite policy dimension a run exhausted; shared with durable settlement metadata. */
+export const PolicyLimit = Schema.Literals([
+  "turns",
+  "tool-calls",
+  "duration",
+  "usage",
+  "tokens",
+  "cost",
+  "repeated-failures",
+]);
+
+export type PolicyLimit = typeof PolicyLimit.Type;
+
+/** A run exhausted one of its finite policy limits. */
+export class AgentPolicyError extends Schema.TaggedError<AgentPolicyError>()("AgentPolicyError", {
+  limit: PolicyLimit,
+  message: Schema.String,
+}) {}
+
+/** A native Effect AI Tool approval was explicitly denied before its Handler started. */
+export class AgentApprovalDenied extends Schema.TaggedError<AgentApprovalDenied>()(
+  "AgentApprovalDenied",
+  {
+    toolCallId: ToolCallId,
+    toolName: Schema.NonEmptyString,
+    message: Schema.String,
+  },
+) {
+  /** Decode the native Effect AI Tool Call ID at the core error boundary. */
+  static override make(input: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly message: string;
+  }): AgentApprovalDenied {
+    return super.make({
+      ...input,
+      toolCallId: Schema.decodeSync(ToolCallId)(input.toolCallId),
+    });
+  }
+}
+
+/** A host denied current execution authority for a Tool Call before its Handler started. */
+export class AgentToolAuthorizationDenied extends Schema.TaggedError<AgentToolAuthorizationDenied>()(
+  "AgentToolAuthorizationDenied",
+  {
+    toolCallId: ToolCallId,
+    toolName: Schema.NonEmptyString,
+    message: Schema.String,
+  },
+) {}
+
+/** A native Effect AI Tool approval has no decision and the ephemeral Run cannot proceed. */
+export class AgentApprovalPending extends Schema.TaggedError<AgentApprovalPending>()(
+  "AgentApprovalPending",
+  {
+    approvalId: Schema.NonEmptyString,
+    toolCallId: ToolCallId,
+    toolName: Schema.NonEmptyString,
+    message: Schema.String,
+  },
+) {
+  /** Decode the native Effect AI Tool Call ID at the core error boundary. */
+  static override make(input: {
+    readonly approvalId: string;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly message: string;
+  }): AgentApprovalPending {
+    return super.make({
+      ...input,
+      toolCallId: Schema.decodeSync(ToolCallId)(input.toolCallId),
+    });
+  }
+}
+
+/** A model response sequence violated an agent-loop protocol invariant. */
+export class ModelProtocolError extends Schema.TaggedError<ModelProtocolError>()(
+  "ModelProtocolError",
+  {
+    message: Schema.String,
+  },
+) {}
+
+/** A run was interrupted without manufacturing a successful result. */
+export class AgentInterrupted extends Schema.TaggedError<AgentInterrupted>()("AgentInterrupted", {
+  message: Schema.String,
+}) {}
+
+/**
+ * The provider rejected a prompt that exceeds the model context window and
+ * compaction recovery is unavailable or was already attempted once. This is
+ * an expected failure: the engine classifies the provider error rather than
+ * surfacing an opaque transport failure.
+ */
+export class ContextOverflowError extends Schema.TaggedError<ContextOverflowError>()(
+  "ContextOverflowError",
+  {
+    message: Schema.String,
+    retried: Schema.Boolean,
+  },
+) {}
+
+/** Local context preparation could not fit a legal prompt inside its target before provider I/O. */
+export class ContextBudgetError extends Schema.TaggedError<ContextBudgetError>()(
+  "ContextBudgetError",
+  {
+    message: Schema.String,
+    estimatedTokens: Schema.Natural,
+    targetTokens: Schema.Natural,
+    completionReserveTokens: Schema.Natural,
+  },
+) {}
+
+/** Schema for framework-owned agent errors; application and Effect AI failures remain separate. */
+export const AgentError = Schema.Union([
+  AgentInputError,
+  AgentOutputError,
+  AgentRunDispositionError,
+  AgentPolicyError,
+  AgentApprovalDenied,
+  AgentToolAuthorizationDenied,
+  AgentApprovalPending,
+  ModelProtocolError,
+  AgentInterrupted,
+  ContextOverflowError,
+  ContextBudgetError,
+]);
+
+export type AgentError = typeof AgentError.Type;

package/src/core/AgentPolicy.ts

@@ -0,0 +1,153 @@
+import * as Duration from "effect/Duration";
+import * as Schema from "effect/Schema";
+
+import { ToolResultBounds } from "./ToolResult.ts";
+
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+
+const CompactionMode = Schema.Literals(["prune", "summarize", "prune-then-summarize"]);
+
+/** Inputs normalized and validated by `CompactionPolicy.make`. */
+export type CompactionPolicyInput = Readonly<{
+  /** Estimated tokens of recent history preserved verbatim across a compaction; defaults to `20_000`. */
+  readonly keepRecentTokens?: number;
+  /** Compaction strategy order; defaults to `"prune-then-summarize"`. */
+  readonly mode?: typeof CompactionMode.Type;
+}>;
+
+/** How the engine reduces model context when `contextTokenLimit` is crossed. */
+export class CompactionPolicy extends Schema.Class<CompactionPolicy>("CompactionPolicy")({
+  keepRecentTokens: PositiveInt,
+  mode: CompactionMode,
+}) {
+  /** Normalize and validate compaction bounds, filling documented defaults. */
+  static override make(input: CompactionPolicyInput = {}): CompactionPolicy {
+    return super.make({
+      keepRecentTokens: input.keepRecentTokens ?? 20_000,
+      mode: input.mode ?? "prune-then-summarize",
+    });
+  }
+}
+
+const FinitePositiveDuration = Schema.Duration.pipe(
+  Schema.refine(
+    (duration): duration is Duration.Duration =>
+      Duration.isFinite(duration) && Duration.isPositive(duration),
+    { expected: "a finite positive duration" },
+  ),
+);
+
+/**
+ * Resolution when `maxTurns`, `maxToolCalls`, or `tokenBudget` is exhausted:
+ * `"final-answer"` gives the model one constrained opportunity to settle with
+ * output (the Run completes with `finishReason: "budget-exhausted"` and the
+ * exhausted-dimension marker), while `"fail"` fails the Run typed. Turn and
+ * Tool Call bounds resolve per RUN-018/RUN-019; the token dimension
+ * participates per RUN-025 with a one-shot bound (at most one grace call).
+ * Duration, cost, and repeated-failure bounds are hard rails regardless of
+ * this setting.
+ */
+const OnExhaustion = Schema.Literals(["final-answer", "fail"]);
+
+const AgentPolicyFields = Schema.Struct({
+  maxTurns: PositiveInt,
+  maxToolCalls: PositiveInt,
+  maxDuration: FinitePositiveDuration,
+  toolConcurrency: PositiveInt,
+  repeatedFailureLimit: NonNegativeInt,
+  onExhaustion: OnExhaustion,
+  tokenBudget: Schema.optionalKey(PositiveInt),
+  /** Tokens withheld from research calls so one final delivery call remains admissible. */
+  completionReserveTokens: NonNegativeInt,
+  costBudgetMicrousd: Schema.optionalKey(NonNegativeInt),
+  /** Per-model-call live-context bound; crossing it triggers compaction rather than failure. */
+  contextTokenLimit: Schema.optionalKey(PositiveInt),
+  toolResultBounds: ToolResultBounds,
+  runStatus: Schema.Literals(["appended", "off"]),
+  compaction: CompactionPolicy,
+}).check(
+  Schema.makeFilter((policy) =>
+    policy.tokenBudget !== undefined && policy.completionReserveTokens > policy.tokenBudget
+      ? {
+          path: ["completionReserveTokens"],
+          issue: "completionReserveTokens cannot exceed tokenBudget",
+        }
+      : undefined,
+  ),
+);
+
+type AgentPolicyFields = typeof AgentPolicyFields.Type;
+
+/** Inputs normalized and validated by `AgentPolicy.make`. */
+export type AgentPolicyInput = Readonly<
+  Omit<
+    AgentPolicyFields,
+    | "maxDuration"
+    | "repeatedFailureLimit"
+    | "onExhaustion"
+    | "toolResultBounds"
+    | "runStatus"
+    | "compaction"
+    | "completionReserveTokens"
+  > & {
+    /** Finite, positive wall-clock duration accepted in any Effect Duration input form. */
+    readonly maxDuration: Duration.Input;
+    /** Non-negative repeated-failure bound; defaults to `3`. */
+    readonly repeatedFailureLimit?: number;
+    /** Turn/Tool-Call/token exhaustion resolution; defaults to `"final-answer"`. */
+    readonly onExhaustion?: typeof OnExhaustion.Type;
+    /** Byte bound for each encoded Tool result; defaults to `50 KiB`. */
+    readonly toolResultBounds?: ToolResultBounds;
+    /** Whether a derived run-status message is appended to each model call; defaults to `"off"` to preserve retained prompt cache boundaries. */
+    readonly runStatus?: AgentPolicyFields["runStatus"];
+    /** Tokens reserved for final delivery; defaults to 20% of tokenBudget, capped at 4,096. */
+    readonly completionReserveTokens?: number;
+    /** Compaction strategy applied when `contextTokenLimit` is crossed; defaults documented on `CompactionPolicy`. */
+    readonly compaction?: CompactionPolicy;
+  }
+>;
+
+/** Schema class for finite agent run limits. */
+export class AgentPolicy extends Schema.Class<AgentPolicy>("AgentPolicy")(AgentPolicyFields) {
+  /** Resolve an optional declaration against finite standalone or parent defaults. */
+  static resolve(input: Partial<AgentPolicyInput> = {}, parent?: AgentPolicy): AgentPolicy {
+    return AgentPolicy.make({
+      maxTurns: 12,
+      maxToolCalls: 24,
+      maxDuration: "5 minutes",
+      toolConcurrency: 4,
+      ...parent,
+      ...input,
+      // A smaller token budget must not inherit a reserve larger than itself.
+      ...(input.completionReserveTokens !== undefined || parent === undefined
+        ? {}
+        : {
+            completionReserveTokens: Math.min(
+              parent.completionReserveTokens,
+              input.tokenBudget ?? parent.tokenBudget ?? parent.completionReserveTokens,
+            ),
+          }),
+    });
+  }
+
+  /** Normalize and validate finite policy bounds, throwing on invalid input. */
+  static override make(input: AgentPolicyInput): AgentPolicy {
+    const completionReserveTokens =
+      input.completionReserveTokens ??
+      (input.tokenBudget === undefined
+        ? 4_096
+        : Math.min(4_096, Math.floor(input.tokenBudget / 5)));
+
+    return super.make({
+      ...input,
+      maxDuration: Duration.fromInputUnsafe(input.maxDuration),
+      repeatedFailureLimit: input.repeatedFailureLimit ?? 3,
+      onExhaustion: input.onExhaustion ?? "final-answer",
+      toolResultBounds: input.toolResultBounds ?? ToolResultBounds.make({ maxBytes: 50 * 1024 }),
+      runStatus: input.runStatus ?? "off",
+      completionReserveTokens,
+      compaction: input.compaction ?? CompactionPolicy.make(),
+    });
+  }
+}

package/src/core/AgentUpdates.ts

@@ -0,0 +1,100 @@
+import { Context, Effect, Option, Schema, Stream } from "effect";
+
+import { AgentId, ThreadId, RunId } from "./Identifiers.ts";
+import { IdempotencyKey } from "./Receipt.ts";
+
+/** Canonical schema-encoded intermediate output, scoped to one logical Run. */
+export class Update extends Schema.Class<Update>("@effect-agent/core/AgentUpdates/Update")({
+  schemaVersion: Schema.Literal(1),
+  agentId: AgentId,
+  threadId: ThreadId,
+  runId: RunId,
+  updateId: IdempotencyKey,
+  sequence: Schema.Int.check(Schema.isGreaterThan(0)),
+  value: Schema.Json,
+}) {}
+
+/** Fail-closed update acceptance and decoding errors; payloads are never included. */
+export class UpdateError extends Schema.TaggedError<UpdateError>()("AgentUpdateError", {
+  reason: Schema.Literals([
+    "validation",
+    "unavailable",
+    "conflict",
+    "capacity",
+    "storage",
+    "identity",
+    "denied",
+  ]),
+}) {}
+
+/** Engine-owned invocation port. The Agent ID and exact update Schema must match the executing definition. */
+export class Emitter extends Context.Service<
+  Emitter,
+  {
+    readonly emit: (request: {
+      readonly target: { readonly id: AgentId; readonly updates?: Schema.Top | undefined };
+      readonly updateId: IdempotencyKey;
+      readonly value: Schema.Json;
+    }) => Effect.Effect<Update, UpdateError>;
+  }
+>()("@effect-agent/core/AgentUpdates/Emitter") {}
+
+/** Structural schema boundary accepted by definitions and their model bindings. */
+type Source<S extends Schema.Top> = {
+  readonly id: AgentId;
+  readonly updates?: S | undefined;
+};
+
+type BoundSource<S extends Schema.Top> = Source<S> | { readonly definition: Source<S> };
+
+/** Emit a decoded update under an explicit stable key. Retries cannot replace accepted values. */
+export const emit = Effect.fn("AgentUpdates.emit")(function* <S extends Schema.Top>(
+  agent: BoundSource<S>,
+  value: NoInfer<S["Type"]>,
+  options: { readonly idempotencyKey: IdempotencyKey },
+): Effect.fn.Return<Update, UpdateError, Emitter | S["EncodingServices"]> {
+  const target = "definition" in agent ? agent.definition : agent;
+
+  if (target.updates === undefined) return yield* new UpdateError({ reason: "unavailable" });
+
+  const updateId = yield* Schema.decodeEffect(IdempotencyKey)(options.idempotencyKey).pipe(
+    Effect.mapError(() => new UpdateError({ reason: "validation" })),
+  );
+
+  const encoded = yield* Schema.encodeEffect(target.updates)(value).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(Schema.Json)),
+    Effect.mapError(() => new UpdateError({ reason: "validation" })),
+  );
+
+  const emitter = yield* Effect.serviceOption(Emitter);
+
+  if (Option.isNone(emitter)) return yield* new UpdateError({ reason: "unavailable" });
+
+  return yield* emitter.value.emit({ target, updateId, value: encoded });
+});
+
+/** Decode canonical update data through its declaring Agent Schema. */
+export const decode = Effect.fn("AgentUpdates.decode")(function* <S extends Schema.Top>(
+  agent: BoundSource<S>,
+  update: Update,
+): Effect.fn.Return<S["Type"], UpdateError, S["DecodingServices"]> {
+  const definition = "definition" in agent ? agent.definition : agent;
+
+  if (definition.updates === undefined) return yield* new UpdateError({ reason: "unavailable" });
+
+  const decoded = yield* Schema.decodeEffect(Update)(update).pipe(
+    Effect.mapError(() => new UpdateError({ reason: "validation" })),
+  );
+
+  if (decoded.agentId !== definition.id) return yield* new UpdateError({ reason: "identity" });
+
+  return yield* Schema.decodeEffect(definition.updates)(decoded.value).pipe(
+    Effect.mapError(() => new UpdateError({ reason: "validation" })),
+  );
+});
+
+/** Decode an encoded update stream without hiding its failures or requirements. */
+export const observe = <S extends Schema.Top, E, R>(
+  agent: BoundSource<S>,
+  updates: Stream.Stream<Update, E, R>,
+) => updates.pipe(Stream.mapEffect((update) => decode(agent, update)));

package/src/core/IdGenerator.ts

@@ -0,0 +1,39 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { IdGenerator as EffectAiIdGenerator } from "effect/unstable/ai";
+
+import { ThreadId, RunId, TurnId } from "./Identifiers.ts";
+
+/** Replaceable authority for creating runtime identities, including deterministic test IDs. */
+export interface Service {
+  /** Create the identity for a new thread. */
+  readonly nextThreadId: Effect.Effect<ThreadId>;
+  /** Create the identity for a new run. */
+  readonly nextRunId: Effect.Effect<RunId>;
+  /** Create the identity for a new model turn. */
+  readonly nextTurnId: Effect.Effect<TurnId>;
+}
+
+const defaultGenerator: Service = {
+  nextThreadId: EffectAiIdGenerator.defaultIdGenerator
+    .generateId()
+    .pipe(Effect.map((id) => Schema.decodeSync(ThreadId)(`thread-${id}`))),
+  nextRunId: EffectAiIdGenerator.defaultIdGenerator
+    .generateId()
+    .pipe(Effect.map((id) => Schema.decodeSync(RunId)(`run-${id}`))),
+  nextTurnId: EffectAiIdGenerator.defaultIdGenerator
+    .generateId()
+    .pipe(Effect.map((id) => Schema.decodeSync(TurnId)(`turn-${id}`))),
+};
+
+/**
+ * Runtime identities default to Effect AI's generator without requiring a Layer.
+ * Randomness is fiber-local and can be seeded in tests. Override this reference
+ * with Layer.succeed/Layer.effect or Effect.provideService for custom identities.
+ * The default holds only Effects: it allocates no mutable state or resources.
+ */
+export const IdGenerator = Context.Reference<Service>("@effect-agent/core/IdGenerator", {
+  defaultValue: () => defaultGenerator,
+});
+
+/** Explicitly select the default generator, replacing any enclosing override. */
+export const layer: Layer.Layer<never> = Layer.succeed(IdGenerator, defaultGenerator);

package/src/core/Identifiers.ts

@@ -0,0 +1,48 @@
+import * as Schema from "effect/Schema";
+
+const identifier = <const Name extends string>(name: Name) =>
+  Schema.NonEmptyString.pipe(Schema.brand(`@effect-agent/core/${name}`));
+
+/** Stable identity of an agent definition, distinct from a display name. */
+export const AgentId = identifier("AgentId");
+export type AgentId = typeof AgentId.Type;
+
+/** Identity shared by runs that participate in one thread history. */
+export const ThreadId = identifier("ThreadId");
+export type ThreadId = typeof ThreadId.Type;
+
+/** Identity of one accepted input submission. */
+export const SubmissionId = identifier("SubmissionId");
+export type SubmissionId = typeof SubmissionId.Type;
+
+/** Durable identity returned once ledger admission and Thread readiness are committed. */
+export const ReceiptId = identifier("ReceiptId");
+export type ReceiptId = typeof ReceiptId.Type;
+
+/** Identity of the single durable terminal outcome owed to one accepted Submission. */
+export const SettlementId = identifier("SettlementId");
+export type SettlementId = typeof SettlementId.Type;
+
+/** Identity of one execution ownership period for accepted work. */
+export const AttemptId = identifier("AttemptId");
+export type AttemptId = typeof AttemptId.Type;
+
+/** Identity of one logical agent run. */
+export const RunId = identifier("RunId");
+export type RunId = typeof RunId.Type;
+
+/** Identity of one model turn within a run. */
+export const TurnId = identifier("TurnId");
+export type TurnId = typeof TurnId.Type;
+
+/** Identity used to correlate a Tool Call with progress and its terminal outcome. */
+export const ToolCallId = identifier("ToolCallId");
+export type ToolCallId = typeof ToolCallId.Type;
+
+/** Stable identity of one configured Subagent capability. */
+export const DelegationId = identifier("DelegationId");
+export type DelegationId = typeof DelegationId.Type;
+
+/** Opaque position in a semantic event sequence. */
+export const EventOffset = identifier("EventOffset");
+export type EventOffset = typeof EventOffset.Type;