@intx/agent 0.1.2 → 0.3.0

package/src/agent.ts

@@ -1,494 +0,0 @@
-// In-process agent runtime.
-//
-// `createAgent` resolves storage, builds the source registry and tool
-// dispatcher, wires `createReactorAssembly`, and exposes the public Agent
-// surface. The agent owns the active inference source object so
-// `setSource` can mutate it in place and the reactor's lazy read at the
-// start of each inference call picks up the new credentials.
-//
-// Composition:
-//   - `send()` enqueues into a FIFO `SendQueue` capped at `sendQueueMax`.
-//     Per-send `AbortSignal` removes queued items or rejects in-flight
-//     callers while letting the reactor cycle finish in the background.
-//   - `stream()` returns a bounded `StreamConsumer` iterator; consumers
-//     buffer independently and noisy backpressure poisons only the
-//     affected iterator.
-//   - `close()` aborts the reactor, drains the send queue with
-//     `AgentClosedError`, terminates every active stream iterator, waits
-//     up to `closeTimeoutMs` for the reactor's shutdown sequence to
-//     complete (audit flush, in-flight commits), and finally releases
-//     the singleton-per-`contextDir` lock so another agent can open the
-//     same directory.
-//
-// `setSource` covers the whole source: id/provider/baseURL/apiKey/model
-// plus the model-bound `defaults` and `capabilities`. Credentials and
-// model rotate together via the shared source object the reactor reads
-// lazily at the start of each inference call. The director never names
-// a model — `capabilities.infer(options?)` does not take one — so the
-// active source's model is the single source of truth and rotations
-// take effect on the next inference call without any wrapper.
-
-import {
-  createDefaultDirector,
-  createReactorAssembly,
-  type AuthzExtensionOptions,
-  type Dependencies,
-  type ReactorEmittedEvent,
-} from "@intx/inference";
-import { createInboundMessage } from "@intx/mime";
-import { createIsogitStore } from "@intx/storage-isogit";
-import type {
-  AssistantTurn,
-  AuditStore,
-  BlobReader,
-  ContextCommit,
-  ContextStore,
-  ConversationTurn,
-  InboundMessage,
-  InferenceSource,
-  ReactorDirector,
-} from "@intx/types/runtime";
-
-import { acquireContextDirLock, type ContextDirLock } from "./lock";
-import { createSourceRegistry, type SourceRegistry } from "./source";
-import { createSendQueue, type SendQueue } from "./send-queue";
-import { createStreamConsumer, type StreamConsumer } from "./stream";
-import { createToolRunner, type AgentTool, type AgentToolRunner } from "./tool";
-
-const DEFAULT_SEND_FROM = "user@local";
-const DEFAULT_SEND_TO = "agent@local";
-const DEFAULT_SEND_QUEUE_MAX = 16;
-const DEFAULT_STREAM_BUFFER_MAX = 1024;
-const DEFAULT_CLOSE_TIMEOUT_MS = 5000;
-
-export type AgentConfig = {
-  /**
-   * The conversation/history store. Exactly one of `contextStore` or
-   * `contextDir` must be supplied. When `contextStore` is given the caller
-   * owns the store's lifetime; the singleton-per-directory lock is not
-   * acquired.
-   */
-  contextStore?: ContextStore;
-
-  /**
-   * Path to a directory the agent will manage as an isogit-backed
-   * `ContextStore & AuditStore`. The singleton-per-directory lock is
-   * acquired when this form is used.
-   */
-  contextDir?: string;
-
-  /** Pre-configured inference sources. Must be non-empty. */
-  sources: InferenceSource[];
-  /** Must match the `id` field of one of `sources`. */
-  defaultSource: string;
-
-  /** System prompt for the default director. */
-  systemPrompt: string;
-  /** Tools registered via `tool()` / `stringTool()`. */
-  tools: AgentTool[];
-  /** Director override. Defaults to `createDefaultDirector`. */
-  director?: ReactorDirector;
-
-  /** Audit store. When omitted with `contextDir`, the isogit store is used. */
-  auditStore?: AuditStore;
-  /** Authz extension hook. */
-  authorize?: AuthzExtensionOptions["authorize"];
-  /** Override the default 10k tool-result size cap. */
-  sizeCapMaxChars?: number;
-
-  /** Override the auto-generated session ID. */
-  sessionId?: string;
-
-  /**
-   * Maximum number of pending sends (active + queued). Once reached,
-   * additional `send()` calls throw `SendQueueFullError` synchronously.
-   * Defaults to 16.
-   */
-  sendQueueMax?: number;
-
-  /**
-   * Maximum events any single `stream()` consumer may buffer. When a
-   * consumer falls more than this many events behind the next read on
-   * that consumer's iterator throws `StreamBackpressureError`; other
-   * consumers are unaffected. Defaults to 1024.
-   */
-  streamBufferMax?: number;
-
-  /**
-   * Inference dependencies (notably `fetch`) for the reactor's underlying
-   * `runInference` call. Production callers should leave this undefined —
-   * the assembly falls back to `createDefaultDependencies()` which binds
-   * `globalThis.fetch`. Pass `setupHarness().deps` from
-   * `@intx/inference-testing` in tests to swap the fetch
-   * implementation for a deterministic stub.
-   */
-  deps?: Dependencies;
-
-  /**
-   * Maximum milliseconds `close()` waits for the reactor's shutdown
-   * sequence (which flushes audit and any pending commits) before
-   * releasing the singleton `contextDir` lock and returning. Defaults
-   * to 5000ms. Set to 0 to release immediately without waiting (useful
-   * for tests where the reactor's shutdown is intentionally blocked).
-   */
-  closeTimeoutMs?: number;
-};
-
-export type SendOptions = {
-  /**
-   * Abort signal for this send. When the signal fires before processing
-   * the call is dropped from the queue and the promise rejects with the
-   * signal's reason. When it fires mid-cycle the promise rejects
-   * immediately, but the underlying reactor cycle keeps running because
-   * the reactor does not expose per-cycle cancellation — the next queued
-   * send waits for that cycle to finish before starting. The reply (if
-   * any) is still visible via `stream()` and `history()`.
-   */
-  signal?: AbortSignal;
-  /** Override the default "from" header on the synthetic inbound message. */
-  from?: string;
-};
-
-export type SendResult = {
-  /** Reply text emitted by the director's `reply` action. */
-  reply: string;
-  /**
-   * Full-fidelity assistant turn that produced the reply. Captured from
-   * the reactor's `inference.done` event preceding `connector.reply`.
-   */
-  turn: ConversationTurn;
-};
-
-export type Agent = {
-  send(
-    content: string | InboundMessage,
-    opts?: SendOptions,
-  ): Promise<SendResult>;
-  stream(): AsyncIterable<ReactorEmittedEvent>;
-  deliver(message: InboundMessage): void;
-  close(): Promise<void>;
-  /**
-   * Replace the active source's fields in place. Picked up at the start
-   * of the next inference call. `model` rotates alongside the
-   * credentials — the director does not name a model, so the active
-   * source's `model` is what the next inference call uses without any
-   * additional plumbing.
-   */
-  setSource(source: InferenceSource): void;
-  /**
-   * Project conversation history from the underlying context store.
-   * Remains callable after `close()` — reads do not need the reactor
-   * and the store is not destroyed by close. Returns the full-fidelity
-   * `ConversationTurn[]` from the store's latest committed state.
-   */
-  history(): Promise<ConversationTurn[]>;
-  /**
-   * List recent checkpoints from the context store. Remains callable
-   * after `close()` for the same reason as `history()`.
-   */
-  checkpoints(limit?: number): Promise<ContextCommit[]>;
-  /**
-   * Read the conversation turns recorded at a specific commit hash.
-   * Remains callable after `close()` for the same reason as
-   * `history()`.
-   */
-  readAt(hash: string): Promise<ConversationTurn[]>;
-  readonly blobReader: BlobReader;
-};
-
-export class AgentConfigError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "AgentConfigError";
-  }
-}
-
-export class AgentClosedError extends Error {
-  constructor() {
-    super("agent is closed");
-    this.name = "AgentClosedError";
-  }
-}
-
-export async function createAgent(config: AgentConfig): Promise<Agent> {
-  const hasStore = config.contextStore !== undefined;
-  const hasDir = config.contextDir !== undefined;
-  if (hasStore === hasDir) {
-    throw new AgentConfigError(
-      "exactly one of contextStore or contextDir is required",
-    );
-  }
-
-  let contextStore: ContextStore;
-  let auditStore: AuditStore | undefined;
-  let lock: ContextDirLock | undefined;
-
-  if (config.contextDir !== undefined) {
-    lock = acquireContextDirLock(config.contextDir);
-    try {
-      const store = await createIsogitStore(config.contextDir);
-      contextStore = store;
-      auditStore = config.auditStore ?? store;
-    } catch (cause) {
-      lock.release();
-      throw cause;
-    }
-  } else if (config.contextStore !== undefined) {
-    contextStore = config.contextStore;
-    auditStore = config.auditStore;
-  } else {
-    throw new AgentConfigError("unreachable: storage form validated above");
-  }
-
-  let sourceRegistry: SourceRegistry;
-  let toolRunner: AgentToolRunner;
-  try {
-    sourceRegistry = createSourceRegistry({
-      sources: config.sources,
-      defaultSource: config.defaultSource,
-    });
-    toolRunner = createToolRunner(config.tools);
-  } catch (cause) {
-    if (lock !== undefined) lock.release();
-    throw cause;
-  }
-
-  let director: ReactorDirector;
-  if (config.director !== undefined) {
-    director = config.director;
-  } else {
-    director = createDefaultDirector(
-      config.systemPrompt,
-      [...toolRunner.definitions],
-      {},
-    );
-  }
-
-  const sessionId = config.sessionId ?? crypto.randomUUID();
-
-  const streamBufferMax = config.streamBufferMax ?? DEFAULT_STREAM_BUFFER_MAX;
-  const streamConsumers = new Set<StreamConsumer>();
-
-  // Per-active-cycle bookkeeping for send(). The reactor produces one or
-  // more inference.done events during a cycle; we keep the most recent
-  // assistant turn so the final connector.reply can be paired with the
-  // full-fidelity turn (rather than a synthesized text-only fallback).
-  type ActiveCycle = { lastAssistantTurn: AssistantTurn | undefined };
-  let activeCycle: ActiveCycle | null = null;
-
-  // sendQueue is built after the reactor (since its `start` callback
-  // delivers into the reactor), but handleEvent — which is wired into the
-  // reactor's assembly — needs to see sendQueue. Assigned exactly once
-  // after the reactor exists and before reactor.start(); no event can
-  // reach handleEvent before the queue is wired.
-  // eslint-disable-next-line prefer-const -- forward declaration; const cannot express this ordering
-  let sendQueue: SendQueue<InboundMessage, SendResult>;
-
-  // shutdownComplete resolves from the assembly's onShutdown hook
-  // (composed after audit flush by the assembly) or, as a fallback, from
-  // handleEvent observing the reactor's terminal `reactor.done` event.
-  // close() awaits this (with a timeout) before releasing the
-  // contextDir lock so a subsequent createAgent on the same directory
-  // sees a quiesced store.
-  let resolveShutdown: () => void = () => {
-    // Reassigned by the Promise constructor below; seed a no-op so the
-    // forward-referenced call in handleEvent is safe even if the
-    // Promise constructor has not yet run (it does, synchronously, on
-    // the next line).
-  };
-  const shutdownComplete = new Promise<void>((resolve) => {
-    resolveShutdown = resolve;
-  });
-
-  function buildSyntheticTurn(text: string): ConversationTurn {
-    return {
-      role: "assistant",
-      content: [{ type: "text", text }],
-      model: sourceRegistry.active.model,
-      timestamp: Date.now(),
-    };
-  }
-
-  function handleEvent(event: ReactorEmittedEvent): void {
-    if (activeCycle !== null && event.type === "inference.done") {
-      activeCycle.lastAssistantTurn = event.data.turn;
-    }
-
-    if (activeCycle !== null) {
-      if (event.type === "connector.reply") {
-        const turn: ConversationTurn =
-          activeCycle.lastAssistantTurn ??
-          buildSyntheticTurn(event.data.content);
-        activeCycle = null;
-        sendQueue.resolveActive({ reply: event.data.content, turn });
-      } else if (event.type === "reactor.error" && event.data.fatal) {
-        // Only fatal reactor errors terminate the active send. Non-fatal
-        // errors (e.g. transient write/commit failures the reactor is
-        // recovering from) are surfaced via stream() but must not
-        // resolve send() — the cycle is still running and may yet
-        // produce connector.reply or a fatal error.
-        activeCycle = null;
-        sendQueue.rejectActive(new Error(`reactor error: ${event.data.error}`));
-      } else if (event.type === "reactor.done") {
-        activeCycle = null;
-        sendQueue.rejectActive(new AgentClosedError());
-      }
-    }
-
-    // reactor.done is the reactor's terminal event. Resolve
-    // shutdownComplete here in addition to the onShutdown hook so close()
-    // does not hang for the full closeTimeoutMs on paths where the hook
-    // never fires (e.g. the reactor's context-store load fails during
-    // start, or the composed onShutdown wrapper throws during audit
-    // flush). resolveShutdown is idempotent.
-    if (event.type === "reactor.done") {
-      resolveShutdown();
-    }
-
-    // Iterate a snapshot so removing closed consumers mid-iteration is
-    // not just relying on Set's iteration tolerance.
-    for (const consumer of Array.from(streamConsumers)) {
-      consumer.push(event);
-      if (consumer.closed) {
-        streamConsumers.delete(consumer);
-      }
-    }
-  }
-
-  const { reactor, blobReader } = createReactorAssembly({
-    sessionId,
-    director,
-    source: sourceRegistry.active,
-    toolRunner,
-    contextStore,
-    onEvent: handleEvent,
-    onShutdown: async () => {
-      resolveShutdown();
-    },
-    ...(auditStore !== undefined ? { auditStore } : {}),
-    ...(config.authorize !== undefined ? { authorize: config.authorize } : {}),
-    ...(config.sizeCapMaxChars !== undefined
-      ? { sizeCapMaxChars: config.sizeCapMaxChars }
-      : {}),
-    ...(config.deps !== undefined ? { deps: config.deps } : {}),
-  });
-
-  sendQueue = createSendQueue<InboundMessage, SendResult>({
-    maxDepth: config.sendQueueMax ?? DEFAULT_SEND_QUEUE_MAX,
-    start: (message) => {
-      activeCycle = { lastAssistantTurn: undefined };
-      reactor.deliver(message);
-    },
-  });
-
-  reactor.start();
-
-  let closed = false;
-
-  function ensureOpen(): void {
-    if (closed) throw new AgentClosedError();
-  }
-
-  function buildInboundMessage(
-    content: string | InboundMessage,
-    opts?: SendOptions,
-  ): InboundMessage {
-    if (typeof content !== "string") return content;
-    // Conversation messages use `content` (a string); the mail-builder
-    // rejects passing `payload` for conversation types.
-    return createInboundMessage({
-      from: opts?.from ?? DEFAULT_SEND_FROM,
-      to: DEFAULT_SEND_TO,
-      content,
-      interchangeType: "conversation.message",
-    });
-  }
-
-  function send(
-    content: string | InboundMessage,
-    opts?: SendOptions,
-  ): Promise<SendResult> {
-    // Closed-agent errors come back as rejections so callers can handle
-    // them with `.catch()` instead of having to defensively wrap every
-    // `agent.send(...)` in a try/catch. `SendQueueFullError` from
-    // `sendQueue.enqueue` is left as a synchronous throw — it signals a
-    // programmer error (the caller exceeded the configured queue cap)
-    // and per the design must fail loud.
-    if (closed) return Promise.reject(new AgentClosedError());
-    const message = buildInboundMessage(content, opts);
-    return sendQueue.enqueue(message, opts?.signal);
-  }
-
-  function stream(): AsyncIterable<ReactorEmittedEvent> {
-    ensureOpen();
-    const consumer = createStreamConsumer(streamBufferMax);
-    streamConsumers.add(consumer);
-    return consumer.iterator();
-  }
-
-  function deliver(message: InboundMessage): void {
-    ensureOpen();
-    reactor.deliver(message);
-  }
-
-  function setSource(source: InferenceSource): void {
-    ensureOpen();
-    sourceRegistry.setSource(source);
-  }
-
-  async function history(): Promise<ConversationTurn[]> {
-    const loaded = await contextStore.load();
-    return loaded.turns;
-  }
-
-  async function checkpoints(limit?: number): Promise<ContextCommit[]> {
-    return contextStore.log(limit);
-  }
-
-  async function readAt(hash: string): Promise<ConversationTurn[]> {
-    return contextStore.readAt(hash);
-  }
-
-  async function close(): Promise<void> {
-    if (closed) return;
-    closed = true;
-    reactor.abort("user_disconnect");
-    sendQueue.drain(new AgentClosedError());
-    activeCycle = null;
-    for (const consumer of streamConsumers) consumer.close();
-    streamConsumers.clear();
-
-    // Wait for the reactor's shutdown sequence (audit flush, in-flight
-    // commits) before releasing the lock so a subsequent createAgent on
-    // the same contextDir does not race with background writers against
-    // the same .git directory. The timeout is a backstop: if the
-    // reactor's shutdown is genuinely stuck (e.g. a parked test fetch
-    // that never resolves) we release the lock anyway rather than
-    // deadlock the caller. `closeTimeoutMs: 0` disables the wait.
-    const timeoutMs = config.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS;
-    if (timeoutMs > 0) {
-      let timer: ReturnType<typeof setTimeout> | undefined;
-      const timeout = new Promise<void>((resolve) => {
-        timer = setTimeout(resolve, timeoutMs);
-      });
-      try {
-        await Promise.race([shutdownComplete, timeout]);
-      } finally {
-        if (timer !== undefined) clearTimeout(timer);
-      }
-    }
-    if (lock !== undefined) lock.release();
-  }
-
-  return {
-    send,
-    stream,
-    deliver,
-    close,
-    setSource,
-    history,
-    checkpoints,
-    readAt,
-    blobReader,
-  };
-}

