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

package/src/engine/internal/error-diagnostic.ts

@@ -0,0 +1,39 @@
+const DIAGNOSTIC_MESSAGE_LIMIT = 4_096;
+const DIAGNOSTIC_TAG_LIMIT = 128;
+
+const boundedDiagnostic = (value: string, maxCharacters: number): string =>
+  value.length <= maxCharacters ? value : value.slice(0, maxCharacters);
+
+const ownStringDiagnostic = (
+  input: unknown,
+  key: "message" | "_tag",
+  maxCharacters: number,
+): string | undefined => {
+  if (input === null || (typeof input !== "object" && typeof input !== "function")) {
+    return undefined;
+  }
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+
+    return descriptor !== undefined && "value" in descriptor && typeof descriptor.value === "string"
+      ? boundedDiagnostic(descriptor.value, maxCharacters)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Total, bounded projection for opaque failures. It never invokes arbitrary coercion hooks. */
+export const errorMessage = (error: unknown): string => {
+  const message = ownStringDiagnostic(error, "message", DIAGNOSTIC_MESSAGE_LIMIT);
+
+  if (message !== undefined) return message;
+
+  return typeof error === "string"
+    ? boundedDiagnostic(error, DIAGNOSTIC_MESSAGE_LIMIT)
+    : "Unknown error";
+};
+
+/** Total, bounded tag projection for opaque failures. */
+export const errorTag = (error: unknown): string =>
+  ownStringDiagnostic(error, "_tag", DIAGNOSTIC_TAG_LIMIT) ?? "UnknownError";

package/src/engine/internal/output-contract.ts

@@ -0,0 +1,173 @@
+import { Schema } from "effect";
+import { Prompt, Tool } from "effect/unstable/ai";
+
+import type * as Agent from "../../core/Agent.ts";
+
+const outputFormatAnnotation = "@effect-agent/engine/Output/format";
+
+/**
+ * Declare ordinary assistant text as an Agent's final-output wire format. Apply this to the
+ * complete output Schema after composing transformations. Its encoded type must be string;
+ * decoding, checks, transformations, and service requirements remain owned by that Schema.
+ * Text is preserved verbatim, including whitespace, quotes, and an empty reply when allowed.
+ * Required completion Tools still take precedence. Unmarked Schemas use JSON final output.
+ *
+ * @example
+ * ```ts
+ * output: Output.text(Schema.String.check(Schema.isMaxLength(20_000)))
+ * ```
+ */
+export const textOutput = <S extends Schema.Top & { readonly Encoded: string }>(
+  schema: S,
+): S["Rebuild"] => schema.annotate({ [outputFormatAnnotation]: "text" });
+
+export const isTextOutput = (schema: Schema.Top): boolean =>
+  Schema.resolveAnnotations(schema)?.[outputFormatAnnotation] === "text";
+
+/**
+ * Model-visible final-output contract (RUN-028).
+ *
+ * For ordinary text completion, the interpreter's only output-conformance
+ * point is `decodeFinalOutput`, which validates the final text after the
+ * model has already finished. This module renders that Schema's wire contract
+ * with the same Effect AI derivation the providers use for Tool parameters
+ * and states it as one framework-owned system message on every model request.
+ * A required completion Tool instead gets a native-tool directive: its Tool
+ * parameter Schema is already carried by the provider request, and ordinary
+ * final text is not an allowed completion path.
+ *
+ * The contract is a per-request projection of the immutable definition —
+ * exactly like the Tool schemas the request already carries. It is inserted
+ * at model-request materialization (after context preparation) and never
+ * into official history, so canonical records, run events, and the committed
+ * DN/DC golden are unchanged.
+ *
+ */
+
+/** Rendering outcome for one definition's output Schema. */
+type OutputContract =
+  | {
+      readonly _tag: "rendered";
+      /** The complete system-message text: directive plus the derived JSON Schema. */
+      readonly message: string;
+      readonly part: Prompt.SystemMessage;
+    }
+  | {
+      readonly _tag: "unrenderable";
+      /** Why Effect AI's JSON-Schema derivation rejected the output Schema. */
+      readonly reason: string;
+    };
+
+const contractDirective = (definition: Agent.AnyDefinition): string =>
+  definition.completion === undefined
+    ? "Final output contract: when the task is complete, the final assistant message must be only " +
+      "JSON that is valid against this JSON Schema — no prose, no Markdown code fences, nothing " +
+      "before or after the JSON."
+    : `Final output contract: when the task is complete without calling the "${definition.completion.tool}" completion Tool, the final assistant message must be only ` +
+      "JSON that is valid against this JSON Schema — no prose, no Markdown code fences, nothing " +
+      `before or after the JSON. When calling the "${definition.completion.tool}" completion Tool, never place this private Agent output JSON in any Tool argument; follow the Tool's parameter schema instead. Call it as the sole application Tool Call, after receiving any other needed application Tool results. Completed provider Tool results may accompany it. The engine projects the successful completion Tool result into the Agent output.`;
+
+const requiredCompletionDirective = (tool: string, hasAlternatives: boolean): string =>
+  `Final output contract: ${hasAlternatives ? "otherwise complete" : "complete only"} by calling the required completion Tool ${JSON.stringify(tool)} ` +
+  "as the sole application Tool Call in its batch. Completed provider Tool results may accompany it. Do not emit an ordinary final assistant text answer. " +
+  "The Tool's canonical parameters and successful result are projected and validated as the Agent output.";
+
+/**
+ * Render the model-visible final-output contract for one definition. The
+ * derivation and message identity are stable for an immutable definition.
+ * An output Schema the Effect AI derivation cannot represent is reported as
+ * `unrenderable`; the caller falls back to the prior behavior — the contract
+ * is guidance, and a Schema that decodes but does not render must not become
+ * a new failure mode.
+ */
+const rendered = (message: string): OutputContract => ({
+  _tag: "rendered",
+  message,
+  part: Prompt.makeMessage("system", { content: message }),
+});
+
+const renderOutputSchemaContract = (definition: Agent.AnyDefinition): OutputContract => {
+  if (definition.completion?.required === true) {
+    return rendered(
+      requiredCompletionDirective(
+        definition.completion.tool,
+        (definition.completionFromTools?.length ?? 0) > 0,
+      ),
+    );
+  }
+  if (isTextOutput(definition.output)) {
+    return rendered(
+      "Final output contract: write the final reply as ordinary assistant text, without JSON wrapping. " +
+        "An empty reply is valid only when allowed by the output Schema and the task instructions." +
+        (definition.completion === undefined
+          ? ""
+          : ` When calling the "${definition.completion.tool}" completion Tool, follow its parameter schema instead and call it as the sole application Tool Call, after receiving any other needed application Tool results; completed provider Tool results may accompany it; the engine projects its successful result into the Agent output.`),
+    );
+  }
+  try {
+    const jsonSchema = Tool.getJsonSchemaFromSchema(definition.output);
+
+    return rendered(
+      `${contractDirective(definition)}\n\n${JSON.stringify(jsonSchema, undefined, 2)}`,
+    );
+  } catch (cause) {
+    return {
+      _tag: "unrenderable",
+      reason: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+};
+
+// Native incremental-response tracking recognizes message objects, not rendered text.
+// Weak keys retain neither discarded definitions nor their Schema graphs.
+const outputContracts = new WeakMap<Agent.AnyDefinition, OutputContract>();
+
+export const outputSchemaContract = (definition: Agent.AnyDefinition): OutputContract => {
+  const cached = outputContracts.get(definition);
+
+  if (cached !== undefined) return cached;
+  const base = renderOutputSchemaContract(definition);
+  const alternatives = definition.completionFromTools ?? [];
+
+  const contract =
+    base._tag === "rendered" && alternatives.length > 0
+      ? rendered(
+          `The following action Tools may complete the Run from their successful canonical result: ${alternatives.map((declaration) => JSON.stringify(declaration.tool)).join(", ")}. ` +
+            "Call such a Tool as the sole application Tool Call, following its parameter schema. Completed provider Tool results may accompany it. It may complete the Run only when it satisfies the whole request. " +
+            "An incomplete or pending result continues the Run. These actions are unavailable during finalization after budget exhaustion.\n\n" +
+            base.message,
+        )
+      : base;
+
+  outputContracts.set(definition, contract);
+
+  return contract;
+};
+
+/**
+ * Insert the contract immediately after the request prompt's last system
+ * message (position 0 when none exists), extending the last contiguous
+ * system block. Placement is normative: the Anthropic provider replaces its
+ * top-level `system` parameter per contiguous system group, so only the last
+ * block survives there — an isolated trailing contract message would discard
+ * the author's instructions, and a contract inside an earlier block (for
+ * example a resumed Thread's original instructions ahead of this Run's
+ * evaluated instructions) would itself be discarded. Extending the last
+ * block keeps author content and contract together on every provider and
+ * preserves the author's per-message cache-control annotations.
+ */
+export const insertOutputContract = (
+  prompt: Prompt.Prompt,
+  message: Prompt.SystemMessage,
+): Prompt.Prompt => {
+  const content = prompt.content;
+  let insertAt = 0;
+
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index]?.role === "system") {
+      insertAt = index + 1;
+    }
+  }
+
+  return Prompt.fromMessages([...content.slice(0, insertAt), message, ...content.slice(insertAt)]);
+};

