@nylorun/harness 0.11.1-beta → 0.13.0-beta

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.13.0-beta
+
+### Minor Changes
+
+- Breaking beta: replace `AgentManifest.middleware` with a capability catalog. The published
+  snapshot is `id`, `name`, optional `outputSchema`, and `capabilities` (`kind`,
+  `hasMiddleware`, declared instructions / tool JSON schemas / model controls). Join traces by
+  capability id. `MiddlewareManifest` is removed; import `CapabilityManifest`.
+- Breaking beta: expose `BuiltAgent` as a type-only facade from `Agent(...).use(...).build()`.
+  Hide compiled middleware, tool registries, and output validators. `AgentBuilder` accepts public
+  agent options. `createExecutionState` requires the original built agent. Drop agent-level
+  `executionVersion`; `ExecutionState.version` stays `1` and leftover keys are ignored. Model
+  adapters receive immutable `ToolDescriptor` metadata only. Remove `defineToolFamily` /
+  `ToolFamily` / `capability.toolFamilies` and the internal Bound\* / `SealedToolCall` root
+  exports. Rename the per-run bag from `scope` to `info`.
+- c5bbb1a: Breaking beta: make Harness `run()` a direct async state-in/state-out executor with
+  serializable pauses, application `info`, cancellation signals, awaited recording, and
+  agent-level output schemas. Runtime owns session scheduling with memory-default or exclusive
+  local storage and imports Harness contracts. Isolate Node adapters under `runtime/node`, stream
+  observations incrementally, and add opt-in bounded token previews with Studio reconciliation.
+  Migrate consumers and deployment guidance together; legacy event records remain archived, not
+  automatically replayed.
+
+## 0.12.0-beta
+
+### Minor Changes
+
+- 4badb5b: Move model execution to session startup, provide Runtime as a mountable Hono router, and generate Hono-first projects with supervised application and Studio development. Studio now resolves root-relative Runtime endpoints correctly for custom mount paths.
+
 ## 0.11.1-beta
 
 ### Patch Changes

package/README.md

@@ -1,10 +1,129 @@
 # `@nylorun/harness`
 
-Nylorun's TypeScript agent runtime.
+Observable, portable, composable agent execution. Harness runs a model/tool loop with invocation-local progress; an application or optional Runtime owns sessions.
 
