@nylorun/harness 0.5.0-beta.1 → 0.8.0-beta.1

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to `@nylorun/harness` are documented in this file.
 
 The project follows [Semantic Versioning](https://semver.org/). Before 1.0, the public API is experimental: breaking changes may occur in minor releases, while patch releases are reserved for compatible fixes.
 
+## [0.8.0-beta.1] - 2026-08-31
+
+### Breaking changes
+
+- `Agent()` now takes identity options instead of a model adapter. Migrate
+  `Agent(adapter).use(...).build()` to
+  `Agent({ id, name, instructions }).use(...).with(adapter).build()`.
+- `.build()` exists only on `BoundAgentBuilder`, the type returned by a single `.with(onModelCall)`.
+  `AgentBuilder` has `.use()` and `.with()` only.
+- `AgentManifest` now includes `id` and `name`. Built agents expose the same fields as `agent.id`
+  and `agent.name`.
+
+### Added
+
+- Optional constructor `instructions` compile as reserved `agent` middleware. A string is
+  normalized to one instruction. Capability-specific instructions still go through `.use()`.
+
+## [0.7.0-beta.1] - 2026-08-30
+
+### Breaking changes
+
+- Removed the bind-time directive argument: migrate `Agent(adapter, directive)` to
+  `Agent(adapter).use({ id: "model", model: directive })`. `AgentManifest.model` is removed.
+- Added `CapabilityDeclaration` support to `.use()`. A declaration owns one capability id, static
+  tool/instruction/model contributions, and optional inline middleware.
+- `ToolExecutionContext` now includes session, turn, step, and call identities.
+
+### Added
+
+- Declarations may own typed lazy session state through `CapabilityState`. State is shared only by
+  that declaration's middleware and tools, is cold after seed recovery, and is disposed on
+  `session.stop()` or recording failure.
+- Added `capability.state.dispose.failed` observations for best-effort disposal failures.
+- Added `capability.state.undeclared`, raised when session state is requested for a capability that
+  declared none.
+
+### Documentation
+
+- Added concise package guidance for direct agent composition and the capability/service/host/core model.
+
+## [0.6.0-beta.1] - 2026-08-29
+
+### Breaking changes since 0.5.0-beta.1
+
+- Removed tool adapters, `.with()`, `executeWith`, preflight, adapter concurrency controls, custom scheduling, adapter manifest fields, and adapter observations/errors.
+- Tools now own their implementation through `execute(args, context)`. Harness centrally executes eligible siblings concurrently and commits normalized results in model-call order.
+- Tool results are explicit `completed`, `denied`, and `failed` discriminated unions. Tool and model implementations may return `deferred` for a runtime handoff.
+
+### Added
+
+- Structural `SessionSeed` import through `agent.run({ seed })` and no-input `session.continue()`. Core validates typed JSON but deliberately leaves historical semantics and provider protocol validation to the host and model adapter.
+- Optional awaited `SessionRecorder`, immutable full-state `SessionRecord` values, monotonic revisions, and effect barriers around input, model requests, candidates, tool results, waiting, final, and stop transitions.
+- JSON-safe active model/tool/interaction records with stable invocation identities, tool ownership provenance, settled/deferred state, and opaque handoff tokens.
+- `model.deferred`, `tool.started`, `tool.completed`, `tool.deferred`, `session.seeded`, `session.continued`, and `session.record.failed` observations.
+
+### Reliability
+
+- Recorder failure now fences later model/tool effects, quarantines late results, stops queued work, preserves the last successfully recorded revision, and exposes `session.record-failed` with the storage error as its cause.
+- Deferred sibling batches settle fully without committing a partial model-facing `tool-results` entry.
+
 ## [0.5.0-beta.1] - 2026-08-28
 
 ### Breaking changes since 0.4.0-rc.1
@@ -30,3 +90,6 @@ The project follows [Semantic Versioning](https://semver.org/). Before 1.0, the
 - Observe attributes are materialized only when a listener is registered. Transcript snapshots on `step.started` share the already-frozen step transcript rather than deep-copying it on every step.
 
 [0.5.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness
+[0.6.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness
+[0.7.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness
+[0.8.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness

package/README.md

@@ -1,124 +1,43 @@
-# @nylorun/harness
+# `@nylorun/harness`
 
-`@nylorun/harness` is a small, provider-neutral agent loop. It seals one model adapter, an optional default model directive, tool adapters, and an ordered middleware onion into a fixed Agent, then runs independent in-memory Sessions. Middleware stages named changes against a session-scoped prompt-prefix state; each Model call receives an immutable canonical prefix, then its candidate is reviewed and its tool plan sealed before any adapter runs.
+`@nylorun/harness` is a small, provider-neutral TypeScript loop for model calls and tools. Compose
+an agent from a model adapter and named capabilities; keep provider clients, stores, HTTP, and
+credentials in ordinary application code.
 
-> **Experimental beta.** Install the current candidate with `npm install @nylorun/harness@beta`. Until 1.0, this API is intentionally experimental: minor releases may contain breaking changes, while patch releases are reserved for compatible fixes. See [CHANGELOG.md](./CHANGELOG.md) for migration notes.
+> **Experimental beta.** Install with `npm install @nylorun/harness@beta`.
 
 ```ts
-import { Agent, adapter, model, tool } from "@nylorun/harness";
+import { Agent, model, tool } from "@nylorun/harness";
 import { z } from "zod";
 
-const local = adapter({
-  id: "local",
-  async execute(call) {
-    return { kind: "completed" as const, output: { echoed: call.args } };
-  },
-});
-
+const adapter = model(async (call) => provider.complete(call));
 const echo = tool({
   name: "echo",
-  description: "Echo a message",
+  description: "Echo text",
   parameters: z.object({ text: z.string() }),
-  executeWith: "local",
-});
-
-const example = model(async (call, { request }) => {
-  return request.toolResults.length === 0
-    ? {
-        output: [{ type: "tool-call", id: "call_1", name: "echo", args: { text: "hello" } }],
-      }
-    : `Completed with ${JSON.stringify(request.toolResults[0]?.output)}`;
+  execute: async ({ text }) => ({ kind: "completed", output: text }),
 });
 
-const session = Agent(example, { id: "example" })
-  .with(local)
-  .use("echo", async (request, next) => {
-    request.configuration.tools.set("echo-tools", [echo], { order: 100 });
-    request.configuration.instructions.set("echo-policy", ["Echo the user text."], { order: 100 });
-    return next();
-  })
-  .use("turn-budget", async (request, next) => {
-    if (request.turnNumber > 8) {
-      return request.tripwire({ code: "turn.limit", message: "Limit reached" });
-    }
-    return next();
-  })
-  .build()
-  .run();
-session.observe((event) => {
-  if (event.type === "model.requested") console.log("model", event.attributes);
-});
-session.input("Echo hello");
-for await (const event of session.stream()) {
-  if (event.type === "final") {
-    console.log(event.output);
-    await session.stop();
-  }
-}
-```
-
-`Agent(model, directive?)` returns a builder. The first argument is the model callback `(call, { request, signal })`; the optional directive (`{ id?, controls?, config? }`) is seeded into every model step and can be replaced or cleared for that call. `.with(adapter, { maxConcurrentCalls? })` registers an adapter by `adapter.id` (required for tool dispatch via `executeWith`); omitted `maxConcurrentCalls` dispatches sibling `execute()` calls in parallel without a Harness cap, while a positive safe integer is a FIFO limit shared by all Sessions from that `BuiltAgent`. Adapter authors remain responsible for concurrent safety when no limit is supplied. Call order has no onion effect. `.use(middleware)` or `.use(id, middleware)` appends middleware (later is more inward); omitted ids become `middleware-1`, `middleware-2`, …. `.build()` validates ids and seals a `BuiltAgent`, or throws `AgentBuildError`. `BuiltAgent.run(options?)` creates an in-memory Session. `session.input("hello")` or `session.input({ text, metadata? })` queues a user message and returns a completion handle; while a turn is running or waiting, that message stays queued until the current turn finals, then a new turn starts. Approve and respond stay on `session.input({ kind: "approve" | "respond", ... })` — those are interaction replies, not messages. `session.interrupt("...")` queues barge-in text: if the current turn still has another step, the interrupt is claimed as that step’s arrivals (same turn, no abort of the in-flight model or tool work); if the turn already finalized, it starts a new turn like ordinary input. `session.stream()` yields the conversation (`input`, per-step `candidate`, then settlement events) — not observe events or tool results. `session.observe(listener)` adds a live, fail-open observer and returns an idempotent unsubscribe function; it does not replay earlier events. `session.stop()` ends that Session only.
+const agent = Agent({
+  id: "echo",
+  name: "Echo",
+  instructions: "Use echo when asked.",
+})
+  .use({ id: "echo", tools: [echo] })
+  .with(adapter)
+  .build();
 
-## Middleware
-
-Middleware is the Model lifecycle:
-
-```ts
-type StepMiddleware = (
-  request: StepRequest,
-  next: () => Promise<StepResponse>,
-) => Promise<StepResponse>;
+const result = await agent.run().input("Echo hello").completed;
 ```
 
-Each `StepRequest` includes opaque `sessionId`, `turnId`, and `stepId` identities, so middleware can associate application-owned state with the current execution. Draft the current call on `request.configuration`: named `instructions.set`, `tools.set`, and `model.select` / `replace` / `clear`; draft current-call tail data on `request.context.set`; or tripwire. `await next()` runs the inner onion and one Model call, then returns a branded `StepResponse`. Review that candidate (`deny`, `requireInteraction`, `requirePreflight`, `replace`, `tripwire`) and return it. Skipping `next()` is legal only by returning `request.tripwire(...)`. `void next()` is not supported.
-
-Configuration and context are fresh assemblies for each model call. A repeated `set` for the same middleware/slot replaces that middleware’s earlier declaration in that step; nothing is retained for the next step. A middleware can declare only its own slot. Cross-cutting policy belongs in the tool-owning middleware or the host's final assembly decision; `deny()` remains available to reject a specific requested call after inspecting its arguments. Effective instruction and visible-tool order is canonical: explicit `order`, middleware registration order, slot name, then declaration order. A model directive is `{ id?, controls?, config? }`; `select` is idempotent, `replace` is the explicit override, and `clear` suppresses the Agent directive only for the current call. Duplicate tool names and invalid schemas tripwire before the Model runs. `reason` is attribution emitted to observers; Harness does not enforce drift policy.
-
-Context is separate from the configuration digest. `context.set(slot, items, { order?, reason? })` contributes only to the current call. `run({ context })` is freshly projected as a host-attributed `type: "session"` item on every call. Applications that need state across calls own it and explicitly re-declare the model-visible portion using the request identities.
-
-`ModelAdapter` receives a projected `ModelCall` first (`prompt`, `tools`, optional `model`, `sessionId`), then `{ request, signal }`: the structured `ModelRequest` escape hatch and its cancellation signal. `prompt` is an ordered typed list: `instructions` (system), then transcript `message` / `tool-result` items, then one `context` item when the committed snapshot is non-empty. Context is a user-role envelope around a JSON array of `{ type?, value }` — structural serialization so a value cannot mint a sibling prompt item, not a sandbox against prompt injection. Tool-result items keep `toolName` and `status`. Arrivals and toolResults stay on `request` — they are already on the transcript before invoke, so appending them would duplicate history. `turnId` and `stepId` stay on `ModelRequest` and observe events, not on `ModelCall`.
-
-`ModelRequest.configuration` carries the selected model directive, ordered instruction text, visible provider tool contracts, contributor provenance, and logical/model/combined digests. `ModelRequest.context` is the current-step snapshot (items, contributors, digest). Immediately before invoking the adapter, Harness emits one `model.requested` event. Its `attributes.call` is the exact deeply immutable `ModelCall` supplied to the adapter; `attributes.configuration` and `attributes.context` are JSON-safe attributed snapshots. This is the immutable logical adapter-input boundary, not a provider-wire trace. Harness does not retain a baseline or audit drift; an observer such as Studio can compare these events and apply its own policy.
-
-A successful Model return is a `ModelCandidate`: an ordered `output` of `text`, `reasoning`, and `tool-call` blocks, plus optional `finishReason`, `usage`, and `evidence`. A string return becomes one text block. Session `final` joins text blocks with `""`; reasoning is stored on the transcript candidate for observability and is never part of that string or of the tool plan. Harness projects its transcript into the portable `ModelCall` and omits reasoning when replaying assistant content. Tool-call `args` are a JSON object; `{}` is valid and is not a stand-in for parse failure. `finishReason` is `stop`, `length`, `tool-calls`, `content-filter`, or `other` — never `error` or `aborted`. Thrown `invoke` or an aborted signal stays on the `model.failed` / abort path. `evidence.extras` is for small safe fields, not raw request or response bodies. Token counts that are present must be non-negative integers; `costUsd` is optional and only when the provider supplied it.
-
-The harness canonicalizes tool-call ids when it mints the response; `sealStep` reuses those ids. `replace` may drop calls and rewrite text or reasoning but cannot change a retained call’s name or arguments or undo an inner denial. A replace that omits `finishReason`, `usage`, or `evidence` keeps the current values.
-
-A tripwire, invalid return, or bind failure on one Session does not stop sibling Sessions. Harness contract breaks are session-scoped. Late `setTimeout` mutations throw and emit observe events; they do not stop a settled Session.
-
-The harness has no automatic turn, Step, or wall-clock timeout. Applications own budgets through middleware.
-
-## Structured errors and beta migration
-
-Harness-created errors are `HarnessError` instances. Their `code` is stable and machine-readable; their `message` is explanatory and is not a compatibility contract. `details` contains only safe identifiers and paths, and `cause` preserves a foreign underlying error when there is one. Middleware-, model-, and adapter-originated errors remain foreign causes; application-owned tripwire and tool-result codes remain unrestricted strings.
-
-Version 0.5.0-beta.1 replaces the following built-in outcome codes without aliases:
-
-| Previous code / condition                                                                      | 0.5 code                                                                                                                                                            |
-| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tool.duplicate-name`                                                                          | `configuration.duplicate-tool-name`                                                                                                                                 |
-| `model.selection-conflict`                                                                     | `configuration.model-selection-conflict`                                                                                                                            |
-| `tool.invalid`                                                                                 | `tool.invalid-name`, `tool.invalid-schema`, or `adapter.not-registered`                                                                                             |
-| `prefix.invalid`                                                                               | `configuration.invalid-instructions`, `configuration.invalid-tools`, `configuration.invalid-slot`, `configuration.invalid-reason`, or `configuration.invalid-order` |
-| prefix status / drift policy                                                                   | Removed; compare `model.requested` events in the observing application.                                                                                             |
-| `response.replace-invalid`                                                                     | `response.invalid-replacement`                                                                                                                                      |
-| `model.failed` for invalid Harness-normalized candidates                                       | `model.invalid-candidate`                                                                                                                                           |
-| `middleware.failed` for Harness middleware-protocol faults                                     | `middleware.request-mutators-revoked`, `middleware.next-after-return`, or `middleware.next-called-twice`                                                            |
-| `tool.execution-failed` / `tool.preflight-failed` for malformed Harness-validated adapter data | `adapter.invalid-outcome`, `tool.invalid-tool-result`, or `interaction.invalid`                                                                                     |
-| `harness.invalid-directive` build diagnostic                                                   | `model.invalid-directive`                                                                                                                                           |
-
-Foreign model invocation failures still report `model.failed`; this distinguishes them from Harness validation failures.
-
-## Zod-only tool schemas
-
-Harness `0.5.0-beta.1` accepts synchronous `z.object(...)` schemas only. Import `z` from `zod`; Harness does not re-export it. `tool()` validates and converts the schema to immutable JSON Schema when the definition is created; raw object literals are prepared on their first declaration.
-
-## Manifest
-
-`agent.manifest` is a frozen description of the sealed onion, the optional default model directive, and adapters (`id` plus an optional `maxConcurrentCalls`). It has no session configuration state. Observe `model.requested` for the per-call, JSON-safe attributed assembly; executable tool validators are omitted.
-
-The package intentionally does not own persistence, restart recovery, credentials, transports, provider-specific wire conversion, background jobs, or detached Tool work.
+## Design boundaries
 
-## Internals
+- **Capabilities** declare model-visible tools, instructions, context, and candidate review through
+  `.use()`.
+- **Services** are dependencies you construct and pass to capabilities, such as a store, MCP client,
+  or container runner.
+- **Host code** owns transport, persistence, credentials, and background work.
+- **Harness core** owns the loop, validation, scheduling, and recording invariants.
 
-The in-memory loop is **build → session → turn → step**. Start with [docs/loop.md](./docs/loop.md). The complete [error-code and observe-event reference](./docs/reference.md) documents the stable machine-readable surfaces.
+See [Examples](../examples/README.md) for complete agents and [CHANGELOG.md](./CHANGELOG.md) for
+release notes.

package/dist/build/agent.d.ts

@@ -1,19 +1,18 @@
 import type { AgentManifest } from "../types/manifest.js";
 import type { BoundMiddleware } from "../types/middleware.js";
-import type { ModelAdapter, ModelDirective } from "../types/model.js";
-import type { Session, SessionOptions } from "../types/session.js";
-import type { AdapterRegistry } from "./adapters.js";
+import type { ModelAdapter } from "../types/model.js";
+import type { Session, SessionRunOptions } from "../types/session.js";
 export interface LoopAgent {
     readonly middleware: readonly BoundMiddleware[];
     readonly invoke: ModelAdapter;
-    readonly directive?: ModelDirective;
-    readonly adapters: AdapterRegistry;
 }
 export declare class BuiltAgent {
     #private;
     readonly middleware: readonly BoundMiddleware[];
     readonly manifest: AgentManifest;
+    readonly id: string;
+    readonly name: string;
     private constructor();
-    run(options?: SessionOptions): Session;
+    run(options?: SessionRunOptions): Session;
 }
-export declare function bindAgent(middleware: readonly BoundMiddleware[], invoke: ModelAdapter, adapters: AdapterRegistry, manifest: AgentManifest, directive?: ModelDirective): BuiltAgent;
+export declare function bindAgent(middleware: readonly BoundMiddleware[], invoke: ModelAdapter, manifest: AgentManifest): BuiltAgent;

package/dist/build/agent.js

@@ -1,28 +1,37 @@
 import { LiveSession } from "../session/session.js";
 import { createId } from "../utils/ids.js";
+import { HarnessError } from "../errors.js";
 let createBoundAgent;
 export class BuiltAgent {
     middleware;
     manifest;
+    id;
+    name;
     #loopAgent;
-    constructor(middleware, invoke, adapters, manifest, directive) {
+    constructor(middleware, invoke, manifest) {
         this.middleware = middleware;
         this.manifest = manifest;
+        this.id = manifest.id;
+        this.name = manifest.name;
         this.#loopAgent = Object.freeze({
             middleware,
             invoke,
-            adapters,
-            ...(directive === undefined ? {} : { directive }),
         });
     }
     static {
-        createBoundAgent = (middleware, invoke, adapters, manifest, directive) => new BuiltAgent(middleware, invoke, adapters, manifest, directive);
+        createBoundAgent = (middleware, invoke, manifest) => new BuiltAgent(middleware, invoke, manifest);
     }
     run(options = {}) {
-        const id = options.id ?? createId("session");
+        const seeded = "seed" in options && options.seed !== undefined;
+        if (seeded &&
+            (("id" in options && options.id !== undefined) ||
+                ("userId" in options && options.userId !== undefined) ||
+                ("context" in options && options.context !== undefined)))
+            throw new HarnessError("session.invalid-seed", "Seeded run options cannot include id, userId, or context outside the seed");
+        const id = (seeded ? options.seed.id : "id" in options ? options.id : undefined) ?? createId("session");
         return new LiveSession(id, this.#loopAgent, options);
     }
 }
-export function bindAgent(middleware, invoke, adapters, manifest, directive) {
-    return createBoundAgent(middleware, invoke, adapters, manifest, directive);
+export function bindAgent(middleware, invoke, manifest) {
+    return createBoundAgent(middleware, invoke, manifest);
 }

package/dist/build/assemble.d.ts

@@ -1,9 +1,8 @@
 import type { BuildResult } from "../types/manifest.js";
 import type { BoundMiddleware } from "../types/middleware.js";
-import type { ModelAdapter, ModelDirective } from "../types/model.js";
-import type { ToolAdapter } from "../types/tool.js";
+import type { ModelAdapter } from "../types/model.js";
 import { type BuiltAgent } from "./agent.js";
-export declare function assembleAgent(middleware: readonly BoundMiddleware[], invoke: ModelAdapter, adapters: readonly {
-    readonly adapter: ToolAdapter;
-    readonly options?: import("../types/tool.js").AdapterExecutionOptions;
-}[], directive?: ModelDirective): BuildResult<BuiltAgent>;
+export declare function assembleAgent(middleware: readonly BoundMiddleware[], invoke: ModelAdapter, identity: Readonly<{
+    id: string;
+    name: string;
+}>): BuildResult<BuiltAgent>;

package/dist/build/assemble.js

@@ -1,50 +1,17 @@
-import { normalizeDirective } from "../model-normalize.js";
-import { isHarnessError } from "../errors.js";
 import { bindAgent } from "./agent.js";
-import { createAdapterRegistry } from "./adapters.js";
 import { createManifest } from "./manifest.js";
 const diagnostic = (code, message, extra = {}) => Object.freeze({ code, message, ...extra });
-export function assembleAgent(middleware, invoke, adapters, directive) {
+export function assembleAgent(middleware, invoke, identity) {
     const diagnostics = [];
-    const adapterIds = new Set();
-    const validAdapters = [];
-    for (const entry of adapters) {
-        const adapter = entry?.adapter;
-        const id = adapter?.id;
-        if (!id)
-            diagnostics.push(diagnostic("adapter.invalid-id", "Adapter id must not be empty"));
-        else if (adapterIds.has(id))
-            diagnostics.push(diagnostic("adapter.duplicate-id", `Duplicate adapter id '${id}'`));
-        else if (typeof adapter.execute !== "function")
-            diagnostics.push(diagnostic("adapter.invalid", `Adapter '${id}' must provide execute()`));
-        else {
-            const limit = entry.options?.maxConcurrentCalls;
-            if (limit !== undefined &&
-                (!Number.isSafeInteger(limit) || !Number.isFinite(limit) || limit < 1)) {
-                diagnostics.push(diagnostic("adapter.invalid-max-concurrent-calls", `Adapter '${id}' maxConcurrentCalls must be a positive safe integer`));
-                continue;
-            }
-            adapterIds.add(id);
-            validAdapters.push(Object.freeze({
-                adapter,
-                options: Object.freeze(limit === undefined ? {} : { maxConcurrentCalls: limit }),
-            }));
-        }
+    if (typeof identity.id !== "string" || identity.id.length === 0) {
+        diagnostics.push(diagnostic("agent.invalid-id", "Agent id must be a non-empty string"));
+    }
+    if (typeof identity.name !== "string" || identity.name.length === 0) {
+        diagnostics.push(diagnostic("agent.invalid-name", "Agent name must be a non-empty string"));
     }
     if (typeof invoke !== "function") {
         diagnostics.push(diagnostic("harness.invalid-model", "A model invoke function is required"));
     }
-    let frozenDirective;
-    if (directive !== undefined) {
-        const normalized = normalizeDirective(directive);
-        if (isHarnessError(normalized))
-            diagnostics.push(diagnostic(normalized.code, normalized.message, {
-                ...(Object.keys(normalized.details).length ? { details: normalized.details } : {}),
-                ...(normalized.cause === undefined ? {} : { cause: normalized.cause }),
-            }));
-        else
-            frozenDirective = normalized;
-    }
     const middlewareIds = new Set();
     const frozen = [];
     for (const item of middleware) {
@@ -59,18 +26,18 @@ export function assembleAgent(middleware, invoke, adapters, directive) {
             frozen.push(Object.freeze({
                 id: item.id,
                 handle: item.handle,
+                ...(item.state === undefined ? {} : { state: item.state }),
             }));
         }
     }
     if (diagnostics.length)
         return Object.freeze({ ok: false, diagnostics: Object.freeze(diagnostics) });
     const frozenMiddleware = Object.freeze(frozen);
-    const registry = createAdapterRegistry(Object.freeze(validAdapters));
     const manifest = createManifest({
+        id: identity.id,
+        name: identity.name,
         middleware: frozenMiddleware,
-        ...(frozenDirective === undefined ? {} : { directive: frozenDirective }),
-        adapters: registry,
     });
-    const agent = bindAgent(frozenMiddleware, invoke, registry, manifest, frozenDirective);
+    const agent = bindAgent(frozenMiddleware, invoke, manifest);
     return Object.freeze({ ok: true, agent, manifest });
 }

package/dist/build/bind-tool.d.ts

@@ -1,4 +1,3 @@
 import type { BoundToolDefinition, ToolDefinition } from "../types/tool.js";
-import type { AdapterRegistry } from "./adapters.js";
-/** Binds one Tool definition against the Agent's adapter registry. */
-export declare function bindTool(item: ToolDefinition, adapters: AdapterRegistry): BoundToolDefinition;
+/** Prepares an executable Tool and records its middleware slot provenance. */
+export declare function bindTool(item: ToolDefinition, owner: BoundToolDefinition["owner"]): BoundToolDefinition;

package/dist/build/bind-tool.js

@@ -1,15 +1,17 @@
 import { HarnessError } from "../errors.js";
 import { normalizedSchemaFor } from "./schema.js";
-/** Binds one Tool definition against the Agent's adapter registry. */
-export function bindTool(item, adapters) {
+/** Prepares an executable Tool and records its middleware slot provenance. */
+export function bindTool(item, owner) {
     if (!item.name)
         throw new HarnessError("tool.invalid-name", "Tool name must not be empty");
-    adapters.require(item.executeWith);
+    if (typeof item.execute !== "function")
+        throw new HarnessError("tool.invalid", `Tool '${item.name}' must provide execute()`);
     const parameters = normalizedSchemaFor(item);
     return Object.freeze({
         name: item.name,
         ...(item.description ? { description: item.description } : {}),
         parameters: parameters,
-        executeWith: item.executeWith,
+        execute: item.execute.bind(item),
+        owner: Object.freeze({ ...owner }),
     });
 }

package/dist/build/builder.d.ts

@@ -1,9 +1,24 @@
-import type { StepMiddleware } from "../types/middleware.js";
-import type { ModelAdapter, ModelDirective } from "../types/model.js";
+import type { BoundMiddleware, CapabilityDeclaration, StepMiddleware } from "../types/middleware.js";
+import type { ModelAdapter } from "../types/model.js";
 import type { BuildDiagnostic } from "../types/shared.js";
-import type { AdapterExecutionOptions, ToolAdapter } from "../types/tool.js";
 import { HarnessError } from "../errors.js";
 import type { BuiltAgent } from "./agent.js";
+export interface AgentOptions {
+    readonly id: string;
+    readonly name: string;
+    readonly instructions?: string | readonly string[];
+}
+interface BuilderState {
+    readonly id: string;
+    readonly name: string;
+    readonly middleware: BoundMiddleware[];
+    invoke?: ModelAdapter;
+    bound: boolean;
+    sealed: boolean;
+    agent?: BuiltAgent;
+    error?: AgentBuildError;
+    middlewareSeq: number;
+}
 export declare class AgentBuildError extends HarnessError {
     readonly diagnostics: readonly BuildDiagnostic[];
     constructor(diagnostics: readonly BuildDiagnostic[]);
@@ -11,21 +26,21 @@ export declare class AgentBuildError extends HarnessError {
 export declare class AgentLifecycleError extends HarnessError {
     constructor(message: string);
 }
-export declare function Agent(model: ModelAdapter, directive?: ModelDirective): AgentBuilder;
+export declare function Agent(options: AgentOptions): AgentBuilder;
 export declare class AgentBuilder {
-    private readonly invoke;
-    private readonly directive?;
-    private readonly middleware;
-    private readonly adapters;
-    private sealed;
-    private agent?;
-    private error?;
-    private middlewareSeq;
-    constructor(invoke: ModelAdapter, directive?: ModelDirective | undefined);
-    with(adapter: ToolAdapter, options?: AdapterExecutionOptions): this;
+    private readonly state;
+    constructor(state: BuilderState);
     use(middleware: StepMiddleware): this;
     use(id: string, middleware: StepMiddleware): this;
-    build(): BuiltAgent;
+    use<State>(declaration: CapabilityDeclaration<State>): this;
+    with(onModelCall: ModelAdapter): BoundAgentBuilder;
     private nextMiddlewareId;
     private push;
+    private assertOpen;
+}
+export declare class BoundAgentBuilder {
+    private readonly state;
+    constructor(state: BuilderState);
+    build(): BuiltAgent;
 }
+export {};

package/dist/build/builder.js

@@ -14,61 +14,112 @@ export class AgentLifecycleError extends HarnessError {
         this.name = "AgentLifecycleError";
     }
 }
-export function Agent(model, directive) {
-    return new AgentBuilder(model, directive);
+export function Agent(options) {
+    return new AgentBuilder(createState(options));
 }
 export class AgentBuilder {
-    invoke;
-    directive;
-    middleware = [];
-    adapters = [];
-    sealed = false;
-    agent;
-    error;
-    middlewareSeq = 0;
-    constructor(invoke, directive) {
-        this.invoke = invoke;
-        this.directive = directive;
-    }
-    with(adapter, options) {
-        if (this.sealed)
-            throw new AgentLifecycleError("AgentBuilder cannot be changed after build()");
-        this.adapters.push({ adapter, ...(options === undefined ? {} : { options }) });
-        return this;
+    state;
+    constructor(state) {
+        this.state = state;
     }
     use(idOrMiddleware, middleware) {
         if (typeof idOrMiddleware === "function") {
             return this.push({ id: this.nextMiddlewareId(), handle: idOrMiddleware });
         }
+        if (typeof idOrMiddleware === "object")
+            return this.push(compileDeclaration(idOrMiddleware));
         return this.push({ id: idOrMiddleware, handle: middleware });
     }
-    build() {
-        if (this.agent)
-            return this.agent;
-        if (this.error)
-            throw this.error;
-        this.sealed = true;
-        const result = assembleAgent(this.middleware, this.invoke, this.adapters, this.directive);
-        if (!result.ok) {
-            this.error = new AgentBuildError(result.diagnostics);
-            throw this.error;
-        }
-        this.agent = result.agent;
-        return this.agent;
+    with(onModelCall) {
+        this.assertOpen("with()");
+        this.state.bound = true;
+        this.state.invoke = onModelCall;
+        return new BoundAgentBuilder(this.state);
     }
     nextMiddlewareId() {
-        const taken = new Set(this.middleware.map((item) => item.id));
+        const taken = new Set(this.state.middleware.map((item) => item.id));
         let id;
         do {
-            this.middlewareSeq += 1;
-            id = `middleware-${this.middlewareSeq}`;
+            this.state.middlewareSeq += 1;
+            id = `middleware-${this.state.middlewareSeq}`;
         } while (taken.has(id));
         return id;
     }
     push(entry) {
-        if (this.sealed)
-            throw new AgentLifecycleError("AgentBuilder cannot be changed after build()");
-        this.middleware.push(entry);
+        this.assertOpen("build()");
+        this.state.middleware.push(entry);
         return this;
     }
+    assertOpen(after) {
+        if (this.state.bound)
+            throw new AgentLifecycleError("AgentBuilder cannot be changed after with()");
+        if (this.state.sealed)
+            throw new AgentLifecycleError(`AgentBuilder cannot be changed after ${after}`);
+    }
+}
+export class BoundAgentBuilder {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    build() {
+        if (this.state.agent)
+            return this.state.agent;
+        if (this.state.error)
+            throw this.state.error;
+        this.state.sealed = true;
+        const result = assembleAgent(this.state.middleware, this.state.invoke, {
+            id: this.state.id,
+            name: this.state.name,
+        });
+        if (!result.ok) {
+            this.state.error = new AgentBuildError(result.diagnostics);
+            throw this.state.error;
+        }
+        this.state.agent = result.agent;
+        return this.state.agent;
+    }
+}
+function createState(options) {
+    const middleware = [];
+    if (options.instructions !== undefined) {
+        const instructions = typeof options.instructions === "string" ? [options.instructions] : options.instructions;
+        middleware.push(compileDeclaration({ id: "agent", instructions }));
+    }
+    return {
+        id: options.id,
+        name: options.name,
+        middleware,
+        bound: false,
+        sealed: false,
+        middlewareSeq: 0,
+    };
+}
+function compileDeclaration(declaration) {
+    const tools = copyItems(declaration.tools, declaration.id);
+    const instructions = copyItems(declaration.instructions, declaration.id);
+    const model = declaration.model;
+    const handle = async (request, next) => {
+        if (tools)
+            request.configuration.tools.set(tools.slot, tools.items);
+        if (instructions)
+            request.configuration.instructions.set(instructions.slot, instructions.items);
+        if (model)
+            request.configuration.model.select(model);
+        return declaration.middleware ? declaration.middleware(request, next) : next();
+    };
+    return {
+        id: declaration.id,
+        handle,
+        ...(declaration.state === undefined
+            ? {}
+            : { state: declaration.state }),
+    };
+}
+function copyItems(value, defaultSlot) {
+    if (value === undefined)
+        return undefined;
+    if (!("items" in value))
+        return Object.freeze({ slot: defaultSlot, items: Object.freeze([...value]) });
+    return Object.freeze({ slot: value.slot, items: Object.freeze([...value.items]) });
 }