@intx/agent 0.1.2

package/src/source.test.ts

@@ -0,0 +1,171 @@
+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

@@ -0,0 +1,93 @@
+// 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 };
+}

package/src/stream.test.ts

@@ -0,0 +1,167 @@
+import { describe, test, expect } from "bun:test";
+
+import type { ReactorEmittedEvent } from "@intx/inference";
+
+import { createStreamConsumer, StreamBackpressureError } from "./stream";
+
+/**
+ * Build a minimal ReactorEmittedEvent suitable for fan-out testing. The
+ * event's structural details do not matter — the stream consumer treats
+ * events opaquely — so we use `reactor.done`, which has an empty `data`.
+ */
+function makeEvent(seq: number): ReactorEmittedEvent {
+  return { type: "reactor.done", seq, data: {} };
+}
+
+async function collect(
+  it: AsyncIterableIterator<ReactorEmittedEvent>,
+  n: number,
+): Promise<ReactorEmittedEvent[]> {
+  const out: ReactorEmittedEvent[] = [];
+  for (let i = 0; i < n; i++) {
+    const r = await it.next();
+    if (r.done === true) break;
+    out.push(r.value);
+  }
+  return out;
+}
+
+describe("createStreamConsumer", () => {
+  test("delivers buffered events to a later iterator read", async () => {
+    const c = createStreamConsumer(8);
+    const it = c.iterator();
+    c.push(makeEvent(1));
+    c.push(makeEvent(2));
+    const got = await collect(it, 2);
+    expect(got.map((e) => e.seq)).toEqual([1, 2]);
+  });
+
+  test("delivers events directly to a waiting iterator", async () => {
+    const c = createStreamConsumer(8);
+    const it = c.iterator();
+    const pending = it.next();
+    c.push(makeEvent(42));
+    const r = await pending;
+    expect(r.done).toBe(false);
+    if (r.done !== true) expect(r.value.seq).toBe(42);
+  });
+
+  test("close terminates pending and subsequent reads with done", async () => {
+    const c = createStreamConsumer(8);
+    const it = c.iterator();
+    const pending = it.next();
+    c.close();
+    const r1 = await pending;
+    expect(r1.done).toBe(true);
+    const r2 = await it.next();
+    expect(r2.done).toBe(true);
+  });
+
+  test("close after buffered events still drains them before done", async () => {
+    const c = createStreamConsumer(8);
+    const it = c.iterator();
+    c.push(makeEvent(1));
+    c.push(makeEvent(2));
+    c.close();
+    const r1 = await it.next();
+    expect(r1.done).toBe(false);
+    const r2 = await it.next();
+    expect(r2.done).toBe(false);
+    const r3 = await it.next();
+    expect(r3.done).toBe(true);
+  });
+
+  test("overflow throws StreamBackpressureError on next read", async () => {
+    const c = createStreamConsumer(3);
+    const it = c.iterator();
+    c.push(makeEvent(1));
+    c.push(makeEvent(2));
+    c.push(makeEvent(3));
+    c.push(makeEvent(4));
+
+    // Buffered events drain first.
+    const r1 = await it.next();
+    expect(r1.done).toBe(false);
+    const r2 = await it.next();
+    expect(r2.done).toBe(false);
+    const r3 = await it.next();
+    expect(r3.done).toBe(false);
+
+    // Next read sees the overflow.
+    await expect(it.next()).rejects.toBeInstanceOf(StreamBackpressureError);
+  });
+
+  test("overflow rejects a pending waiter", async () => {
+    const c = createStreamConsumer(2);
+    const it = c.iterator();
+    const pending = it.next();
+    // Direct delivery to the waiter does NOT increase the buffer.
+    c.push(makeEvent(1));
+    const r1 = await pending;
+    expect(r1.done).toBe(false);
+
+    // Now buffer 2 events (capacity), then a 3rd while another waiter is
+    // pending — wait, an immediate waiter would consume the 3rd directly.
+    // Instead saturate the buffer first.
+    c.push(makeEvent(2));
+    c.push(makeEvent(3));
+    // Saturated. A pending waiter at this point will be served from the
+    // buffer; the overflow only fires on a push that has no waiter and a
+    // full buffer.
+    c.push(makeEvent(4));
+
+    // Drain.
+    const r2 = await it.next();
+    expect(r2.done).toBe(false);
+    const r3 = await it.next();
+    expect(r3.done).toBe(false);
+
+    await expect(it.next()).rejects.toBeInstanceOf(StreamBackpressureError);
+  });
+
+  test("multiple consumers buffer independently", async () => {
+    const a = createStreamConsumer(8);
+    const b = createStreamConsumer(8);
+    const ai = a.iterator();
+    const bi = b.iterator();
+
+    a.push(makeEvent(1));
+    b.push(makeEvent(1));
+    a.push(makeEvent(2));
+    b.push(makeEvent(2));
+
+    const aGot = await collect(ai, 2);
+    const bGot = await collect(bi, 2);
+    expect(aGot.map((e) => e.seq)).toEqual([1, 2]);
+    expect(bGot.map((e) => e.seq)).toEqual([1, 2]);
+  });
+
+  test("iterator.return() closes the consumer", async () => {
+    const c = createStreamConsumer(8);
+    const it = c.iterator();
+    expect(c.closed).toBe(false);
+    await it.return?.();
+    expect(c.closed).toBe(true);
+    const r = await it.next();
+    expect(r.done).toBe(true);
+  });
+
+  test("push after close is ignored", async () => {
+    const c = createStreamConsumer(8);
+    const it = c.iterator();
+    c.close();
+    c.push(makeEvent(1));
+    const r = await it.next();
+    expect(r.done).toBe(true);
+  });
+
+  test("Symbol.asyncIterator returns the iterator itself", async () => {
+    const c = createStreamConsumer(8);
+    const it = c.iterator();
+    expect(it[Symbol.asyncIterator]()).toBe(it);
+  });
+
+  test("rejects maxBuffer < 1", () => {
+    expect(() => createStreamConsumer(0)).toThrow();
+  });
+});