-For installation, examples, API details, and release notes, see the
-[Nylorun Harness repository](https://github.com/nylorun/harness).
+> **Breaking beta:** this interface replaces the Session-returning `run()` API. See [migration](../MIGRATION.md).
 
-> **Experimental beta.** Install with `npm install @nylorun/harness@beta`.
+## Run an agent
 
-Repository development: [contributing](../CONTRIBUTING.md). Package publication: [releasing](../RELEASING.md).
+```ts
+import { Agent } from "@nylorun/harness";
+
+const agent = Agent({ id: "assistant", name: "Assistant" }).build();
+const result = await agent.run({
+  input: "Hello",
+  onModelCall: async (call) => "Hello back!", // Your model adapter
+});
+if (result.status === "completed") console.log(result.output);
+
+const next = await agent.run({
+  state: result.state,
+  input: "Continue our conversation",
+  onModelCall,
+});
+```
+
+Every call returns a Promise. Omitted state starts an empty execution. The built agent retains definitions, not progress; supplied state is never mutated. Multiple calls may use the same agent concurrently. Applications must coordinate concurrent updates to the same conversation.
+
+Outcomes are `completed` (with `output`), `paused` (with `pending`), `cancelled`, or `failed` (with `error`). Each includes serializable `state`. Invalid options, incompatible state, and invalid continuation inputs reject before model/tool execution. Operational failures return `failed`. Recording failures reject.
+
+## Built agent interface
+
+`Agent(...).use(...).build()` returns a `BuiltAgent<Info, Output>`. Import `BuiltAgent` with `import type`; it has no runtime constructor or `instanceof` check. Its public members are `id`, `name`, `manifest`, and `run`. The manifest is a frozen capability catalog (`id`, `name`, optional `outputSchema`, and `capabilities`); compiled middleware, the tool registry, and output validators remain internal. Correlate traces by `event.middlewareId` / `ToolReference.capabilityId` to `manifest.capabilities[].id`.
+
+`createExecutionState(agent)` requires the original built agent so it can include the configured output contract. Adding application-owned methods such as `close()` with `Object.assign(agent, { close })` preserves this identity. If you wrap or copy an agent, initialize state using the original agent. State remains serializable and inspectable.
+
+Model adapters receive immutable `ToolDescriptor` values in `context.request.tools` and `context.request.configuration.tools`. Descriptors preserve `name`, optional `description`, `owner`, `inputSchema.jsonSchema`, and optional `outputSchema.jsonSchema`. They contain no executable tool, original definition, or validator. Implement tools through registered capabilities; adapters return tool-call candidates for Harness to validate and dispatch.
+
+## Optional controls
+
+```ts
+const result = await agent.run({
+  state,
+  input,
+  onModelCall,
+  info: { userId, tenantId },
+  signal: controller.signal,
+  onEvent: (event) => console.log(event),
+  record: (state) => sessionStore.save(sessionId, state),
+});
+```
+
+`info` is extra application data available as `request.info` in middleware and `context.info` in tools. Type it with `Agent<MyInfo>(...)`. Harness does not put info into state, observations, or model requests. Middleware can deliberately add model-visible data through its existing `request.context` interface. The application owns authentication and authorization, including checking access to the original resource after continuation.
+
+`signal` is cooperative: Harness checks before further work, forwards it to adapters and tools, and waits for dispatched work to settle. Cancellation preserves settled results, cannot undo external effects, and cannot forcibly stop an uncooperative dependency. Harness has no cancellation or shutdown method. The developer owns clients, connections, subprocesses, and their cleanup.
+
+To cancel a saved pause, call `run({ state, input: { kind: "continue" }, signal: AbortSignal.abort(), onModelCall })`. This settles the pending plan without dispatching it. `state.cancelledCalls` retains unresolved invocation references and deferred tokens for reconciliation, outside the model transcript; cancelling a deferred job does not stop external work by itself. Runtime's `host.cancel(agent, sessionId)` applies this transition and persists it before accepting replacement work.
+
+`onEvent` reports ordered events with execution, run, turn, step, model invocation, and tool call identifiers where applicable. Observer exceptions produce `observation.failed` diagnostics without changing results. Observations describe execution; they do not acknowledge durable commits. Explicit model-visible content and tool output can appear in events, so applications still control sensitive data they put there.
+
+`record` receives independent immutable JSON snapshots, serially. Harness awaits each recording barrier: accepted plans after middleware unwinds and before dispatch, active work markers, settled tool batches, pauses, and final outcomes. A rejected recording stops further dispatch; active work has settled before rejection. An external operation may succeed before a write fails. An intermediate active snapshot requires reconciliation and never authorizes automatic replay.
+
+## Final output contracts
+
+```ts
+import { z } from "zod";
+const agent = Agent({
+  id: "extractor",
+  name: "Extractor",
+  outputSchema: z.object({ answer: z.string() }),
+}).build();
+// A completed result.output is inferred as { answer: string }.
+```
+
+The schema belongs to the agent definition, is supplied to adapters, and validates the accepted final response after middleware. Adapters return a JSON output block for structured results. There is no per-run or per-turn schema override. Tool output schemas remain tool-specific. With an explicitly typed info bag and output schema, use `Agent<MyInfo, typeof schema>({...})`.
+
+## Register and expose tools
+
+```ts
+const lookup = {
+  name: "lookup",
+  inputSchema: z.object({ id: z.string() }),
+  execute: async ({ id }, { info, signal }) => ({
+    kind: "completed" as const,
+    output: await database.lookup(id, { info, signal }),
+  }),
+};
+const agent = Agent({ id: "assistant", name: "Assistant" })
+  .use({ id: "database", tools: [lookup] })
+  .build();
+```
+
+`.use()` registers code. Middleware selects registered tools through `request.configuration.tools.set(slot, tools)`. Changing the subset needs no restoration callback. Unregistered executable closures are rejected before a model call. Middleware wrapping order is preserved; tool plans are accepted only after the stack unwinds.
+
+When identity depends on discovered data, keep one registered tool and put that data in the arguments (or authorize it from `info`):
+
+```ts
+const queryTable = {
+  name: "query_table",
+  inputSchema: z.object({ table: z.string(), query: z.string() }),
+  execute: async ({ table, query }, { info, signal }) => ({
+    kind: "completed" as const,
+    output: await warehouse.query({ table, query, principal: info, signal }),
+  }),
+};
+```
+
+## Pause and continue
+
+An approval or response request, or a tool returning `{ kind: "deferred", token }`, settles the invocation as `paused`. Persist the returned state intact. Rebuild the same agent definition and call `run()` again:
+
+```ts
+await agent.run({
+  state: savedState,
+  input: { kind: "approve", interactionId, approved: true },
+  info: freshApplicationInfo,
+  onModelCall,
+});
+// A response uses { kind: "respond", interactionId, value }.
+// A deferred settlement uses { kind: "settle", invocationId, outcome:
+//   { kind: "completed", output: jobResult } }.
+```
+
+Registered tools restore by name from the rebuilt definition. Accepted descriptors, arguments, ordering, decisions, and invocation IDs survive; settled tools and middleware are not rerun for restoration. An execute-time interaction may re-enter that tool with `context.resume`; use its saved token to continue, not repeat prior effects.
+
+`createExecutionState(agent)` and `validateExecutionState(value)` help initialize and validate state. Applications should not hand-author pending plans. State is a trusted continuation record, not an authorization credential; never accept client-controlled state without validation and access control.
+
+Missing definitions, changed contracts or bindings, and duplicate/mismatched continuation inputs reject. Family versions must change for incompatible implementations. Schema comparisons cannot detect arbitrary behavior changes inside JavaScript functions. Hosts own agent generation, drain of old definitions, and any migrate-in-place of saved state.
+
+Completed turns and explicit pauses can continue in a new process. Automatic crash replay and deferred model continuation are not supported. One-shot child work is `await child.run(...)`; separately addressable child sessions belong to a host.

package/dist/definition/agent-definition.d.ts

@@ -0,0 +1,11 @@
+import type { BoundMiddleware } from "./bound.js";
+import type { ToolRegistry } from "./registry.js";
+import type { TurnOutputContract } from "./output-contract.js";
+export interface AgentDefinition {
+    readonly id: string;
+    readonly middleware: readonly BoundMiddleware[];
+    readonly registry: ToolRegistry;
+    readonly output?: TurnOutputContract;
+}
+export declare function registerDefinition(agent: object, definition: AgentDefinition): void;
+export declare function definitionFor(agent: object): AgentDefinition;

package/dist/definition/agent-definition.js

@@ -0,0 +1,12 @@
+import { HarnessError } from "../errors.js";
+// Definition lookup only; execution progress is never retained here.
+const definitions = new WeakMap();
+export function registerDefinition(agent, definition) {
+    definitions.set(agent, definition);
+}
+export function definitionFor(agent) {
+    const definition = definitions.get(agent);
+    if (!definition)
+        throw new HarnessError("execution.invalid-input", "createExecutionState() requires the original agent returned by Agent(...).build(); initialize wrapper state with that original agent.");
+    return definition;
+}

package/dist/definition/assemble.d.ts

@@ -0,0 +1,22 @@
+import type { BoundMiddleware } from "./bound.js";
+import type { BuiltAgent } from "../types/agent.js";
+import type { AgentManifest } from "../types/manifest.js";
+import type { BuildDiagnostic } from "../types/shared.js";
+import type { RunOptions, RunResult } from "../types/execution.js";
+import type { ToolSchemaSource } from "../types/tool.js";
+import type { AgentDefinition } from "./agent-definition.js";
+type BuildResult<Agent> = {
+    readonly ok: true;
+    readonly agent: Agent;
+    readonly manifest: AgentManifest;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly BuildDiagnostic[];
+};
+type AgentRun = (definition: AgentDefinition, options: RunOptions<any>) => Promise<RunResult<any>>;
+export declare function assembleAgent(middleware: readonly BoundMiddleware[], identity: Readonly<{
+    id: string;
+    name: string;
+    outputSchema?: ToolSchemaSource;
+}>, run: AgentRun): BuildResult<BuiltAgent>;
+export {};

package/dist/{build → definition}/assemble.js

@@ -1,7 +1,7 @@
-import { bindAgent } from "./agent.js";
+import { bindAgent } from "./bind-agent.js";
 import { createManifest } from "./manifest.js";
 const diagnostic = (code, message, extra = {}) => Object.freeze({ code, message, ...extra });
-export function assembleAgent(middleware, invoke, identity) {
+export function assembleAgent(middleware, identity, run) {
     const diagnostics = [];
     if (typeof identity.id !== "string" || identity.id.length === 0) {
         diagnostics.push(diagnostic("agent.invalid-id", "Agent id must be a non-empty string"));
@@ -9,9 +9,6 @@ export function assembleAgent(middleware, invoke, identity) {
     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"));
-    }
     const middlewareIds = new Set();
     const frozen = [];
     for (const item of middleware) {
@@ -26,7 +23,8 @@ export function assembleAgent(middleware, invoke, identity) {
             frozen.push(Object.freeze({
                 id: item.id,
                 handle: item.handle,
-                ...(item.state === undefined ? {} : { state: item.state }),
+                hasMiddleware: item.hasMiddleware,
+                ...(item.tools === undefined ? {} : { tools: item.tools }),
                 ...(item.contributions === undefined ? {} : { contributions: item.contributions }),
             }));
         }
@@ -37,8 +35,9 @@ export function assembleAgent(middleware, invoke, identity) {
     const manifest = createManifest({
         id: identity.id,
         name: identity.name,
+        outputSchema: identity.outputSchema,
         middleware: frozenMiddleware,
     });
-    const agent = bindAgent(frozenMiddleware, invoke, manifest);
+    const agent = bindAgent(frozenMiddleware, manifest, identity, run);
     return Object.freeze({ ok: true, agent, manifest });
 }

package/dist/definition/bind-agent.d.ts

@@ -0,0 +1,9 @@
+import type { AgentManifest } from "../types/manifest.js";
+import type { BoundMiddleware } from "./bound.js";
+import type { BuiltAgent } from "../types/agent.js";
+import type { RunOptions, RunResult } from "../types/execution.js";
+import type { ToolSchemaSource } from "../types/tool.js";
+import { type AgentDefinition } from "./agent-definition.js";
+export declare function bindAgent(middleware: readonly BoundMiddleware[], manifest: AgentManifest, options: {
+    outputSchema?: ToolSchemaSource;
+} | undefined, run: (definition: AgentDefinition, options: RunOptions<any>) => Promise<RunResult<any>>): BuiltAgent;

package/dist/definition/bind-agent.js

@@ -0,0 +1,21 @@
+import { bindOutputContract } from "./output-contract.js";
+import { registerDefinition } from "./agent-definition.js";
+import { ToolRegistry } from "./registry.js";
+export function bindAgent(middleware, manifest, options = {}, run) {
+    const definition = Object.freeze({
+        id: manifest.id,
+        middleware,
+        registry: new ToolRegistry(middleware),
+        ...(options.outputSchema === undefined
+            ? {}
+            : { output: bindOutputContract(options.outputSchema) }),
+    });
+    const agent = {
+        id: definition.id,
+        name: manifest.name,
+        manifest,
+        run: (options) => run(definition, options),
+    };
+    registerDefinition(agent, definition);
+    return agent;
+}

package/dist/{build → definition}/bind-tool.d.ts

@@ -1,3 +1,4 @@
-import type { BoundToolDefinition, ToolDefinition } from "../types/tool.js";
+import type { BoundToolDefinition } from "./bound.js";
+import type { ToolDefinition } from "../types/tool.js";
 /** Prepares an executable Tool and records its middleware slot provenance. */
 export declare function bindTool(item: ToolDefinition, owner: BoundToolDefinition["owner"]): BoundToolDefinition;

package/dist/{build → definition}/bind-tool.js

@@ -8,6 +8,7 @@ export function bindTool(item, owner) {
         throw new HarnessError("tool.invalid", `Tool '${item.name}' must provide execute()`);
     const schemas = normalizedSchemasFor(item);
     return Object.freeze({
+        source: item,
         name: item.name,
         ...(item.description ? { description: item.description } : {}),
         inputSchema: schemas.inputSchema,

package/dist/definition/bound.d.ts

@@ -0,0 +1,16 @@
+import type { MiddlewareContributions, StepMiddleware } from "../types/middleware.js";
+import type { ToolDefinition, ToolExecutionContext, ToolInputSchema, ToolOutcome, ToolOutputSchema, ToolOwner, ToolSchema } from "../types/tool.js";
+export interface BoundToolDefinition<Info = unknown> extends Omit<ToolDefinition<ToolInputSchema, Info, ToolOutputSchema | undefined>, "inputSchema" | "outputSchema" | "execute"> {
+    readonly inputSchema: ToolSchema<unknown>;
+    readonly outputSchema?: ToolSchema<unknown>;
+    readonly execute: (args: unknown, context: ToolExecutionContext<Info>) => Promise<ToolOutcome>;
+    readonly owner: ToolOwner;
+    readonly source: ToolDefinition<any, any, any>;
+}
+export interface BoundMiddleware {
+    readonly id: string;
+    readonly handle: StepMiddleware;
+    readonly hasMiddleware: boolean;
+    readonly tools?: readonly ToolDefinition<any, any, any>[];
+    readonly contributions?: MiddlewareContributions;
+}

package/dist/definition/builder.d.ts

@@ -0,0 +1,30 @@
+import type { CapabilityDeclaration, StepMiddleware } from "../types/middleware.js";
+import type { BuildDiagnostic } from "../types/shared.js";
+import { HarnessError } from "../errors.js";
+import type { ToolSchemaSource, SchemaOutput } from "../types/tool.js";
+import type { BuiltAgent } from "../types/agent.js";
+export interface AgentOptions<Schema extends ToolSchemaSource | undefined = undefined> {
+    readonly outputSchema?: Schema;
+    readonly id: string;
+    readonly name: string;
+    readonly instructions?: string | readonly string[];
+}
+export declare class AgentBuildError extends HarnessError {
+    readonly diagnostics: readonly BuildDiagnostic[];
+    constructor(diagnostics: readonly BuildDiagnostic[]);
+}
+export declare class AgentLifecycleError extends HarnessError {
+    constructor(message: string);
+}
+export declare function Agent<Info = unknown, Schema extends ToolSchemaSource | undefined = undefined>(options: AgentOptions<Schema>): AgentBuilder<Info, Schema>;
+export declare class AgentBuilder<Info = unknown, Schema extends ToolSchemaSource | undefined = undefined> {
+    #private;
+    constructor(options: AgentOptions<Schema>);
+    use(middleware: StepMiddleware<Info>): this;
+    use(id: string, middleware: StepMiddleware<Info>): this;
+    use(declaration: CapabilityDeclaration<Info>): this;
+    build(): BuiltAgent<Info, Schema extends ToolSchemaSource ? SchemaOutput<Schema> : string>;
+    private nextMiddlewareId;
+    private push;
+    private assertOpen;
+}

package/dist/definition/builder.js

@@ -0,0 +1,94 @@
+import { HarnessError } from "../errors.js";
+import { execute } from "../execution/run.js";
+import { assembleAgent } from "./assemble.js";
+import { compileDeclaration } from "./declaration.js";
+export class AgentBuildError extends HarnessError {
+    diagnostics;
+    constructor(diagnostics) {
+        super("agent.build-failed", diagnostics.map((item) => item.message).join("; ") || "Agent build failed");
+        this.diagnostics = diagnostics;
+        this.name = "AgentBuildError";
+    }
+}
+export class AgentLifecycleError extends HarnessError {
+    constructor(message) {
+        super("agent.lifecycle-sealed", message);
+        this.name = "AgentLifecycleError";
+    }
+}
+export function Agent(options) {
+    return new AgentBuilder(options);
+}
+export class AgentBuilder {
+    #state;
+    constructor(options) {
+        this.#state = createState(options);
+    }
+    use(idOrMiddleware, middleware) {
+        if (typeof idOrMiddleware === "function") {
+            return this.push({
+                id: this.nextMiddlewareId(),
+                handle: idOrMiddleware,
+                hasMiddleware: true,
+            });
+        }
+        if (typeof idOrMiddleware === "object")
+            return this.push(compileDeclaration(idOrMiddleware));
+        return this.push({
+            id: idOrMiddleware,
+            handle: middleware,
+            hasMiddleware: true,
+        });
+    }
+    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, {
+            id: this.#state.id,
+            name: this.#state.name,
+            outputSchema: this.#state.outputSchema,
+        }, execute);
+        if (!result.ok) {
+            this.#state.error = new AgentBuildError(result.diagnostics);
+            throw this.#state.error;
+        }
+        this.#state.agent = result.agent;
+        return this.#state.agent;
+    }
+    nextMiddlewareId() {
+        const taken = new Set(this.#state.middleware.map((item) => item.id));
+        let id;
+        do {
+            this.#state.middlewareSeq += 1;
+            id = `middleware-${this.#state.middlewareSeq}`;
+        } while (taken.has(id));
+        return id;
+    }
+    push(entry) {
+        this.assertOpen();
+        this.#state.middleware.push(entry);
+        return this;
+    }
+    assertOpen() {
+        if (this.#state.sealed)
+            throw new AgentLifecycleError("AgentBuilder cannot be changed after build()");
+    }
+}
+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,
+        outputSchema: options.outputSchema,
+        name: options.name,
+        middleware,
+        sealed: false,
+        middlewareSeq: 0,
+    };
+}

package/dist/definition/declaration.d.ts

@@ -0,0 +1,3 @@
+import type { BoundMiddleware } from "./bound.js";
+import type { CapabilityDeclaration } from "../types/middleware.js";
+export declare function compileDeclaration<State>(declaration: CapabilityDeclaration<State>): BoundMiddleware;

package/dist/definition/declaration.js

@@ -0,0 +1,53 @@
+export function compileDeclaration(declaration) {
+    const tools = copyItems(declaration.tools, declaration.id);
+    const instructions = copyItems(declaration.instructions, declaration.id);
+    const model = declaration.model;
+    const contributions = snapshotContributions(instructions?.items, tools?.items, 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,
+        hasMiddleware: declaration.middleware !== undefined,
+        tools: tools?.items,
+        ...(contributions === undefined ? {} : { contributions }),
+    };
+}
+function snapshotContributions(instructions, tools, model) {
+    const snapInstructions = instructions === undefined ? undefined : Object.freeze([...instructions]);
+    const snapTools = tools === undefined
+        ? undefined
+        : Object.freeze(tools.map((tool) => Object.freeze({
+            name: tool.name,
+            ...(tool.description === undefined ? {} : { description: tool.description }),
+        })));
+    const snapModel = model === undefined ? undefined : snapshotModel(model);
+    if (snapInstructions === undefined && snapTools === undefined && snapModel === undefined) {
+        return undefined;
+    }
+    return Object.freeze({
+        ...(snapInstructions === undefined ? {} : { instructions: snapInstructions }),
+        ...(snapTools === undefined ? {} : { tools: snapTools }),
+        ...(snapModel === undefined ? {} : { model: snapModel }),
+    });
+}
+function snapshotModel(model) {
+    return Object.freeze({
+        ...(model.id === undefined ? {} : { id: model.id }),
+        ...(model.controls === undefined ? {} : { controls: Object.freeze({ ...model.controls }) }),
+    });
+}
+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]) });
+}

package/dist/{build → definition}/helpers.d.ts

@@ -1,6 +1,6 @@
 import type { ModelAdapter } from "../types/model.js";
 import type { StepMiddleware } from "../types/middleware.js";
 import type { ToolDefinition, ToolInputSchema, ToolOutputSchema } from "../types/tool.js";
-export declare const tool: <InputSchema extends ToolInputSchema, State = never, OutputSchema extends ToolOutputSchema | undefined = undefined>(value: ToolDefinition<InputSchema, State, OutputSchema>) => ToolDefinition<InputSchema, State, OutputSchema>;
+export declare const tool: <InputSchema extends ToolInputSchema, Info = unknown, OutputSchema extends ToolOutputSchema | undefined = undefined>(value: ToolDefinition<InputSchema, Info, OutputSchema>) => ToolDefinition<InputSchema, Info, OutputSchema>;
 export declare const model: <T extends ModelAdapter>(value: T) => T;
 export declare const middleware: <T extends StepMiddleware>(value: T) => T;

package/dist/{build → definition}/manifest.d.ts

@@ -1,7 +1,9 @@
+import type { BoundMiddleware } from "./bound.js";
 import type { AgentManifest } from "../types/manifest.js";
-import type { BoundMiddleware } from "../types/middleware.js";
+import type { ToolSchemaSource } from "../types/tool.js";
 export declare function createManifest(input: {
     id: string;
     name: string;
+    outputSchema?: ToolSchemaSource;
     middleware: readonly BoundMiddleware[];
 }): AgentManifest;

package/dist/definition/manifest.js

@@ -0,0 +1,45 @@
+import { bindOutputContract } from "./output-contract.js";
+import { normalizedSchemasFor } from "./schema.js";
+import { deepFreeze } from "../utils/immutable.js";
+export function createManifest(input) {
+    const capabilities = input.middleware.map((item) => projectCapability(item));
+    return deepFreeze({
+        id: input.id,
+        name: input.name,
+        ...(input.outputSchema === undefined
+            ? {}
+            : { outputSchema: bindOutputContract(input.outputSchema).schema.jsonSchema }),
+        capabilities,
+    });
+}
+function projectCapability(item) {
+    const contributions = item.contributions;
+    return {
+        id: item.id,
+        kind: capabilityKind(item),
+        hasMiddleware: item.hasMiddleware,
+        ...(contributions?.instructions === undefined
+            ? {}
+            : { instructions: contributions.instructions }),
+        ...(item.tools === undefined ? {} : { tools: item.tools.map((tool) => projectTool(tool)) }),
+        ...(contributions?.model === undefined ? {} : { model: contributions.model }),
+    };
+}
+function capabilityKind(item) {
+    if (item.id === "agent")
+        return "agent";
+    if (item.contributions !== undefined)
+        return "capability";
+    return "middleware";
+}
+function projectTool(tool) {
+    const schemas = normalizedSchemasFor(tool);
+    return {
+        name: tool.name,
+        ...(tool.description === undefined ? {} : { description: tool.description }),
+        inputSchema: schemas.inputSchema.jsonSchema,
+        ...(schemas.outputSchema === undefined
+            ? {}
+            : { outputSchema: schemas.outputSchema.jsonSchema }),
+    };
+}

package/dist/{session → definition}/output-contract.d.ts

@@ -1,6 +1,6 @@
-import type { BoundToolSchema, ToolSchemaSource } from "../types/tool.js";
+import type { ToolSchema, ToolSchemaSource } from "../types/tool.js";
 /** Runtime-only validator paired with the portable JSON Schema projected to models. */
 export interface TurnOutputContract {
-    readonly schema: BoundToolSchema<unknown>;
+    readonly schema: ToolSchema<unknown>;
 }
 export declare function bindOutputContract(source: ToolSchemaSource): TurnOutputContract;

package/dist/{session → definition}/output-contract.js

@@ -1,5 +1,5 @@
 import { HarnessError, isHarnessError } from "../errors.js";
-import { normalizeSchema } from "../build/schema.js";
+import { normalizeSchema } from "./schema.js";
 export function bindOutputContract(source) {
     try {
         return Object.freeze({ schema: normalizeSchema(source, "output") });

package/dist/definition/registry.d.ts

@@ -0,0 +1,10 @@
+import type { BoundMiddleware, BoundToolDefinition } from "./bound.js";
+import type { ToolReference } from "../types/execution.js";
+/** Definition-only lookup; no per-run selections or progress live here. */
+export declare class ToolRegistry {
+    private readonly tools;
+    private readonly owners;
+    constructor(middleware: readonly BoundMiddleware[]);
+    reference(tool: BoundToolDefinition): ToolReference;
+    restore(reference: ToolReference): BoundToolDefinition;
+}