@infinityi/engine-lib 1.0.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infinityi/engine-lib",
-  "version": "1.0.0",
+  "version": "1.3.1",
   "description": "Agent infrastructure for TypeScript, built on @infinityi/forge.",
   "type": "module",
   "license": "MIT",

package/examples/README.md

@@ -1,24 +0,0 @@
-# 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 })`.

package/examples/incident-analysis.ts

@@ -1,100 +0,0 @@
-/**
- * Example 1 — incident analysis.
- *
- * A monitoring component detects a crash and asks an "incident analyst" agent to
- * investigate. Recent logs are injected as run-time context, and the agent is
- * given a read-only `fetch_recent_logs` tool. Mirrors README "Example 1".
- *
- * Run it:  `bun examples/incident-analysis.ts`
- *
- * In your own app, swap in a real provider such as
- * `createAnthropic({ apiKey, model })`. This example uses a scripted provider so
- * it runs offline, with no API key.
- */
-
-import { defineAgent } from "@infinityi/engine-lib/agent";
-import { runAgent } from "@infinityi/engine-lib/execution";
-import { staticContext } from "@infinityi/engine-lib/context";
-import { defineTool } from "@infinityi/engine-lib/tools";
-import { s } from "@infinityi/engine-lib/schema";
-import {
-  scriptedProvider,
-  textResult,
-  toolCallResult,
-} from "@infinityi/engine-lib/testing";
-
-// A read-only tool the agent may call. In a real deployment `execute` would hit
-// your log store; here it returns a fixed slice.
-const fetchRecentLogs = defineTool({
-  name: "fetch_recent_logs",
-  description: "Fetch the last N log lines for a service.",
-  parameters: s.object({
-    service: s.string(),
-    lines: s.optional(s.number({ int: true })),
-  }),
-  execute: ({ service, lines }) => ({
-    ok: true,
-    content: [
-      `[${service}] OutOfMemoryError: Java heap space`,
-      `[${service}] GC overhead limit exceeded (${lines ?? 200} lines scanned)`,
-    ].join("\n"),
-  }),
-});
-
-// Real provider (swap in for production):
-//   import { createAnthropic } from "@infinityi/engine-lib/providers";
-//   const provider = createAnthropic({ apiKey, model: "claude-sonnet-4" });
-// Scripted provider: turn 1 calls the tool, turn 2 produces the analysis.
-const provider = scriptedProvider([
-  toolCallResult([
-    {
-      id: "c1",
-      name: "fetch_recent_logs",
-      arguments: { service: "checkout", lines: 200 },
-    },
-  ]),
-  textResult(
-    "Root cause: the checkout service ran out of heap (OutOfMemoryError), confirmed " +
-      "by the GC overhead messages in the logs. Next steps: raise -Xmx, capture a heap " +
-      "dump on OOM, and review the recent deploy for an unbounded cache.",
-  ),
-]);
-
-const incidentAnalyst = defineAgent({
-  name: "incident-analyst",
-  provider,
-  instructions:
-    "You are an SRE assistant. Diagnose the likely root cause of the crash and " +
-    "propose concrete next steps. Cite the log lines you relied on.",
-  tools: [fetchRecentLogs],
-});
-
-async function onServerCrash(event: {
-  service: string;
-  exitCode: number;
-  timestamp: string;
-  version: string;
-}) {
-  const result = await runAgent(incidentAnalyst, {
-    input: `Service "${event.service}" crashed with exit code ${event.exitCode}.`,
-    context: [
-      staticContext({
-        crashedAt: event.timestamp,
-        deployedVersion: event.version,
-      }),
-    ],
-    onEvent: (e) => {
-      if (e.type === "tool.call") console.log(`  ↻ tool call: ${e.name}`);
-    },
-  });
-  console.log("\n--- incident analysis ---");
-  console.log(result.output);
-  console.log(`\n(steps: ${result.steps}, agent: ${result.agent})`);
-}
-
-await onServerCrash({
-  service: "checkout",
-  exitCode: 137,
-  timestamp: new Date().toISOString(),
-  version: "2.4.1",
-});

package/examples/lifecycle.ts