package/src/engine/internal/primitive-delta.ts

@@ -0,0 +1,80 @@
+import { Option, Schema } from "effect";
+import { Response } from "effect/unstable/ai";
+
+import { utf8ByteLength } from "../../core/internal/utf8.ts";
+import { boundedValueFootprint } from "./bounded-value.ts";
+
+const brand = "~effect/ai/Content/Part";
+const keys = [brand, "type", "id", "delta", "metadata"];
+
+const decode = Schema.decodeUnknownOption(
+  Schema.toType(Schema.Union([Response.TextDeltaPart, Response.ReasoningDeltaPart])),
+);
+
+const overhead = (type: "text-delta" | "reasoning-delta") => ({
+  source: boundedValueFootprint(
+    Response.makePart(type, { id: "", delta: "" }),
+    Number.MAX_SAFE_INTEGER,
+  ),
+  encoded: boundedValueFootprint(
+    { type, id: "", delta: "", metadata: {} },
+    Number.MAX_SAFE_INTEGER,
+  ),
+});
+
+const overheads = {
+  "text-delta": overhead("text-delta"),
+  "reasoning-delta": overhead("reasoning-delta"),
+};
+
+/**
+ * Copy the common primitive delta into owned data before native Schema validation.
+ * Descriptor checks select this optimization; they do not replace the native codec.
+ * Extra fields, accessors, and nonempty metadata use the general ownership path.
+ * No provider object survives, including an empty metadata object's hidden storage.
+ * Unlike a generic footprint shortcut, this cannot retain an exotic backing buffer.
+ */
+export const ownPrimitiveDelta = (part: unknown, maxBytes: number) => {
+  try {
+    if (part === null || typeof part !== "object") return undefined;
+    if (Array.isArray(part) || ArrayBuffer.isView(part)) return undefined;
+    const prototype = Object.getPrototypeOf(part);
+
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    if (Reflect.ownKeys(part).length !== keys.length) return undefined;
+    const snapshot: Record<string, unknown> = {};
+
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(part, key);
+
+      if (descriptor === undefined || !("value" in descriptor)) return undefined;
+      snapshot[key] = descriptor.value;
+    }
+    const { type, id, delta, metadata } = snapshot;
+
+    if (type !== "text-delta" && type !== "reasoning-delta") return undefined;
+    if (typeof id !== "string" || typeof delta !== "string") return undefined;
+    if (metadata === null || typeof metadata !== "object") return undefined;
+    if (Array.isArray(metadata) || ArrayBuffer.isView(metadata)) return undefined;
+    const metadataPrototype = Object.getPrototypeOf(metadata);
+
+    if (metadataPrototype !== Object.prototype && metadataPrototype !== null) return undefined;
+    if (Reflect.ownKeys(metadata).length !== 0) return undefined;
+    const fixed = overheads[type];
+
+    if (fixed.source === undefined || fixed.encoded === undefined) return undefined;
+    const bytes = utf8ByteLength(id) + utf8ByteLength(delta);
+
+    if (bytes + fixed.source > maxBytes || bytes + fixed.encoded > maxBytes) return undefined;
+    // Never pass the provider's metadata object (or any other object) to the decoder.
+    snapshot.metadata = {};
+    const validated = decode(snapshot);
+
+    if (Option.isNone(validated)) return undefined;
+
+    return { ownedPart: validated.value, retainedBytes: bytes + fixed.encoded };
+  } catch {
+    // Reflection may throw for proxies. The general path owns the typed failure.
+    return undefined;
+  }
+};

