@infinityi/engine-lib 1.0.0

package/dist/testing/conformance.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Provider conformance suite (Phase 8).
+ *
+ * A shared, fixture-driven test battery that **every** {@link Provider} adapter
+ * must pass — the in-house OpenAI / Anthropic / Google / OpenAI-compatible
+ * adapters as well as any third-party adapter. It guarantees cross-provider
+ * parity on the parts of the contract that callers above the provider layer
+ * rely on: buffered completion, streaming, tool calling, usage reporting,
+ * capability honesty, and error mapping.
+ *
+ * The battery is provider-agnostic: each adapter supplies its **native wire
+ * fixtures** (the JSON / SSE bytes its vendor would return) plus the canonical
+ * normalized values those fixtures should decode to. The battery drives the
+ * public `Provider` seam through an injected fake `fetch` and asserts the
+ * normalized {@link CompletionResult} / {@link StreamEvent} shape — never the
+ * vendor wire format.
+ *
+ * Shipped from its own subpath (`@infinityi/engine-lib/testing/conformance`)
+ * rather than the main `@infinityi/engine-lib/testing` barrel. It registers
+ * tests against Bun's test-runner API when called, while remaining safe to
+ * import in non-Bun runtimes.
+ *
+ * @example
+ * ```ts
+ * import { describe, expect, it } from "bun:test";
+ * import { runProviderConformance } from "@infinityi/engine-lib/testing/conformance";
+ * import { createOpenAICompatible } from "@infinityi/engine-lib/providers";
+ *
+ * runProviderConformance("openai-compatible", {
+ *   testApi: { describe, expect, it },
+ *   makeProvider: ({ fetch }) => createOpenAICompatible({ baseUrl: "https://h/v1", model: "m", fetch }),
+ *   expectPath: "/chat/completions",
+ *   fixtures: {
+ *     text: { body: { choices: [{ finish_reason: "stop", message: { content: "hi" } }] }, expectText: "hi" },
+ *     // …toolCall, usage, stream
+ *   },
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { describe as bunDescribe, expect as bunExpect, it as bunIt } from "bun:test";
+import type { PipelineLike } from "@infinityi/forge/http/client";
+import type { Provider, Usage } from "../providers/types";
+/** A `fetch`-compatible function. */
+type FetchFn = typeof globalThis.fetch;
+export interface ConformanceTestApi {
+    readonly describe: typeof bunDescribe;
+    readonly expect: typeof bunExpect;
+    readonly it: typeof bunIt;
+}
+/** The transport seams the battery injects into the adapter under test. */
+export interface ProviderIO {
+    /** Fake `fetch` returning the fixture bytes. */
+    readonly fetch: FetchFn;
+    /** Optional resilience override (the battery passes a no-retry pipeline
+     * for the error-mapping case so it doesn't pay the default retry backoff). */
+    readonly resilience?: PipelineLike;
+}
+/** Build a fresh adapter wired to the supplied transport seams. */
+export type MakeProvider = (io: ProviderIO) => Provider;
+/** Native wire fixtures plus the canonical normalized values they decode to. */
+export interface ConformanceFixtures {
+    /** A buffered completion whose body decodes to assistant text. */
+    readonly text: {
+        readonly body: unknown;
+        readonly expectText: string;
+    };
+    /** A buffered completion whose body decodes to a single tool call. */
+    readonly toolCall: {
+        readonly body: unknown;
+        readonly expectName: string;
+        readonly expectArgs?: Record<string, unknown>;
+    };
+    /** A buffered completion whose body reports token usage. */
+    readonly usage: {
+        readonly body: unknown;
+        readonly expect: Usage;
+    };
+    /**
+     * A streaming response (raw `text/event-stream` bytes) that yields text
+     * deltas and a final finish. Provide this iff the adapter declares
+     * `capabilities.streaming` — the battery cross-checks the two.
+     */
+    readonly stream?: {
+        readonly sse: string;
+        readonly expectText: string;
+    };
+}
+/** Options for {@link runProviderConformance}. */
+export interface ConformanceOptions {
+    /** Factory building the adapter under test from an injected fake `fetch`. */
+    readonly makeProvider: MakeProvider;
+    /** The native wire fixtures for this provider. */
+    readonly fixtures: ConformanceFixtures;
+    /** Substring asserted to appear in the request URL (e.g. `/messages`). */
+    readonly expectPath?: string;
+    /** Test-runner API. Pass Bun's `{ describe, expect, it }` from a test file. */
+    readonly testApi?: ConformanceTestApi;
+}
+/**
+ * Register a `describe()` block of shared assertions the `Provider` adapter
+ * `name` must satisfy. Call it from a `*.test.ts` file (it uses `bun:test`).
+ */
+export declare function runProviderConformance(name: string, opts: ConformanceOptions): void;
+export {};

package/dist/testing/conformance.js

@@ -0,0 +1,132 @@
+import {
+  jsonFetch,
+  sseFetch
+} from "../index-dexgmwg6.js";
+import"../index-vnby35rm.js";
+import"../index-19pwq79t.js";
+import {
+  combine
+} from "../index-bqg01r42.js";
+import"../index-zfgr4xx3.js";
+import {
+  ProviderError
+} from "../index-7690reng.js";
+import {
+  user
+} from "../index-1p6mb2vz.js";
+
+// src/testing/conformance.ts
+function getTestApi() {
+  const globals = globalThis;
+  if (typeof globals.describe === "function" && typeof globals.expect === "function" && typeof globals.it === "function") {
+    return {
+      describe: globals.describe,
+      expect: globals.expect,
+      it: globals.it
+    };
+  }
+  try {
+    const requireFn = (0, eval)("require");
+    const api = typeof requireFn === "function" ? requireFn("bun:test") : undefined;
+    if (typeof api?.describe === "function" && typeof api.expect === "function" && typeof api.it === "function") {
+      return {
+        describe: api.describe,
+        expect: api.expect,
+        it: api.it
+      };
+    }
+  } catch {}
+  throw new Error("runProviderConformance requires Bun's test runner; call it from a Bun test file.");
+}
+var NO_RETRY = combine();
+var REQUEST = { messages: [user("hi")] };
+async function collect(events) {
+  const out = [];
+  for await (const event of events)
+    out.push(event);
+  return out;
+}
+function runProviderConformance(name, opts) {
+  const { describe, expect, it } = opts.testApi ?? getTestApi();
+  const { makeProvider, fixtures, expectPath } = opts;
+  describe(`provider conformance — ${name}`, () => {
+    it("declares honest, well-formed capabilities and identity", () => {
+      const provider = makeProvider({
+        fetch: jsonFetch(fixtures.text.body).fetch
+      });
+      expect(typeof provider.name).toBe("string");
+      expect(provider.name.length).toBeGreaterThan(0);
+      expect(typeof provider.defaultModel).toBe("string");
+      expect(provider.defaultModel.length).toBeGreaterThan(0);
+      const caps = provider.capabilities;
+      for (const flag of [
+        caps.tools,
+        caps.streaming,
+        caps.multimodalInput,
+        caps.parallelToolCalls,
+        caps.structuredOutput
+      ]) {
+        expect(typeof flag).toBe("boolean");
+      }
+      if (fixtures.stream !== undefined)
+        expect(caps.streaming).toBe(true);
+    });
+    it("completes a buffered turn into normalized text", async () => {
+      const { fetch, calls } = jsonFetch(fixtures.text.body);
+      const result = await makeProvider({ fetch }).complete(REQUEST);
+      expect(calls.length).toBeGreaterThan(0);
+      if (expectPath !== undefined)
+        expect(calls[0]?.url).toContain(expectPath);
+      expect(result.finishReason).toBe("stop");
+      expect(typeof result.model).toBe("string");
+      const text = result.message.content.filter((p) => p.type === "text").map((p) => p.text).join("");
+      expect(text).toBe(fixtures.text.expectText);
+    });
+    it("surfaces a tool call with an id, name, and parsed arguments", async () => {
+      const result = await makeProvider({
+        fetch: jsonFetch(fixtures.toolCall.body).fetch
+      }).complete(REQUEST);
+      expect(result.finishReason).toBe("tool_calls");
+      expect(result.toolCalls.length).toBeGreaterThan(0);
+      const call = result.toolCalls[0];
+      expect(typeof call.id).toBe("string");
+      expect(call.id.length).toBeGreaterThan(0);
+      expect(call.name).toBe(fixtures.toolCall.expectName);
+      if (fixtures.toolCall.expectArgs !== undefined) {
+        expect(call.arguments).toEqual(fixtures.toolCall.expectArgs);
+      }
+      expect(result.message.content.some((p) => p.type === "tool_call")).toBe(true);
+    });
+    it("normalizes token usage", async () => {
+      const result = await makeProvider({
+        fetch: jsonFetch(fixtures.usage.body).fetch
+      }).complete(REQUEST);
+      expect(result.usage).toBeDefined();
+      expect(result.usage?.inputTokens).toBe(fixtures.usage.expect.inputTokens);
+      expect(result.usage?.outputTokens).toBe(fixtures.usage.expect.outputTokens);
+      expect(result.usage?.totalTokens).toBe(fixtures.usage.expect.totalTokens);
+    });
+    it("maps a non-2xx response to a ProviderError", async () => {
+      const provider = makeProvider({
+        fetch: jsonFetch({ error: "boom" }, { status: 500 }).fetch,
+        resilience: NO_RETRY
+      });
+      await expect(provider.complete(REQUEST)).rejects.toBeInstanceOf(ProviderError);
+    });
+    const streamFixture = fixtures.stream;
+    if (streamFixture !== undefined) {
+      it("streams text deltas bracketed by message_start and finish", async () => {
+        const events = await collect(makeProvider({ fetch: sseFetch(streamFixture.sse).fetch }).stream(REQUEST));
+        expect(events[0]?.type).toBe("message_start");
+        expect(events[events.length - 1]?.type).toBe("finish");
+        const text = events.filter((e) => e.type === "text_delta").map((e) => e.text).join("");
+        expect(text).toBe(streamFixture.expectText);
+      });
+    } else {
+      it.skip("streaming (no stream fixture provided)", () => {});
+    }
+  });
+}
+export {
+  runProviderConformance
+};

package/dist/testing/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `@infinityi/engine-lib/testing` — in-memory helpers and assertions for tests.
+ *
+ * Phase 1 ships only the helpers relevant to the foundation layer;
+ * provider and session doubles arrive with Phases 2 and 5.
+ *
+ * @module
+ */
+import type { Message } from "../messages/types";
+import type { Schema } from "../schema/types";
+import type { EngineContext } from "../runtime/types";
+import type { CompletionRequest, CompletionResult, Provider, ProviderCapabilities, ToolCall, Usage } from "../providers/types";
+import { InMemorySessionStore } from "../session/index";
+import type { StreamEvent } from "../providers/stream";
+/** Build a `Message[]` from arguments, for readable test fixtures. */
+export declare function conversation(...messages: Message[]): Message[];
+/** Options for {@link mockProvider}. */
+export interface MockProviderOptions {
+    readonly name?: string;
+    readonly defaultModel?: string;
+    readonly capabilities?: Partial<ProviderCapabilities>;
+    /** Scripted buffered result (or a function of the request). */
+    readonly result?: CompletionResult | ((req: CompletionRequest) => CompletionResult);
+    /** Scripted stream events (or a function of the request). When omitted, a
+     * single text/finish stream is derived from {@link MockProviderOptions.result}. */
+    readonly events?: StreamEvent[] | ((req: CompletionRequest) => StreamEvent[]);
+    /** Called with every request, so tests can assert on what was sent. */
+    readonly onRequest?: (req: CompletionRequest, ctx?: EngineContext) => void;
+}
+/**
+ * A network-free {@link Provider} for contract tests and Phase-4 run-loop
+ * tests. Returns scripted results/streams and records every request.
+ */
+export declare function mockProvider(opts?: MockProviderOptions): Provider;
+/** Drain a {@link Provider.stream} into a {@link CompletionResult} for assertions. */
+export declare function collectProviderStream(provider: Provider, req: CompletionRequest, ctx?: EngineContext): Promise<CompletionResult>;
+/**
+ * Parse `input` with `schema`, returning the typed value. Throws (failing
+ * the test) with a readable message listing all issues if invalid.
+ */
+export declare function expectValid<T>(schema: Schema<T>, input: unknown): T;
+/** A recorded outbound call captured by a {@link RecordingFetch}. */
+export interface RecordedCall {
+    readonly url: string;
+    readonly init?: RequestInit;
+}
+/** A fake `fetch` plus the list of calls it recorded. */
+export interface RecordingFetch {
+    readonly fetch: typeof fetch;
+    readonly calls: RecordedCall[];
+}
+/** A `ReadableStream<Uint8Array>` that emits `chunks` (one enqueue each). */
+export declare function byteStreamOf(...chunks: string[]): ReadableStream<Uint8Array>;
+/**
+ * A `fetch` that returns a fixed JSON `body` / `status` and records every call,
+ * for driving a {@link Provider} adapter without a network.
+ */
+export declare function jsonFetch(body: unknown, init?: {
+    status?: number;
+}): RecordingFetch;
+/**
+ * A `fetch` that returns a fixed `text/event-stream` body and records every
+ * call, for driving a {@link Provider} adapter's `stream()` without a network.
+ */
+export declare function sseFetch(sse: string): RecordingFetch;
+/**
+ * Build a buffered text {@link CompletionResult} (`finishReason: "stop"`) for
+ * scripting a {@link mockProvider} or {@link scriptedProvider} turn.
+ */
+export declare function textResult(text: string, usage?: Usage): CompletionResult;
+/**
+ * Build a tool-call {@link CompletionResult} (`finishReason: "tool_calls"`),
+ * mirroring each {@link ToolCall} as a `tool_call` message part.
+ */
+export declare function toolCallResult(calls: ToolCall[], usage?: Usage): CompletionResult;
+/**
+ * A {@link Provider} that returns each scripted result in turn; the last
+ * result repeats once the script is exhausted. Handy for multi-turn run-loop
+ * tests (e.g. a tool call followed by a final answer).
+ */
+export declare function scriptedProvider(results: readonly CompletionResult[], opts?: MockProviderOptions): Provider;
+export { InMemorySessionStore } from "../session/index";
+/** Construct a fresh in-memory {@link SessionStore} double. */
+export declare function inMemorySessionStore(): InMemorySessionStore;

package/dist/testing/index.js

@@ -0,0 +1,31 @@
+import {
+  byteStreamOf,
+  collectProviderStream,
+  conversation,
+  expectValid,
+  inMemorySessionStore,
+  jsonFetch,
+  mockProvider,
+  scriptedProvider,
+  sseFetch,
+  textResult,
+  toolCallResult
+} from "../index-dexgmwg6.js";
+import {
+  InMemorySessionStore
+} from "../index-vnby35rm.js";
+import"../index-zfgr4xx3.js";
+export {
+  toolCallResult,
+  textResult,
+  sseFetch,
+  scriptedProvider,
+  mockProvider,
+  jsonFetch,
+  inMemorySessionStore,
+  expectValid,
+  conversation,
+  collectProviderStream,
+  byteStreamOf,
+  InMemorySessionStore
+};

package/dist/tools/define.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `defineTool` — the ergonomic constructor for {@link ToolDefinition}s.
+ *
+ * Application code should prefer this constructor over hand-writing
+ * `ToolDefinition` objects. The argument type `TArgs` is inferred from the
+ * parameter schema (`parameters: Schema<TArgs>`), so `execute` receives
+ * fully-typed, already-validated arguments with zero annotations.
+ *
+ * @example
+ * ```ts
+ * import { s } from "@infinityi/engine-lib/schema";
+ * import { defineTool } from "@infinityi/engine-lib/tools";
+ *
+ * const readFile = defineTool({
+ *   name: "read_file",
+ *   description: "Read a file from the workspace.",
+ *   parameters: s.object({ path: s.string() }),
+ *   execute: async ({ path }) => ({ ok: true, content: await workspace.read(path) }),
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { Schema } from "../schema/types";
+import type { ToolContext, ToolDefinition, ToolResult } from "./types";
+/** The shape passed to {@link defineTool}, with `execute` typed against the schema. */
+export interface ToolSpec<TArgs> {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: Schema<TArgs>;
+    execute(args: TArgs, ctx: ToolContext): ToolResult | Promise<ToolResult>;
+}
+/**
+ * Define a tool with argument types inferred from its parameter schema.
+ *
+ * Pure: validates that `name` is non-empty and returns a frozen
+ * {@link ToolDefinition}. No execution or registration happens here. Return
+ * `{ ok: false, error }` for expected/domain failures; reserve thrown errors
+ * for unexpected implementation faults. `runAgent` isolates both forms as tool
+ * results so one bad tool call does not crash the whole run.
+ */
+export declare function defineTool<TArgs>(spec: ToolSpec<TArgs>): ToolDefinition<TArgs>;

package/dist/tools/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@infinityi/engine-lib/tools` — the tool contract: declarative tool definitions, the
+ * structured tool-result model, and the mappers that connect tools to the
+ * conversation model (Phase 1) and the provider toolset (Phase 2).
+ *
+ * @module
+ */
+export { defineTool } from "./define";
+export type { ToolSpec } from "./define";
+export { renderToolContent, toProviderTool, toToolResultMessage } from "./result";
+export type { ToolContext, ToolDefinition, ToolFailure, ToolResult, ToolSuccess, } from "./types";

package/dist/tools/index.js

@@ -0,0 +1,15 @@
+import {
+  defineTool
+} from "../index-w34cbktd.js";
+import {
+  renderToolContent,
+  toProviderTool,
+  toToolResultMessage
+} from "../index-rentvdpp.js";
+import"../index-1p6mb2vz.js";
+export {
+  toToolResultMessage,
+  toProviderTool,
+  renderToolContent,
+  defineTool
+};

package/dist/tools/result.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Normalization between the Phase-3 tool layer and its neighbours.
+ *
+ * Two directions:
+ * - {@link renderToolContent} / {@link toToolResultMessage} map a
+ *   {@link ToolResult} *down* into the Phase-1 conversation model (a
+ *   `role: "tool"` {@link Message}), reusing the `toolResult` factory.
+ * - {@link toProviderTool} maps a {@link ToolDefinition} *across* into the
+ *   Phase-2 {@link ProviderTool} the provider advertises to the model.
+ *
+ * @module
+ */
+import type { Message, TextPart } from "../messages/types";
+import type { ProviderTool } from "../providers/types";
+import type { ToolDefinition, ToolResult } from "./types";
+/**
+ * Render a {@link ToolResult}'s payload into `TextPart[]`.
+ *
+ * This rendering is part of the stable tool contract: strings pass through
+ * unchanged; `undefined`/`null` become empty text; any other value is
+ * JSON-encoded so structured results survive into the text-only Phase-1
+ * tool-result part.
+ */
+export declare function renderToolContent(result: ToolResult): TextPart[];
+/**
+ * Map a {@link ToolResult} into a Phase-1 tool-result {@link Message}.
+ *
+ * A failure is marked `isError: true` so the model sees a recoverable tool
+ * error rather than a crashed run.
+ */
+export declare function toToolResultMessage(toolCallId: string, result: ToolResult): Message;
+/**
+ * Project a {@link ToolDefinition} into the provider-facing {@link ProviderTool}
+ * (name + optional description + JSON-Schema parameters).
+ */
+export declare function toProviderTool(tool: ToolDefinition): ProviderTool;

package/dist/tools/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The tool contract — a named capability the model can invoke.
+ *
+ * A {@link ToolDefinition} couples a Phase-1 parameter {@link Schema} (used to
+ * advertise the tool to a provider and to validate model-supplied arguments at
+ * the boundary in Phase 4) with a typed `execute` function. Execution returns a
+ * structured {@link ToolResult}: a *successful* outcome carries content fed back
+ * to the model, while a *failed* outcome is surfaced to the model as a tool
+ * error rather than thrown — bad arguments and tool failures become data the
+ * model can recover from, not unhandled exceptions. The stable application
+ * path is {@link defineTool}; hand-written {@link ToolDefinition} objects are
+ * mainly useful for adapters and tests.
+ *
+ * @module
+ */
+import type { EngineContext } from "../runtime/types";
+import type { Schema } from "../schema/types";
+import type { RunBridge } from "../execution/types";
+/**
+ * Per-invocation context handed to a tool's {@link ToolDefinition.execute}.
+ *
+ * Extends the shared {@link EngineContext} (telemetry / logger / cancellation
+ * signal) with call-correlation metadata. Only the owning agent's *name* is
+ * exposed — not the agent itself — so tools never carry a forward dependency on
+ * the agent module.
+ */
+export interface ToolContext extends EngineContext {
+    /** Correlates this invocation to the model's `ToolCall.id`. */
+    readonly toolCallId: string;
+    /** Name of the agent that owns this tool, when run inside one. */
+    readonly agentName?: string;
+    /**
+     * Bridge to the surrounding run, present when the tool is dispatched by the
+     * Phase-4 loop. Lets a tool forward nested events and report token usage to
+     * the parent run (used by sub-agent-as-tool); absent when a tool is invoked
+     * outside `runAgent`.
+     */
+    readonly run?: RunBridge;
+}
+/**
+ * A successful tool outcome.
+ *
+ * `content` is rendered to text for the model: strings pass through unchanged;
+ * any other value is JSON-encoded (see `renderToolContent`).
+ */
+export interface ToolSuccess {
+    readonly ok: true;
+    readonly content: unknown;
+}
+/**
+ * A failed tool outcome for expected/domain failures such as "file not found"
+ * or "permission denied". Surfaced to the model as a tool error (an `isError`
+ * tool-result message), never thrown out of the run loop.
+ *
+ * `error` is intentionally a string in the stable contract. If a tool needs to
+ * return structured diagnostics, encode them in the string or return a
+ * structured success payload with an application-level status.
+ */
+export interface ToolFailure {
+    readonly ok: false;
+    readonly error: string;
+}
+/** The structured result of a tool invocation, discriminated on `ok`. */
+export type ToolResult = ToolSuccess | ToolFailure;
+/**
+ * A named capability the model can invoke.
+ *
+ * `TArgs` is the validated argument type; with {@link defineTool} it is inferred
+ * from `parameters` so `execute` receives fully-typed arguments.
+ */
+export interface ToolDefinition<TArgs = unknown> {
+    readonly name: string;
+    readonly description?: string;
+    /** Parameter schema: `.jsonSchema` is advertised to the provider, `.parse` validates args. */
+    readonly parameters: Schema<TArgs>;
+    /**
+     * Run the tool with already-validated arguments.
+     *
+     * Return `{ ok: true, content }` for success and `{ ok: false, error }` for
+     * expected/domain failures. Throw only for unexpected implementation faults;
+     * `runAgent` catches thrown errors and feeds them back to the model as
+     * recoverable tool-result errors.
+     */
+    execute(args: TArgs, ctx: ToolContext): ToolResult | Promise<ToolResult>;
+}

package/docs/README.md

@@ -0,0 +1,36 @@
+# engine-lib documentation
+
+- **Guide & concepts:** [`../README.md`](../README.md) - project goal, design principles, and annotated usage scenarios.
+- **Runnable examples:** [`../examples/`](../examples/) - small, offline programs you can run with `bun`.
+
+## API reference
+
+The full API reference is generated from source doc-comments with
+[TypeDoc](https://typedoc.org):
+
+```bash
+bun run docs   # writes HTML to docs/api/ (git-ignored)
+```
+
+Then open `docs/api/index.html`. Configuration lives in `typedoc.json` in the
+source repository; the documented entry points are the public import surfaces:
+
+| Import | Module |
+| --- | --- |
+| `@infinityi/engine-lib` | stable root barrel: schemas, messages, errors, provider factories, tools, agents, execution, sessions, context helpers, event subscribers |
+| `@infinityi/engine-lib/schema` | schema builder, JSON Schema export, and validation helpers |
+| `@infinityi/engine-lib/messages` | provider-neutral message and content helpers |
+| `@infinityi/engine-lib/errors` | public error taxonomy |
+| `@infinityi/engine-lib/runtime` | Forge secret and telemetry integration helpers |
+| `@infinityi/engine-lib/providers` | provider contracts, built-in provider factories, and advanced adapter/HTTP/SSE helpers |
+| `@infinityi/engine-lib/tools` | tool definitions and tool-result mapping helpers |
+| `@infinityi/engine-lib/agent` | agent definitions, registries, handoffs, and sub-agent-as-tool helpers |
+| `@infinityi/engine-lib/execution` | `runAgent` and run result/event types |
+| `@infinityi/engine-lib/session` | session handles and session store contract |
+| `@infinityi/engine-lib/context` | context providers and context-window strategies |
+| `@infinityi/engine-lib/events` | event hub, subscribers, event projection helpers, and telemetry bridge |
+| `@infinityi/engine-lib/lifecycle` | Forge lifecycle adapter (`agentRuntimeComponent`) |
+| `@infinityi/engine-lib/testing` | network-free test doubles (`mockProvider`, `scriptedProvider`, `textResult`, `toolCallResult`, `jsonFetch`/`sseFetch`, `inMemorySessionStore`) |
+| `@infinityi/engine-lib/testing/conformance` | the provider conformance battery (`runProviderConformance`) |
+
+The output is intentionally not committed; regenerate it locally or in CI.

package/examples/README.md

@@ -0,0 +1,24 @@
+# Examples
+
+Small, self-contained programs demonstrating the engine-lib API. Each one runs
+**offline** with `bun` — they use the network-free test doubles from
+`@infinityi/engine-lib/testing` (scripted providers) so no API key is required.
+
+```bash
+bun examples/incident-analysis.ts   # context injection + a read-only tool
+bun examples/terminal-coder.ts       # streaming tokens + a persisted session
+bun examples/multi-agent.ts          # handoff/delegation + sub-agent-as-tool
+bun examples/lifecycle.ts            # forge.boot with agentRuntimeComponent
+```
+
+| File | Demonstrates |
+| --- | --- |
+| [`incident-analysis.ts`](./incident-analysis.ts) | `defineAgent` + `defineTool`, `staticContext` injection, `onEvent` tool-call observation |
+| [`terminal-coder.ts`](./terminal-coder.ts) | streaming (`stream: true`) `token` events, `createSession` history persistence |
+| [`multi-agent.ts`](./multi-agent.ts) | Phase 7 — `handoffs` / `transfer_to_<name>` and `asTool(agent)` |
+| [`lifecycle.ts`](./lifecycle.ts) | Phase 8 — `agentRuntimeComponent` start/healthcheck/stop under `forge.boot` |
+
+> The examples import from `@infinityi/engine-lib`, so they work both inside this
+> repository and from the published package. In your own application, pass a real
+> provider, e.g. `createOpenAI({ apiKey, model })` or
+> `createAnthropic({ apiKey, model })`.