@@ -1,53 +0,0 @@
-/**
- * Example 4 — Forge lifecycle integration (Phase 8).
- *
- * Boot the engine-lib runtime as a `@infinityi/forge/lifecycle` component:
- * `agentRuntimeComponent` validates providers on start, exposes a health probe,
- * and runs an `onStop` hook on graceful shutdown — all orchestrated by
- * `forge.boot`.
- *
- * Run it:  `bun examples/lifecycle.ts`
- *
- * Uses in-memory doubles so it runs offline. `installSignals: false` + a no-op
- * `exit` keep the example from installing real process signal handlers.
- */
-
-import { boot } from "@infinityi/forge/lifecycle";
-
-import { agentRuntimeComponent } from "@infinityi/engine-lib/lifecycle";
-import {
-  inMemorySessionStore,
-  mockProvider,
-} from "@infinityi/engine-lib/testing";
-
-const store = inMemorySessionStore();
-const runtime = agentRuntimeComponent({
-  providers: [mockProvider({ name: "openai", defaultModel: "gpt-5" })],
-  sessionStore: store,
-  // A real probe would issue a cheap completion; here it's a no-op success.
-  probe: () => Promise.resolve(),
-  probeOnStart: true,
-  onStop: () => console.log("  onStop: flushing session store"),
-});
-
-const app = await boot({
-  components: [runtime],
-  installSignals: false,
-  exit: () => {},
-});
-console.log(
-  "booted — ready:",
-  app.ready,
-  "| components:",
-  app.components.map((c) => c.name),
-);
-
-const health = await runtime.healthcheck?.({
-  signal: new AbortController().signal,
-  logger: console,
-});
-console.log("healthcheck:", health?.status, health?.data);
-
-await app.stop("example-complete");
-await app.done;
-console.log("drained cleanly");

package/examples/multi-agent.ts

@@ -1,93 +0,0 @@
-/**
- * Example 3 — multi-agent coordination (Phase 7).
- *
- * Two complementary composition patterns, both driven by the same `runAgent`
- * loop (no separate orchestrator):
- *   1. Handoff/delegation — a triage agent transfers the conversation to a
- *      specialist via a synthetic `transfer_to_<name>` tool.
- *   2. Sub-agent-as-tool — a lead agent invokes a researcher agent through the
- *      normal tool-calling path with `asTool(...)`.
- *
- * Run it:  `bun examples/multi-agent.ts`
- *
- * Uses scripted providers so it runs offline.
- */
-
-import { asTool, defineAgent } from "@infinityi/engine-lib/agent";
-import { runAgent } from "@infinityi/engine-lib/execution";
-import {
-  scriptedProvider,
-  textResult,
-  toolCallResult,
-} from "@infinityi/engine-lib/testing";
-
-// --- 1. Handoff / delegation ---------------------------------------------
-
-const billing = defineAgent({
-  name: "billing",
-  provider: scriptedProvider([
-    textResult("I've issued your refund — it'll land in 3-5 days."),
-  ]),
-  instructions: "Handle billing and refunds.",
-});
-
-// Triage's model calls the synthetic `transfer_to_billing` tool to hand off.
-const triage = defineAgent({
-  name: "triage",
-  provider: scriptedProvider([
-    toolCallResult([{ id: "h1", name: "transfer_to_billing", arguments: {} }]),
-  ]),
-  instructions: "Route the user to the right specialist.",
-  handoffs: [billing],
-});
-
-const handoffResult = await runAgent(triage, { input: "I want a refund" });
-console.log("=== handoff ===");
-console.log("answer:", handoffResult.output);
-console.log(
-  "final agent:",
-  handoffResult.agent,
-  "| trail:",
-  handoffResult.handoffs,
-);
-
-// --- 2. Sub-agent-as-tool -------------------------------------------------
-
-const researcher = defineAgent({
-  name: "researcher",
-  provider: scriptedProvider([
-    textResult(
-      "Bun is a fast all-in-one JS runtime, bundler, and test runner.",
-    ),
-  ]),
-  instructions: "Research deeply and report concisely.",
-});
-
-const lead = defineAgent({
-  name: "lead",
-  // Turn 1: delegate to the researcher tool. Turn 2: summarize its finding.
-  provider: scriptedProvider([
-    toolCallResult([
-      { id: "c1", name: "researcher", arguments: { input: "What is Bun?" } },
-    ]),
-    textResult(
-      "Summary: Bun is a fast all-in-one JavaScript runtime/bundler/test-runner.",
-    ),
-  ]),
-  instructions: "Delegate research, then summarize.",
-  tools: [
-    asTool(researcher, { description: "Delegate research to a specialist." }),
-  ],
-});
-
-const childEvents: string[] = [];
-const toolResult = await runAgent(lead, {
-  input: "Give me a one-line summary of Bun.",
-  onEvent: (e) => {
-    if (e.type === "agent.child")
-      childEvents.push(`${e.agent}@depth${e.depth}: ${e.event.type}`);
-  },
-});
-console.log("\n=== sub-agent-as-tool ===");
-console.log("answer:", toolResult.output);
-console.log("child events:", childEvents.length, "(e.g.", childEvents[0] + ")");

