@infinityi/engine-lib 1.0.0 → 1.4.0

package/docs/getting-started.md

@@ -0,0 +1,73 @@
+# Getting started
+
+Install the package in an application:
+
+```bash
+bun add @infinityi/engine-lib
+```
+
+For local development in this repository:
+
+```bash
+bun install
+bun run check
+bun test
+bun run build
+```
+
+## Minimal run
+
+Use a real provider in production and the testing provider in examples or unit
+tests:
+
+```ts
+import { defineAgent, runAgent } from "@infinityi/engine-lib";
+import { mockProvider, textResult } from "@infinityi/engine-lib/testing";
+
+const agent = defineAgent({
+  name: "assistant",
+  provider: mockProvider({ result: () => textResult("hello") }),
+});
+
+const result = await runAgent(agent, { input: "Say hello." });
+console.log(result.output);
+```
+
+Runnable version: [`../examples/01-minimal-agent.ts`](../examples/01-minimal-agent.ts).
+
+## Import paths
+
+Prefer the root import for stable application wiring:
+
+```ts
+import { defineAgent, defineTool, runAgent, s } from "@infinityi/engine-lib";
+```
+
+Use subpaths for domain-specific or optional surfaces:
+
+```ts
+import { createOpenAI } from "@infinityi/engine-lib/providers";
+import { filesystemTools } from "@infinityi/engine-lib/tools-fs";
+import { createSqliteSessionStore } from "@infinityi/engine-lib/session-stores";
+import { mockProvider } from "@infinityi/engine-lib/testing";
+```
+
+Optional tool packs may need optional peer dependencies from `package.json`
+when consumed outside this repository.
+
+## Examples and API docs
+
+Run the offline examples:
+
+```bash
+bun run examples
+```
+
+Generate local API docs:
+
+```bash
+bun run docs
+```
+
+Then open `docs/api/index.html`.
+

package/docs/multi-agent.md

@@ -0,0 +1,52 @@
+# Multi-agent coordination
+
+engine-lib supports two composition patterns without a separate orchestrator:
+handoffs and sub-agents as tools.
+
+## Handoffs
+
+A handoff transfers the active run to another agent. The conversation history is
+preserved and the final result records the trail.
+
+```ts
+const billing = defineAgent({ name: "billing", provider, instructions: "Handle billing." });
+
+const triage = defineAgent({
+  name: "triage",
+  provider,
+  instructions: "Route the user.",
+  handoffs: [billing],
+});
+```
+
+Runnable version:
+[`../examples/06-multi-agent-handoff.ts`](../examples/06-multi-agent-handoff.ts).
+
+String-named handoff targets require a registry:
+
+```ts
+const registry = createAgentRegistry([billing]);
+const triage = defineAgent({ name: "triage", provider, handoffs: ["billing"] });
+await runAgent(triage, { input: "refund", registry });
+```
+
+Use `maxHandoffs` to bound routing loops.
+
+## Sub-agent as tool
+
+`asTool(agent)` wraps a child agent as a normal tool. The parent model decides
+when to call it. The child output is fed back as the tool result, child usage is
+folded into parent usage, and child events surface as `agent.child`.
+
+```ts
+const researcher = defineAgent({ name: "researcher", provider });
+const lead = defineAgent({
+  name: "lead",
+  provider,
+  tools: [asTool(researcher)],
+});
+```
+
+Runnable version:
+[`../examples/07-sub-agent-tool.ts`](../examples/07-sub-agent-tool.ts).
+

package/docs/optional-tool-packs.md

