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

package/src/core/SemanticMemoryIndex.ts

@@ -0,0 +1,250 @@
+import { Context, Effect, Schema } from "effect";
+
+import * as MemoryNamespace from "./MemoryNamespace.ts";
+import { MemoryPassage } from "./MemoryReference.ts";
+import { ActiveMemoryDocument, MemoryKey } from "./MemoryStore.ts";
+
+const Identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+
+const Positive = Schema.Int.check(
+  Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+);
+
+const Timestamp = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+const Vector = Schema.Array(Schema.Finite).check(Schema.isMinLength(1), Schema.isMaxLength(4_096));
+
+/** A host declaration of the exact embedding space and deterministic chunking policy. */
+export class SemanticMemoryProfile extends Schema.Class<SemanticMemoryProfile>(
+  "@effect-agent/core/SemanticMemoryProfile",
+)({
+  version: Schema.Literal(1),
+  provider: Identity,
+  model: Identity,
+  modelRevision: Identity,
+  dimensions: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 4_096 })),
+  chunker: Schema.Literal("utf8-codepoint@1"),
+  maxChunkBytes: Schema.Int.check(Schema.isBetween({ minimum: 4, maximum: 8_192 })),
+  distance: Schema.Literal("cosine"),
+}) {}
+
+export class SemanticMemoryChunk extends Schema.Class<SemanticMemoryChunk>(
+  "@effect-agent/core/SemanticMemoryChunk",
+)({
+  passageId: MemoryPassage.fields.passageId,
+  ordinal: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 255 })),
+  startByte: Schema.Natural,
+  endByte: Schema.Natural,
+  text: Schema.NonEmptyString.check(Schema.isMaxLength(8_192)),
+  vector: Vector,
+}) {}
+
+const SourceFields = {
+  key: MemoryKey.Wire,
+  source: ActiveMemoryDocument.Wire.fields.source,
+  sourceGeneration: Positive,
+};
+
+class MemoryIndexSourceWire extends Schema.Class<MemoryIndexSourceWire>(
+  "@effect-agent/core/MemoryIndexSource",
+)(SourceFields) {}
+
+export type MemoryIndexSource<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<
+  MemoryIndexSourceWire,
+  "key"
+> & { readonly key: MemoryKey<Namespace> };
+
+export const MemoryIndexSource = {
+  Wire: MemoryIndexSourceWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryIndexSource<Namespace>,
+  ): MemoryIndexSource<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryIndexSourceWire)(fields), {
+      key: MemoryKey.make(fields.key),
+    }),
+};
+
+/** A complete replacement, prepared before touching the disposable index. */
+class MemoryIndexReplacementWire extends Schema.Class<MemoryIndexReplacementWire>(
+  "@effect-agent/core/MemoryIndexReplacement",
+)({
+  source: MemoryIndexSource.Wire,
+  profile: SemanticMemoryProfile,
+  chunks: Schema.Array(SemanticMemoryChunk).check(Schema.isMinLength(1), Schema.isMaxLength(256)),
+}) {}
+
+export type MemoryIndexReplacement<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> =
+  Omit<MemoryIndexReplacementWire, "source"> & { readonly source: MemoryIndexSource<Namespace> };
+
+export const MemoryIndexReplacement = {
+  Wire: MemoryIndexReplacementWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryIndexReplacement<Namespace>,
+  ): MemoryIndexReplacement<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryIndexReplacementWire)(fields), {
+      source: fields.source,
+    }),
+};
+
+class MemoryIndexCandidateWire extends Schema.Class<MemoryIndexCandidateWire>(
+  "@effect-agent/core/MemoryIndexCandidate",
+)({
+  ...SourceFields,
+  passageId: SemanticMemoryChunk.fields.passageId,
+  ordinal: SemanticMemoryChunk.fields.ordinal,
+  startByte: SemanticMemoryChunk.fields.startByte,
+  endByte: SemanticMemoryChunk.fields.endByte,
+  text: SemanticMemoryChunk.fields.text,
+  score: Schema.Finite.check(Schema.isBetween({ minimum: -1, maximum: 1 })),
+  indexedAt: Timestamp,
+}) {}
+
+export type MemoryIndexCandidate<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> =
+  Omit<MemoryIndexCandidateWire, "key"> & { readonly key: MemoryKey<Namespace> };
+
+export const MemoryIndexCandidate = {
+  Wire: MemoryIndexCandidateWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryIndexCandidate<Namespace>,
+  ): MemoryIndexCandidate<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryIndexCandidateWire)(fields), {
+      key: MemoryKey.make(fields.key),
+    }),
+};
+
+class MemoryIndexQueryWire extends Schema.Class<MemoryIndexQueryWire>(
+  "@effect-agent/core/MemoryIndexQuery",
+)({
+  namespace: MemoryKey.Wire.fields.namespace,
+  vector: Vector,
+  limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 128 })),
+  minScore: Schema.Finite.check(Schema.isBetween({ minimum: -1, maximum: 1 })),
+  maxScannedChunks: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65_536 })),
+}) {}
+
+export type MemoryIndexQuery<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<
+  MemoryIndexQueryWire,
+  "namespace"
+> & { readonly namespace: Namespace };
+
+export const MemoryIndexQuery = {
+  Wire: MemoryIndexQueryWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryIndexQuery<Namespace>,
+  ): MemoryIndexQuery<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryIndexQueryWire)(fields), {
+      namespace: fields.namespace,
+    }),
+};
+
+class MemoryIndexSearchWire extends Schema.Class<MemoryIndexSearchWire>(
+  "@effect-agent/core/MemoryIndexSearch",
+)({
+  candidates: Schema.Array(MemoryIndexCandidate.Wire).check(Schema.isMaxLength(128)),
+  scannedChunks: Schema.Natural,
+}) {}
+
+export type MemoryIndexSearch<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<
+  MemoryIndexSearchWire,
+  "candidates"
+> & { readonly candidates: ReadonlyArray<MemoryIndexCandidate<Namespace>> };
+
+export const MemoryIndexSearch = {
+  Wire: MemoryIndexSearchWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryIndexSearch<Namespace>,
+  ): MemoryIndexSearch<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryIndexSearchWire)(fields), {
+      candidates: fields.candidates,
+    }),
+};
+
+export class MemoryIndexError extends Schema.TaggedError<MemoryIndexError>()("MemoryIndexError", {
+  operation: Identity,
+  reason: Schema.Literals([
+    "invalid-input",
+    "unavailable",
+    "corrupt",
+    "incompatible",
+    "fenced",
+    "budget",
+  ]),
+}) {}
+
+/**
+ * Optional disposable ranking index with one fixed embedding/chunking profile.
+ * replace validates a complete replacement before atomically exchanging chunks. Failure leaves
+ * the last successful index intact. Older generations and divergent same-generation source
+ * identities are fenced; refreshing the same source is allowed. Source IDs must equal key IDs.
+ * withdraw retains a terminal tombstone that fences every later replacement for that key.
+ *
+ * Vectors match the profile dimensions and have positive finite squared norms. Chunks form a
+ * nonempty contiguous ordinal/byte sequence starting at zero, with unique passage IDs and exact
+ * UTF-8 byte ranges bounded by maxChunkBytes. Implementations snapshot mutable caller values.
+ *
+ * Bounded adapters count every source key, including tombstones, against capacity. Replacement
+ * capacity is measured after removing the old chunks. Search rejects scans over maxScannedChunks
+ * instead of ranking a truncated prefix. scannedChunks counts all indexed chunks in the namespace
+ * before threshold/limit. Ties sort by source ID, revision, then ordinal in UTF-16 code-unit order.
+ * Scope close clears the index and makes captured methods fail unavailable.
+ *
+ * Search is ranking only: callers MUST recheck authoritative revision, access, and withdrawal.
+ * This port tracks no builds, extraction progress, or corpus completeness. The host owns source
+ * discovery, refresh scheduling, and required freshness.
+ */
+export class SemanticMemoryIndex extends Context.Service<
+  SemanticMemoryIndex,
+  {
+    readonly profile: SemanticMemoryProfile;
+    readonly replace: <Namespace extends MemoryNamespace.Any>(
+      request: MemoryIndexReplacement<Namespace>,
+    ) => Effect.Effect<void, MemoryIndexError>;
+    readonly withdraw: <Namespace extends MemoryNamespace.Any>(
+      source: MemoryIndexSource<Namespace>,
+    ) => Effect.Effect<void, MemoryIndexError>;
+    readonly search: <Namespace extends MemoryNamespace.Any>(
+      query: MemoryIndexQuery<Namespace>,
+    ) => Effect.Effect<MemoryIndexSearch<Namespace>, MemoryIndexError>;
+  }
+>()("@effect-agent/core/SemanticMemoryIndex") {
+  static fromAdapter(adapter: {
+    readonly profile: SemanticMemoryProfile;
+    readonly replace: (request: MemoryIndexReplacement) => Effect.Effect<void, MemoryIndexError>;
+    readonly withdraw: (source: MemoryIndexSource) => Effect.Effect<void, MemoryIndexError>;
+    readonly search: (
+      query: MemoryIndexQuery,
+    ) => Effect.Effect<MemoryIndexSearch, MemoryIndexError>;
+  }): SemanticMemoryIndex["Service"] {
+    return {
+      ...adapter,
+      search: Effect.fn("SemanticMemoryIndex.search")(function* <
+        Namespace extends MemoryNamespace.Any,
+      >(query: MemoryIndexQuery<Namespace>) {
+        const result = yield* adapter.search(query);
+
+        const checked = yield* Schema.decodeEffect(MemoryIndexSearch.Wire)(result).pipe(
+          Effect.mapError(() =>
+            MemoryIndexError.make({ operation: "restore index search", reason: "corrupt" }),
+          ),
+        );
+
+        const candidates: Array<MemoryIndexCandidate<Namespace>> = [];
+
+        for (const candidate of checked.candidates) {
+          if (!MemoryNamespace.equals(candidate.key.namespace, query.namespace))
+            return yield* MemoryIndexError.make({
+              operation: "restore index namespace",
+              reason: "corrupt",
+            });
+          candidates.push(
+            MemoryIndexCandidate.make({
+              ...candidate,
+              key: MemoryKey.make({ ...candidate.key, namespace: query.namespace }),
+            }),
+          );
+        }
+
+        return MemoryIndexSearch.make({ ...checked, candidates });
+      }),
+    };
+  }
+}

