@infinityi/engine-lib 1.0.0 → 1.4.0

package/examples/04-sessions-context.ts

@@ -0,0 +1,40 @@
+import {
+  createSession,
+  defineAgent,
+  dynamicContext,
+  runAgent,
+  staticContext,
+} from "@infinityi/engine-lib";
+import { scriptedProvider, textResult } from "@infinityi/engine-lib/testing";
+
+const session = createSession({ id: "example-user-1" });
+const agent = defineAgent({
+  name: "assistant",
+  instructions: "Use injected context, but do not assume it is persistent.",
+  provider: scriptedProvider([
+    textResult("First turn recorded."),
+    textResult("Second turn used prior session history."),
+  ]),
+});
+
+await runAgent(agent, {
+  input: "Remember this conversation.",
+  session,
+  context: [
+    staticContext("Plan: enterprise", "Account"),
+    dynamicContext("clock", () => "Today is 2026-06-11."),
+  ],
+});
+
+const second = await runAgent(agent, {
+  input: "What happened before?",
+  session,
+});
+
+const persisted = await session.messages();
+
+console.log({
+  secondOutput: second.output,
+  persistedRoles: persisted.map((message) => message.role),
+});
+

package/examples/05-events-subscribers.ts

@@ -0,0 +1,35 @@
+import { defineAgent, runAgent } from "@infinityi/engine-lib";
+import type { RunSubscriber } from "@infinityi/engine-lib/events";
+import { scriptedProvider, textResult } from "@infinityi/engine-lib/testing";
+
+const auditLog: string[] = [];
+const afterFailingSink: string[] = [];
+
+const auditSubscriber: RunSubscriber = async (event) => {
+  auditLog.push(event.type);
+};
+
+const failingSubscriber: RunSubscriber = async () => {
+  throw new Error("audit sink is unavailable");
+};
+
+const stillRunsSubscriber: RunSubscriber = async (event) => {
+  afterFailingSink.push(event.type);
+};
+
+const agent = defineAgent({
+  name: "observable",
+  provider: scriptedProvider([textResult("done")]),
+});
+
+const result = await runAgent(agent, {
+  input: "Emit events.",
+  subscribers: [auditSubscriber, failingSubscriber, stillRunsSubscriber],
+});
+
+console.log({
+  output: result.output,
+  auditLog,
+  afterFailingSink,
+});
+

package/examples/06-multi-agent-handoff.ts

@@ -0,0 +1,27 @@
+import { defineAgent, runAgent } from "@infinityi/engine-lib";
+import { handoffToolName } from "@infinityi/engine-lib/agent";
+import { scriptedProvider, textResult, toolCallResult } from "@infinityi/engine-lib/testing";
+
+const billing = defineAgent({
+  name: "billing",
+  instructions: "Handle billing questions.",
+  provider: scriptedProvider([textResult("Refund issued by billing.")]),
+});
+
+const triage = defineAgent({
+  name: "triage",
+  instructions: "Route to the right specialist.",
+  handoffs: [billing],
+  provider: scriptedProvider([
+    toolCallResult([{ id: "handoff-1", name: handoffToolName("billing"), arguments: {} }]),
+  ]),
+});
+
+const result = await runAgent(triage, { input: "I need a refund." });
+
+console.log({
+  output: result.output,
+  finalAgent: result.agent,
+  handoffs: result.handoffs,
+});
+

package/examples/07-sub-agent-tool.ts

@@ -0,0 +1,26 @@
+import { asTool, defineAgent, runAgent } from "@infinityi/engine-lib";
+import { scriptedProvider, textResult, toolCallResult } from "@infinityi/engine-lib/testing";
+
+const researcher = defineAgent({
+  name: "researcher",
+  instructions: "Research the request and return concise findings.",
+  provider: scriptedProvider([textResult("Database latency increased after deploy 42.")]),
+});
+
+const lead = defineAgent({
+  name: "lead",
+  instructions: "Delegate research when useful, then answer.",
+  tools: [asTool(researcher)],
+  provider: scriptedProvider([
+    toolCallResult([{ id: "research-1", name: "researcher", arguments: { input: "latency" } }]),
+    textResult("Likely cause: deploy 42 increased database latency."),
+  ]),
+});
+
+const result = await runAgent(lead, { input: "Why did latency spike?" });
+
+console.log({
+  output: result.output,
+  totalTokens: result.usage.totalTokens,
+});
+