package/src/stream.ts

@@ -0,0 +1,142 @@
+// Bounded per-consumer fan-out for the agent's reactor event stream.
+//
+// Each call to `agent.stream()` creates a fresh `StreamConsumer`. The
+// agent feeds every reactor event to every consumer; consumers buffer
+// independently. If a consumer falls more than `maxBuffer` events behind
+// it is poisoned with `StreamBackpressureError` and its iterator throws
+// on the next read — the consumer is removed but other consumers keep
+// running.
+//
+// Loud failure matches the defensive-coding rule: silently dropping
+// events would hide consumer bugs, and unbounded buffering would let a
+// stalled consumer balloon the agent's memory. The cap is configurable
+// via `streamBufferMax` on `AgentConfig`.
+
+import type { ReactorEmittedEvent } from "@intx/inference";
+
+export class StreamBackpressureError extends Error {
+  readonly maxBuffer: number;
+
+  constructor(maxBuffer: number) {
+    super(`stream consumer fell more than ${String(maxBuffer)} events behind`);
+    this.name = "StreamBackpressureError";
+    this.maxBuffer = maxBuffer;
+  }
+}
+
+type Waiter = {
+  resolve: (value: IteratorResult<ReactorEmittedEvent>) => void;
+  reject: (reason: unknown) => void;
+};
+
+export type StreamConsumer = {
+  /** Deliver an event to this consumer's buffer. */
+  push(event: ReactorEmittedEvent): void;
+  /** Cleanly terminate the iterator with `done: true`. */
+  close(): void;
+  /** True once close() or an overflow has poisoned the consumer. */
+  readonly closed: boolean;
+  /** Iterator handed back to the caller of `stream()`. */
+  iterator(): AsyncIterableIterator<ReactorEmittedEvent>;
+};
+
+export function createStreamConsumer(maxBuffer: number): StreamConsumer {
+  if (maxBuffer < 1) {
+    throw new Error(`streamBufferMax must be >= 1, got ${String(maxBuffer)}`);
+  }
+
+  const buffer: ReactorEmittedEvent[] = [];
+  const waiters: Waiter[] = [];
+  let overflow: StreamBackpressureError | undefined;
+  let done = false;
+
+  function settleOverflowedWaiters(err: StreamBackpressureError): void {
+    while (waiters.length > 0) {
+      const w = waiters.shift();
+      if (w === undefined) return;
+      w.reject(err);
+    }
+  }
+
+  function settleDoneWaiters(): void {
+    while (waiters.length > 0) {
+      const w = waiters.shift();
+      if (w === undefined) return;
+      w.resolve({ value: undefined, done: true });
+    }
+  }
+
+  function push(event: ReactorEmittedEvent): void {
+    if (done || overflow !== undefined) return;
+
+    if (waiters.length > 0) {
+      const w = waiters.shift();
+      if (w === undefined) return;
+      w.resolve({ value: event, done: false });
+      return;
+    }
+
+    if (buffer.length >= maxBuffer) {
+      overflow = new StreamBackpressureError(maxBuffer);
+      settleOverflowedWaiters(overflow);
+      return;
+    }
+
+    buffer.push(event);
+  }
+
+  function close(): void {
+    if (done) return;
+    done = true;
+    settleDoneWaiters();
+  }
+
+  function nextResult(): Promise<IteratorResult<ReactorEmittedEvent>> {
+    if (overflow !== undefined) {
+      // Drain any buffered events before throwing so the caller sees
+      // every event up to the overflow point.
+      if (buffer.length > 0) {
+        const ev = buffer.shift();
+        if (ev !== undefined) {
+          return Promise.resolve({ value: ev, done: false });
+        }
+      }
+      return Promise.reject(overflow);
+    }
+    if (buffer.length > 0) {
+      const ev = buffer.shift();
+      if (ev !== undefined) {
+        return Promise.resolve({ value: ev, done: false });
+      }
+    }
+    if (done) {
+      return Promise.resolve({ value: undefined, done: true });
+    }
+    return new Promise((resolve, reject) => {
+      waiters.push({ resolve, reject });
+    });
+  }
+
+  function iterator(): AsyncIterableIterator<ReactorEmittedEvent> {
+    const it: AsyncIterableIterator<ReactorEmittedEvent> = {
+      next: nextResult,
+      async return() {
+        close();
+        return { value: undefined, done: true };
+      },
+      [Symbol.asyncIterator]() {
+        return it;
+      },
+    };
+    return it;
+  }
+
+  return {
+    push,
+    close,
+    get closed() {
+      return done || overflow !== undefined;
+    },
+    iterator,
+  };
+}