@intx/agent 0.1.2 → 0.3.0

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

package/src/tool.ts

@@ -1,148 +0,0 @@
-// Tool registration and dispatch.
-//
-// Two registration shapes are supported:
-//
-//   `tool({ definition, handler })`        — handler receives the full
-//                                            ToolCall and returns the full
-//                                            ToolResult. Use when the
-//                                            handler needs the callId or
-//                                            wants to set isError/detail/
-//                                            pendingMarker.
-//
-//   `stringTool({ definition, handler })`  — sugar for the common case of
-//                                            "compute a string from the
-//                                            parsed arguments." The callId
-//                                            is filled in from the
-//                                            surrounding ToolCall, and
-//                                            isError is false unless the
-//                                            handler throws.
-//
-// `createToolRunner(tools)` builds a `ToolRunner` that dispatches by tool
-// name. Per the ToolRunner contract (packages/types/src/runtime.ts), `run`
-// must not throw — unknown tool names and handler exceptions are surfaced
-// as `ToolResult` with `isError: true` so the model sees them and can
-// recover.
-
-import type {
-  ToolCall,
-  ToolDefinition,
-  ToolResult,
-  ToolRunner,
-} from "@intx/types/runtime";
-
-export type ToolHandler = (
-  call: ToolCall,
-  signal: AbortSignal,
-) => Promise<ToolResult>;
-
-export type StringToolHandler = (
-  args: Record<string, unknown>,
-  signal: AbortSignal,
-) => Promise<string>;
-
-export type AgentTool =
-  | { kind: "full"; definition: ToolDefinition; handler: ToolHandler }
-  | {
-      kind: "string";
-      definition: ToolDefinition;
-      handler: StringToolHandler;
-    };
-
-export function tool(args: {
-  definition: ToolDefinition;
-  handler: ToolHandler;
-}): AgentTool {
-  return { kind: "full", definition: args.definition, handler: args.handler };
-}
-
-export function stringTool(args: {
-  definition: ToolDefinition;
-  handler: StringToolHandler;
-}): AgentTool {
-  return {
-    kind: "string",
-    definition: args.definition,
-    handler: args.handler,
-  };
-}
-
-/**
- * Adapt a pre-built ToolRunner (e.g. the one returned by
- * `createPosixTools`) into a list of AgentTools that can be passed to
- * `createAgent({ tools })`. Each definition becomes a full-handler
- * AgentTool that delegates to the runner's `run`.
- *
- * Use this when integrating tool packages whose public surface is a
- * single ToolRunner rather than individual handlers.
- */
-export function fromToolRunner(runner: {
-  readonly definitions: readonly ToolDefinition[];
-  run: ToolRunner["run"];
-}): AgentTool[] {
-  return runner.definitions.map((definition) => ({
-    kind: "full",
-    definition,
-    handler: (call, signal) => runner.run(call, signal),
-  }));
-}
-
-export class DuplicateToolError extends Error {
-  readonly toolName: string;
-
-  constructor(toolName: string) {
-    super(`duplicate tool name: ${toolName}`);
-    this.name = "DuplicateToolError";
-    this.toolName = toolName;
-  }
-}
-
-export type AgentToolRunner = ToolRunner & {
-  readonly definitions: readonly ToolDefinition[];
-};
-
-/**
- * Build a `ToolRunner` that dispatches by tool name. Throws
- * `DuplicateToolError` at construction if any two tools share a name.
- *
- * At call time, unknown tool names and exceptions from handlers are
- * converted to `ToolResult { isError: true }` so the contract on
- * `ToolRunner.run` ("must not throw") is upheld.
- */
-export function createToolRunner(tools: AgentTool[]): AgentToolRunner {
-  const byName = new Map<string, AgentTool>();
-  for (const t of tools) {
-    if (byName.has(t.definition.name)) {
-      throw new DuplicateToolError(t.definition.name);
-    }
-    byName.set(t.definition.name, t);
-  }
-
-  const definitions: readonly ToolDefinition[] = tools.map((t) => t.definition);
-
-  return {
-    definitions,
-    async run(call, signal): Promise<ToolResult> {
-      const found = byName.get(call.name);
-      if (found === undefined) {
-        return {
-          callId: call.id,
-          content: `unknown tool: ${call.name}`,
-          isError: true,
-        };
-      }
-      try {
-        if (found.kind === "full") {
-          return await found.handler(call, signal);
-        }
-        const text = await found.handler(call.arguments, signal);
-        return { callId: call.id, content: text };
-      } catch (err) {
-        return {
-          callId: call.id,
-          content: err instanceof Error ? err.message : String(err),
-          isError: true,
-        };
-      }
-    },
-  };
-}

package/tsconfig.json

@@ -1,4 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "include": ["src/**/*.ts"]
-}