package/examples/08-testing-agent.ts

@@ -0,0 +1,31 @@
+import { defineAgent, defineTool, runAgent, s } from "@infinityi/engine-lib";
+import { scriptedProvider, textResult, toolCallResult } from "@infinityi/engine-lib/testing";
+
+const double = defineTool({
+  name: "double",
+  parameters: s.object({ value: s.number({ int: true }) }),
+  execute: ({ value }) => ({ ok: true, content: value * 2 }),
+});
+
+const agent = defineAgent({
+  name: "testable",
+  tools: [double],
+  provider: scriptedProvider([
+    toolCallResult([{ id: "double-1", name: "double", arguments: { value: 21 } }]),
+    textResult("The answer is 42."),
+  ]),
+});
+
+const result = await runAgent(agent, { input: "Double 21." });
+
+if (result.output !== "The answer is 42.") {
+  throw new Error(`unexpected output: ${result.output}`);
+}
+
+const usedTool = result.messages.some((message) => message.role === "tool");
+if (!usedTool) {
+  throw new Error("expected the agent to use the double tool");
+}
+
+console.log("agent test passed");
+

package/examples/09-tools-filesystem.ts

@@ -0,0 +1,49 @@
+import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { ToolContext, ToolDefinition, ToolResult } from "@infinityi/engine-lib/tools";
+import { filesystemTools } from "@infinityi/engine-lib/tools-fs";
+
+const root = await realpath(await mkdtemp(join(tmpdir(), "engine-lib-example-fs-")));
+const ctx: ToolContext = { toolCallId: "example-fs", agentName: "example" };
+
+try {
+  await writeFile(join(root, "service.ts"), [
+    "export function status() {",
+    "  return 'degraded';",
+    "}",
+  ].join("\n"));
+
+  const fs = filesystemTools({ allowedRoots: [root] });
+
+  const map = await runTool(fs.repoMap, { include_symbols: true });
+  const search = await runTool(fs.searchText, { pattern: "degraded", mode: "literal" });
+  const read = await runTool(fs.read, { path: "service.ts", include_line_numbers: true });
+  const diff = await runTool(fs.diffStatus, {});
+
+  console.log({
+    root,
+    mapped: ok(map),
+    searched: ok(search),
+    read: ok(read),
+    diff: ok(diff),
+  });
+} finally {
+  await rm(root, { recursive: true, force: true });
+}
+
+async function runTool<TArgs>(
+  tool: ToolDefinition<TArgs>,
+  args: TArgs,
+): Promise<ToolResult> {
+  return tool.execute(args, ctx);
+}
+
+function ok(result: ToolResult): boolean {
+  if (!result.ok) {
+    throw new Error(result.error);
+  }
+  return true;
+}
+

package/examples/10-tools-http-web.ts

@@ -0,0 +1,74 @@
+import type { ToolContext, ToolDefinition, ToolResult } from "@infinityi/engine-lib/tools";
+import { httpTools } from "@infinityi/engine-lib/tools-http";
+import { webTools, type SearchProvider } from "@infinityi/engine-lib/tools-web";
+
+const html = [
+  "<html>",
+  "<head><title>Status</title></head>",
+  "<body>",
+  "<main><h1>Status</h1><p>All public systems are operational.</p></main>",
+  "<a href=\"/docs\">Docs</a>",
+  "</body>",
+  "</html>",
+].join("");
+
+const fakeFetch = (async (input: Parameters<typeof fetch>[0]) => {
+  const url = String(input);
+  if (url.endsWith("/robots.txt")) {
+    return new Response("User-agent: *\nAllow: /\n", {
+      headers: { "content-type": "text/plain" },
+    });
+  }
+  if (url.endsWith("/status")) {
+    return new Response(html, {
+      headers: { "content-type": "text/html" },
+    });
+  }
+  return new Response(JSON.stringify({ ok: true }), {
+    headers: { "content-type": "application/json" },
+  });
+}) as typeof fetch;
+
+const searchProvider: SearchProvider = {
+  search: ({ query, maxResults }) => [
+    {
+      url: "https://example.com/status",
+      title: `Result for ${query}`,
+      snippet: `Returning ${maxResults} result(s).`,
+    },
+  ],
+};
+
+const ctx: ToolContext = { toolCallId: "example-web", agentName: "example" };
+const http = httpTools({ allowedHosts: ["example.com"], fetch: fakeFetch });
+const web = webTools({
+  allowedHosts: ["example.com"],
+  fetch: fakeFetch,
+  searchProvider,
+  robots: "enforce",
+});
+
+const httpResult = await runTool(http.httpGet, { url: "https://example.com/api" });
+const searchResult = await runTool(web.webSearch, { query: "status", max_results: 1 });
+const pageResult = await runTool(web.fetchPage, { url: "https://example.com/status" });
+
+console.log({
+  http: content(httpResult),
+  search: content(searchResult),
+  page: content(pageResult),
+});
+
+async function runTool<TArgs>(
+  tool: ToolDefinition<TArgs>,
+  args: TArgs,
+): Promise<ToolResult> {
+  return tool.execute(args, ctx);
+}
+
+function content(result: ToolResult): unknown {
+  if (!result.ok) {
+    throw new Error(result.error);
+  }
+  return result.content;
+}
+

