@infinityi/engine-lib 1.0.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infinityi/engine-lib",
-  "version": "1.0.0",
+  "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
+    }
   }
 }

package/dist/index-02s1fjxr.js

@@ -1,226 +0,0 @@
-import {
-  SchemaValidationError
-} from "./index-7690reng.js";
-
-// src/schema/validate.ts
-function issue(path, message) {
-  return { path: [...path], message };
-}
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function validateJsonSchema(node, input, path = []) {
-  const issues = [];
-  if (node.enum !== undefined) {
-    if (!node.enum.includes(input)) {
-      issues.push(issue(path, `expected one of ${JSON.stringify(node.enum)}`));
-    }
-    return issues;
-  }
-  switch (node.type) {
-    case "string":
-      if (typeof input !== "string")
-        issues.push(issue(path, "expected string"));
-      break;
-    case "boolean":
-      if (typeof input !== "boolean")
-        issues.push(issue(path, "expected boolean"));
-      break;
-    case "null":
-      if (input !== null)
-        issues.push(issue(path, "expected null"));
-      break;
-    case "number":
-      if (typeof input !== "number" || Number.isNaN(input)) {
-        issues.push(issue(path, "expected number"));
-      }
-      break;
-    case "integer":
-      if (typeof input !== "number" || !Number.isInteger(input)) {
-        issues.push(issue(path, "expected integer"));
-      }
-      break;
-    case "array": {
-      if (!Array.isArray(input)) {
-        issues.push(issue(path, "expected array"));
-        break;
-      }
-      if (node.items !== undefined) {
-        input.forEach((element, index) => {
-          issues.push(...validateJsonSchema(node.items, element, [...path, index]));
-        });
-      }
-      break;
-    }
-    case "object": {
-      if (!isPlainObject(input)) {
-        issues.push(issue(path, "expected object"));
-        break;
-      }
-      const properties = node.properties ?? {};
-      const required = node.required ?? [];
-      for (const key of required) {
-        if (input[key] === undefined) {
-          issues.push(issue([...path, key], "required"));
-        }
-      }
-      for (const [key, propSchema] of Object.entries(properties)) {
-        const value = input[key];
-        if (value === undefined)
-          continue;
-        issues.push(...validateJsonSchema(propSchema, value, [...path, key]));
-      }
-      if (node.additionalProperties === false) {
-        for (const key of Object.keys(input)) {
-          if (!(key in properties)) {
-            issues.push(issue([...path, key], "unexpected property"));
-          }
-        }
-      }
-      break;
-    }
-    default:
-      break;
-  }
-  return issues;
-}
-
-// src/schema/builder.ts
-var optionalSchemas = new WeakSet;
-function makeSchema(jsonSchema) {
-  return {
-    jsonSchema,
-    safeParse(input) {
-      const issues = validateJsonSchema(jsonSchema, input);
-      if (issues.length === 0)
-        return { success: true, data: input };
-      return {
-        success: false,
-        error: new SchemaValidationError("schema validation failed", { issues })
-      };
-    },
-    parse(input) {
-      const result = this.safeParse(input);
-      if (!result.success)
-        throw result.error;
-      return result.data;
-    }
-  };
-}
-var s = {
-  string(opts) {
-    const node = { type: "string" };
-    if (opts?.description !== undefined)
-      node.description = opts.description;
-    if (opts?.enum !== undefined)
-      node.enum = opts.enum;
-    return makeSchema(node);
-  },
-  number(opts) {
-    const node = { type: opts?.int ? "integer" : "number" };
-    if (opts?.description !== undefined)
-      node.description = opts.description;
-    return makeSchema(node);
-  },
-  boolean(opts) {
-    const node = { type: "boolean" };
-    if (opts?.description !== undefined)
-      node.description = opts.description;
-    return makeSchema(node);
-  },
-  enum(values, opts) {
-    const node = { type: "string", enum: values };
-    if (opts?.description !== undefined)
-      node.description = opts.description;
-    return makeSchema(node);
-  },
-  array(item, opts) {
-    const node = { type: "array", items: item.jsonSchema };
-    if (opts?.description !== undefined)
-      node.description = opts.description;
-    return makeSchema(node);
-  },
-  object(props, opts) {
-    const properties = {};
-    const required = [];
-    for (const [key, prop] of Object.entries(props)) {
-      properties[key] = prop.jsonSchema;
-      if (!optionalSchemas.has(prop))
-        required.push(key);
-    }
-    const node = {
-      type: "object",
-      properties,
-      additionalProperties: false
-    };
-    if (required.length > 0)
-      node.required = required;
-    if (opts?.description !== undefined)
-      node.description = opts.description;
-    return makeSchema(node);
-  },
-  optional(inner) {
-    const schema = {
-      jsonSchema: inner.jsonSchema,
-      safeParse(input) {
-        if (input === undefined)
-          return { success: true, data: undefined };
-        return inner.safeParse(input);
-      },
-      parse(input) {
-        const result = this.safeParse(input);
-        if (!result.success)
-          throw result.error;
-        return result.data;
-      }
-    };
-    optionalSchemas.add(schema);
-    return schema;
-  }
-};
-// src/schema/json-schema.ts
-function toJsonSchema(schema) {
-  return schema.jsonSchema;
-}
-function asSchema(impl) {
-  return {
-    jsonSchema: impl.jsonSchema,
-    parse: impl.parse.bind(impl),
-    safeParse: impl.safeParse?.bind(impl) ?? ((input) => {
-      try {
-        return { success: true, data: impl.parse(input) };
-      } catch (error) {
-        if (error instanceof SchemaValidationError)
-          return { success: false, error };
-        return {
-          success: false,
-          error: new SchemaValidationError("schema validation failed", {
-            cause: error,
-            issues: [{ path: [], message: String(error) }]
-          })
-        };
-      }
-    })
-  };
-}
-function fromJsonSchema(jsonSchema) {
-  return {
-    jsonSchema,
-    safeParse(input) {
-      const issues = validateJsonSchema(jsonSchema, input);
-      if (issues.length === 0)
-        return { success: true, data: input };
-      return {
-        success: false,
-        error: new SchemaValidationError("schema validation failed", { issues })
-      };
-    },
-    parse(input) {
-      const result = this.safeParse(input);
-      if (!result.success)
-        throw result.error;
-      return result.data;
-    }
-  };
-}
-export { validateJsonSchema, s, toJsonSchema, asSchema, fromJsonSchema };

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/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?");