effect-agent 0.1.0-beta.9 → 0.1.0-beta.91

package/src/core/Thread.ts

@@ -0,0 +1,371 @@
+import { Clock, Context, DateTime, Effect, Layer, Schema, SynchronizedRef } from "effect";
+import { Prompt } from "effect/unstable/ai";
+
+import { ThreadId, RunId } from "./Identifiers.ts";
+import { utf8ByteLength } from "./internal/utf8.ts";
+
+/** Bound applied to one text projection before it can enter a model context. */
+export const ThreadText = Schema.String.check(Schema.isMaxLength(64 * 1024));
+const MAX_THREAD_MESSAGES = 1_024;
+const MAX_THREAD_CONTENT_BYTES = 4 * 1024 * 1024;
+const MAX_THREADS = 256;
+const MAX_STORE_CONTENT_BYTES = 64 * 1024 * 1024;
+
+/** One append-only native Effect AI message in a conversation. */
+export class ThreadMessage extends Schema.Class<ThreadMessage>(
+  "@effect-agent/capabilities/ThreadMessage",
+)({
+  threadId: ThreadId,
+  sequence: Schema.Natural,
+  runId: Schema.optionalKey(RunId),
+  message: Prompt.Message,
+  encodedBytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_THREAD_CONTENT_BYTES)),
+  timestamp: Schema.DateTimeUtcFromString,
+}) {}
+
+/** An identified, ordered conversation snapshot. Storage and execution recovery are separate concerns. */
+export class Thread extends Schema.Class<Thread>("@effect-agent/capabilities/ThreadSnapshot")({
+  version: Schema.Literal(1),
+  threadId: ThreadId,
+  nextSequence: Schema.Natural,
+  contentBytes: Schema.Natural.check(Schema.isLessThanOrEqualTo(MAX_THREAD_CONTENT_BYTES)),
+  messages: Schema.Array(ThreadMessage).check(Schema.isMaxLength(MAX_THREAD_MESSAGES)),
+}) {}
+
+/** Portable conversation snapshot. Its format is independent of the durable execution journal. */
+export class ThreadExport extends Schema.Class<ThreadExport>(
+  "@effect-agent/capabilities/ThreadExport",
+)({
+  format: Schema.Literal("effect-agent/ephemeral-thread@1"),
+  exportedAt: Schema.DateTimeUtcFromString,
+  snapshot: Thread,
+}) {}
+
+/** Native message accepted by the append-only thread. */
+export class ThreadAppend extends Schema.Class<ThreadAppend>(
+  "@effect-agent/capabilities/ThreadAppend",
+)({
+  runId: Schema.optionalKey(RunId),
+  message: Prompt.Message,
+}) {}
+
+/** The requested Thread has not been created in this store. */
+export class ThreadNotFound extends Schema.TaggedError<ThreadNotFound>()("ThreadNotFound", {
+  threadId: ThreadId,
+}) {}
+
+/** A process-local Thread store reached an explicit count or encoded-content bound. */
+export class ThreadLimitExceeded extends Schema.TaggedError<ThreadLimitExceeded>()(
+  "ThreadLimitExceeded",
+  {
+    threadId: ThreadId,
+    limit: Schema.Literals(["messages", "content-bytes", "threads", "store-content-bytes"]),
+    limitValue: Schema.Natural,
+    observedValue: Schema.Natural,
+  },
+) {}
+
+/** Engine history was not an append-only extension of the official snapshot. */
+export class ThreadHistoryDiverged extends Schema.TaggedError<ThreadHistoryDiverged>()(
+  "ThreadHistoryDiverged",
+  { threadId: ThreadId, message: Schema.String },
+) {}
+
+/** Native Prompt encoding failed before a bounded state mutation. */
+export class ThreadEncodingError extends Schema.TaggedError<ThreadEncodingError>()(
+  "ThreadEncodingError",
+  { threadId: ThreadId, message: Schema.String },
+) {}
+
+export type ThreadError =
+  | ThreadNotFound
+  | ThreadLimitExceeded
+  | ThreadHistoryDiverged
+  | ThreadEncodingError;
+
+/** Reconstruct exact Effect AI Prompt history, including tools, reasoning, files, and options. */
+export const toPrompt = (snapshot: Thread): Prompt.Prompt =>
+  Prompt.fromMessages(snapshot.messages.map((entry) => entry.message));
+
+/**
+ * Process-local state for conversation history. Updates remain visible even
+ * when a Run later fails; this service has no successful-Run commit boundary or durable recovery.
+ * ThreadHistory.layer uses this store for ordinary Runs and interactive history.
+ * Scope closure releases all in-memory state.
+ */
+export class Store extends Context.Service<
+  Store,
+  {
+    readonly create: (threadId: ThreadId) => Effect.Effect<Thread, ThreadLimitExceeded>;
+    readonly append: (
+      threadId: ThreadId,
+      message: ThreadAppend,
+    ) => Effect.Effect<Thread, ThreadNotFound | ThreadLimitExceeded | ThreadEncodingError>;
+    /**
+     * Record an engine-emitted full history only when it is an append-only
+     * extension of the exact official Prompt already stored. The entire
+     * suffix commits in one transaction or not at all: concurrent writers are
+     * serialized, a writer whose history no longer extends the committed
+     * official history fails with ThreadHistoryDiverged, and a limit
+     * failure inside the suffix records nothing. Earlier updates remain committed if the Run
+     * later fails or is interrupted; this transaction covers one update, not the whole Run.
+     */
+    readonly recordHistory: (
+      threadId: ThreadId,
+      runId: RunId,
+      history: Prompt.Prompt,
+    ) => Effect.Effect<Thread, ThreadError>;
+    readonly snapshot: (threadId: ThreadId) => Effect.Effect<Thread, ThreadNotFound>;
+    readonly export: (threadId: ThreadId) => Effect.Effect<ThreadExport, ThreadNotFound>;
+  }
+>()("@effect-agent/capabilities/EphemeralThreads") {}
+
+const encodeMessage = (
+  threadId: ThreadId,
+  message: Prompt.Message,
+): Effect.Effect<string, ThreadEncodingError> =>
+  Schema.encodeEffect(Prompt.Message)(message).pipe(
+    Effect.map((encoded) => JSON.stringify(encoded)),
+    Effect.mapError((error) =>
+      ThreadEncodingError.make({
+        threadId,
+        message: `Could not encode native Effect AI message: ${error.message}`,
+      }),
+    ),
+  );
+
+const findSnapshot = (
+  state: ReadonlyMap<ThreadId, Thread>,
+  threadId: ThreadId,
+): Effect.Effect<Thread, ThreadNotFound> => {
+  const snapshot = state.get(threadId);
+
+  return snapshot === undefined
+    ? Effect.fail(ThreadNotFound.make({ threadId }))
+    : Effect.succeed(snapshot);
+};
+
+const totalStoreBytes = (threads: ReadonlyMap<ThreadId, Thread>): number => {
+  let total = 0;
+
+  for (const snapshot of threads.values()) total += snapshot.contentBytes;
+
+  return total;
+};
+
+const appendEncoded = Effect.fn("Thread.Store.appendEncoded")(function* (
+  threads: ReadonlyMap<ThreadId, Thread>,
+  current: Thread,
+  append: ThreadAppend,
+  encoded: string,
+  timestamp: DateTime.Utc,
+) {
+  const threadId = current.threadId;
+
+  if (current.messages.length >= MAX_THREAD_MESSAGES) {
+    return yield* ThreadLimitExceeded.make({
+      threadId,
+      limit: "messages",
+      limitValue: MAX_THREAD_MESSAGES,
+      observedValue: current.messages.length + 1,
+    });
+  }
+  const messageBytes = utf8ByteLength(encoded);
+  const contentBytes = current.contentBytes + messageBytes;
+
+  if (contentBytes > MAX_THREAD_CONTENT_BYTES) {
+    return yield* ThreadLimitExceeded.make({
+      threadId,
+      limit: "content-bytes",
+      limitValue: MAX_THREAD_CONTENT_BYTES,
+      observedValue: contentBytes,
+    });
+  }
+  const storeBytes = totalStoreBytes(threads) + messageBytes;
+
+  if (storeBytes > MAX_STORE_CONTENT_BYTES) {
+    return yield* ThreadLimitExceeded.make({
+      threadId,
+      limit: "store-content-bytes",
+      limitValue: MAX_STORE_CONTENT_BYTES,
+      observedValue: storeBytes,
+    });
+  }
+
+  const message = ThreadMessage.make({
+    threadId,
+    sequence: current.nextSequence,
+    ...(append.runId === undefined ? {} : { runId: append.runId }),
+    message: append.message,
+    encodedBytes: messageBytes,
+    timestamp,
+  });
+
+  const next = Thread.make({
+    version: current.version,
+    threadId: current.threadId,
+    nextSequence: current.nextSequence + 1,
+    contentBytes,
+    messages: [...current.messages, message],
+  });
+
+  return [next, new Map(threads).set(threadId, next)] as const;
+});
+
+/** In-memory storage shared for the consumer's Scope; it does not survive process loss. */
+export const layerMemory = Layer.effect(
+  Store,
+  Effect.gen(function* () {
+    const state = yield* SynchronizedRef.make<ReadonlyMap<ThreadId, Thread>>(new Map());
+
+    yield* Effect.addFinalizer(() => SynchronizedRef.set(state, new Map()));
+
+    return Store.of({
+      create: (threadId) =>
+        SynchronizedRef.modifyEffect(
+          state,
+          Effect.fn(function* (threads) {
+            const existing = threads.get(threadId);
+
+            if (existing !== undefined) return [existing, threads] as const;
+            if (threads.size >= MAX_THREADS) {
+              return yield* ThreadLimitExceeded.make({
+                threadId,
+                limit: "threads",
+                limitValue: MAX_THREADS,
+                observedValue: threads.size + 1,
+              });
+            }
+
+            const created = Thread.make({
+              version: 1,
+              threadId,
+              nextSequence: 0,
+              contentBytes: 0,
+              messages: [],
+            });
+
+            return [created, new Map(threads).set(threadId, created)] as const;
+          }),
+        ),
+      append: Effect.fn("Thread.Store.append")(function* (threadId, message) {
+        const encoded = yield* encodeMessage(threadId, message.message);
+        const timestamp = DateTime.toUtc(DateTime.makeUnsafe(yield* Clock.currentTimeMillis));
+
+        return yield* SynchronizedRef.modifyEffect(
+          state,
+          Effect.fn(function* (threads) {
+            const current = yield* findSnapshot(threads, threadId);
+
+            return yield* appendEncoded(threads, current, message, encoded, timestamp);
+          }),
+        );
+      }),
+      recordHistory: Effect.fn("Thread.Store.recordHistory")(
+        function* (threadId, historyRunId, history) {
+          const incoming = yield* Effect.forEach(history.content, (message) =>
+            encodeMessage(threadId, message).pipe(Effect.map((encoded) => ({ message, encoded }))),
+          );
+
+          // Publish the complete suffix only after verification and every bounded append succeed.
+          return yield* SynchronizedRef.modifyEffect(
+            state,
+            Effect.fn(function* (threads) {
+              const current = yield* findSnapshot(threads, threadId);
+
+              const currentEncoded = yield* Effect.forEach(current.messages, (entry) =>
+                encodeMessage(threadId, entry.message),
+              );
+
+              if (
+                incoming.length < currentEncoded.length ||
+                currentEncoded.some((encoded, index) => encoded !== incoming[index]?.encoded)
+              ) {
+                return yield* ThreadHistoryDiverged.make({
+                  threadId,
+                  message: "Engine history is not an append-only extension of official history",
+                });
+              }
+              const timestamp = DateTime.toUtc(DateTime.makeUnsafe(yield* Clock.currentTimeMillis));
+
+              if (incoming.length === currentEncoded.length) return [current, threads] as const;
+
+              const messages = [...current.messages];
+              let contentBytes = current.contentBytes;
+              let storeBytes = totalStoreBytes(threads);
+              let nextSequence = current.nextSequence;
+
+              for (const entry of incoming.slice(currentEncoded.length)) {
+                const append = ThreadAppend.make({ runId: historyRunId, message: entry.message });
+
+                // Preserve append's first failing bound and observed value without publishing
+                // intermediate snapshots or rescanning the store for each suffix message.
+                if (messages.length >= MAX_THREAD_MESSAGES) {
+                  return yield* ThreadLimitExceeded.make({
+                    threadId,
+                    limit: "messages",
+                    limitValue: MAX_THREAD_MESSAGES,
+                    observedValue: messages.length + 1,
+                  });
+                }
+                const messageBytes = utf8ByteLength(entry.encoded);
+
+                contentBytes += messageBytes;
+                if (contentBytes > MAX_THREAD_CONTENT_BYTES) {
+                  return yield* ThreadLimitExceeded.make({
+                    threadId,
+                    limit: "content-bytes",
+                    limitValue: MAX_THREAD_CONTENT_BYTES,
+                    observedValue: contentBytes,
+                  });
+                }
+                storeBytes += messageBytes;
+                if (storeBytes > MAX_STORE_CONTENT_BYTES) {
+                  return yield* ThreadLimitExceeded.make({
+                    threadId,
+                    limit: "store-content-bytes",
+                    limitValue: MAX_STORE_CONTENT_BYTES,
+                    observedValue: storeBytes,
+                  });
+                }
+                messages.push(
+                  ThreadMessage.make({
+                    threadId,
+                    sequence: nextSequence,
+                    ...(append.runId === undefined ? {} : { runId: append.runId }),
+                    message: append.message,
+                    encodedBytes: messageBytes,
+                    timestamp,
+                  }),
+                );
+                nextSequence += 1;
+              }
+
+              const snapshot = Thread.make({
+                version: current.version,
+                threadId,
+                nextSequence,
+                contentBytes,
+                messages,
+              });
+
+              return [snapshot, new Map(threads).set(threadId, snapshot)] as const;
+            }),
+          );
+        },
+      ),
+      snapshot: (threadId) =>
+        SynchronizedRef.get(state).pipe(Effect.flatMap((all) => findSnapshot(all, threadId))),
+      export: (threadId) =>
+        Effect.gen(function* () {
+          const snapshot = yield* findSnapshot(yield* SynchronizedRef.get(state), threadId);
+
+          return ThreadExport.make({
+            format: "effect-agent/ephemeral-thread@1",
+            exportedAt: DateTime.toUtc(DateTime.makeUnsafe(yield* Clock.currentTimeMillis)),
+            snapshot,
+          });
+        }),
+    });
+  }),
+);