@@ -0,0 +1,93 @@
+# Optional tool packs
+
+The root package does not expose file, shell, HTTP, or web access. These modules
+are opt-in subpaths and must be configured by the host application.
+
+## Shell tools
+
+Import:
+
+```ts
+import { shellTools } from "@infinityi/engine-lib/tools-shell";
+```
+
+Safety controls:
+
+- required `allowedCwds`
+- environment allow/deny filtering
+- command allow/deny policy
+- optional approval hook
+- timeout and output caps
+- audit events for policy, approval, execution, chunks, and errors
+
+Runnable version: [`../examples/11-shell-tools.ts`](../examples/11-shell-tools.ts).
+
+## Filesystem tools
+
+Import:
+
+```ts
+import { filesystemTools } from "@infinityi/engine-lib/tools-fs";
+```
+
+Capabilities:
+
+- `repo_map`
+- `find_files`
+- `search_text`
+- `search_semantic`
+- `symbols`
+- `read`
+- `open_window`
+- `edit_replace`
+- `edit_range`
+- `apply_patch`
+- `write_file`
+- `diff_status`
+
+All paths must resolve inside configured `allowedRoots`.
+
+Runnable version:
+[`../examples/09-tools-filesystem.ts`](../examples/09-tools-filesystem.ts).
+
+## HTTP tools
+
+Import:
+
+```ts
+import { httpTools, createHttpToolClient } from "@infinityi/engine-lib/tools-http";
+```
+
+Safety controls:
+
+- explicit `allowedHosts` or `allowPublicInternet`
+- denied hosts
+- protocol allowlist
+- private-network denial by default
+- credentialed URL denial by default
+- redirect target checks
+- model-supplied header allowlist
+- timeout, retry, response byte, and body character caps
+
+## Web tools
+
+Import:
+
+```ts
+import { webTools } from "@infinityi/engine-lib/tools-web";
+```
+
+The web pack builds on the HTTP client and adds:
+
+- `web_search`
+- `fetch_page`
+- `extract_readable_text`
+- `crawl_links`
+
+Search requires an injected `SearchProvider`. No search vendor, browser
+automation, JavaScript rendering, cookie jar, or authenticated session handling
+is bundled.
+
+Runnable HTTP and web example:
+[`../examples/10-tools-http-web.ts`](../examples/10-tools-http-web.ts).
+

package/docs/providers.md

@@ -0,0 +1,68 @@
+# Providers
+
+Providers normalize LLM APIs behind one contract: `complete()` for buffered
+turns and `stream()` for token/tool-call deltas.
+
+Application imports:
+
+```ts
+import {
+  createAnthropic,
+  createGoogle,
+  createOpenAI,
+  createOpenAICompatible,
+} from "@infinityi/engine-lib/providers";
+```
+
+Root imports also expose the built-in factories.
+
+## Built-in factories
+
+```ts
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5" });
+const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-opus-4-7" });
+const google = createGoogle({ apiKey: process.env.GOOGLE_API_KEY!, model: "gemini-2.5-pro" });
+const local = createOpenAICompatible({ baseUrl: "http://localhost:1234/v1", model: "local-model" });
+```
+
+Provider API keys accept raw strings or Forge `Secret<string>` values.
+
+Runnable real-provider example:
+[`../examples/12-provider-openai.ts`](../examples/12-provider-openai.ts).
+
+## Capabilities
+
+Every provider declares:
+
+- `tools`
+- `streaming`
+- `multimodalInput`
+- `parallelToolCalls`
+- `structuredOutput`
+
+Treat these as adapter truth and degrade gracefully. For example, a UI can hide
+streaming controls when `provider.capabilities.streaming` is false.
+
+## Vendor-specific options
+
+Use normalized request fields first: `temperature`, `topP`,
+`maxOutputTokens`, `stopSequences`, `tools`, `toolChoice`, and
+`responseSchema`.
+
+Use `providerOptions` only for vendor-specific request body fields that are not
+first-classed yet.
+
+## Custom adapters
+
+Advanced imports from `@infinityi/engine-lib/providers` include:
+
+- `createProvider`
+- `createProviderHttp`
+- `parseSse`
+- `StreamAccumulator`
+- `collectStream`
+- `AdapterSpec`
+
+Adapter authors should also wire the conformance battery from
+`@infinityi/engine-lib/testing/conformance`.
+

