@intx/agent 0.1.2 → 0.2.2

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 };
-}

package/src/stream.test.ts

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

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

package/src/tool.test.ts

@@ -1,217 +0,0 @@
-import { describe, test, expect } from "bun:test";
-
-import type { ToolDefinition } from "@intx/types/runtime";
-
-import {
-  createToolRunner,
-  DuplicateToolError,
-  fromToolRunner,
-  stringTool,
-  tool,
-} from "./tool";
-
-const DEF_A: ToolDefinition = {
-  name: "a",
-  description: "tool a",
-  inputSchema: { type: "object" },
-};
-
-const DEF_B: ToolDefinition = {
-  name: "b",
-  description: "tool b",
-  inputSchema: { type: "object" },
-};
-
-describe("createToolRunner", () => {
-  test("dispatches to a full handler by tool name", async () => {
-    const runner = createToolRunner([
-      tool({
-        definition: DEF_A,
-        handler: async (call) => ({
-          callId: call.id,
-          content: `got ${String(call.arguments.x)}`,
-        }),
-      }),
-    ]);
-
-    const result = await runner.run(
-      { id: "c1", name: "a", arguments: { x: 5 } },
-      new AbortController().signal,
-    );
-
-    expect(result).toEqual({ callId: "c1", content: "got 5" });
-  });
-
-  test("lifts the string handler return into a ToolResult", async () => {
-    const runner = createToolRunner([
-      stringTool({
-        definition: DEF_A,
-        handler: async (args) => `hello ${String(args.name)}`,
-      }),
-    ]);
-
-    const result = await runner.run(
-      { id: "c2", name: "a", arguments: { name: "world" } },
-      new AbortController().signal,
-    );
-
-    expect(result).toEqual({ callId: "c2", content: "hello world" });
-  });
-
-  test("returns an error ToolResult for an unknown tool name", async () => {
-    const runner = createToolRunner([
-      tool({
-        definition: DEF_A,
-        handler: async (call) => ({ callId: call.id, content: "" }),
-      }),
-    ]);
-
-    const result = await runner.run(
-      { id: "c3", name: "nope", arguments: {} },
-      new AbortController().signal,
-    );
-
-    expect(result.isError).toBe(true);
-    expect(result.callId).toBe("c3");
-    expect(result.content).toBe("unknown tool: nope");
-  });
-
-  test("wraps a thrown error from a full handler into an error ToolResult", async () => {
-    const runner = createToolRunner([
-      tool({
-        definition: DEF_A,
-        handler: async () => {
-          throw new Error("boom");
-        },
-      }),
-    ]);
-
-    const result = await runner.run(
-      { id: "c4", name: "a", arguments: {} },
-      new AbortController().signal,
-    );
-
-    expect(result).toEqual({ callId: "c4", content: "boom", isError: true });
-  });
-
-  test("wraps a thrown error from a string handler into an error ToolResult", async () => {
-    const runner = createToolRunner([
-      stringTool({
-        definition: DEF_A,
-        handler: async () => {
-          throw new Error("bad input");
-        },
-      }),
-    ]);
-
-    const result = await runner.run(
-      { id: "c5", name: "a", arguments: {} },
-      new AbortController().signal,
-    );
-
-    expect(result).toEqual({
-      callId: "c5",
-      content: "bad input",
-      isError: true,
-    });
-  });
-
-  test("exposes definitions in registration order", () => {
-    const runner = createToolRunner([
-      tool({
-        definition: DEF_A,
-        handler: async (call) => ({ callId: call.id, content: "" }),
-      }),
-      stringTool({ definition: DEF_B, handler: async () => "x" }),
-    ]);
-
-    expect(runner.definitions.map((d) => d.name)).toEqual(["a", "b"]);
-  });
-
-  test("throws DuplicateToolError at construction on duplicate names", () => {
-    expect(() =>
-      createToolRunner([
-        tool({
-          definition: DEF_A,
-          handler: async (call) => ({ callId: call.id, content: "" }),
-        }),
-        stringTool({ definition: DEF_A, handler: async () => "x" }),
-      ]),
-    ).toThrow(DuplicateToolError);
-  });
-
-  test("propagates the AbortSignal to the handler", async () => {
-    let received: AbortSignal | undefined;
-    const runner = createToolRunner([
-      tool({
-        definition: DEF_A,
-        handler: async (call, signal) => {
-          received = signal;
-          return { callId: call.id, content: "ok" };
-        },
-      }),
-    ]);
-
-    const ctl = new AbortController();
-    await runner.run({ id: "c6", name: "a", arguments: {} }, ctl.signal);
-
-    expect(received).toBe(ctl.signal);
-  });
-
-  test("fromToolRunner wraps each definition as a full-handler AgentTool", async () => {
-    const calls: string[] = [];
-    const stubRunner = {
-      definitions: [DEF_A, DEF_B] as const,
-      run: async (call: {
-        id: string;
-        name: string;
-        arguments: Record<string, unknown>;
-      }) => {
-        calls.push(call.name);
-        return Promise.resolve({
-          callId: call.id,
-          content: `ran ${call.name}`,
-        });
-      },
-    };
-
-    const tools = fromToolRunner(stubRunner);
-    const runner = createToolRunner(tools);
-
-    expect(runner.definitions.map((d) => d.name)).toEqual(["a", "b"]);
-
-    const ra = await runner.run(
-      { id: "c8", name: "a", arguments: {} },
-      new AbortController().signal,
-    );
-    expect(ra).toEqual({ callId: "c8", content: "ran a" });
-
-    const rb = await runner.run(
-      { id: "c9", name: "b", arguments: {} },
-      new AbortController().signal,
-    );
-    expect(rb).toEqual({ callId: "c9", content: "ran b" });
-
-    expect(calls).toEqual(["a", "b"]);
-  });
-
-  test("string handler receives the parsed arguments object", async () => {
-    let received: Record<string, unknown> | undefined;
-    const runner = createToolRunner([
-      stringTool({
-        definition: DEF_A,
-        handler: async (args) => {
-          received = args;
-          return "ok";
-        },
-      }),
-    ]);
-
-    await runner.run(
-      { id: "c7", name: "a", arguments: { foo: 1, bar: "x" } },
-      new AbortController().signal,
-    );
-
-    expect(received).toEqual({ foo: 1, bar: "x" });
-  });
-});