package/src/core/ToolExposure.ts

@@ -0,0 +1,74 @@
+import { Context, Schema } from "effect";
+import type { Tool } from "effect/unstable/ai";
+
+/** Registered native names only. Empty selection deliberately clears non-pinned Tools. */
+export const ToolNames = Schema.Array(
+  Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256)),
+).check(
+  Schema.isMaxLength(1_024),
+  Schema.makeFilter((names) => new Set(names).size === names.length, {
+    title: "Tool names are unique",
+  }),
+);
+
+/** One run-scoped replacement, independent of search and of model-visible result text. */
+export class Selection extends Schema.Class<Selection>("@effect-agent/core/ToolExposure/Selection")(
+  {
+    toolNames: ToolNames,
+  },
+) {}
+
+/** Exact declarations used by one model request, with the selection that produced them. */
+export class Snapshot extends Schema.Class<Snapshot>("@effect-agent/core/ToolExposure/Snapshot")({
+  exposedToolNames: ToolNames,
+  selection: Schema.optionalKey(Selection),
+}) {}
+
+export const Limits = Schema.Struct({
+  maxTools: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(1_024)),
+  maxSchemaBytes: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(4_194_304)),
+});
+
+/** Omission preserves eager exposure. Selection changes take effect only after a complete batch. */
+export interface Configuration {
+  readonly initialToolNames?: ReadonlyArray<string> | undefined;
+  readonly maxTools?: number | undefined;
+  readonly maxSchemaBytes?: number | undefined;
+}
+
+/** Trusted grouping metadata; never inferred from a Tool's name. */
+export const ToolNamespace = Context.Reference<string | undefined>(
+  "@effect-agent/core/ToolExposure/ToolNamespace",
+  { defaultValue: () => undefined },
+);
+
+/** An ordinary readonly Tool whose successful result has a `toolNames` field of native names. */
+export const DiscoveryTool = Context.Reference<boolean>(
+  "@effect-agent/core/ToolExposure/DiscoveryTool",
+  { defaultValue: () => false },
+);
+
+/** Remains selected while eligible. Host visibility and inherited grants may hide an explicit
+ * pin without failing the Run; discovery, context rollover and required completion stay mandatory.
+ */
+export const PinnedTool = Context.Reference<boolean>("@effect-agent/core/ToolExposure/PinnedTool", {
+  defaultValue: () => false,
+});
+
+/** Extra documentation candidates executed through their owning native Tool, such as Code Mode. */
+export interface AdditionalCatalogEntry {
+  readonly tool: Tool.Any;
+  readonly namespace: string;
+  readonly method: string;
+}
+
+export const AdditionalToolCatalog = Context.Reference<ReadonlyArray<AdditionalCatalogEntry>>(
+  "@effect-agent/core/ToolExposure/AdditionalToolCatalog",
+  { defaultValue: () => [] },
+);
+
+/** The owning Tool description embeds its complete additional catalogue. */
+export const IncludesCatalogDocumentation = Context.Reference<boolean>(
+  "@effect-agent/core/ToolExposure/IncludesCatalogDocumentation",
+  { defaultValue: () => false },
+);