package/docs/retrieval.md

@@ -0,0 +1,83 @@
+# Retrieval
+
+`@infinityi/engine-lib/retrieval` is an opt-in module for host-owned RAG
+pipelines. It provides contracts and small local implementations, then adapts
+retrievers back into the existing `ContextProvider` flow.
+
+The module does not provide a hosted retrieval service, managed vector database,
+or vendor embedding client. Applications supply those pieces behind the exported
+interfaces.
+
+## Index Documents
+
+```ts
+import {
+  InMemoryVectorStore,
+  createTextChunker,
+  indexDocuments,
+  staticDocumentLoader,
+  type EmbeddingProvider,
+} from "@infinityi/engine-lib/retrieval";
+
+const embeddings: EmbeddingProvider = {
+  name: "toy",
+  defaultModel: "toy-embedding",
+  dimensions: 3,
+  async embed(req) {
+    return {
+      model: req.model ?? "toy-embedding",
+      vectors: req.input.map((text) => [text.length, text.includes("database") ? 1 : 0, 1]),
+      dimensions: 3,
+    };
+  },
+};
+
+const store = new InMemoryVectorStore({ dimensions: 3 });
+
+await indexDocuments({
+  loaders: [
+    staticDocumentLoader([
+      {
+        id: "runbook",
+        content: "If the database is unavailable, fail over to the standby.",
+        source: { uri: "runbooks/database.md", title: "Database Runbook" },
+      },
+    ]),
+  ],
+  chunker: createTextChunker({ maxChars: 1_000, overlapChars: 100 }),
+  embeddings,
+  store,
+});
+```
+
+`InMemoryVectorStore` computes similarity by scanning every stored record. It is
+intended for tests, examples, and small local corpora; production-scale or
+latency-sensitive systems should implement `VectorStore` with a dedicated vector
+database or search service.
+
+## Inject Retrieved Context
+
+```ts
+import {
+  createVectorRetriever,
+  retrieverContext,
+} from "@infinityi/engine-lib/retrieval";
+
+const retriever = createVectorRetriever({ embeddings, store, topK: 4 });
+
+await runAgent(agent, {
+  input: "How do I recover the database?",
+  context: [retrieverContext({ retriever, maxContextTokens: 1_500 })],
+});
+```
+
+`retrieverContext` derives the query from the current run input by default,
+renders citations such as `[1] Database Runbook, lines 1-3`, and returns no
+context when there is no query or no retrieval hit.
+
+## Hybrid Retrieval
+
+Pass a `KeywordRetriever` hook to `createVectorRetriever` when a host wants to
+combine lexical and vector search. `mergeHybridResults` normalizes the vector and
+keyword score channels independently, de-duplicates by id, applies weights, and
+returns ranked `RetrievalResult`s.

package/docs/sessions-and-context.md