package/src/index.ts

@@ -1,38 +0,0 @@
-// @intx/agent — in-process agent runtime.
-//
-// Sits on top of `createReactorAssembly` from `@intx/inference` to
-// provide a code-driven agent surface: send a message, stream events,
-// project history, hot-swap inference sources. Peer to `@intx/harness`;
-// the harness drives the reactor from a mail transport (INBOX watch,
-// connector threads, outbound replies via MessageTransport) while the
-// agent drives it from in-process calls.
-
-export { AgentInUseError } from "./lock";
-export {
-  type AgentTool,
-  type AgentToolRunner,
-  type StringToolHandler,
-  type ToolHandler,
-  DuplicateToolError,
-  createToolRunner,
-  fromToolRunner,
-  stringTool,
-  tool,
-} from "./tool";
-export {
-  type SourceRegistry,
-  InvalidInferenceSourceError,
-  SourceNotFoundError,
-  createSourceRegistry,
-} from "./source";
-export {
-  type Agent,
-  type AgentConfig,
-  type SendOptions,
-  type SendResult,
-  AgentClosedError,
-  AgentConfigError,
-  createAgent,
-} from "./agent";
-export { SendQueueFullError } from "./send-queue";
-export { StreamBackpressureError } from "./stream";

package/src/lock.test.ts