package/examples/terminal-coder.ts

@@ -1,80 +0,0 @@
-/**
- * Example 2 — terminal coder.
- *
- * A coding terminal streams tokens to the screen, persists the conversation in a
- * session (so history carries across prompts), and lets the agent call
- * file/command tools. Mirrors README "Example 2".
- *
- * Run it:  `bun examples/terminal-coder.ts`
- *
- * Uses a scripted provider so it runs offline. In an app, swap in a real
- * provider such as `createOpenAI({ apiKey, model })`.
- */
-
-import { defineAgent } from "@infinityi/engine-lib/agent";
-import { runAgent } from "@infinityi/engine-lib/execution";
-import { createSession } from "@infinityi/engine-lib/session";
-import { defineTool } from "@infinityi/engine-lib/tools";
-import { s } from "@infinityi/engine-lib/schema";
-import {
-  scriptedProvider,
-  textResult,
-  toolCallResult,
-} from "@infinityi/engine-lib/testing";
-
-const readFile = defineTool({
-  name: "read_file",
-  description: "Read a file from the workspace.",
-  parameters: s.object({ path: s.string() }),
-  execute: ({ path }) => ({
-    ok: true,
-    content: `// ${path}\nexport const answer = 42;\n`,
-  }),
-});
-
-const runCommand = defineTool({
-  name: "run_command",
-  description: "Run a shell command in the workspace.",
-  parameters: s.object({ command: s.string() }),
-  execute: ({ command }) => ({ ok: true, content: `$ ${command}\nok` }),
-});
-
-const provider = scriptedProvider([
-  toolCallResult([
-    { id: "c1", name: "read_file", arguments: { path: "src/index.ts" } },
-  ]),
-  textResult(
-    "`src/index.ts` exports `answer = 42`. Want me to add a test for it?",
-  ),
-]);
-
-const coder = defineAgent({
-  name: "terminal-coder",
-  provider,
-  instructions:
-    "You are a coding assistant operating inside the user's terminal.",
-  tools: [readFile, runCommand],
-});
-
-// One terminal tab = one session, so history persists across prompts (backed by
-// the built-in InMemorySessionStore here).
-const session = createSession({ id: "tab-1" });
-
-async function onUserPrompt(prompt: string) {
-  process.stdout.write(`\n> ${prompt}\n`);
-  const stream = runAgent(coder, { input: prompt, session, stream: true });
-  for await (const event of stream) {
-    if (event.type === "token") process.stdout.write(event.delta); // live output
-    if (event.type === "tool.call")
-      process.stdout.write(`\n  ↻ ${event.name}\n`); // tool spinner
-  }
-  const result = await stream.completed;
-  // `result.messages` is the full run history (incl. the system instruction);
-  // the session persists the new turn's messages, which `session.messages()` replays.
-  const persisted = await session.messages();
-  process.stdout.write(
-    `\n  (turn done — ${result.messages.length} messages in history, ${persisted.length} persisted)\n`,
-  );
-}
-
-await onUserPrompt("What does src/index.ts export?");