@@ -0,0 +1,82 @@
+# Sessions and context
+
+Sessions store durable conversation history. Context providers inject
+request-time information without persisting it.
+
+Application imports:
+
+```ts
+import {
+  createSession,
+  dynamicContext,
+  staticContext,
+  truncateOldest,
+} from "@infinityi/engine-lib";
+```
+
+Runnable version:
+[`../examples/04-sessions-context.ts`](../examples/04-sessions-context.ts).
+
+## Sessions
+
+```ts
+const session = createSession({ id: "user-123" });
+
+await runAgent(agent, { input: "first", session });
+await runAgent(agent, { input: "second", session });
+
+const history = await session.messages();
+```
+
+Successful runs append only conversation messages:
+
+- user input
+- assistant turns
+- tool-result messages
+
+Instructions and injected context are rebuilt for each request and are not
+persisted.
+
+## Durable stores
+
+Durable stores live on `@infinityi/engine-lib/session-stores`:
+
+- `createSqliteSessionStore`
+- `createPostgresSessionStore`
+- `RedisSessionStore`
+- `FilesystemJsonlSessionStore`
+- `ForgeDataSessionStore`
+
+Stores expose `migrate()` when they own schema setup and `close()` when they own
+resources. Use `SessionStoreCodec` to add encryption at rest.
+
+## Context
+
+```ts
+await runAgent(agent, {
+  input: "answer with account facts",
+  context: [
+    staticContext({ plan: "enterprise" }, "Account"),
+    dynamicContext("clock", () => new Date().toISOString()),
+  ],
+});
+```
+
+Context providers resolve once per run before the first provider call.
+
+## Context windows
+
+Use `contextWindow` to trim the provider request view without mutating the
+canonical session history:
+
+```ts
+await runAgent(agent, {
+  input: "newest",
+  messages: priorMessages,
+  contextWindow: {
+    maxTokens: 8_000,
+    strategy: truncateOldest(),
+  },
+});
+```
+

package/docs/testing-and-lifecycle.md

@@ -0,0 +1,60 @@
+# Testing and lifecycle
+
+## Testing helpers
+
+Import:
+
+```ts
+import {
+  mockProvider,
+  scriptedProvider,
+  textResult,
+  toolCallResult,
+} from "@infinityi/engine-lib/testing";
+```
+
+Use `mockProvider` for simple one-turn tests and request inspection. Use
+`scriptedProvider` for multi-turn tests such as tool call followed by final
+answer.
+
+Runnable version:
+[`../examples/08-testing-agent.ts`](../examples/08-testing-agent.ts).
+
+Other helpers:
+
+- `conversation`
+- `collectProviderStream`
+- `expectValid`
+- `jsonFetch`
+- `sseFetch`
+- `inMemorySessionStore`
+
+## Provider conformance
+
+Adapter authors should use:
+
+```ts
+import { runProviderConformance } from "@infinityi/engine-lib/testing/conformance";
+```
+
+The battery checks buffered completion, streaming, tool calling, usage,
+capability honesty, and error mapping through fake transports.
+
+## Lifecycle
+
+Import:
+
+```ts
+import { agentRuntimeComponent } from "@infinityi/engine-lib/lifecycle";
+```
+
+`agentRuntimeComponent` adapts providers and optional session stores to a Forge
+lifecycle component:
+
+- `start()` validates provider names and default models
+- `probeOnStart` can fail boot when providers are unhealthy
+- `healthcheck()` maps provider probes to Forge health results
+- `stop()` runs a host shutdown hook, such as closing a durable store
+
+Runnable version: [`../examples/13-lifecycle.ts`](../examples/13-lifecycle.ts).
+

package/docs/tools.md

@@ -0,0 +1,69 @@
+# Tools and schemas
+
+Tools are named capabilities the model may call. Schemas validate model-supplied
+arguments before execution.
+
+Application imports:
+
+```ts
+import { defineTool, s } from "@infinityi/engine-lib";
+```
+
+## Define a tool
+
+```ts
+const lookupService = defineTool({
+  name: "lookup_service",
+  description: "Return status for an internal service.",
+  parameters: s.object({
+    service: s.enum(["api", "worker", "billing"]),
+  }),
+  execute: ({ service }) => ({
+    ok: true,
+    content: { service, status: "healthy" },
+  }),
+});
+```
+
+Runnable version: [`../examples/02-custom-tool.ts`](../examples/02-custom-tool.ts).
+
+## Schema builder
+
+The `s` builder covers the JSON-Schema subset needed for provider tool
+parameters and structured outputs:
+
+- `s.string()`
+- `s.number()`
+- `s.boolean()`
+- `s.enum([...])`
+- `s.array(item)`
+- `s.object(shape)`
+- `s.optional(inner)`
+
+Objects are strict by default and reject unknown properties. Optional object
+fields are derived from `s.optional(...)`.
+
+Use `asSchema()` or `fromJsonSchema()` when adapting an external schema library
+or raw JSON Schema.
+
+## Tool results
+
+Return success for expected output:
+
+```ts
+return { ok: true, content: data };
+```
+
+Return failure for domain errors the model can recover from:
+
+```ts
+return { ok: false, error: "file not found" };
+```
+
+Throw only for unexpected implementation faults. `runAgent` catches thrown tool
+errors and feeds them back as tool-result errors instead of crashing the entire
+run.
+
+Example test pattern:
+[`../examples/08-testing-agent.ts`](../examples/08-testing-agent.ts).
+