package/examples/11-shell-tools.ts

@@ -0,0 +1,39 @@
+import type { ToolContext, ToolDefinition, ToolResult } from "@infinityi/engine-lib/tools";
+import { shellTools } from "@infinityi/engine-lib/tools-shell";
+
+const cwd = process.cwd();
+const shell = shellTools({
+  allowedCwds: [cwd],
+  policy: {
+    allow: [process.execPath],
+    deny: [/\brm\b/, /\bsudo\b/],
+  },
+  env: { allow: ["PATH"] },
+  requiresApproval: (request) => request.command !== process.execPath,
+  approve: () => ({ approved: false, reason: "example denies unrecognized commands" }),
+});
+
+const result = await runTool(shell.runCommand, {
+  command: process.execPath,
+  args: ["-e", "console.log('hello from shell tool')"],
+  cwd,
+  timeoutMs: 5_000,
+});
+
+console.log(content(result));
+
+async function runTool<TArgs>(
+  tool: ToolDefinition<TArgs>,
+  args: TArgs,
+): Promise<ToolResult> {
+  const ctx: ToolContext = { toolCallId: "example-shell", agentName: "example" };
+  return tool.execute(args, ctx);
+}
+
+function content(result: ToolResult): unknown {
+  if (!result.ok) {
+    throw new Error(result.error);
+  }
+  return result.content;
+}
+

package/examples/12-provider-openai.ts

@@ -0,0 +1,24 @@
+import { createOpenAI, defineAgent, runAgent } from "@infinityi/engine-lib";
+
+const apiKey = process.env.OPENAI_API_KEY;
+
+if (apiKey === undefined || apiKey === "") {
+  console.log("Set OPENAI_API_KEY to run the real OpenAI provider example.");
+  process.exit(0);
+}
+
+const provider = createOpenAI({
+  apiKey,
+  model: process.env.OPENAI_MODEL ?? "gpt-5",
+});
+
+const agent = defineAgent({
+  name: "openai-example",
+  provider,
+  instructions: "Answer in one sentence.",
+});
+
+const result = await runAgent(agent, { input: "What is engine-lib?" });
+
+console.log(result.output);
+

package/examples/13-lifecycle.ts

@@ -0,0 +1,37 @@
+import { agentRuntimeComponent } from "@infinityi/engine-lib/lifecycle";
+import { mockProvider } from "@infinityi/engine-lib/testing";
+
+const provider = mockProvider({ name: "mock-provider", defaultModel: "mock-model" });
+const component = agentRuntimeComponent({
+  providers: [provider],
+  probeOnStart: true,
+  probe: async (candidate) => {
+    await candidate.complete({ messages: [] });
+  },
+  onStop: () => {
+    console.log("runtime stopped");
+  },
+});
+
+const signal = new AbortController().signal;
+const logger = {
+  trace: console.debug,
+  debug: console.debug,
+  info: console.log,
+  warn: console.warn,
+  error: console.error,
+};
+
+if (component.start !== undefined) {
+  await component.start({ signal, logger } as Parameters<typeof component.start>[0]);
+}
+
+if (component.healthcheck !== undefined) {
+  const health = await component.healthcheck({ signal, logger } as Parameters<typeof component.healthcheck>[0]);
+  console.log(health);
+}
+
+if (component.stop !== undefined) {
+  await component.stop({ signal, logger } as Parameters<typeof component.stop>[0]);
+}
+

package/examples/14-retrieval.ts