package/src/core/SemanticMemoryRevalidation.ts

@@ -0,0 +1,254 @@
+import { Effect, Encoding, Schema } from "effect";
+
+import { utf8ByteLength as byteLength } from "./internal/utf8.ts";
+import { MemoryLookup, MemoryPassage } from "./MemoryReference.ts";
+import { MemoryAccess } from "./MemoryRevalidation.ts";
+import type { MemoryKey } from "./MemoryStore.ts";
+import { MemoryDocument, MemoryReader, MemoryStorageError } from "./MemoryStore.ts";
+import type { MemoryIndexCandidate } from "./SemanticMemoryIndex.ts";
+import {
+  MemoryIndexError,
+  MemoryIndexSearch,
+  SemanticMemoryProfile,
+} from "./SemanticMemoryIndex.ts";
+
+export class SemanticMemoryError extends Schema.TaggedError<SemanticMemoryError>()(
+  "SemanticMemoryError",
+  {
+    operation: Schema.NonEmptyString,
+    reason: Schema.Literals([
+      "invalid-input",
+      "invalid-embedding",
+      "budget",
+      "timeout",
+      "source-changed",
+      "unavailable",
+    ]),
+  },
+) {}
+
+export class SemanticCandidateLimits extends Schema.Class<SemanticCandidateLimits>(
+  "@effect-agent/core/SemanticCandidateLimits",
+)({
+  maxCandidates: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 128 })),
+  maxScannedChunks: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65_536 })),
+  maxSourceBytes: Schema.optionalKey(
+    Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 67_108_864 })),
+  ),
+  /** Aggregate UTF-8 JSON passage bytes, including repeated provenance; defaults to 16 MiB. */
+  maxOutputBytes: Schema.optionalKey(
+    Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 67_108_864 })),
+  ),
+  minScore: Schema.Finite.check(Schema.isBetween({ minimum: -1, maximum: 1 })),
+}) {}
+
+export class SemanticCandidateResult extends Schema.Class<SemanticCandidateResult>(
+  "@effect-agent/core/SemanticCandidateResult",
+)({
+  lookup: MemoryLookup,
+  scannedChunks: Schema.Natural,
+  staleExcluded: Schema.Natural,
+  unauthorizedExcluded: Schema.Natural,
+}) {}
+
+const readDocument = Effect.fn("semanticCandidates.readDocument")(function* (key: MemoryKey) {
+  const reader = yield* MemoryReader;
+
+  const document = yield* reader.get(key).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(Schema.NullOr(MemoryDocument.Wire))),
+    Effect.catchTag("SchemaError", () =>
+      Effect.fail(
+        MemoryStorageError.make({ operation: "validate semantic source", reason: "corrupt" }),
+      ),
+    ),
+  );
+
+  if (
+    document !== null &&
+    (document.key.namespace.address !== key.namespace.address ||
+      document.key.id !== key.id ||
+      document.source.id !== key.id)
+  )
+    return yield* MemoryStorageError.make({
+      operation: "validate semantic source identity",
+      reason: "corrupt",
+    });
+
+  return document;
+});
+
+/**
+ * Revalidate one ranked batch locally. No embedding or index access; stale scored text is excluded.
+ * Charge each accepted passage's full JSON encoding before retaining it, including duplicates and
+ * authoritative metadata/attribution. maxOutputBytes bounds their aggregate, not source reads or
+ * a transport envelope. One passage is constructed at a time before this check.
+ */
+export const revalidateSemanticMemoryCandidates = Effect.fn("revalidateSemanticMemoryCandidates")(
+  function* (
+    found: MemoryIndexSearch,
+    access: MemoryAccess,
+    profile: SemanticMemoryProfile,
+    limits: SemanticCandidateLimits,
+  ) {
+    const input = yield* Schema.decodeEffect(
+      Schema.Struct({
+        found: MemoryIndexSearch.Wire,
+        access: MemoryAccess.Wire,
+        profile: SemanticMemoryProfile,
+        limits: SemanticCandidateLimits,
+      }),
+    )({ found, access, profile, limits }).pipe(
+      Effect.mapError(() =>
+        MemoryIndexError.make({ operation: "validate candidates", reason: "corrupt" }),
+      ),
+    );
+
+    found = input.found;
+    access = input.access;
+    profile = input.profile;
+    limits = input.limits;
+    if (
+      found.candidates.length > limits.maxCandidates ||
+      found.scannedChunks > limits.maxScannedChunks ||
+      found.scannedChunks < found.candidates.length
+    ) {
+      return yield* MemoryIndexError.make({
+        operation: "validate candidate bounds",
+        reason: "corrupt",
+      });
+    }
+
+    const groups = new Map<
+      string,
+      {
+        readonly key: MemoryKey;
+        readonly candidates: Array<{
+          readonly rank: number;
+          readonly candidate: MemoryIndexCandidate;
+        }>;
+      }
+    >();
+
+    const rankedPassages: Array<{ readonly rank: number; readonly passage: MemoryPassage }> = [];
+    let staleExcluded = 0;
+    let unauthorizedExcluded = 0;
+
+    for (const [rank, candidate] of found.candidates.entries()) {
+      if (
+        candidate.key.namespace.address !== access.namespace.address ||
+        candidate.source.id !== candidate.key.id ||
+        candidate.score < limits.minScore
+      ) {
+        return yield* MemoryIndexError.make({
+          operation: "validate candidate identity",
+          reason: "corrupt",
+        });
+      }
+      const group = groups.get(candidate.key.id);
+
+      if (group === undefined) {
+        groups.set(candidate.key.id, { key: candidate.key, candidates: [{ rank, candidate }] });
+      } else group.candidates.push({ rank, candidate });
+    }
+    const maxSourceBytes = limits.maxSourceBytes ?? 16_777_216;
+    const maxOutputBytes = limits.maxOutputBytes ?? 16_777_216;
+    let sourceBytes = 0;
+    let outputBytes = 0;
+
+    for (const group of groups.values()) {
+      yield* Effect.yieldNow;
+      const document = yield* readDocument(group.key);
+
+      if (document === null || document._tag === "WithdrawnMemoryDocument") {
+        staleExcluded += group.candidates.length;
+        continue;
+      }
+      if (!document.scopes.includes(access.scope)) {
+        unauthorizedExcluded += group.candidates.length;
+        continue;
+      }
+
+      const current = group.candidates.filter(
+        ({ candidate }) =>
+          document.generation === candidate.sourceGeneration &&
+          document.source.revision === candidate.source.revision &&
+          document.source.locator === candidate.source.locator,
+      );
+
+      staleExcluded += group.candidates.length - current.length;
+      if (current.length === 0) continue;
+      const encoded = JSON.stringify(document);
+      const remainingSourceBytes = maxSourceBytes - sourceBytes;
+      const encodedBytes = encoded.length <= remainingSourceBytes ? byteLength(encoded) : undefined;
+
+      if (encodedBytes === undefined || encodedBytes > remainingSourceBytes) {
+        return yield* SemanticMemoryError.make({
+          operation: "query source bytes",
+          reason: "budget",
+        });
+      }
+      sourceBytes += encodedBytes;
+      const encodedDocument = Encoding.encodeHex(document.content.text);
+
+      for (const { rank, candidate } of current) {
+        if (!sameExcerpt(encodedDocument, candidate, profile.maxChunkBytes)) {
+          staleExcluded += 1;
+          continue;
+        }
+
+        const passage = MemoryPassage.make({
+          version: 1,
+          authority: access.namespace.address,
+          source: document.source,
+          passageId: candidate.passageId,
+          content: { ...document.content, text: candidate.text },
+        });
+
+        const encodedPassage = JSON.stringify(passage);
+        const remainingOutputBytes = maxOutputBytes - outputBytes;
+
+        const passageBytes =
+          encodedPassage.length <= remainingOutputBytes ? byteLength(encodedPassage) : undefined;
+
+        if (passageBytes === undefined || passageBytes > remainingOutputBytes) {
+          return yield* SemanticMemoryError.make({
+            operation: "query output bytes",
+            reason: "budget",
+          });
+        }
+        outputBytes += passageBytes;
+        rankedPassages.push({ rank, passage });
+      }
+    }
+
+    const passages = rankedPassages
+      .sort((left, right) => left.rank - right.rank)
+      .map(({ passage }) => passage);
+
+    return SemanticCandidateResult.make({
+      lookup: passages.length === 0 ? { _tag: "NoMatch" } : { _tag: "Found", passages },
+      scannedChunks: found.scannedChunks,
+      staleExcluded,
+      unauthorizedExcluded,
+    });
+  },
+);
+
+const sameExcerpt = (
+  encodedDocument: string,
+  candidate: {
+    readonly startByte: number;
+    readonly endByte: number;
+    readonly text: string;
+  },
+  maxChunkBytes: number,
+): boolean => {
+  const hex = Encoding.encodeHex(candidate.text);
+
+  return (
+    candidate.startByte < candidate.endByte &&
+    hex.length / 2 === candidate.endByte - candidate.startByte &&
+    hex.length / 2 <= maxChunkBytes &&
+    encodedDocument.slice(candidate.startByte * 2, candidate.endByte * 2) === hex
+  );
+};