package/src/engine/internal/provider-result-staging.ts

@@ -0,0 +1,211 @@
+import type { Schema } from "effect";
+
+const MAX_JSON_DEPTH = 128;
+
+export interface BoundedJsonSnapshot {
+  readonly value: Schema.Json;
+  readonly bytes: number;
+}
+
+const FailedSnapshot = Symbol("@effect-agent/engine/FailedProviderResultSnapshot");
+
+/**
+ * @internal Normalize one untrusted JSON value into an owned, frozen snapshot while counting the
+ * exact UTF-8 bytes of that same snapshot. The traversal never invokes `toJSON` or accessors,
+ * rejects non-plain objects and excessive nesting, and stops as soon as the byte budget is spent.
+ */
+const snapshotJson = (
+  root: unknown,
+  maxBytes: number,
+  maxDepth: number,
+  rejectNonFiniteNumbers: boolean,
+): BoundedJsonSnapshot | undefined => {
+  if (
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < 0 ||
+    !Number.isSafeInteger(maxDepth) ||
+    maxDepth < 0
+  ) {
+    return undefined;
+  }
+  let total = 0;
+  const ancestors = new WeakSet<object>();
+
+  const add = (bytes: number): boolean => {
+    if (bytes > maxBytes - total) return false;
+    total += bytes;
+
+    return true;
+  };
+
+  const addString = (value: string): boolean => {
+    if (!add(2)) return false;
+    for (let index = 0; index < value.length; index += 1) {
+      const code = value.charCodeAt(index);
+
+      if (code === 0x22 || code === 0x5c) {
+        if (!add(2)) return false;
+      } else if (code <= 0x1f) {
+        // Backspace, tab, newline, form-feed, and carriage-return use two-byte escapes; all other
+        // control characters use a six-byte `\\u00xx` escape.
+        if (!add(code >= 0x08 && code <= 0x0d && code !== 0x0b ? 2 : 6)) return false;
+      } else if (code <= 0x7f) {
+        if (!add(1)) return false;
+      } else if (code <= 0x7ff) {
+        if (!add(2)) return false;
+      } else if (code >= 0xd800 && code <= 0xdbff) {
+        const low = value.charCodeAt(index + 1);
+
+        if (low >= 0xdc00 && low <= 0xdfff) {
+          if (!add(4)) return false;
+          index += 1;
+        } else if (!add(6)) {
+          return false;
+        }
+      } else if (code >= 0xdc00 && code <= 0xdfff) {
+        if (!add(6)) return false;
+      } else if (!add(3)) {
+        return false;
+      }
+    }
+
+    return true;
+  };
+
+  const visit = (value: unknown, depth: number): Schema.Json | typeof FailedSnapshot => {
+    if (depth > maxDepth) return FailedSnapshot;
+    if (value === null) return add(4) ? null : FailedSnapshot;
+    switch (typeof value) {
+      case "string":
+        return addString(value) ? value : FailedSnapshot;
+      case "boolean":
+        return add(value ? 4 : 5) ? value : FailedSnapshot;
+      case "number": {
+        // JSON's numeric representation is inherently bounded for one IEEE-754 value. Retain the
+        // wire-equivalent null for non-finite values so counting and later serialization agree.
+        if (!Number.isFinite(value)) {
+          return rejectNonFiniteNumbers ? FailedSnapshot : add(4) ? null : FailedSnapshot;
+        }
+        const encoded = JSON.stringify(value);
+
+        return encoded !== undefined && add(encoded.length) ? value : FailedSnapshot;
+      }
+      case "object": {
+        if (ancestors.has(value)) return FailedSnapshot;
+        const isArray = Array.isArray(value);
+        const prototype = Object.getPrototypeOf(value);
+
+        if (prototype !== (isArray ? Array.prototype : Object.prototype) && prototype !== null) {
+          return FailedSnapshot;
+        }
+        if (
+          Object.getOwnPropertyDescriptor(value, "toJSON") !== undefined ||
+          (prototype !== null && Object.getOwnPropertyDescriptor(prototype, "toJSON") !== undefined)
+        ) {
+          return FailedSnapshot;
+        }
+        ancestors.add(value);
+        try {
+          if (isArray) {
+            const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+
+            if (
+              lengthDescriptor === undefined ||
+              !("value" in lengthDescriptor) ||
+              typeof lengthDescriptor.value !== "number" ||
+              !Number.isSafeInteger(lengthDescriptor.value) ||
+              lengthDescriptor.value < 0
+            ) {
+              return FailedSnapshot;
+            }
+            if (!add(1)) return FailedSnapshot;
+            const snapshot: Array<Schema.Json> = [];
+
+            for (let index = 0; index < lengthDescriptor.value; index += 1) {
+              if (index > 0 && !add(1)) return FailedSnapshot;
+              const descriptor = Object.getOwnPropertyDescriptor(value, index);
+
+              if (descriptor === undefined) {
+                if (!add(4)) return FailedSnapshot;
+                snapshot.push(null);
+                continue;
+              }
+              if (!("value" in descriptor)) return FailedSnapshot;
+              const item = visit(descriptor.value, depth + 1);
+
+              if (item === FailedSnapshot) return FailedSnapshot;
+              snapshot.push(item);
+            }
+            if (!add(1)) return FailedSnapshot;
+            Object.setPrototypeOf(snapshot, null);
+
+            return Object.freeze(snapshot);
+          }
+          if (!add(1)) return FailedSnapshot;
+          const entries: Array<readonly [string, Schema.Json]> = [];
+          let first = true;
+
+          for (const key in value) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+
+            if (descriptor === undefined || !descriptor.enumerable) continue;
+            if (!("value" in descriptor)) return FailedSnapshot;
+            if (!first && !add(1)) return FailedSnapshot;
+            first = false;
+            if (!addString(key) || !add(1)) return FailedSnapshot;
+            const item = visit(descriptor.value, depth + 1);
+
+            if (item === FailedSnapshot) return FailedSnapshot;
+            entries.push([key, item]);
+          }
+          if (!add(1)) return FailedSnapshot;
+          const snapshot: Record<string, Schema.Json> = Object.fromEntries(entries);
+
+          Object.setPrototypeOf(snapshot, null);
+
+          return Object.freeze(snapshot);
+        } finally {
+          ancestors.delete(value);
+        }
+      }
+      case "bigint":
+      case "function":
+      case "symbol":
+      case "undefined":
+        return FailedSnapshot;
+    }
+
+    return FailedSnapshot;
+  };
+
+  try {
+    const value = visit(root, 0);
+
+    return value === FailedSnapshot ? undefined : { value, bytes: total };
+  } catch {
+    // Revoked or adversarial proxies and reflection failures are protocol-invalid, never trusted.
+    return undefined;
+  }
+};
+
+/**
+ * Normalize provider-owned JSON using JSON serialization's `NaN`/infinity to
+ * `null` behavior. Provider events use this form so byte accounting matches
+ * their eventual JSON representation.
+ */
+export const boundedJsonSnapshot = (
+  root: unknown,
+  maxBytes: number,
+  maxDepth = MAX_JSON_DEPTH,
+): BoundedJsonSnapshot | undefined => snapshotJson(root, maxBytes, maxDepth, false);
+
+/**
+ * Validate canonical JSON without repairing non-finite numbers. Recovery
+ * inputs use this form because changing a recorded value would fabricate
+ * history.
+ */
+export const boundedCanonicalJsonSnapshot = (
+  root: unknown,
+  maxBytes: number,
+  maxDepth = MAX_JSON_DEPTH,
+): BoundedJsonSnapshot | undefined => snapshotJson(root, maxBytes, maxDepth, true);

