@retinue/agentkit 0.1.0 → 0.2.0

package/README.md

@@ -1,310 +1,92 @@
-# @retinue/agentkit
-
-Server-side half of the reusable AI platform. Implements the specifications in
-[`../docs`](../docs).
-
-## Status
-
-Implemented and exercised end to end. 174 source files, ~36,000 lines, 2,143 tests.
-
-This section said *"Contracts only … there is no execution logic yet"* until 2026-08-24,
-which stopped being true a long time before it was corrected — a README that understates
-a package this far is worse than none, because the reader concludes it does nothing and
-looks elsewhere.
-
-What exists now: a durable run loop with leases, checkpointing and recovery; a streaming
-agent engine with tool calls, approvals, questions and citations; three storage adapter
-families held to one conformance suite; usage accounting with quota enforcement; MCP tool
-import; and a GraphQL surface. `examples/` is a runnable application over all of it, and
-`shareflow/` is the first real integration.
-
-Verified against real Postgres, Redis and a live model provider, not only in memory — the
-distinction matters, and `docs/09` records which claims rest on which.
-
-## Modules
+<img src="https://raw.githubusercontent.com/Rise-Experts/retinue/main/brand/retinue-mark.svg" alt="Retinue" width="72" />
 
-| Module | Specification | Contains |
-|---|---|---|
-| `core` | [02](../docs/02-core-and-persistence.md) | `ExecutionContext`, branded IDs, typed message parts, error and event contracts |
-| `capabilities` | #198, #196 | `createRuntime` — the composition root. The wired set is **derived** from the dependencies supplied, not declared beside them, so there is one statement of intent and one of fact. A capability that is off is **enforced**: `runtime.stores.messages` throws when `history` is off, so no caller has to remember to check |
-| `capabilities` *(model)* | #198 | What a runtime does, **declared and cross-checked**. A capability on with nothing wired refuses to construct; so does one wired that nothing declares — the second direction is what catches a feature present, tested and reachable from nothing. Profiles for the two common shapes: a chat assistant, and a headless automation |
-| `models` | [03](../docs/03-intelligence-runtime.md) | Model definitions, capabilities, pricing, resolution policy |
-| `agents` | [03](../docs/03-intelligence-runtime.md) | `AgentManifest` — declarative, stored, versioned |
-| `tools` | [03](../docs/03-intelligence-runtime.md) | Tool descriptors, effect classification, result envelope, meta-tools |
-| `skills` | [03](../docs/03-intelligence-runtime.md) | Versioned skills with a compact catalog entry and lazily loaded body |
-| `context` | [03](../docs/03-intelligence-runtime.md) | Context providers, section metadata, prompt budgets |
-| `runtime` | [04](../docs/04-durable-runtime-and-hitl.md) | Run lifecycle states and execution limits |
-| `hitl` | [04](../docs/04-durable-runtime-and-hitl.md) | Durable questions, approvals and idempotency |
-| `persistence` | [02](../docs/02-core-and-persistence.md) | Tenant-scoped store ports and infrastructure ports |
-| `usage` | [12](../docs/12-usage-and-accounting.md) | Recomputed rollups keyed on tenant, period and principal; quota enforcement at admission across **every** applicable limit — calendar windows, rolling windows and per-model allowances — with a warning below the limit; provider reconciliation that reports rather than corrects |
-| `evaluation` | [09](../docs/09-quality-and-release.md) | Deterministic graders for six of seven expectation kinds, a pinned and cached judge for the seventh, and a release comparison that names the cases that moved |
-| `mcp` | [10](../docs/10-mcp-integration.md) | Outbound MCP-server connections, tool import with safe-by-default effect classification, per-run catalog snapshots for drift detection, and an HTTP egress policy |
-| `files` | [05](../docs/05-knowledge-and-documents.md) | The attachment lifecycle: capped uploads, mediated reads, scheduled deletion, orphan reconciliation; the reference-not-inject context provider and the bounded `read_attachment` step |
-| `documents` | [05](../docs/05-knowledge-and-documents.md) | Extraction to structured blocks (headings, tables, lists), bounded parsers for PDF/Markdown/CSV/JSON, OCR and vision ports, confidence flagging, typed failures, and the bounded `read_document` step |
-| `artifacts` | [05](../docs/05-knowledge-and-documents.md) | Named, versioned assistant output: content by reference, compare-and-set versioning, required provenance, restore, and conversation-scoped access |
-| `export` | [05](../docs/05-knowledge-and-documents.md) | Deterministic PDF and Markdown rendering, one export per version per format, downloads through the mediated file path |
-| `knowledge` | [05](../docs/05-knowledge-and-documents.md) | Structure-aware chunking, the batched embedding pipeline, incremental resumable re-indexing, the freshness target, and hybrid rank-fusion retrieval with an honest empty result |
-| `citations` | [05](../docs/05-knowledge-and-documents.md) | Per-claim provenance as a durable snapshot, groundedness derived from the citation graph, permission checked at citation time |
-| `adapters` | [02](../docs/02-core-and-persistence.md) | Every storage and infrastructure implementation: `memory` (18 files, the reference), `postgres` (26), `supabase` (RLS over the Postgres adapters), `redis`, `bullmq`, `otel`. All three store families are held to the same conformance suite — 29 memory / 28 postgres (1 n/a) / 29 supabase, with no unaccounted cells |
-| `authorization` | [11](../docs/11-authorization.md) | The policy port. **Frozen v1.** Tools are filtered before discovery and re-authorized during execution; untrusted text can never widen capability |
-| `graphql` | [06](../docs/06-graphql-and-frontend.md) | SDL plus a thin resolver map the host mounts on its own server, so the library takes no GraphQL server dependency |
-| `idempotency` | [04](../docs/04-durable-runtime-and-hitl.md) | The idempotency contract. **Frozen v1.** Every external or destructive call carries a key derived from tenant, run and tool-call identity |
-| `principal-memory` | [15](../docs/15-user-memory.md) | Per-person memory, scoped to the principal as well as the tenant — enforced in the adapters and by RLS, not by a `WHERE` clause the caller has to remember |
-| `retention` | [18](../docs/18-data-retention.md) | Retention windows and the deletion path |
-| `security` | [17](../docs/17-security-review.md) | The security review as executable acceptances, each with a revisit date the release gate checks |
-| `telemetry` | [16](../docs/16-load-and-resilience.md) | The telemetry port and its OTel adapter |
-| `loadtest` | [16](../docs/16-load-and-resilience.md) | Load, soak and failure injection harnesses |
-| `worker` | [05](../docs/05-knowledge-and-documents.md) | The export worker |
-| `server` | [06](../docs/06-graphql-and-frontend.md) | The reference GraphQL host, SSE endpoint, boot, config, health and the runnable API and worker commands. Reached at the `./server` subpath; `graphql`, `graphql-yoga` and `@whatwg-node/server` are **optional peers**, so a consumer embedding the runtime in their own server installs none of them. Rules **R12** and **R13** keep the dependency one-way |
-| `tools/library` | — | The first-party tools (#188), reached at the `./tools` subpath: web fetch and search, HTTP, CSV, JSON, read-only SQL, knowledge search, attachments, time and arithmetic. Envelopes only — rule **R7** forbids I/O here |
-| `toolkit` | — | The deterministic functions those tools delegate to, and the only place the outbound HTTP client is built. Separate from `tools/` precisely because it *does* perform I/O |
-| `testing` | [09](../docs/09-quality-and-release.md) | The conformance suite every adapter runs, plus PGlite fixtures. Named `testing` and shipped deliberately: an adapter written outside this repository has to be holdable to the same behaviour |
-
-## Rules these contracts encode
+# @retinue/agentkit
 
-1. Every tenant-sensitive operation takes an explicit tenant context. `findById(id)` is
-   forbidden; ports use `findById({ tenantId, id })`.
-2. `ExecutionContext` identity is constructed by the host application. Model-generated
-   input can never override it.
-3. Tools are authorization-filtered before discovery **and** re-authorized during
-   execution.
-4. Every external or destructive tool call carries an idempotency key derived from
-   tenant, run and tool-call identity.
-5. Untrusted text — tenant-authored skill bodies, MCP tool descriptions — can never
-   widen capability. Authorization lives in the policy layer, never in the prompt.
+[![npm](https://img.shields.io/npm/v/@retinue/agentkit)](https://www.npmjs.com/package/@retinue/agentkit)
+[![licence](https://img.shields.io/npm/l/@retinue/agentkit)](https://github.com/Rise-Experts/retinue/blob/main/LICENSE)
+[![provenance](https://img.shields.io/badge/provenance-attested-brightgreen)](https://www.npmjs.com/package/@retinue/agentkit#provenance)
 
-## Scripts
+**A durable AI agent runtime for TypeScript.** Agents that survive a restart, tools that ask before
+they act, and retrieval that cites its sources — behind ports you can replace.
 
-```bash
-npm run typecheck -w @retinue/agentkit
-npm test -w @retinue/agentkit
-npm run build -w @retinue/agentkit
-```
+For teams building an assistant or an automation that has to be *correct*: a run that crashes resumes
+instead of vanishing, an external write waits for a human, and every token is accounted for.
 
-From the repository root, the checks that gate a change:
+## Install
 
 ```bash
-npm run conformance          # the adapter matrix, and it fails on an unaccounted cell
-npm run check:boundaries     # the dependency rules between workspaces
-npm run check:reachability    # every declared capability is wired, every run event is emitted
-npm run security:review      # the acceptances in `security`, and their revisit dates
-```
-
-`check:reachability` exists because the recurring defect in this codebase is not code that
-is wrong — it is code that is **correct, tested and unreachable**. Citations, questions,
-usage recording, compaction, skills and MCP import were each built, each passing tests,
-and each wired to nothing.
-
-## Subpaths
-
-The root is the **semver boundary**: what is exported from it is API, and what is not exported from it cannot be
-broken. So it is **five values** — it was 392 (#199).
-
-```ts
-import { createRuntime, resolveCapabilities, defineAgent, asId, AgentPlatformError } from "@retinue/agentkit";
-```
-
-Every **type** is still exported from the root, by `export type *`, which emits no import. That is what makes the
-cut affordable: a consumer holding an `ExecutionContext` does not have to know which layer defined it, and a type
-cannot be broken by being imported. The split is **types by subject, values by consumer**.
-
-The root's runtime graph now reaches *nothing* — not `ai`, not `zod`. Those are still real dependencies of the
-package, because `./runtime` and `./tools` need them, and they stay `dependencies` rather than peers: a consumer
-who installs this will use at least one subpath and should not have to install two more things to do it.
-
-```ts
-import { createDefaultEngine } from "@retinue/agentkit/runtime";
-import { defineTool, createStandardToolProvider } from "@retinue/agentkit/tools";  // no peer: uses global fetch
-import { createMemoryRunStore } from "@retinue/agentkit/persistence";              // no peer at all
-import { createPostgresRunStore } from "@retinue/agentkit/adapters/postgres";      // peer: pg
-import { typeDefs, createResolvers } from "@retinue/agentkit/server";              // peer: graphql, graphql-yoga
+npm i @retinue/agentkit
 ```
 
-`src/entries/README.md` lists them all, including why there is no `./testing` yet.
+Node 20+. Provider SDKs, PostgreSQL, Redis and BullMQ are **optional peers** — install only what you use.
+The package root imports nothing but `ai` and `zod`.
 
-## Capabilities
-
-Eight booleans, declared and cross-checked against the wiring — REQ-043 (#197).
+## Your first agent
 
 ```ts
-const runtime = createRuntime({
-  profile: "automation",              // or "assistant", or no profile and set them yourself
-  capabilities: { memory: "on" },     // an override, without restating the rest
-  floor: { runs },                    // what every runtime needs
-  stores: { usage, principalMemory },
+import { createAgent } from "@retinue/agentkit/providers";
+
+const agent = createAgent({
+  manifest: {
+    id: "assistant",
+    name: "Assistant",
+    instructions: "You are a helpful assistant. Be concise.",
+    // A capability, not a hardcoded model id — swapping providers is config.
+    modelPolicy: { role: "smart" },
+  },
 });
-```
-
-| Capability | Needs | On means |
-|---|---|---|
-| `history` | `messages` | Prior turns reach the model |
-| `memory` | `principalMemory` | Per-person memory is read and written |
-| `compaction` | `summaries`, `summarizer` | A long thread is condensed rather than refused |
-| `citations` | `citations` | Claims carry provenance |
-| `questions` | `interactions` | A run can park on a question and resume |
-| `skills` | `skills` | Named instruction blocks load on demand |
-| `mcp` | `mcpConnections`, `mcpClient` | Another server's tools are importable |
-| `usage` | `usage` | Spend is metered |
-
-**A declaration that disagrees with the wiring refuses to start**, in both directions and naming every
-mismatch at once. Declared on with nothing wired is the obvious half. Wired but *not* declared is the half that
-matters more: it is how a declaration drifts into a lie, and this repo has found the same defect six times
-(#157, #159, #161, #163, #165, #185) — a capability that existed, passed its tests, and was wired to nothing.
 
-**Off removes the cost.** No store is required, no query is issued, and reading the dependency of an off
-capability throws rather than returning undefined — access is the gate, so no caller has to remember to check.
-
-**Approvals and quotas are not on this list, deliberately.** They have no off switch. An automation that needs no
-human approves through a *policy* that records what it approved, which is auditable; a boolean that removed the
-gate would remove the record with it. That distinction is the difference between "nobody had to approve this" and
-"nobody knows whether anybody approved this".
-
-### The minimum viable configuration
-
-The smallest thing that runs a tool-calling automation — no conversation, no memory, no human in the loop:
+const result = await agent.run({
+  conversationId: "conv-1",
+  message: "Draft a one-line launch note for our analytics dashboard.",
+});
 
-```ts
-const runtime = createRuntime({ profile: "automation", floor: { runs }, stores: { usage } });
+console.log(result.text);     // the assistant's reply
+console.log(result.outcome);  // "completed" | "failed" | "cancelled" | …
 ```
 
-One store beyond the floor. A run in this configuration has **no `conversationId`** — absent, not invented
-(#198): the conversation-scoped capabilities are unavailable rather than operating on a fabricated id, which is
-what #164 did with `principalId` and why every per-person figure silently read as a machine's.
-
-All 256 combinations of the eight are constructed and gate-checked in `capabilities/__tests__/runtime.test.ts`.
-That test used to enumerate six hand-picked mixes, on the reasoning that the matrix would "assert that
-combinations nobody has thought about work" — which is backwards for a surface of eight independent booleans,
-where the combination nobody thought about is the one a customer picks first.
-
-## Tools
-
-Fifteen first-party tools, at `@retinue/agentkit/tools`. **Wiring is the toggle** — a tool exists when its
-dependency was supplied and not otherwise, because a separate `enable` flag beside a `sqlQuery` function is how a
-deployment ends up with a tool that is enabled and unwired:
+`createAgent` is the batteries-included path: it wires the in-memory stores, the model registry and the
+default engine for you, and reads `ANTHROPIC_API_KEY` from the environment. Swap in PostgreSQL, Redis and
+your own model catalogue when you need them — same code above.
 
-```ts
-const tools = createStandardToolProvider({
-  deps: { authorization, idempotency, approvals },
-  http: {},                                          // fetch_url, fetch_json, http_request, http_write
-  search: braveProvider,                             // web_search — omitted, and the tool does not exist
-  sql: { query: readOnlyPool, readOnly: true, schemas: ["app"] },
-  knowledge: { retriever, authSubjects: (ctx) => [String(ctx.conversationId)] },
-});
-```
+## What you get
 
 | | |
 |---|---|
-| `fetch_url`, `fetch_json`, `http_request` | `read`. Egress-policy checked before any request, redirects refused rather than followed, bodies bounded while reading and fenced as untrusted content |
-| `http_write` | `external-write`, so approval and an idempotency key are required by the registry. Two tools rather than one with a `method` argument, because effect is classified per *tool* — a single tool could only be gated for every call or none |
-| `parse_csv`, `query_json` | `read`, pure. They take text, not a path or a URL: reading is `read_attachment`'s or `fetch_url`'s job, and each should be checked by the thing that should check it |
-| `sql_query`, `sql_schema` | `read`, and only honest because `createSqlQuery` demands a `readOnly: true` acknowledgement. The keyword scan inside it is a second line of defence; the connection is the control |
-| `search_knowledge` | `read`. `authSubjects` comes from the host, never from tool input — a model must not widen its own read scope by asking |
-| `read_attachment`, `list_attachments`, `read_document` | `read`, through `FileService` so the entitlement check is not duplicated |
-| `now`, `calculate` | `read`, pure. `calculate` is a parser, not `eval`: the expression comes from a model |
-
-Credentials are configured per host (`headersFor`) and never appear in a tool's input schema. The client refuses
-an `authorization` or `cookie` header supplied by a caller rather than forwarding it.
+| **Durable runs** | Leases, checkpoints and recovery. Kill the worker mid-turn; the run resumes rather than disappearing |
+| **Approval gates** | An external write stops and waits for a person. Idempotency keys mean a retry does not fire the side effect twice |
+| **Tools that scale** | A compact catalogue in context, full schemas fetched on demand, authorization re-checked at execution |
+| **Knowledge with citations** | Block-aware chunking, hybrid retrieval fused by rank, and answers that point at the source |
+| **Injection containment** | Untrusted content is wrapped in a nonce-delimited envelope with delimiter forgery neutralised — structural, not a detector |
+| **Usage you can bill** | Per-model, per-principal token and cost accounting, with quotas enforced before a run is admitted |
+| **Flows and teams** | Durable multi-step workflows; a team compiles to a flow, and each member's turn is a child run with its own ceiling |
+| **Replaceable everything** | 31 ports, three adapter families, one conformance suite held over all of them |
 
-## Flows and teams
+## Composing it yourself
 
-`@retinue/agentkit/flows` — REQ-038 ([#187](https://github.com/Rise-Experts/retinue/issues/187)) and REQ-037
-([#186](https://github.com/Rise-Experts/retinue/issues/186)).
-
-**A team is a kind of flow step, and a team compiles to a flow.** Both issues say they share design, and they are
-right: a flow's step and a team's member turn are the same idea, and modelling them separately produces two
-overlapping notions of "a step" to keep in agreement forever.
+The root exports five values and every type. Everything else sits behind a documented subpath, so a
+consumer never installs a dependency they do not use:
 
 ```ts
-import { compileTeam, createFlowRunner } from "@retinue/agentkit/flows";
+import { createRuntime, defineAgent } from "@retinue/agentkit";
+import { createDefaultEngine } from "@retinue/agentkit/runtime";
+import { createPostgresConversationStore } from "@retinue/agentkit/adapters/postgres";
 ```
 
-### The interpreter is a pure function
-
-`advance(definition, execution, outcome)` returns the next execution and **one effect** for the caller to perform.
-It performs nothing itself — no agent call, no tool call, no clock read, no store write. Every property these two
-REQs ask for is a consequence rather than a separate mechanism:
-
-| Property | Why it follows |
-|---|---|
-| Durable resume | The returned execution *is* the position. A host persists it; after a restart it calls `advance` again and gets the same effect. There is no interpreter instance to rebuild |
-| Idempotency across a resume | The effect's key is `(executionId, step, attempt)` — all three are in the stored state, so a step that wrote externally and crashed produces the *same* key and the idempotency store answers with the first result |
-| Budgets | Checked before the effect is produced, so an over-budget flow performs nothing rather than spending and then noticing |
-| Tests | Feeding outcomes to a function needs no agent, no database and no clock. The awkward cases — a crash mid-step, a retry surviving a process death — are testable at all |
-
-The alternative, an async interpreter that awaits its own effects, is shorter and cannot be made durable without a
-checkpoint after every `await` — which is the same state machine with the states implicit.
-
-### A definition and an execution are different things
-
-`FlowExecution.flowVersion` is pinned at start and the definition is read at that version for the execution's whole
-life. **Editing a flow does not change one already running.** Proven live: a v2 with a completely different shape
-was published while an execution sat parked at a checkpoint, and it still finished through v1.
-
-The store refuses to overwrite a version at all — `(tenant_id, flow_id, version)` is the primary key with no
-`ON CONFLICT` — which is what makes the pin worth having.
-
-### Step kinds
-
-`agent`, `team`, `tool`, `branch`, `wait`, `checkpoint`, `subflow`, `done`. A `checkpoint` uses the **existing**
-HITL path, so a parked flow is the same object the assistant surface already answers.
-
-Two arithmetic details that were bugs first: `done` consumes no budget and is not gated by one, because a budget
-stops *work* and finishing is not work. Counting it meant a flow whose ceiling exactly matched its work always
-failed on the last step — so `maxSteps: 3` really meant two steps and a marker. A `branch` does count, because a
-branch can loop.
-
-### Failure is chosen in the definition
-
-`retry` (bounded, with backoff), `skip`, `escalate`, `fail`. A retry gets a **different** idempotency key, because
-reusing it would have the store answer with the *failed* first result — a retry policy that silently does nothing.
-A failed step that spent money is still charged, or a retrying flow costs more than its ceiling allows.
-
-### Teams
-
-`sequential` chains one agent step per member, each reading the previous one's output *and* the original brief —
-passing only the previous output loses the request by the third member, which is how a chain of agents drifts off
-the question. `manager-led` compiles to **one** agent step whose tools include a delegation tool, so the engine's
-own turn loop does the iterating and a delegation is a real tool call: authorised, approved, deduplicated and
-accounted for unchanged, because it *is* one rather than resembling one.
-
-A member's tools are an **intersection**, never a union: a member cannot reach a tool the delegating context could
-not, and the delegation tool itself is always stripped — a member that could delegate would be a manager.
-
-### An agent step is a child run
-
-Each agent step creates a `Run` of its own and the flow parks on it (#202). A run rather than an inline model
-call, because a `Run` is what earns checkpointing, recovery, quota admission and its own usage rows — calling a
-model from the runner would be a second turn implementation with none of those, and it would pass a demo.
-
-Three decisions inside that, each with an appealing wrong answer:
-
-- **The child has no conversation.** `ConversationRunCoordinator` claims a *conversation's* single run slot, so a
-  flow inside a conversation whose steps also claimed it would deadlock against the conversation's own turn — the
-  parent holds the slot and waits for a child that can never get it. A conversation-less run (#198) has no slot to
-  contend for, and what the member needs travels in the run's `input`.
-- **The ceiling is the flow's remainder**, re-derived per step. Handing each member the flow's original budget
-  would let every one of them spend the whole thing. Visible live: the first member gets 6 steps, the second 5.
-- **Two ways to wake up, and only one of them is load-bearing.** `onRunSettled` on the worker is the fast path;
-  correctness is a *poll* of the child's state at the top of every resume. A crash between the child completing
-  and the notification being sent loses the message, and a parent that only woke on notifications would sit
-  forever with nothing looking again.
-
-`Run.input` and `Run.limits` exist because of this. #198 made a run able to exist without a conversation, but the
-only place a request could live was a `Message` — and a message requires a conversation. So the run shape said "no
-conversation needed" while the storage said its input still needed one.
-
-`npm run flow -w @retinue/example-app` drives all of it against Postgres: a flow straight through, one parked for
-a person, a reload from storage by something that never held it, the version pin against a published v2, a team
-whose members become child runs with shrinking ceilings, a lost notification recovered by the poll, and a failing
-member routed into its step's policy.
+Anything reachable only by a deep import is **not** API — and that is enforced against the published
+tarball rather than asserted here.
 
-## Import convention
+## Documentation
 
-The package is ESM with `NodeNext` resolution, so relative imports carry an explicit
-`.js` extension even in TypeScript sources.
+- [Getting started](https://docs.retinue.riseexperts.de/docs/getting-started/installation) — install, first agent, configuration
+- [Core concepts](https://docs.retinue.riseexperts.de/docs/concepts/architecture) — agents, tools, durable runtime, retrieval, HITL
+- [Package surface](https://docs.retinue.riseexperts.de/docs/reference/package-surface) — every module, subpath, capability and tool
+- [Versioning and deprecation](https://github.com/Rise-Experts/retinue/blob/main/docs/19-versioning.md) — what semver covers, and how you are told before it changes
+- [Specifications](https://github.com/Rise-Experts/retinue/tree/main/docs) — the design documents, kept as reference
 
 ## Licence
 
-MIT — see [LICENSE](./LICENSE).
+MIT — see [LICENSE](https://github.com/Rise-Experts/retinue/blob/main/LICENSE).
 
-Copyright (c) 2026 Azeem Sarwar and Rise Experts.
+Copyright (c) 2026 [Azeem Sarwar](https://github.com/azeem-sarwar) and
+[Rise Experts](https://github.com/Rise-Experts).

package/dist/adapters/embeddings/openai.d.ts

@@ -0,0 +1,45 @@
+/**
+ * An OpenAI-compatible embedding adapter — REQ-050 (#209), task #219.
+ *
+ * The `EmbeddingProvider` port has existed since #136 with **no adapter of any kind**, which means the semantic
+ * half of hybrid retrieval has never run against a real model in this repository: every test supplies a stub, and
+ * a stub measures the stub. That is why this exists before the eval does — a retrieval score computed over
+ * hash-based pseudo-vectors is a number about nothing.
+ *
+ * OpenAI's shape rather than OpenAI specifically: the same request works against Azure OpenAI, Together, a local
+ * `llama.cpp` server and anything else that copied the endpoint, so `baseUrl` is the whole configuration story.
+ *
+ * ## Two properties worth stating
+ *
+ * **Order is checked, not assumed.** The API returns objects carrying an `index`, and the port's contract is one
+ * vector per input *in order*. A provider that returned them out of order — or dropped one — would silently pair
+ * every chunk with its neighbour's vector, and retrieval would still work well enough to look fine. So the
+ * response is sorted by `index` and the count is verified.
+ *
+ * **The model reference records a version.** Providers change what a model id returns without renaming it, and a
+ * corpus embedded across such a change has two incomparable halves. The port carries the ref per chunk precisely
+ * so that is detectable; this passes the caller's version through rather than inventing one.
+ */
+import type { EmbeddingProvider } from "../../knowledge/index.js";
+export type OpenAiEmbeddingsConfig = {
+    readonly apiKey: string;
+    /** Defaults to `text-embedding-3-small`, which is 1536 dimensions — the platform's `EMBEDDING_DIMENSIONS`. */
+    readonly modelId?: string;
+    /**
+     * The version this deployment is recording for these vectors.
+     *
+     * Not derivable from the API: OpenAI publishes no version for an embedding model, which is exactly the problem
+     * the field exists for. A deployment that re-embeds after noticing a change bumps this itself.
+     */
+    readonly version?: string;
+    readonly dimensions?: number;
+    readonly baseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+    /** Inputs per request. The endpoint accepts many; the ceiling is the request body's size, not a count. */
+    readonly batchSize?: number;
+    readonly timeoutMs?: number;
+};
+export declare const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+export declare const DEFAULT_EMBEDDING_BATCH = 96;
+export declare const createOpenAiEmbeddings: (config: OpenAiEmbeddingsConfig) => EmbeddingProvider;
+//# sourceMappingURL=openai.d.ts.map

package/dist/adapters/embeddings/openai.js

@@ -0,0 +1,109 @@
+/**
+ * An OpenAI-compatible embedding adapter — REQ-050 (#209), task #219.
+ *
+ * The `EmbeddingProvider` port has existed since #136 with **no adapter of any kind**, which means the semantic
+ * half of hybrid retrieval has never run against a real model in this repository: every test supplies a stub, and
+ * a stub measures the stub. That is why this exists before the eval does — a retrieval score computed over
+ * hash-based pseudo-vectors is a number about nothing.
+ *
+ * OpenAI's shape rather than OpenAI specifically: the same request works against Azure OpenAI, Together, a local
+ * `llama.cpp` server and anything else that copied the endpoint, so `baseUrl` is the whole configuration story.
+ *
+ * ## Two properties worth stating
+ *
+ * **Order is checked, not assumed.** The API returns objects carrying an `index`, and the port's contract is one
+ * vector per input *in order*. A provider that returned them out of order — or dropped one — would silently pair
+ * every chunk with its neighbour's vector, and retrieval would still work well enough to look fine. So the
+ * response is sorted by `index` and the count is verified.
+ *
+ * **The model reference records a version.** Providers change what a model id returns without renaming it, and a
+ * corpus embedded across such a change has two incomparable halves. The port carries the ref per chunk precisely
+ * so that is detectable; this passes the caller's version through rather than inventing one.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+export const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+export const DEFAULT_EMBEDDING_BATCH = 96;
+export const createOpenAiEmbeddings = (config) => {
+    const modelId = config.modelId ?? DEFAULT_EMBEDDING_MODEL;
+    const model = {
+        modelId,
+        version: config.version ?? "1",
+        dimensions: config.dimensions ?? 1536,
+    };
+    const doFetch = config.fetchImpl ?? fetch;
+    const base = (config.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    const batchSize = config.batchSize ?? DEFAULT_EMBEDDING_BATCH;
+    const embedBatch = async (texts) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeoutMs ?? 60_000);
+        let response;
+        try {
+            response = await doFetch(`${base}/embeddings`, {
+                method: "POST",
+                signal: controller.signal,
+                headers: { authorization: `Bearer ${config.apiKey}`, "content-type": "application/json" },
+                body: JSON.stringify({
+                    model: modelId,
+                    input: texts,
+                    // Asked for explicitly, because the 3-series models support shortening and a deployment that pinned
+                    // 1536 in its column must get 1536 rather than whatever the default becomes.
+                    ...(model.dimensions === 1536 ? {} : { dimensions: model.dimensions }),
+                }),
+            });
+        }
+        catch (error) {
+            throw new AgentPlatformError({
+                code: error.name === "AbortError" ? "timeout" : "provider_unavailable",
+                message: `The embedding endpoint did not respond: ${error.message}`,
+                retryable: true,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const payload = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            const rateLimited = response.status === 429;
+            throw new AgentPlatformError({
+                code: rateLimited ? "rate_limited" : response.status >= 500 ? "provider_unavailable" : "provider_error",
+                message: `The embedding endpoint returned ${response.status}: ${payload.error?.message ?? "no message"}`,
+                // A 5xx and a rate limit are worth retrying; a 400 means the request is wrong and will stay wrong.
+                retryable: rateLimited || response.status >= 500,
+            });
+        }
+        const data = [...(payload.data ?? [])].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+        if (data.length !== texts.length) {
+            throw new AgentPlatformError({
+                code: "provider_error",
+                message: `Asked for ${texts.length} embeddings and received ${data.length}. Pairing them would attach every chunk to the wrong vector.`,
+                retryable: false,
+            });
+        }
+        return data.map((entry, at) => {
+            const vector = entry.embedding;
+            if (vector === undefined || vector.length !== model.dimensions) {
+                throw new AgentPlatformError({
+                    code: "provider_error",
+                    message: `Embedding ${at} has ${vector?.length ?? 0} dimensions; this deployment records ${model.dimensions}.`,
+                    retryable: false,
+                });
+            }
+            return vector;
+        });
+    };
+    return {
+        model,
+        async embed(texts) {
+            if (texts.length === 0)
+                return [];
+            const out = [];
+            // Sequential batches, deliberately: parallel ones hit the rate limit on a first index of a real corpus,
+            // and the failure arrives as a 429 in the middle of a job rather than as a slower job.
+            for (let at = 0; at < texts.length; at += batchSize) {
+                out.push(...(await embedBatch(texts.slice(at, at + batchSize))));
+            }
+            return out;
+        },
+    };
+};
+//# sourceMappingURL=openai.js.map

package/dist/agents/agent.d.ts

@@ -15,8 +15,10 @@ import { type ProviderCredentials } from "../models/provider-factory.js";
 import type { ModelProvider } from "../models/index.js";
 import type { AuthorizationPolicy } from "../authorization/index.js";
 import { type ContextProvider } from "../context/index.js";
-import { type ToolProvider } from "../tools/index.js";
+import { type ToolProvider, type ToolSearch, type ToolsetResolver } from "../tools/index.js";
+import type { TokenBudget } from "../core/budget.js";
 import { type AgentEngine, type ProcessOutcome } from "../runtime/index.js";
+import type { Guardrail } from "../guardrails/index.js";
 import { type ResolvedModelInfo } from "./engine.js";
 import type { AgentManifest } from "./index.js";
 import { type AgentManifestInput } from "./define.js";
@@ -38,6 +40,25 @@ export type CreateAgentConfig = {
      */
     readonly randomHex?: (bytes: number) => string;
     readonly authorization?: AuthorizationPolicy;
+    /**
+     * Checks to run before the model sees a turn and before anything leaves it — REQ-046 (#205), AC-5.
+     *
+     * Here so a host can add one without composing the runtime by hand: this facade exists to be the short path,
+     * and a guardrail that could only be wired through the long one would be a guardrail most deployments never
+     * add.
+     */
+    readonly guardrails?: readonly Guardrail[];
+    /**
+     * Search over the catalogue, which is what makes `find_tools` exist — REQ-045 (#204), task #210.
+     *
+     * Absent means no `find_tools`. Wire it with `createToolSearch()` for keyword search, or pass an
+     * `EmbeddingProvider` to it for hybrid — and see `tools/find.ts` on why keyword-only is the honest default.
+     */
+    readonly toolSearch?: ToolSearch;
+    /** A ceiling in tokens on the tool list handed to the model — task #210, AC-3. Absent means no ceiling. */
+    readonly catalogBudget?: TokenBudget;
+    /** A tenant's category switches, applied before authorization — task #210, AC-4. */
+    readonly toolsets?: ToolsetResolver;
     readonly tenantId?: string;
     /** Test/advanced seam: override how a manifest resolves to a model (e.g. a mock model). */
     readonly resolveModel?: (manifest: AgentManifest, context: ExecutionContext) => ResolvedModelInfo;