package/src/core/ToolResult.ts

@@ -0,0 +1,170 @@
+import * as Schema from "effect/Schema";
+
+import { codePointUtf8Length, utf8ByteLength } from "./internal/utf8.ts";
+
+/**
+ * The minimal `TruncatedToolResult` envelope (empty head/tail, a 16-digit
+ * `originalBytes`) encodes to at most 81 UTF-8 bytes; 256 guarantees every
+ * accepted bound fits the envelope plus some real content, so the bound is a
+ * hard resource guard rather than a best-effort one.
+ */
+const ENVELOPE_FLOOR_BYTES = 256;
+
+/** Byte bound applied to one encoded application Tool result before it enters history. */
+export class ToolResultBounds extends Schema.Class<ToolResultBounds>("ToolResultBounds")({
+  maxBytes: Schema.Int.check(Schema.isGreaterThanOrEqualTo(ENVELOPE_FLOOR_BYTES)),
+}) {}
+
+/**
+ * Canonical envelope replacing an encoded Tool result that exceeded its
+ * policy bounds. `head` and `tail` are an exact prefix and suffix of the
+ * original encoded JSON text; the middle is dropped, never paraphrased.
+ */
+export class TruncatedToolResult extends Schema.Class<TruncatedToolResult>("TruncatedToolResult")({
+  truncatedToolResult: Schema.Literal(true),
+  originalBytes: Schema.Natural,
+  head: Schema.String,
+  tail: Schema.String,
+}) {}
+
+/**
+ * Canonical fail-closed sentinel replacing an encoded Tool result that could
+ * not be JSON-serialized at all (cyclic value, BigInt, `undefined`, throwing
+ * `toJSON`). The original value never enters history or durable records —
+ * an unserializable value is unbounded by construction, so the bound seam
+ * replaces it wholesale rather than passing it through (runtime spec §9).
+ */
+export class UnserializableToolResult extends Schema.Class<UnserializableToolResult>(
+  "UnserializableToolResult",
+)({
+  unserializableToolResult: Schema.Literal(true),
+  reason: Schema.String.check(Schema.isMaxLength(256)),
+}) {}
+
+/**
+ * Build the encoded sentinel for a serialization failure. Total by
+ * construction — the cause is untrusted (a hostile `toString` or an
+ * accessor-backed `Error.message` can itself throw on this last-resort
+ * path) — and byte-bound: the complete encoded sentinel stays within the
+ * 256-byte `ToolResultBounds` schema floor, so it fits every accepted
+ * policy without the caller re-applying bounds.
+ */
+export const unserializableToolResult = (
+  cause: unknown,
+): typeof UnserializableToolResult.Encoded => {
+  let reason: string;
+
+  try {
+    const message = cause instanceof Error ? cause.message : cause;
+
+    reason = typeof message === "string" ? message : String(message);
+  } catch {
+    reason = "unserializable value";
+  }
+
+  const build = (clipped: string): typeof UnserializableToolResult.Encoded =>
+    Schema.encodeSync(UnserializableToolResult)(
+      UnserializableToolResult.make({
+        unserializableToolResult: true,
+        reason: clipped,
+      }),
+    );
+
+  // JSON escaping inflates bytes, so shrink by whole code points until the
+  // encoded sentinel fits the floor; the empty reason always fits.
+  let clipped = takePrefixWithinBytes(reason, 128);
+  let sentinel = build(clipped);
+
+  while (clipped.length > 0 && utf8ByteLength(JSON.stringify(sentinel)) > 256) {
+    const last = clipped.codePointAt(clipped.length - 1);
+
+    clipped = clipped.slice(0, clipped.length - (last !== undefined && last > 0xffff ? 2 : 1));
+    sentinel = build(clipped);
+  }
+
+  return sentinel;
+};
+
+const takePrefixWithinBytes = (value: string, maxBytes: number): string => {
+  let bytes = 0;
+  let index = 0;
+
+  while (index < value.length) {
+    const codePoint = value.codePointAt(index) ?? 0;
+    const width = codePointUtf8Length(codePoint);
+
+    if (bytes + width > maxBytes) break;
+    bytes += width;
+    index += codePoint > 0xffff ? 2 : 1;
+  }
+
+  return value.slice(0, index);
+};
+
+const takeSuffixWithinBytes = (value: string, maxBytes: number): string => {
+  let bytes = 0;
+  let index = value.length;
+
+  while (index > 0) {
+    const unit = value.charCodeAt(index - 1);
+    const isLowSurrogate = unit >= 0xdc00 && unit <= 0xdfff;
+    const pairStart = isLowSurrogate && index >= 2 ? index - 2 : index - 1;
+    const codePoint = value.codePointAt(pairStart) ?? 0;
+    const width = codePointUtf8Length(codePoint);
+
+    if (bytes + width > maxBytes) break;
+    bytes += width;
+    index = pairStart;
+  }
+
+  return value.slice(index);
+};
+
+/**
+ * Bound one encoded Tool result to `bounds.maxBytes` UTF-8 bytes.
+ *
+ * Within bounds the input is returned unchanged. Over bounds the result is
+ * the JSON-encoded `TruncatedToolResult` envelope preserving an exact prefix
+ * and suffix of the input, split ~50/50 across the byte budget left after
+ * the envelope's own overhead and shrunk deterministically until the encoded
+ * envelope itself fits. Slicing never splits a UTF-16 surrogate pair, so the
+ * envelope always re-encodes as valid JSON.
+ *
+ * The Schema-level 256-byte floor on `ToolResultBounds.maxBytes` guarantees
+ * every accepted bound fits the minimal envelope (at most 81 bytes), so the
+ * returned value never exceeds `maxBytes` for a decodable bound. The
+ * minimal-envelope fallback below survives purely as defense in depth.
+ */
+export const applyToolResultBounds = (encodedJson: string, bounds: ToolResultBounds): string => {
+  const originalBytes = utf8ByteLength(encodedJson);
+
+  if (originalBytes <= bounds.maxBytes) return encodedJson;
+
+  const render = (head: string, tail: string): string =>
+    JSON.stringify(
+      Schema.encodeSync(TruncatedToolResult)(
+        TruncatedToolResult.make({ truncatedToolResult: true, originalBytes, head, tail }),
+      ),
+    );
+
+  const minimal = render("", "");
+  const contentBudget = bounds.maxBytes - utf8ByteLength(minimal);
+
+  if (contentBudget <= 0) return minimal;
+  let headBudget = Math.floor(contentBudget / 2);
+  let tailBudget = contentBudget - headBudget;
+
+  for (;;) {
+    const head = takePrefixWithinBytes(encodedJson, headBudget);
+    const tail = takeSuffixWithinBytes(encodedJson, tailBudget);
+    const output = render(head, tail);
+    const outputBytes = utf8ByteLength(output);
+
+    if (outputBytes <= bounds.maxBytes) return output;
+    if (headBudget === 0 && tailBudget === 0) return minimal;
+    const shrink = Math.max(1, Math.ceil((outputBytes - bounds.maxBytes) / 2));
+
+    headBudget = Math.max(0, headBudget - shrink);
+    tailBudget = Math.max(0, tailBudget - shrink);
+  }
+};