@intx/agent 0.1.2 → 0.3.0

package/src/send-queue.test.ts

@@ -1,207 +0,0 @@
-import { describe, test, expect } from "bun:test";
-
-import { createSendQueue, SendQueueFullError } from "./send-queue";
-
-/**
- * Tests use `string` as the result type so the queue's generic R parameter
- * holds a real value (it cannot be `void` under
- * `@typescript-eslint/no-invalid-void-type`). The actual values are
- * arbitrary; tests assert ordering and lifecycle, not result content.
- */
-
-describe("createSendQueue", () => {
-  test("starts the first enqueued item immediately", () => {
-    const started: string[] = [];
-    const q = createSendQueue<string, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    void q.enqueue("a");
-    expect(started).toEqual(["a"]);
-  });
-
-  test("queues subsequent items and starts each on resolveActive", async () => {
-    const started: string[] = [];
-    const q = createSendQueue<string, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    const p1 = q.enqueue("a");
-    const p2 = q.enqueue("b");
-    expect(started).toEqual(["a"]);
-
-    q.resolveActive("r1");
-    expect(await p1).toBe("r1");
-    expect(started).toEqual(["a", "b"]);
-
-    q.resolveActive("r2");
-    expect(await p2).toBe("r2");
-  });
-
-  test("throws SendQueueFullError synchronously at capacity", () => {
-    const started: number[] = [];
-    const q = createSendQueue<number, string>({
-      maxDepth: 2,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    void q.enqueue(1);
-    void q.enqueue(2);
-    expect(() => q.enqueue(3)).toThrow(SendQueueFullError);
-  });
-
-  test("rejects pre-aborted signal without enqueuing", async () => {
-    const ctl = new AbortController();
-    ctl.abort();
-
-    const started: number[] = [];
-    const q = createSendQueue<number, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    await expect(q.enqueue(1, ctl.signal)).rejects.toBeDefined();
-    expect(started).toEqual([]);
-    expect(q.depth).toBe(0);
-  });
-
-  test("removes a queued item whose signal fires before processing", async () => {
-    const started: number[] = [];
-    const ctl = new AbortController();
-    const q = createSendQueue<number, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    const p1 = q.enqueue(1);
-    const p2 = q.enqueue(2, ctl.signal);
-    const p3 = q.enqueue(3);
-
-    expect(started).toEqual([1]);
-    ctl.abort();
-    await expect(p2).rejects.toBeDefined();
-
-    q.resolveActive("r1");
-    expect(await p1).toBe("r1");
-    expect(started).toEqual([1, 3]);
-
-    q.resolveActive("r3");
-    expect(await p3).toBe("r3");
-  });
-
-  test("settles caller on in-flight abort but waits for consumer to advance", async () => {
-    const started: number[] = [];
-    const ctl = new AbortController();
-    const q = createSendQueue<number, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    const p1 = q.enqueue(1, ctl.signal);
-    const p2 = q.enqueue(2);
-    expect(started).toEqual([1]);
-
-    ctl.abort();
-    await expect(p1).rejects.toBeDefined();
-    // Active slot is still held until the consumer reports the cycle done.
-    expect(started).toEqual([1]);
-
-    q.resolveActive("late-r1");
-    expect(started).toEqual([1, 2]);
-
-    q.resolveActive("r2");
-    expect(await p2).toBe("r2");
-  });
-
-  test("late resolveActive after abort is a no-op for the caller", async () => {
-    const ctl = new AbortController();
-    const started: number[] = [];
-    const q = createSendQueue<number, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    const p = q.enqueue(1, ctl.signal);
-    ctl.abort();
-    await expect(p).rejects.toBeDefined();
-
-    q.resolveActive("late");
-    expect(q.depth).toBe(0);
-  });
-
-  test("drain rejects active and pending jobs with the given reason", async () => {
-    const started: number[] = [];
-    const q = createSendQueue<number, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    const p1 = q.enqueue(1);
-    const p2 = q.enqueue(2);
-    const reason = new Error("closed");
-
-    q.drain(reason);
-    await expect(p1).rejects.toBe(reason);
-    await expect(p2).rejects.toBe(reason);
-    expect(q.depth).toBe(0);
-  });
-
-  test("depth reflects active + pending", () => {
-    const started: number[] = [];
-    const q = createSendQueue<number, string>({
-      maxDepth: 4,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    expect(q.depth).toBe(0);
-    void q.enqueue(1);
-    expect(q.depth).toBe(1);
-    void q.enqueue(2);
-    expect(q.depth).toBe(2);
-
-    q.resolveActive("r1");
-    expect(q.depth).toBe(1);
-    q.resolveActive("r2");
-    expect(q.depth).toBe(0);
-  });
-
-  test("capacity check counts the abandoned active slot", async () => {
-    const ctl = new AbortController();
-    const started: number[] = [];
-    const q = createSendQueue<number, string>({
-      maxDepth: 2,
-      start: (item) => {
-        started.push(item);
-      },
-    });
-
-    const p1 = q.enqueue(1, ctl.signal);
-    void q.enqueue(2);
-    ctl.abort();
-    await expect(p1).rejects.toBeDefined();
-
-    // Active slot still occupied (consumer has not advanced). Adding a
-    // third would exceed maxDepth=2.
-    expect(() => q.enqueue(3)).toThrow(SendQueueFullError);
-  });
-});

package/src/send-queue.ts

@@ -1,200 +0,0 @@
-// FIFO queue for serializing send() calls against a single reactor.
-//
-// The agent processes one reactor cycle at a time, so concurrent send()
-// callers are queued. Each queued item carries the caller's resolve/reject
-// hooks and an optional AbortSignal:
-//
-//   - If the signal is already aborted when enqueue() is called the queue
-//     rejects synchronously without enqueueing.
-//   - If the signal fires while the item is still queued the item is
-//     removed and rejected.
-//   - If the signal fires while the item is active the caller-facing
-//     promise rejects immediately, but the reactor cycle continues in the
-//     background. The queue does not start the next item until the consumer
-//     reports the cycle done via resolveActive/rejectActive. This keeps the
-//     queue ordered against actual reactor cycles — two send() promises
-//     cannot interleave at the reactor level.
-//
-// Queue depth (active + pending) is bounded by `maxDepth`; exceeding it
-// throws `SendQueueFullError` synchronously from enqueue() so a buggy
-// caller flooding sends fails loud instead of silently buffering.
-
-export class SendQueueFullError extends Error {
-  readonly maxDepth: number;
-
-  constructor(maxDepth: number) {
-    super(`send queue is full (max depth ${String(maxDepth)})`);
-    this.name = "SendQueueFullError";
-    this.maxDepth = maxDepth;
-  }
-}
-
-type Job<T, R> = {
-  item: T;
-  signal?: AbortSignal;
-  abortHandler?: () => void;
-  resolve: (value: R) => void;
-  reject: (reason: unknown) => void;
-  /**
-   * True once the caller-facing promise has been settled (resolve or
-   * reject). Subsequent settles are no-ops. The active slot may remain
-   * occupied after a settle when the caller aborted mid-cycle — the queue
-   * waits for the consumer's resolveActive/rejectActive before pumping the
-   * next item.
-   */
-  settled: boolean;
-};
-
-export type SendQueueOptions<T> = {
-  maxDepth: number;
-  /**
-   * Called when a job moves from pending to active. The consumer drives
-   * the underlying work and must eventually call `resolveActive` or
-   * `rejectActive` exactly once.
-   */
-  start: (item: T) => void;
-};
-
-export type SendQueue<T, R> = {
-  enqueue(item: T, signal?: AbortSignal): Promise<R>;
-  /** Mark the active job complete with success and pump the next. */
-  resolveActive(value: R): void;
-  /** Mark the active job complete with failure and pump the next. */
-  rejectActive(reason: unknown): void;
-  /** Reject the active job (if any) and every pending job with `reason`. */
-  drain(reason: unknown): void;
-  /** Current pending count (queued + active). */
-  readonly depth: number;
-};
-
-function abortReason(signal: AbortSignal): unknown {
-  return signal.reason ?? new DOMException("aborted", "AbortError");
-}
-
-export function createSendQueue<T, R>(
-  opts: SendQueueOptions<T>,
-): SendQueue<T, R> {
-  const pending: Job<T, R>[] = [];
-  let active: Job<T, R> | null = null;
-
-  function settle(
-    job: Job<T, R>,
-    kind: "resolve" | "reject",
-    value: unknown,
-  ): void {
-    if (job.settled) return;
-    job.settled = true;
-    if (job.abortHandler !== undefined && job.signal !== undefined) {
-      job.signal.removeEventListener("abort", job.abortHandler);
-    }
-    if (kind === "resolve") {
-      // The queue's value type is checked at enqueue / resolveActive; the
-      // generic narrowing here is safe by construction.
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- generic resolve value
-      job.resolve(value as R);
-    } else {
-      job.reject(value);
-    }
-  }
-
-  function pump(): void {
-    while (active === null && pending.length > 0) {
-      const next = pending.shift();
-      if (next === undefined) return;
-      if (next.signal?.aborted === true) {
-        settle(next, "reject", abortReason(next.signal));
-        continue;
-      }
-      active = next;
-      opts.start(next.item);
-      return;
-    }
-  }
-
-  function enqueue(item: T, signal?: AbortSignal): Promise<R> {
-    if (signal?.aborted === true) {
-      return Promise.reject(abortReason(signal));
-    }
-
-    const depth = pending.length + (active !== null ? 1 : 0);
-    if (depth >= opts.maxDepth) {
-      throw new SendQueueFullError(opts.maxDepth);
-    }
-
-    let resolve!: (value: R) => void;
-    let reject!: (reason: unknown) => void;
-    const promise = new Promise<R>((res, rej) => {
-      resolve = res;
-      reject = rej;
-    });
-
-    const job: Job<T, R> = {
-      item,
-      ...(signal !== undefined ? { signal } : {}),
-      resolve,
-      reject,
-      settled: false,
-    };
-
-    if (signal !== undefined) {
-      const handler = (): void => {
-        const reason = abortReason(signal);
-        if (active === job) {
-          // In flight: settle the caller now; the consumer will eventually
-          // call resolveActive/rejectActive which becomes a no-op and
-          // advances the queue.
-          settle(job, "reject", reason);
-        } else {
-          const idx = pending.indexOf(job);
-          if (idx >= 0) pending.splice(idx, 1);
-          settle(job, "reject", reason);
-        }
-      };
-      signal.addEventListener("abort", handler, { once: true });
-      job.abortHandler = handler;
-    }
-
-    pending.push(job);
-    pump();
-    return promise;
-  }
-
-  function resolveActive(value: R): void {
-    if (active === null) return;
-    const job = active;
-    active = null;
-    settle(job, "resolve", value);
-    pump();
-  }
-
-  function rejectActive(reason: unknown): void {
-    if (active === null) return;
-    const job = active;
-    active = null;
-    settle(job, "reject", reason);
-    pump();
-  }
-
-  function drain(reason: unknown): void {
-    const drained: Job<T, R>[] = [];
-    if (active !== null) {
-      drained.push(active);
-      active = null;
-    }
-    drained.push(...pending);
-    pending.length = 0;
-    for (const job of drained) {
-      settle(job, "reject", reason);
-    }
-  }
-
-  return {
-    enqueue,
-    resolveActive,
-    rejectActive,
-    drain,
-    get depth() {
-      return pending.length + (active !== null ? 1 : 0);
-    },
-  };
-}

package/src/source.test.ts

@@ -1,171 +0,0 @@
-import { describe, test, expect } from "bun:test";
-
-import type { InferenceSource } from "@intx/types/runtime";
-
-import {
-  createSourceRegistry,
-  InvalidInferenceSourceError,
-  SourceNotFoundError,
-} from "./source";
-
-const S_ANTHROPIC: InferenceSource = {
-  id: "anthropic:claude-3-5-sonnet",
-  provider: "anthropic",
-  baseURL: "https://api.anthropic.com",
-  apiKey: "sk-anthropic-1",
-  model: "claude-3-5-sonnet",
-};
-
-const S_OPENAI: InferenceSource = {
-  id: "openai:gpt-4o",
-  provider: "openai",
-  baseURL: "https://api.openai.com",
-  apiKey: "sk-openai-1",
-  model: "gpt-4o",
-};
-
-/**
- * Test helper: produce an intentionally-invalid `InferenceSource` value so
- * we can verify that runtime validation rejects it. The whole point is to
- * exercise the arktype check, which requires bypassing the static type.
- */
-function invalidSource(value: unknown): InferenceSource {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- intentional invalid input for arktype validation test
-  return value as InferenceSource;
-}
-
-describe("createSourceRegistry", () => {
-  test("selects the source whose id matches defaultSource", () => {
-    const reg = createSourceRegistry({
-      sources: [S_ANTHROPIC, S_OPENAI],
-      defaultSource: "openai:gpt-4o",
-    });
-    expect(reg.active.provider).toBe("openai");
-    expect(reg.active.model).toBe("gpt-4o");
-    expect(reg.active.apiKey).toBe("sk-openai-1");
-  });
-
-  test("rejects an empty sources[] array", () => {
-    expect(() =>
-      createSourceRegistry({ sources: [], defaultSource: "anything" }),
-    ).toThrow(InvalidInferenceSourceError);
-  });
-
-  test("rejects sources that fail InferenceSource arktype validation", () => {
-    expect(() =>
-      createSourceRegistry({
-        sources: [invalidSource({ id: "x", provider: "x", apiKey: "k" })],
-        defaultSource: "anything",
-      }),
-    ).toThrow(InvalidInferenceSourceError);
-  });
-
-  test("rejects a source entry missing model", () => {
-    const noModel = invalidSource({
-      id: "anthropic:none",
-      provider: "anthropic",
-      baseURL: "u",
-      apiKey: "k",
-    });
-    expect(() =>
-      createSourceRegistry({
-        sources: [noModel],
-        defaultSource: "anthropic:none",
-      }),
-    ).toThrow(InvalidInferenceSourceError);
-  });
-
-  test("rejects sources[] with duplicate ids", () => {
-    expect(() =>
-      createSourceRegistry({
-        sources: [S_ANTHROPIC, { ...S_ANTHROPIC, apiKey: "sk-other" }],
-        defaultSource: S_ANTHROPIC.id,
-      }),
-    ).toThrow(InvalidInferenceSourceError);
-  });
-
-  test("throws SourceNotFoundError when defaultSource matches no source", () => {
-    expect(() =>
-      createSourceRegistry({
-        sources: [S_ANTHROPIC],
-        defaultSource: "openai:gpt-4o",
-      }),
-    ).toThrow(SourceNotFoundError);
-  });
-
-  test("active is a mutable holder; setSource mutates fields in place", () => {
-    const reg = createSourceRegistry({
-      sources: [S_ANTHROPIC],
-      defaultSource: "anthropic:claude-3-5-sonnet",
-    });
-    const reference = reg.active;
-
-    reg.setSource({
-      id: "anthropic:claude-3-5-haiku",
-      provider: "anthropic",
-      baseURL: "https://proxy.example.com",
-      apiKey: "sk-new",
-      model: "claude-3-5-haiku",
-    });
-
-    expect(reg.active).toBe(reference);
-    expect(reg.active.id).toBe("anthropic:claude-3-5-haiku");
-    expect(reg.active.provider).toBe("anthropic");
-    expect(reg.active.baseURL).toBe("https://proxy.example.com");
-    expect(reg.active.apiKey).toBe("sk-new");
-    expect(reg.active.model).toBe("claude-3-5-haiku");
-  });
-
-  test("setSource overwrites defaults and capabilities, including deletion", () => {
-    const reg = createSourceRegistry({
-      sources: [
-        {
-          ...S_ANTHROPIC,
-          defaults: { maxTokens: 1024 },
-          capabilities: ["text"],
-        },
-      ],
-      defaultSource: S_ANTHROPIC.id,
-    });
-
-    reg.setSource({
-      ...S_ANTHROPIC,
-      defaults: { maxTokens: 4096 },
-      capabilities: ["text", "vision"],
-    });
-    expect(reg.active.defaults).toEqual({ maxTokens: 4096 });
-    expect(reg.active.capabilities).toEqual(["text", "vision"]);
-
-    reg.setSource(S_ANTHROPIC);
-    expect(reg.active.defaults).toBeUndefined();
-    expect(reg.active.capabilities).toBeUndefined();
-  });
-
-  test("setSource throws InvalidInferenceSourceError on invalid input", () => {
-    const reg = createSourceRegistry({
-      sources: [S_ANTHROPIC],
-      defaultSource: S_ANTHROPIC.id,
-    });
-
-    expect(() => reg.setSource(invalidSource({ provider: "x" }))).toThrow(
-      InvalidInferenceSourceError,
-    );
-  });
-
-  test("does not mutate the caller's sources[] entries", () => {
-    const inputs: InferenceSource[] = [{ ...S_ANTHROPIC }];
-    const reg = createSourceRegistry({
-      sources: inputs,
-      defaultSource: S_ANTHROPIC.id,
-    });
-
-    reg.setSource({
-      ...S_ANTHROPIC,
-      baseURL: "https://other.example.com",
-      apiKey: "sk-other",
-    });
-
-    expect(inputs[0]?.apiKey).toBe("sk-anthropic-1");
-    expect(inputs[0]?.baseURL).toBe("https://api.anthropic.com");
-  });
-});

package/src/source.ts

@@ -1,93 +0,0 @@
-// Inference source registry.
-//
-// The agent accepts an array of pre-configured inference sources and a
-// `defaultSource` id at construction. The source whose `id` matches
-// `defaultSource` becomes the active source — the same object reference
-// is what the reactor's assembly holds and reads lazily at each
-// inference call.
-//
-// `setSource` mutates that shared object in place so the next inference
-// call observes the new credentials, model, and bound defaults. In-flight
-// calls keep using the values they read at start-of-call (the reactor
-// does not refetch mid-stream); the swap is therefore safe with respect
-// to torn state.
-
-import { type } from "arktype";
-
-import {
-  InferenceSource as InferenceSourceValidator,
-  applyInferenceSourceFields,
-  type InferenceSource,
-} from "@intx/types/runtime";
-
-export class InvalidInferenceSourceError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "InvalidInferenceSourceError";
-  }
-}
-
-export class SourceNotFoundError extends Error {
-  readonly id: string;
-
-  constructor(id: string) {
-    super(`no source in sources[] has id ${id}`);
-    this.name = "SourceNotFoundError";
-    this.id = id;
-  }
-}
-
-export type SourceRegistry = {
-  /**
-   * The mutable active source. The same object reference is held by the
-   * reactor; mutating it through `setSource` is what swaps the source for
-   * subsequent inference calls.
-   */
-  readonly active: InferenceSource;
-  /** Replace the active source's fields in place. */
-  setSource(source: InferenceSource): void;
-};
-
-export function createSourceRegistry(opts: {
-  sources: InferenceSource[];
-  defaultSource: string;
-}): SourceRegistry {
-  if (opts.sources.length === 0) {
-    throw new InvalidInferenceSourceError("sources[] must be non-empty");
-  }
-
-  const validated: InferenceSource[] = [];
-  const seenIds = new Set<string>();
-  for (const [i, raw] of opts.sources.entries()) {
-    const parsed = InferenceSourceValidator(raw);
-    if (parsed instanceof type.errors) {
-      throw new InvalidInferenceSourceError(
-        `sources[${String(i)}]: ${parsed.summary}`,
-      );
-    }
-    if (seenIds.has(parsed.id)) {
-      throw new InvalidInferenceSourceError(
-        `sources[${String(i)}]: duplicate id ${parsed.id}`,
-      );
-    }
-    seenIds.add(parsed.id);
-    validated.push(parsed);
-  }
-
-  const initial = validated.find((s) => s.id === opts.defaultSource);
-  if (initial === undefined) {
-    throw new SourceNotFoundError(opts.defaultSource);
-  }
-
-  const active: InferenceSource = { ...initial };
-
-  function setSource(source: InferenceSource): void {
-    const parsed = InferenceSourceValidator(source);
-    if (parsed instanceof type.errors) {
-      throw new InvalidInferenceSourceError(parsed.summary);
-    }
-    applyInferenceSourceFields(active, parsed);
-  }
-
-  return { active, setSource };
-}