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

package/src/core/RememberingStore.ts

@@ -0,0 +1,300 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+import type * as MemoryNamespace from "./MemoryNamespace.ts";
+import { MemorySourceReference } from "./MemoryReference.ts";
+import { MemoryDocument, MemoryKey, MemoryWrite } from "./MemoryStore.ts";
+
+const Identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+
+const Counter = Schema.Int.check(
+  Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+);
+
+/** Host source-order lineage. Sequence is monotonic only within one authorityGeneration.
+ * Opaque revision strings and different authority generations are never ordered.
+ */
+export const SourcePosition = Schema.Struct({
+  authorityGeneration: Identity,
+  sequence: Counter,
+});
+
+export type SourcePosition = typeof SourcePosition.Type;
+
+export const comparePosition = (left: SourcePosition, right: SourcePosition): number | undefined =>
+  left.authorityGeneration === right.authorityGeneration
+    ? Math.sign(left.sequence - right.sequence)
+    : undefined;
+
+export const Source = Schema.Struct({
+  key: MemoryKey.Wire,
+  locator: MemorySourceReference.fields.locator,
+  revision: Schema.NonEmptyString.check(Schema.isMaxLength(1_024)),
+  position: SourcePosition,
+});
+
+export type Source = typeof Source.Type;
+
+class IntentWire extends Schema.Class<IntentWire>("@effect-agent/remembering/Intent")({
+  version: Schema.Literal(1),
+  /** Stable host-selected idempotency identity, including processor/schema version. It must be
+   * unique across all source-owner Stores writing this target for the receipt retention window.
+   */
+  id: Identity,
+  /** Trusted invocation identity, never taken from extracted/model values. */
+  invocationId: Identity,
+  source: Source,
+  target: MemoryKey.Wire,
+}) {}
+
+export type Intent<
+  S extends MemoryNamespace.Any = MemoryNamespace.Any,
+  T extends MemoryNamespace.Any = MemoryNamespace.Any,
+> = Omit<IntentWire, "source" | "target"> & {
+  readonly source: Omit<Source, "key"> & { readonly key: MemoryKey<S> };
+  readonly target: MemoryKey<T>;
+};
+
+export const Intent = {
+  Wire: IntentWire,
+  make: <S extends MemoryNamespace.Any, T extends MemoryNamespace.Any>(
+    fields: Intent<S, T>,
+  ): Intent<S, T> =>
+    Object.assign(Schema.decodeUnknownSync(IntentWire)(fields), {
+      source: { ...fields.source, key: MemoryKey.make(fields.source.key) },
+      target: MemoryKey.make(fields.target),
+    }),
+};
+
+/** Half-open UTF-8 byte range in the exact authoritative source revision. A quote proves
+ * provenance only. Applications decide whether it supports a fact and may be shared.
+ */
+export const Evidence = Schema.Struct({
+  source: Schema.Struct({ ...MemorySourceReference.fields, revision: Source.fields.revision }),
+  startByte: Counter,
+  endByte: Counter,
+  quote: Schema.NonEmptyString.check(Schema.isMaxLength(65_536)),
+});
+
+export type Evidence = typeof Evidence.Type;
+
+export const Proposal = Schema.Struct({
+  version: Schema.Literal(1),
+  value: Schema.Json,
+  evidence: Schema.Array(Evidence).check(Schema.isMinLength(1), Schema.isMaxLength(128)),
+});
+
+export type Proposal = typeof Proposal.Type;
+
+export interface Extracted<Value> {
+  readonly value: Value;
+  readonly evidence: ReadonlyArray<Evidence>;
+}
+
+export class Invalidation extends Schema.Class<Invalidation>(
+  "@effect-agent/remembering/Invalidation",
+)({
+  version: Schema.Literal(1),
+  id: Identity,
+  source: MemoryKey.Wire,
+  position: SourcePosition,
+  reason: Schema.Literals(["source-edit", "source-deletion", "source-revocation", "forget"]),
+}) {}
+
+export type BoundInvalidation<S extends MemoryNamespace.Any> = Omit<Invalidation, "source"> & {
+  readonly source: MemoryKey<S>;
+};
+
+const PreparedFields: {
+  readonly proposal: typeof Proposal;
+  readonly attempt: typeof Counter;
+  readonly purpose: Schema.Literals<readonly ["remember", "cleanup"]>;
+  readonly applied: Schema.NullOr<typeof MemoryDocument.Wire>;
+} = {
+  proposal: Proposal,
+  attempt: Counter,
+  purpose: Schema.Literals(["remember", "cleanup"]),
+  /** Original applied revision, retained for source-aware conditional cleanup. */
+  applied: Schema.NullOr(MemoryDocument.Wire),
+};
+
+const CompletedFields: {
+  readonly proposal: Schema.NullOr<typeof Proposal>;
+  readonly attempt: typeof Counter;
+  readonly applied: Schema.NullOr<typeof MemoryDocument.Wire>;
+  readonly outcome: Schema.Literals<readonly ["applied", "no-change", "rejected", "suppressed"]>;
+  readonly cleaned: typeof Schema.Boolean;
+} = {
+  proposal: Schema.NullOr(Proposal),
+  attempt: Counter,
+  applied: Schema.NullOr(MemoryDocument.Wire),
+  outcome: Schema.Literals(["applied", "no-change", "rejected", "suppressed"]),
+  cleaned: Schema.Boolean,
+};
+
+interface ProgressSchema extends Schema.Union<
+  readonly [
+    Schema.TaggedStruct<"Pending", {}>,
+    Schema.TaggedStruct<"Proposed", typeof PreparedFields>,
+    Schema.TaggedStruct<
+      "Prepared",
+      typeof PreparedFields & { readonly command: typeof MemoryWrite.Wire }
+    >,
+    Schema.TaggedStruct<"Completed", typeof CompletedFields>,
+  ]
+> {}
+
+export const Progress: ProgressSchema = Schema.Union([
+  Schema.TaggedStruct("Pending", {}),
+  Schema.TaggedStruct("Proposed", PreparedFields),
+  Schema.TaggedStruct("Prepared", { ...PreparedFields, command: MemoryWrite.Wire }),
+  Schema.TaggedStruct("Completed", CompletedFields),
+]);
+
+export type Progress<T extends MemoryNamespace.Any = MemoryNamespace.Any> =
+  | (typeof Progress.members)[0]["Type"]
+  | (Omit<(typeof Progress.members)[1]["Type"], "applied"> & {
+      readonly applied: MemoryDocument<T> | null;
+    })
+  | (Omit<(typeof Progress.members)[2]["Type"], "applied" | "command"> & {
+      readonly applied: MemoryDocument<T> | null;
+      readonly command: MemoryWrite<T>;
+    })
+  | (Omit<(typeof Progress.members)[3]["Type"], "applied"> & {
+      readonly applied: MemoryDocument<T> | null;
+    });
+
+/** Retain this source-target reference after removing a job from the active queue. It contains
+ * the immutable proposal and original application receipt needed by later invalidation.
+ * Prepared commands must never be pruned or replaced while their outcome is uncertain.
+ */
+export class Checkpoint extends Schema.Class<Checkpoint>("@effect-agent/remembering/Checkpoint")({
+  version: Counter,
+  intent: Intent.Wire,
+  suppression: Schema.NullOr(Invalidation),
+  progress: Progress,
+}) {}
+
+/** A checked checkpoint bound to the caller's original namespace definitions. */
+export type BoundCheckpoint<S extends MemoryNamespace.Any, T extends MemoryNamespace.Any> = Omit<
+  Checkpoint,
+  "intent" | "progress" | "suppression"
+> & {
+  readonly intent: Intent<S, T>;
+  readonly progress: Progress<T>;
+  readonly suppression: BoundInvalidation<S> | null;
+};
+
+export class Admission extends Schema.Class<Admission>("@effect-agent/remembering/Admission")({
+  id: Identity,
+  status: Schema.Literals(["queued", "duplicate"]),
+}) {}
+
+export class InvalidationReceipt extends Schema.Class<InvalidationReceipt>(
+  "@effect-agent/remembering/InvalidationReceipt",
+)({
+  id: Identity,
+  status: Schema.Literals(["accepted", "duplicate", "stale"]),
+  affected: Counter,
+}) {}
+
+export class AdmissionError extends Schema.TaggedError<AdmissionError>()(
+  "RememberingAdmissionError",
+  {
+    reason: Schema.Literals(["invalid-input", "conflict", "capacity", "suppressed", "disabled"]),
+  },
+) {}
+
+export class CheckpointError extends Schema.TaggedError<CheckpointError>()(
+  "RememberingCheckpointError",
+  {
+    reason: Schema.Literals(["fenced", "missing", "corrupt"]),
+  },
+) {}
+
+export class ProcessingError extends Schema.TaggedError<ProcessingError>()(
+  "RememberingProcessingError",
+  {
+    reason: Schema.Literals([
+      "invalid-input",
+      "invalid-evidence",
+      "source-changed",
+      "budget",
+      "timeout",
+      "disabled",
+      "cleanup-rejected",
+    ]),
+  },
+) {}
+
+export const MutationPoint = Schema.Literals([
+  "admission:before",
+  "admission:after",
+  "proposal:before",
+  "proposal:after",
+  "command:before",
+  "command:after",
+  "rebase:before",
+  "rebase:after",
+  "completion:before",
+  "completion:after",
+  "suppression:before",
+  "suppression:after",
+  "cleanup:before",
+  "cleanup:after",
+]);
+
+export type MutationPoint = typeof MutationPoint.Type;
+
+export class MutationFailure extends Schema.TaggedError<MutationFailure>()(
+  "RememberingMutationFailure",
+  {
+    point: MutationPoint,
+  },
+) {}
+
+/** Explicit transition failpoints. No-op unless a test installs a replacement. */
+export class MutationFailpoint extends Context.Service<
+  MutationFailpoint,
+  {
+    readonly hit: (point: MutationPoint) => Effect.Effect<void, MutationFailure>;
+  }
+>()("@effect-agent/remembering/MutationFailpoint") {
+  static readonly layer = Layer.succeed(this, { hit: () => Effect.void });
+}
+
+/** Host-owned durable admission/checkpoint port. It is not a scheduler or profile store.
+ * The explicit port binds an existing host job transaction; its Effects retain their E and R.
+ * Hosts may acquire it from their own Context service. The protocol never provides its requirements.
+ *
+ * admit atomically binds the complete intent, receipt, source authority, and ready obligation.
+ * Identical retries return duplicate; reusing an id with different intent fails conflict.
+ * read/save validate the complete intent. save atomically checks expectedVersion and advances
+ * its fence; invalidation advances the same fence. A failed CAS must never dispatch new work.
+ *
+ * invalidate durably records suppression before source acknowledgement and marks every retained
+ * source-target reference ready for reconciliation/cleanup. It MUST preserve Prepared commands.
+ * Older positions cannot undo newer authority; forget is terminal for that source identity.
+ * Bind the active authorityGeneration before admission. Unknown or mismatched lineages fail
+ * closed; an explicit host restore cutover installs a new lineage and fences all old workers.
+ * Source edits suppress contributions from earlier positions; deletion/forget include their own
+ * position. A duplicate invalidation cannot lose pending cleanup. New admissions against an old
+ * authority, withdrawn source, or terminal forget fail suppressed.
+ *
+ * Bound active jobs, proposals, references and receipts. Capacity failure rejects new admission;
+ * it never evicts an unresolved command, suppression, or cleanup obligation. Retain references,
+ * receipts and suppression for the entire supported delivery/replay/restore window. Expired or
+ * incompatible restores fail closed. The host owns alarms, outboxes, ordering, retries, leases,
+ * source authorization and whether extraction is enabled. Cleanup remains runnable when it is off.
+ */
+export interface Store<E = never, R = never> {
+  readonly admit: (intent: Intent) => Effect.Effect<Admission, E | AdmissionError, R>;
+  readonly read: (intent: Intent) => Effect.Effect<Checkpoint, E | CheckpointError, R>;
+  readonly save: (input: {
+    readonly intent: Intent;
+    readonly expectedVersion: number;
+    readonly progress: Progress;
+  }) => Effect.Effect<Checkpoint, E | CheckpointError, R>;
+  readonly invalidate: (
+    event: Invalidation,
+  ) => Effect.Effect<InvalidationReceipt, E | AdmissionError, R>;
+}

