@infinityi/engine-lib 1.3.1 → 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

@@ -0,0 +1,52 @@
+import {
+  createSession,
+  defineAgent,
+  defineTool,
+  runAgent,
+  s,
+  staticContext,
+} from "@infinityi/engine-lib";
+import { scriptedProvider, textResult, toolCallResult } from "@infinityi/engine-lib/testing";
+
+const serviceStatus = defineTool({
+  name: "service_status",
+  description: "Read current status for a production service.",
+  parameters: s.object({
+    service: s.enum(["api", "worker", "billing"]),
+  }),
+  execute: ({ service }) => ({
+    ok: true,
+    content: {
+      service,
+      status: "degraded",
+      signals: ["p95 latency above SLO", "error rate normal", "recent deploy: 42"],
+    },
+  }),
+});
+
+const incidentAgent = defineAgent({
+  name: "incident-analyst",
+  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."),
+  ]),
+});
+
+const session = createSession({ id: "incident-2026-06-11" });
+const events: string[] = [];
+
+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),
+});
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infinityi/engine-lib",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Agent infrastructure for TypeScript, built on @infinityi/forge.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs/README.md",
+    "docs",
     "examples"
   ],
   "exports": {
@@ -60,6 +60,22 @@
       "import": "./dist/tools/index.js",
       "types": "./dist/tools/index.d.ts"
     },
+    "./tools-shell": {
+      "import": "./dist/tools-shell/index.js",
+      "types": "./dist/tools-shell/index.d.ts"
+    },
+    "./tools-fs": {
+      "import": "./dist/tools-fs/index.js",
+      "types": "./dist/tools-fs/index.d.ts"
+    },
+    "./tools-http": {
+      "import": "./dist/tools-http/index.js",
+      "types": "./dist/tools-http/index.d.ts"
+    },
+    "./tools-web": {
+      "import": "./dist/tools-web/index.js",
+      "types": "./dist/tools-web/index.d.ts"
+    },
     "./agent": {
       "import": "./dist/agent/index.js",
       "types": "./dist/agent/index.d.ts"
@@ -72,10 +88,18 @@
       "import": "./dist/session/index.js",
       "types": "./dist/session/index.d.ts"
     },
+    "./session-stores": {
+      "import": "./dist/session-stores/index.js",
+      "types": "./dist/session-stores/index.d.ts"
+    },
     "./context": {
       "import": "./dist/context/index.js",
       "types": "./dist/context/index.d.ts"
     },
+    "./retrieval": {
+      "import": "./dist/retrieval/index.js",
+      "types": "./dist/retrieval/index.d.ts"
+    },
     "./events": {
       "import": "./dist/events/index.js",
       "types": "./dist/events/index.d.ts"
@@ -95,20 +119,70 @@
   },
   "scripts": {
     "clean": "bun -e \"const fs = require('fs'); fs.rmSync('dist', { recursive: true, force: true });\"",
-    "build:js": "bun build src/index.ts src/schema/index.ts src/messages/index.ts src/errors.ts src/runtime/index.ts src/providers/index.ts src/tools/index.ts src/agent/index.ts src/execution/index.ts src/session/index.ts src/context/index.ts src/events/index.ts src/testing/index.ts src/testing/conformance.ts src/lifecycle/index.ts --outdir dist --root src --splitting --external bun:test --target node",
+    "build:js": "bun build src/index.ts src/schema/index.ts src/messages/index.ts src/errors.ts src/runtime/index.ts src/providers/index.ts src/tools/index.ts src/tools-shell/index.ts src/tools-fs/index.ts src/tools-http/index.ts src/tools-web/index.ts src/agent/index.ts src/execution/index.ts src/session/index.ts src/session-stores/index.ts src/context/index.ts src/retrieval/index.ts src/events/index.ts src/testing/index.ts src/testing/conformance.ts src/lifecycle/index.ts --outdir dist --root src --splitting --external bun:test --external typescript --external @vscode/ripgrep --external diff --external fuse.js --external glob --external ignore --external minisearch --external @mozilla/readability --external linkedom --external robots-parser --target node",
     "build:types": "tsc -p tsconfig.build.json",
     "build": "bun run clean && bun run build:js && bun run build:types",
     "check": "tsc --noEmit",
     "test": "bun test",
     "docs": "typedoc",
+    "examples": "bun run examples/incident-analysis.ts && bun run examples/01-minimal-agent.ts && bun run examples/02-custom-tool.ts && bun run examples/03-streaming.ts && bun run examples/04-sessions-context.ts && bun run examples/05-events-subscribers.ts && bun run examples/06-multi-agent-handoff.ts && bun run examples/07-sub-agent-tool.ts && bun run examples/08-testing-agent.ts && bun run examples/09-tools-filesystem.ts && bun run examples/10-tools-http-web.ts && bun run examples/11-shell-tools.ts && bun run examples/12-provider-openai.ts && bun run examples/13-lifecycle.ts && bun run examples/14-retrieval.ts",
     "prepublishOnly": "bun run check && bun test && bun run build"
   },
   "devDependencies": {
+    "@mozilla/readability": "^0.6.0",
     "@types/bun": "^1.3.14",
+    "@vscode/ripgrep": "^1.18.0",
+    "diff": "^9.0.0",
+    "fuse.js": "^7.4.2",
+    "glob": "^13.0.6",
+    "ignore": "^7.0.5",
+    "linkedom": "^0.18.12",
+    "minisearch": "^7.2.0",
+    "robots-parser": "^3.0.1",
     "typedoc": "^0.28.19",
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@infinityi/forge": "^1.0.0"
+    "@infinityi/forge": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "@vscode/ripgrep": "^1.18.0",
+    "diff": "^9.0.0",
+    "fuse.js": "^7.4.2",
+    "glob": "^13.0.6",
+    "ignore": "^7.0.5",
+    "linkedom": "^0.18.12",
+    "minisearch": "^7.2.0",
+    "robots-parser": "^3.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@mozilla/readability": {
+      "optional": true
+    },
+    "@vscode/ripgrep": {
+      "optional": true
+    },
+    "diff": {
+      "optional": true
+    },
+    "fuse.js": {
+      "optional": true
+    },
+    "glob": {
+      "optional": true
+    },
+    "ignore": {
+      "optional": true
+    },
+    "linkedom": {
+      "optional": true
+    },
+    "minisearch": {
+      "optional": true
+    },
+    "robots-parser": {
+      "optional": true
+    }
   }
 }