@@ -0,0 +1,65 @@
+import { defineAgent, runAgent } from "@infinityi/engine-lib";
+import {
+  InMemoryVectorStore,
+  createTextChunker,
+  createVectorRetriever,
+  indexDocuments,
+  retrieverContext,
+  staticDocumentLoader,
+  type EmbeddingProvider,
+} from "@infinityi/engine-lib/retrieval";
+import { scriptedProvider, textResult } from "@infinityi/engine-lib/testing";
+
+const embeddings: EmbeddingProvider = {
+  name: "toy-embeddings",
+  defaultModel: "toy-embedding",
+  dimensions: 4,
+  async embed(req) {
+    return {
+      model: req.model ?? "toy-embedding",
+      dimensions: 4,
+      vectors: req.input.map((text) => [
+        text.toLowerCase().includes("database") ? 1 : 0,
+        text.toLowerCase().includes("standby") ? 1 : 0,
+        text.toLowerCase().includes("cache") ? 1 : 0,
+        Math.min(text.length / 100, 1),
+      ]),
+    };
+  },
+};
+
+const store = new InMemoryVectorStore({ dimensions: 4 });
+
+await indexDocuments({
+  loaders: [
+    staticDocumentLoader([
+      {
+        id: "database-runbook",
+        content: "When the database is unavailable, fail over to the standby and verify replication lag.",
+        source: { uri: "runbooks/database.md", title: "Database Runbook" },
+      },
+      {
+        id: "cache-runbook",
+        content: "When the cache is saturated, scale the cache tier before restarting workers.",
+        source: { uri: "runbooks/cache.md", title: "Cache Runbook" },
+      },
+    ]),
+  ],
+  chunker: createTextChunker({ maxChars: 120, overlapChars: 20 }),
+  embeddings,
+  store,
+});
+
+const retriever = createVectorRetriever({ embeddings, store, topK: 2 });
+const agent = defineAgent({
+  name: "retrieval-demo",
+  instructions: "Answer from retrieved context and cite sources by marker.",
+  provider: scriptedProvider([textResult("Fail over to standby and verify replication lag. [1]")]),
+});
+
+const result = await runAgent(agent, {
+  input: "How should I recover a database outage?",
+  context: [retrieverContext({ retriever, maxContextTokens: 500 })],
+});
+
+console.log(result.output);

package/examples/incident-analysis.ts

@@ -1,100 +1,52 @@
-/**
- * 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";
+  createSession,
+  defineAgent,
+  defineTool,
+  runAgent,
+  s,
+  staticContext,
+} from "@infinityi/engine-lib";
+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.",
+const serviceStatus = defineTool({
+  name: "service_status",
+  description: "Read current status for a production service.",
   parameters: s.object({
-    service: s.string(),
-    lines: s.optional(s.number({ int: true })),
+    service: s.enum(["api", "worker", "billing"]),
   }),
-  execute: ({ service, lines }) => ({
+  execute: ({ service }) => ({
     ok: true,
-    content: [
-      `[${service}] OutOfMemoryError: Java heap space`,
-      `[${service}] GC overhead limit exceeded (${lines ?? 200} lines scanned)`,
-    ].join("\n"),
+    content: {
+      service,
+      status: "degraded",
+      signals: ["p95 latency above SLO", "error rate normal", "recent deploy: 42"],
+    },
   }),
 });
 
-// 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({
+const incidentAgent = 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],
+  instructions: "Analyze incidents with evidence. Keep the final answer actionable.",
+  tools: [serviceStatus],
+  provider: scriptedProvider([
+    toolCallResult([{ id: "status-1", name: "service_status", arguments: { service: "api" } }]),
+    textResult("API latency is degraded. The leading suspect is deploy 42; roll back or inspect its database path."),
+  ]),
 });
 
-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})`);
-}
+const session = createSession({ id: "incident-2026-06-11" });
+const events: string[] = [];
 
-await onServerCrash({
-  service: "checkout",
-  exitCode: 137,
-  timestamp: new Date().toISOString(),
-  version: "2.4.1",
+const result = await runAgent(incidentAgent, {
+  input: "Why is the API slow?",
+  session,
+  context: [staticContext({ region: "us-east-1", severity: "sev2" }, "Incident")],
+  onEvent: (event) => events.push(event.type),
 });
+
+console.log({
+  output: result.output,
+  events,
+  persistedMessages: (await session.messages()).map((message) => message.role),
+});
+