@@ -1,93 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { resolve } from "node:path";
-
-import { acquireContextDirLock, AgentInUseError } from "./lock";
-
-describe("acquireContextDirLock", () => {
-  test("returns a lock whose path is the resolved absolute path", () => {
-    const lock = acquireContextDirLock("/tmp/agent-lock-1");
-    try {
-      expect(lock.path).toBe(resolve("/tmp/agent-lock-1"));
-    } finally {
-      lock.release();
-    }
-  });
-
-  test("rejects a second acquisition of the same directory", () => {
-    const lock = acquireContextDirLock("/tmp/agent-lock-2");
-    try {
-      expect(() => acquireContextDirLock("/tmp/agent-lock-2")).toThrow(
-        AgentInUseError,
-      );
-    } finally {
-      lock.release();
-    }
-  });
-
-  test("re-acquires the same directory after release", () => {
-    const lock1 = acquireContextDirLock("/tmp/agent-lock-3");
-    lock1.release();
-    const lock2 = acquireContextDirLock("/tmp/agent-lock-3");
-    try {
-      expect(lock2.path).toBe(resolve("/tmp/agent-lock-3"));
-    } finally {
-      lock2.release();
-    }
-  });
-
-  test("collides on lexically distinct but equivalent paths", () => {
-    const lock = acquireContextDirLock("/tmp/agent-lock-4/../agent-lock-4/foo");
-    try {
-      expect(() => acquireContextDirLock("/tmp/agent-lock-4/foo")).toThrow(
-        AgentInUseError,
-      );
-    } finally {
-      lock.release();
-    }
-  });
-
-  test("collides on a relative path that resolves to the same absolute path", () => {
-    const absolute = resolve("relative-lock-test-dir");
-    const lock = acquireContextDirLock("relative-lock-test-dir");
-    try {
-      expect(lock.path).toBe(absolute);
-      expect(() => acquireContextDirLock(absolute)).toThrow(AgentInUseError);
-    } finally {
-      lock.release();
-    }
-  });
-
-  test("does not collide between distinct directories", () => {
-    const lock1 = acquireContextDirLock("/tmp/agent-lock-5a");
-    const lock2 = acquireContextDirLock("/tmp/agent-lock-5b");
-    try {
-      expect(lock1.path).not.toBe(lock2.path);
-    } finally {
-      lock1.release();
-      lock2.release();
-    }
-  });
-
-  test("release is idempotent", () => {
-    const lock = acquireContextDirLock("/tmp/agent-lock-6");
-    lock.release();
-    lock.release();
-    const reacquired = acquireContextDirLock("/tmp/agent-lock-6");
-    reacquired.release();
-  });
-
-  test("AgentInUseError exposes contextDir as the resolved path", () => {
-    const lock = acquireContextDirLock("/tmp/agent-lock-7");
-    try {
-      acquireContextDirLock("/tmp/agent-lock-7");
-      throw new Error("should have thrown AgentInUseError");
-    } catch (err) {
-      expect(err).toBeInstanceOf(AgentInUseError);
-      if (err instanceof AgentInUseError) {
-        expect(err.contextDir).toBe(resolve("/tmp/agent-lock-7"));
-      }
-    } finally {
-      lock.release();
-    }
-  });
-});