package/src/core/RunEvent.ts

@@ -0,0 +1,366 @@
+import { Schema } from "effect";
+
+import { Update } from "./AgentUpdates.ts";
+import { AgentId, ThreadId, DelegationId, RunId, ToolCallId, TurnId } from "./Identifiers.ts";
+import { DelegationDepth } from "./SubagentContract.ts";
+import { Selection } from "./ToolExposure.ts";
+import { RunTotals } from "./Usage.ts";
+
+const RunEventBase = {
+  eventVersion: Schema.Literal(1),
+  runId: RunId,
+  threadId: ThreadId,
+  agentId: AgentId,
+  sequence: Schema.Natural,
+  timestamp: Schema.DateTimeUtcFromString,
+  turnId: Schema.optionalKey(TurnId),
+  toolCallId: Schema.optionalKey(ToolCallId),
+};
+
+/** A schema-encoded Agent update accepted by the owning Run. */
+export class AgentUpdateEmitted extends Schema.TaggedClass<AgentUpdateEmitted>()(
+  "AgentUpdateEmitted",
+  { ...RunEventBase, update: Update },
+) {}
+
+/** Signals that the runtime has created a run and assigned its identities. */
+export class RunStarted extends Schema.TaggedClass<RunStarted>()("RunStarted", RunEventBase) {}
+
+/** Signals the start of a positive-numbered model turn. */
+export class TurnStarted extends Schema.TaggedClass<TurnStarted>()("TurnStarted", {
+  ...RunEventBase,
+  turn: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+/** Signals that the model request for a turn is starting. */
+export class ModelStarted extends Schema.TaggedClass<ModelStarted>()("ModelStarted", {
+  ...RunEventBase,
+  turn: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+/** Carries one live assistant text delta. */
+export class TextDelta extends Schema.TaggedClass<TextDelta>()("TextDelta", {
+  ...RunEventBase,
+  text: Schema.String,
+}) {}
+
+/** Carries reasoning content explicitly exposed by the provider. */
+export class ReasoningDelta extends Schema.TaggedClass<ReasoningDelta>()("ReasoningDelta", {
+  ...RunEventBase,
+  text: Schema.String,
+}) {}
+
+/** Reports a complete model-declared Tool Call and its execution boundary. */
+export class ToolCallDeclared extends Schema.TaggedClass<ToolCallDeclared>()("ToolCallDeclared", {
+  ...RunEventBase,
+  toolCallId: ToolCallId,
+  toolName: Schema.NonEmptyString,
+  parameters: Schema.Json,
+  providerExecuted: Schema.Boolean,
+}) {}
+
+/** Signals that a validated Tool Call handler has started. */
+export class ToolCallStarted extends Schema.TaggedClass<ToolCallStarted>()("ToolCallStarted", {
+  ...RunEventBase,
+  toolCallId: ToolCallId,
+  toolName: Schema.NonEmptyString,
+}) {}
+
+/** Carries a preliminary Tool result that is not the call's terminal outcome. */
+export class ToolProgress extends Schema.TaggedClass<ToolProgress>()("ToolProgress", {
+  ...RunEventBase,
+  toolCallId: ToolCallId,
+  toolName: Schema.NonEmptyString,
+  result: Schema.Json,
+  providerExecuted: Schema.Boolean,
+}) {}
+
+/** Records the successful terminal result of a Tool Call. */
+export class ToolCallSucceeded extends Schema.TaggedClass<ToolCallSucceeded>()(
+  "ToolCallSucceeded",
+  {
+    ...RunEventBase,
+    toolCallId: ToolCallId,
+    toolName: Schema.NonEmptyString,
+    toolSelection: Schema.optionalKey(Selection),
+    result: Schema.Json,
+    providerExecuted: Schema.Boolean,
+  },
+) {}
+
+/**
+ * How this boundary handled a failed invocation, independently of its native failure mode.
+ * `returned-to-model` records the result path; delivery still requires the complete batch to
+ * commit and a later model call. A sibling, policy or later operation can still fail the Run.
+ * This classification never implies that side effects were rolled back.
+ */
+export const ToolFailureHandling = Schema.Literals([
+  "propagated",
+  "returned-to-model",
+  "returned-to-caller",
+]);
+
+export type ToolFailureHandling = typeof ToolFailureHandling.Type;
+
+/** Records a terminal Tool Call failure using safe, serializable diagnostics. */
+export class ToolCallFailed extends Schema.TaggedClass<ToolCallFailed>()("ToolCallFailed", {
+  ...RunEventBase,
+  toolCallId: ToolCallId,
+  toolName: Schema.NonEmptyString,
+  errorTag: Schema.NonEmptyString,
+  message: Schema.String,
+  providerExecuted: Schema.Boolean,
+  /** Native configuration when a local Tool is known; absent on provider results and old events. */
+  failureMode: Schema.optionalKey(Schema.Literals(["error", "return"])),
+  /** Actual route at this boundary. Absence on older events means unknown, never recoverable. */
+  failureHandling: Schema.optionalKey(ToolFailureHandling),
+  /** Synthetic policy rejection; no handler ran and the failure streak is unchanged. */
+  budgetRejected: Schema.optionalKey(Schema.Literal(true)),
+}) {}
+
+/** Signals that a decoded Tool Call requires approval before execution. */
+export class ApprovalRequested extends Schema.TaggedClass<ApprovalRequested>()(
+  "ApprovalRequested",
+  {
+    ...RunEventBase,
+    toolCallId: ToolCallId,
+    toolName: Schema.NonEmptyString,
+  },
+) {}
+
+/** Records the normalized finish reason for a completed assistant turn. */
+export class TurnCompleted extends Schema.TaggedClass<TurnCompleted>()("TurnCompleted", {
+  ...RunEventBase,
+  turn: Schema.Int.check(Schema.isGreaterThan(0)),
+  finishReason: Schema.Literals([
+    "stop",
+    "length",
+    "content-filter",
+    "tool-calls",
+    "error",
+    "pause",
+    "other",
+    "unknown",
+  ]),
+}) {}
+
+/** Advisory that one policy limit crossed its warning fraction; emitted once per limit per run. */
+export class BudgetWarning extends Schema.TaggedClass<BudgetWarning>()("BudgetWarning", {
+  ...RunEventBase,
+  limit: Schema.Literals(["tokens", "tool-calls", "turns", "duration", "context"]),
+  consumed: Schema.Natural,
+  limitValue: Schema.Natural,
+}) {}
+
+/** Records that the engine reduced model context at a Turn seam without erasing source history. */
+export class CompactionPerformed extends Schema.TaggedClass<CompactionPerformed>()(
+  "CompactionPerformed",
+  {
+    ...RunEventBase,
+    turn: Schema.Int.check(Schema.isGreaterThan(0)),
+    kind: Schema.Literals(["clear-tool-results", "summarize", "rollover"]),
+    tokensBeforeEstimate: Schema.Natural,
+    tokensAfterEstimate: Schema.Natural,
+  },
+) {}
+
+/**
+ * Dimension that bound when a Run settled through the final-answer resolution
+ * (RUN-018; the token dimension per RUN-025). This is the exhausted marker
+ * the re-delegation grant flow (RUN-021) consumes and the durable
+ * `SubmissionSettled` record persists (RUN-011).
+ */
+export const ExhaustedLimit = Schema.Literals(["tokens", "tool-calls", "turns"]);
+export type ExhaustedLimit = typeof ExhaustedLimit.Type;
+
+const CompletionFinishReason = Schema.Literals(["completed", "model-stop", "budget-exhausted"]);
+
+type CompletionMetadata = Readonly<{
+  finishReason: typeof CompletionFinishReason.Type;
+  exhausted?: ExhaustedLimit | undefined;
+}>;
+
+const validateCompletionMetadata = ({
+  exhausted,
+  finishReason,
+}: CompletionMetadata): string | undefined => {
+  const isBudgetExhausted = finishReason === "budget-exhausted";
+
+  return isBudgetExhausted === (exhausted !== undefined)
+    ? undefined
+    : '`exhausted` must be present exactly when `finishReason` is "budget-exhausted"';
+};
+
+const RunCompletedFields = Schema.Struct({
+  ...RunEventBase,
+  output: Schema.Json,
+  /** Schema-encoded application disposition, present only for an ordinary completed Run. */
+  runDisposition: Schema.optionalKey(Schema.Json),
+  turns: Schema.Int.check(Schema.isGreaterThan(0)),
+  finishReason: CompletionFinishReason,
+  exhausted: Schema.optionalKey(ExhaustedLimit),
+  /** Own Run usage, excluding attached descendants. Missing legacy reports are unknown. */
+  usage: Schema.optionalKey(RunTotals),
+  delegatedUsage: Schema.optionalKey(RunTotals),
+}).check(
+  Schema.makeFilter((event) => validateCompletionMetadata(event)),
+  Schema.makeFilter((event) =>
+    event.finishReason === "budget-exhausted" && event.runDisposition !== undefined
+      ? {
+          path: ["runDisposition"],
+          issue: '`runDisposition` is not allowed when `finishReason` is "budget-exhausted"',
+        }
+      : undefined,
+  ),
+);
+
+/**
+ * Successful terminal event carrying Schema-compatible output and the completed turn count.
+ * `"budget-exhausted"` marks a Run that settled through the policy's final-answer resolution
+ * after Turn, Tool Call, or token exhaustion — never a plain `"model-stop"` (RUN-011); its
+ * `turns` count may exceed `maxTurns` by the single grace Turn, and `exhausted` names the
+ * dimension that bound.
+ *
+ * Invariant: `exhausted` is present exactly when `finishReason` is
+ * `"budget-exhausted"`, and a budget-exhausted completion has no application
+ * run disposition. The checked Struct enforces both rules during construction,
+ * decoding, and encoding without replacing the class in `RunEvent`.
+ */
+export class RunCompleted extends Schema.TaggedClass<RunCompleted>()(
+  "RunCompleted",
+  RunCompletedFields,
+) {}
+
+/** Terminal event for a run that failed with an expected error. */
+export class RunFailed extends Schema.TaggedClass<RunFailed>()("RunFailed", {
+  ...RunEventBase,
+  usage: Schema.optionalKey(RunTotals),
+  delegatedUsage: Schema.optionalKey(RunTotals),
+  errorTag: Schema.NonEmptyString,
+  message: Schema.String,
+}) {}
+
+/** Terminal event for a run stopped by interruption. */
+export class RunInterrupted extends Schema.TaggedClass<RunInterrupted>()("RunInterrupted", {
+  ...RunEventBase,
+  message: Schema.String,
+}) {}
+
+/** Terminal event for a run awaiting resumable external input. */
+export class RunSuspended extends Schema.TaggedClass<RunSuspended>()("RunSuspended", {
+  ...RunEventBase,
+  usage: Schema.optionalKey(RunTotals),
+  delegatedUsage: Schema.optionalKey(RunTotals),
+  reason: Schema.String,
+}) {}
+
+const SubagentText = Schema.String.check(Schema.isMaxLength(4 * 1024));
+
+const SubagentEventBase = {
+  ...RunEventBase,
+  turnId: TurnId,
+  toolCallId: ToolCallId,
+  delegationId: DelegationId,
+  childThreadId: ThreadId,
+  childRunId: RunId,
+  targetAgentId: AgentId,
+  depth: DelegationDepth,
+};
+
+/** Signals that a delegation Tool Call passed preflight with preallocated child identity. */
+export class SubagentRequested extends Schema.TaggedClass<SubagentRequested>()(
+  "SubagentRequested",
+  SubagentEventBase,
+) {}
+
+/** Signals that the child run has started inside its parent-owned scoped region. */
+export class SubagentStarted extends Schema.TaggedClass<SubagentStarted>()(
+  "SubagentStarted",
+  SubagentEventBase,
+) {}
+
+/** Carries a bounded child progress summary without duplicating the child event stream. */
+export class SubagentProgress extends Schema.TaggedClass<SubagentProgress>()("SubagentProgress", {
+  ...SubagentEventBase,
+  summary: SubagentText,
+}) {}
+
+/**
+ * Records the child run's successful terminal outcome before the parent join.
+ * Same invariant as `RunCompleted`: `exhausted` is present exactly when
+ * `finishReason` is `"budget-exhausted"` (the pair travels verbatim from the
+ * child's terminal event); consumers treat a divergent pair fail-safe.
+ */
+export class SubagentCompleted extends Schema.TaggedClass<SubagentCompleted>()(
+  "SubagentCompleted",
+  Schema.Struct({
+    ...SubagentEventBase,
+    turns: Schema.Int.check(Schema.isGreaterThan(0)),
+    finishReason: CompletionFinishReason,
+    exhausted: Schema.optionalKey(ExhaustedLimit),
+    /**
+     * The child's own observed usage. Delegated usage covers its attached descendants separately.
+     */
+    usage: Schema.optionalKey(RunTotals),
+    delegatedUsage: Schema.optionalKey(RunTotals),
+  }).check(Schema.makeFilter((event) => validateCompletionMetadata(event))),
+) {}
+
+/** Records the child run's expected terminal failure using safe, serializable diagnostics. */
+export class SubagentFailed extends Schema.TaggedClass<SubagentFailed>()("SubagentFailed", {
+  ...SubagentEventBase,
+  usage: Schema.optionalKey(RunTotals),
+  delegatedUsage: Schema.optionalKey(RunTotals),
+  errorTag: Schema.NonEmptyString,
+  message: SubagentText,
+}) {}
+
+/** Records that the child run was stopped by interruption before a terminal outcome. */
+export class SubagentInterrupted extends Schema.TaggedClass<SubagentInterrupted>()(
+  "SubagentInterrupted",
+  {
+    ...SubagentEventBase,
+    usage: Schema.optionalKey(RunTotals),
+    delegatedUsage: Schema.optionalKey(RunTotals),
+    reason: SubagentText,
+  },
+) {}
+
+/** Records that the child's terminal outcome was joined into its parent delegation Tool Call. */
+export class SubagentJoined extends Schema.TaggedClass<SubagentJoined>()("SubagentJoined", {
+  ...SubagentEventBase,
+  usage: Schema.optionalKey(RunTotals),
+  delegatedUsage: Schema.optionalKey(RunTotals),
+}) {}
+
+/** Versioned union of stable semantic run events, excluding raw provider chunks. */
+export const RunEvent = Schema.Union([
+  AgentUpdateEmitted,
+  RunStarted,
+  TurnStarted,
+  ModelStarted,
+  TextDelta,
+  ReasoningDelta,
+  ToolCallDeclared,
+  ToolCallStarted,
+  ToolProgress,
+  ToolCallSucceeded,
+  ToolCallFailed,
+  ApprovalRequested,
+  TurnCompleted,
+  BudgetWarning,
+  CompactionPerformed,
+  RunCompleted,
+  RunFailed,
+  RunInterrupted,
+  RunSuspended,
+  SubagentRequested,
+  SubagentStarted,
+  SubagentProgress,
+  SubagentCompleted,
+  SubagentFailed,
+  SubagentInterrupted,
+  SubagentJoined,
+]);
+
+export type RunEvent = typeof RunEvent.Type;

package/src/core/RunPolicyUsage.ts

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+
+/**
+ * Cumulative policy accounting for one logical Run across replacement Attempts.
+ * Turns and model-declared calls include a pending batch. The failure streak excludes that
+ * entire batch until its declaration-ordered outcomes are folded once during continuation.
+ * Programmatic calls are reserved before execution; finalization is reserved before its model call.
+ */
+export const RunPolicyUsage = Schema.Struct({
+  committedTurns: Schema.Natural,
+  toolCalls: Schema.Natural,
+  programmaticToolCalls: Schema.Natural,
+  consecutiveToolFailures: Schema.Natural,
+  finalizationUsed: Schema.Boolean,
+});
+
+export type RunPolicyUsage = typeof RunPolicyUsage.Type;