package/src/core/SubagentContract.ts

@@ -0,0 +1,196 @@
+import { Context, Schema } from "effect";
+
+import { AgentId, ThreadId, DelegationId, RunId, ToolCallId, SubmissionId } from "./Identifiers.ts";
+
+const Natural = Schema.Natural;
+
+/** Tree authority ceiling. Each child exposes only its own Toolkit's permitted names. */
+export class SubagentGrant extends Schema.Class<SubagentGrant>(
+  "@effect-agent/capabilities/SubagentGrant",
+)({
+  allowedToolNames: Schema.Array(Schema.NonEmptyString).check(Schema.isMaxLength(128)),
+  maxDepth: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 16 })),
+  /** Omitted permits either lifetime within the depth and reserved subtree budgets. */
+  childLifetimes: Schema.optionalKey(
+    Schema.Array(Schema.Literals(["attached", "background"])).check(Schema.isMaxLength(2)),
+  ),
+}) {}
+
+/** Intersect inherited authority; another delegation can never restore a removed capability. */
+export const narrowSubagentGrant = (
+  declared: SubagentGrant,
+  inherited?: SubagentGrant,
+): SubagentGrant =>
+  inherited === undefined
+    ? declared
+    : SubagentGrant.make({
+        allowedToolNames: declared.allowedToolNames.filter((name) =>
+          inherited.allowedToolNames.includes(name),
+        ),
+        maxDepth: Math.min(declared.maxDepth, inherited.maxDepth),
+        childLifetimes: (declared.childLifetimes ?? ["attached", "background"]).filter((lifetime) =>
+          (inherited.childLifetimes ?? ["attached", "background"]).includes(lifetime),
+        ),
+      });
+
+/** Finite delegable caps for one parent Run. Absent means not configured; present values are finite. */
+export class SubagentDelegationCaps extends Schema.Class<SubagentDelegationCaps>(
+  "@effect-agent/capabilities/SubagentDelegationCaps",
+)({
+  maxTotalChildInvocations: Schema.optionalKey(Natural),
+  maxConcurrentChildren: Schema.optionalKey(Natural),
+  maxTurns: Schema.optionalKey(Natural),
+  maxToolCalls: Schema.optionalKey(Natural),
+  maxDurationMillis: Schema.optionalKey(Natural),
+  maxInputTokens: Schema.optionalKey(Natural),
+  maxOutputTokens: Schema.optionalKey(Natural),
+  maxCostMicrousd: Schema.optionalKey(Natural),
+  maxResultBytes: Schema.optionalKey(Natural),
+}) {}
+
+const AmountFields = {
+  turns: Natural,
+  toolCalls: Natural,
+  durationMillis: Natural,
+  inputTokens: Natural,
+  outputTokens: Natural,
+  costMicrousd: Natural,
+  resultBytes: Natural,
+} as const;
+
+/** Exact amounts across every reservable delegation dimension. */
+export class SubagentReservationAmounts extends Schema.Class<SubagentReservationAmounts>(
+  "@effect-agent/capabilities/SubagentReservationAmounts",
+)(AmountFields) {}
+
+/** One child reservation against the parent Run's shared delegation pool. */
+export const SubagentBudgetReservation = Schema.Struct({
+  caps: SubagentDelegationCaps,
+  allocation: SubagentReservationAmounts,
+  /** Slots reserved for every descendant input beneath this input; absent reserves none. */
+  descendantInvocations: Schema.optionalKey(Natural),
+});
+
+export type SubagentBudgetReservation = typeof SubagentBudgetReservation.Type;
+
+/** Root-relative delegation depth; the direct child of a top-level run has depth 1. */
+export const DelegationDepth = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export type DelegationDepth = typeof DelegationDepth.Type;
+
+/** @deprecated Names are application-owned; use DelegationTool metadata for classification. */
+export const delegationToolPrefix = "delegate_";
+
+/** @deprecated Checks a legacy spelling only, never execution, nesting or recovery semantics. */
+export const isDelegationToolName = (toolName: string): boolean =>
+  toolName.startsWith(delegationToolPrefix);
+
+/** Marks a Tool implementing the idempotent Subagent establishment protocol. */
+export const DelegationTool = Context.Reference<boolean>("@effect-agent/core/DelegationTool", {
+  defaultValue: () => false,
+});
+
+/** Marks a host-managed idempotent worker operation, independently of its Tool name. */
+export const WorkerOperationTool = Context.Reference<boolean>(
+  "@effect-agent/core/WorkerOperationTool",
+  {
+    defaultValue: () => false,
+  },
+);
+
+/** Identifies the background launch operation within a generated management Toolkit. */
+export const BackgroundSpawnTool = Context.Reference<boolean>(
+  "@effect-agent/core/BackgroundSpawnTool",
+  {
+    defaultValue: () => false,
+  },
+);
+
+/** Declaration metadata and inherited authority determine the effective visible Tool set. */
+export const isSubagentToolAllowed = (
+  grant: SubagentGrant | undefined,
+  depth: number,
+  name: string,
+  annotations: Context.Context<never>,
+): boolean =>
+  grant === undefined ||
+  (grant.allowedToolNames.includes(name) &&
+    (Context.get(annotations, BackgroundSpawnTool)
+      ? depth < grant.maxDepth &&
+        (grant.childLifetimes ?? ["attached", "background"]).includes("background")
+      : Context.get(annotations, DelegationTool)
+        ? depth < grant.maxDepth &&
+          (grant.childLifetimes ?? ["attached", "background"]).includes("attached")
+        : true));
+
+/** Persisted preparation classification, checked against the resolved Tool before replay. */
+export const ToolExecutionKind = Schema.Literals(["ordinary", "delegation", "orchestration"]);
+export type ToolExecutionKind = typeof ToolExecutionKind.Type;
+
+/** Resolve only trusted declaration metadata; names never authorize automatic replay. */
+export const getToolExecutionKind = (annotations: Context.Context<never>): ToolExecutionKind =>
+  Context.get(annotations, WorkerOperationTool)
+    ? "orchestration"
+    : Context.get(annotations, DelegationTool)
+      ? "delegation"
+      : "ordinary";
+
+/** Immutable lineage from a child Thread to the parent identity that established it. */
+export class SubagentParentLink extends Schema.Class<SubagentParentLink>("SubagentParentLink")({
+  delegationId: DelegationId,
+  parentAgentId: AgentId,
+  parentThreadId: ThreadId,
+  parentRunId: RunId,
+  parentToolCallId: ToolCallId,
+  depth: DelegationDepth,
+}) {}
+
+/**
+ * Classification of one bounded durable delegation failure.
+ * `"child-failed"` and `"child-aborted"` project the
+ * child's canonical failed/aborted Settlement; `"child-compatibility"`
+ * projects the framework's `ChildCompatibilityFailure` child Settlement (the
+ * stored child Binding digest was unavailable — recovery never substituted
+ * current code); `"establishment-denied"` is a fail-closed coordinator
+ * refusal (lineage/digest verification, divergent replay); and
+ * `"declaration-unavailable"` is retained for decoding failures recorded by
+ * versions that required an explicit durable digest declaration.
+ */
+export const SubagentExecutionFailureClassification = Schema.Literals([
+  "child-failed",
+  "child-aborted",
+  "child-compatibility",
+  "establishment-denied",
+  "declaration-unavailable",
+]);
+
+export type SubagentExecutionFailureClassification =
+  typeof SubagentExecutionFailureClassification.Type;
+
+export const maxErrorTagLength = 256;
+const BoundedErrorTag = Schema.NonEmptyString.check(Schema.isMaxLength(maxErrorTagLength));
+
+/**
+ * Bounded framework projection of a durable child failure, shared by attached joins and reports.
+ * A failed or aborted durable child
+ * joins its parent Tool Call as exactly this typed failure: a classification,
+ * the child references, and the coordinator's bounded `{errorTag, message}`
+ * projection — never a raw Cause, stack, provider response, secret, or child
+ * payload. The typed child failure union does not survive a durable
+ * Settlement, so `mapChildFailure` remains the ephemeral-path contract;
+ * Schema-declared durable domain-failure mapping is a recorded later
+ * extension.
+ */
+export class SubagentExecutionFailure extends Schema.TaggedError<SubagentExecutionFailure>()(
+  "SubagentExecutionFailure",
+  {
+    delegationId: DelegationId,
+    targetAgentId: AgentId,
+    classification: SubagentExecutionFailureClassification,
+    /** Child references, present once establishment reached a child identity. */
+    childThreadId: Schema.optionalKey(ThreadId),
+    childSubmissionId: Schema.optionalKey(SubmissionId),
+    childRunId: Schema.optionalKey(RunId),
+    errorTag: BoundedErrorTag,
+    message: Schema.String.check(Schema.isMaxLength(4 * 1024)),
+  },
+) {}