package/src/engine/internal/tool-derivative.ts

@@ -0,0 +1,106 @@
+import { Cause, Effect, ErrorReporter, Exit, Stream } from "effect";
+
+import type { RunToolFailureObserver, ToolFailureObservation } from "../RunOptions.ts";
+
+/** @internal Only the explicitly installed trusted observer sees this live value. */
+export const deliverToolFailure = (
+  observer: RunToolFailureObserver,
+  observation: ToolFailureObservation,
+): Effect.Effect<void> =>
+  isolateToolDerivative(Effect.suspend(() => observer.observe(observation)));
+
+/**
+ * Report failures of derivative work without consuming external interruption. Reporter defects
+ * are isolated too. Neither observer delivery nor telemetry owns the authoritative Tool outcome.
+ */
+const reportDerivativeCause = <E>(cause: Cause.Cause<E>): Effect.Effect<void> => {
+  const reportableReasons: Array<Cause.Reason<E>> = [];
+  const interruptionReasons: Array<Cause.Interrupt> = [];
+
+  for (const reason of cause.reasons) {
+    if (Cause.isInterruptReason(reason)) interruptionReasons.push(reason);
+    else reportableReasons.push(reason);
+  }
+
+  const reportExit =
+    reportableReasons.length === 0
+      ? Effect.succeed(Exit.succeed(undefined))
+      : Effect.exit(ErrorReporter.report(Cause.fromReasons(reportableReasons)));
+
+  return Effect.flatMap(reportExit, (exit) => {
+    if (Exit.isFailure(exit)) {
+      for (const reason of exit.cause.reasons) {
+        if (Cause.isInterruptReason(reason)) interruptionReasons.push(reason);
+      }
+    }
+
+    return interruptionReasons.length === 0
+      ? Effect.void
+      : Effect.failCause(Cause.fromReasons<never>(interruptionReasons));
+  });
+};
+
+/** @internal Isolate reporting defects independently of Logger/Tracer configuration. */
+export const isolateToolDerivative = <R>(
+  effect: Effect.Effect<void, never, R>,
+): Effect.Effect<void, never, R> => effect.pipe(Effect.catchCause(reportDerivativeCause));
+
+/**
+ * @internal Emit one authoritative value, then run derivative work from either the next pull or
+ * structured finalization on early close. Telemetry and application observation share this one
+ * owner. A started action is never retried after interruption.
+ */
+export const emitThenAfter = <A, E, R, E2, R2>(
+  event: Effect.Effect<A, E, R>,
+  after: Effect.Effect<void, E2, R2>,
+): Stream.Stream<A, E | E2, R | R2> =>
+  Stream.unwrap(
+    Effect.sync(() => {
+      let firstPull = true;
+      let afterPhase: "unarmed" | "pending" | "running" | "completed" = "unarmed";
+
+      const runAfter = Effect.suspend((): Effect.Effect<void, E2, R2> => {
+        if (afterPhase !== "pending") return Effect.void;
+        afterPhase = "running";
+
+        return after.pipe(
+          Effect.onExit(() =>
+            Effect.sync(() => {
+              afterPhase = "completed";
+            }),
+          ),
+        );
+      });
+
+      const pull = Effect.suspend(
+        (): Effect.Effect<readonly [A], E | E2 | Cause.Done<void>, R | R2> => {
+          if (firstPull) {
+            return Effect.map(event, (value) => {
+              firstPull = false;
+              afterPhase = "pending";
+
+              return [value] as const;
+            });
+          }
+
+          return Effect.andThen(runAfter, Cause.done());
+        },
+      );
+
+      return Stream.fromPull(Effect.succeed(pull)).pipe(
+        Stream.ensuring(
+          // A typed `after` failure remains visible to an ordinary second pull. Cleanup owns
+          // only early close; capture its Exit after terminal annotation. The isolated Tool span
+          // derives its export status from that annotation even if cleanup consumes the private
+          // span marker. External interruption still escapes.
+          Effect.exit(Effect.interruptible(runAfter)).pipe(
+            Effect.flatMap((exit) => {
+              if (Exit.isSuccess(exit)) return Effect.void;
+
+              return reportDerivativeCause(exit.cause);
+            }),
+          ),
+        ),
+      );
+    }),
+  );