package/src/lock.ts

@@ -1,57 +0,0 @@
-// Process-wide registry of held context-directory locks.
-//
-// The agent enforces a runtime singleton-per-contextDir invariant: at most one
-// in-process agent may own a given context directory at a time. Holding two
-// agents against the same directory simultaneously corrupts both the git
-// state and the audit collector's bookkeeping.
-//
-// This is a best-effort in-process check. It does not coordinate across OS
-// processes, and it compares lexically-resolved absolute paths — two paths
-// that point to the same directory through symlinks or `..`/`/./` segments
-// are normalized by `path.resolve`, but a hard link or a separately mounted
-// bind to the same inode will not be detected. Callers passing their own
-// `contextStore` (rather than a `contextDir` string) bypass the lock; they
-// are responsible for their store's lifetime.
-
-import { resolve } from "node:path";
-
-const heldLocks = new Set<string>();
-
-export class AgentInUseError extends Error {
-  readonly contextDir: string;
-
-  constructor(contextDir: string) {
-    super(`an agent is already open for context directory: ${contextDir}`);
-    this.name = "AgentInUseError";
-    this.contextDir = contextDir;
-  }
-}
-
-export type ContextDirLock = {
-  /** Absolute, resolved path of the locked directory. */
-  readonly path: string;
-  /** Release the lock. Idempotent. */
-  release(): void;
-};
-
-/**
- * Acquire the process-wide lock for `contextDir`. Throws `AgentInUseError`
- * if another agent already holds it. The returned `release` is idempotent.
- */
-export function acquireContextDirLock(contextDir: string): ContextDirLock {
-  const path = resolve(contextDir);
-  if (heldLocks.has(path)) {
-    throw new AgentInUseError(path);
-  }
-  heldLocks.add(path);
-
-  let released = false;
-  return {
-    path,
-    release() {
-      if (released) return;
-      released = true;
-      heldLocks.delete(path);
-    },
-  };
-}