package/examples/01-minimal-agent.ts

@@ -0,0 +1,19 @@
+import { defineAgent, runAgent } from "@infinityi/engine-lib";
+import { mockProvider, textResult } from "@infinityi/engine-lib/testing";
+
+const agent = defineAgent({
+  name: "assistant",
+  provider: mockProvider({
+    result: () => textResult("Hello from a local mock provider."),
+  }),
+  instructions: "Answer briefly.",
+});
+
+const result = await runAgent(agent, { input: "Say hello." });
+
+console.log({
+  output: result.output,
+  steps: result.steps,
+  finishReason: result.finishReason,
+});
+

package/examples/02-custom-tool.ts

@@ -0,0 +1,32 @@
+import { defineAgent, defineTool, runAgent, s } from "@infinityi/engine-lib";
+import { scriptedProvider, textResult, toolCallResult } from "@infinityi/engine-lib/testing";
+
+const lookupService = defineTool({
+  name: "lookup_service",
+  description: "Return status for an internal service.",
+  parameters: s.object({
+    service: s.enum(["api", "worker", "billing"]),
+  }),
+  execute: ({ service }) => ({
+    ok: true,
+    content: {
+      service,
+      status: service === "billing" ? "degraded" : "healthy",
+      since: "2026-06-11T12:00:00Z",
+    },
+  }),
+});
+
+const agent = defineAgent({
+  name: "status",
+  tools: [lookupService],
+  provider: scriptedProvider([
+    toolCallResult([{ id: "call-1", name: "lookup_service", arguments: { service: "billing" } }]),
+    textResult("Billing is degraded and has been since 2026-06-11T12:00:00Z."),
+  ]),
+});
+
+const result = await runAgent(agent, { input: "Check billing." });
+
+console.log(result.output);
+

package/examples/03-streaming.ts

@@ -0,0 +1,46 @@
+import { defineAgent, defineTool, runAgent, s } from "@infinityi/engine-lib";
+import type { RunEvent } from "@infinityi/engine-lib/execution";
+import { scriptedProvider, textResult, toolCallResult } from "@infinityi/engine-lib/testing";
+
+const echo = defineTool({
+  name: "echo",
+  parameters: s.object({ value: s.string() }),
+  execute: ({ value }) => ({ ok: true, content: value }),
+});
+
+const agent = defineAgent({
+  name: "streamer",
+  tools: [echo],
+  provider: scriptedProvider([
+    toolCallResult([{ id: "echo-1", name: "echo", arguments: { value: "checked" } }]),
+    textResult("Streaming run completed."),
+  ]),
+});
+
+const events: string[] = [];
+const handle = runAgent(agent, { input: "Run with events.", stream: true });
+
+for await (const event of handle) {
+  events.push(describeEvent(event));
+}
+
+const result = await handle.completed;
+
+console.log({
+  events,
+  output: result.output,
+});
+
+function describeEvent(event: RunEvent): string {
+  switch (event.type) {
+    case "token":
+      return `token:${event.delta}`;
+    case "tool.call":
+      return `tool.call:${event.name}`;
+    case "tool.result":
+      return `tool.result:${event.name}:${event.result.ok ? "ok" : "error"}`;
+    default:
+      return event.type;
+  }
+}
+