@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/capabilities/invocation.js

@@ -1,28 +1,81 @@
+/**
+ * Execution of one host-selected synchronous invocation.
+ *
+ * An invocation is the smallest Core-owned unit of work: the App decides which handler to
+ * call and supplies payload and authorization facts, while this module runs the handler once,
+ * threads cancellation and diagnostics, and pairs an optional journal start with a receipt.
+ * Selection, authorization and retries stay outside.
+ *
+ * Exports: `executeInvocation` and the invocation contracts re-exported at the bottom.
+ */
 import { invocationId } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
 import { diagnosticError } from '../diagnostics/index.js';
 import { NodeReports } from '../execution/reporting.js';
-/** Execute a host-selected synchronous call. Selection, authorization facts and payload shape stay outside. */
+/**
+ * Run one synchronous invocation and record its effects.
+ *
+ * @param invocation Handler whose `call` performs the work; its `id` becomes the tool id in
+ *   diagnostics and journal records.
+ * @param input Payload handed to the handler unchanged.
+ * @param context App context passed to the ports below; it is never inspected here.
+ * @param ports Per-context callbacks for diagnostics, cancellation, journalling and receipt
+ *   capture. All are optional: without them the handler still runs, just unrecorded.
+ * @returns Nothing. The outcome is conveyed through the journal receipt, when one is bound.
+ * @throws TypeError when the handler identity is missing, or when the handler returns a
+ *   promise despite the synchronous contract.
+ * @throws Whatever the handler throws, unchanged, including the abort error raised by the
+ *   signal checks.
+ */
 export function executeInvocation(invocation, input, context, ports = {}) {
     const toolId = invocation.id;
+    // Identify the call before touching the ports: journal and diagnostics records cannot be
+    // reconciled with an anonymous handler.
     if (!toolId?.trim())
         throw new TypeError('Invalid invocation handler identity');
     const journal = ports.journal?.(context), id = invocationId(), startedAtMs = Date.now();
-    const diagnostics = ports.diagnostics?.(context)?.child(id, { invocationId: id, nodeRole: 'invocation', definitionKind: 'tool-invocation', definitionId: toolId, nodeId: toolId, nodeName: toolId, nodeKind: 'tool-invocation' });
-    const callId = journal?.beginTool({ toolId, input, invocation: { ...diagnostics?.identity, invocationId: id, startedAtMs } });
-    diagnostics?.emit('tool.call', () => ({ toolId, invocationId: id, ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}) }));
+    const diagnostics = ports.diagnostics?.(context)?.child(id, {
+        invocationId: id,
+        nodeRole: 'invocation',
+        definitionKind: 'tool-invocation',
+        definitionId: toolId,
+        nodeId: toolId,
+        nodeName: toolId,
+        nodeKind: 'tool-invocation',
+    });
+    const callId = journal?.beginTool({
+        toolId,
+        input,
+        invocation: { ...diagnostics?.identity, invocationId: id, startedAtMs },
+    });
+    diagnostics?.emit('tool.call', () => ({
+        toolId,
+        invocationId: id,
+        ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}),
+    }));
+    // Held outside the try block so the failure path can still tell cancellation from an error.
     let activeSignal;
     let reports;
     try {
         const checkpoint = ports.checkpoint?.(context);
-        const signal = activeSignal = ports.signal?.(context);
+        const signal = (activeSignal = ports.signal?.(context));
         signal?.throwIfAborted();
         reports = new NodeReports(diagnostics, signal, 'tool.result');
-        synchronous(invocation.call(input, context, { mode: 'sync', invocationId: id, signal: signal ?? new AbortController().signal, diagnostics,
-            report: reports.report.bind(reports), createSubFlowLogger: reports.createSubFlowLogger.bind(reports) }), 'Invocation handlers must be synchronous');
+        // The helper rejects a promise and drains its rejection: a handler that turns async must
+        // fail here instead of escaping as an unhandled rejection.
+        synchronous(invocation.call(input, context, {
+            mode: 'sync',
+            invocationId: id,
+            signal: signal ?? new AbortController().signal,
+            diagnostics,
+            report: reports.report.bind(reports),
+            createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
+        }), 'Invocation handlers must be synchronous');
         ports.signal?.(context)?.throwIfAborted();
         if (callId) {
             const receipt = ports.receipt?.(context, checkpoint);
+            // Cancellation may have arrived while the handler or receipt ran; a successful record
+            // must not be committed for a request the host has already abandoned.
             ports.signal?.(context)?.throwIfAborted();
             journal.finishTool({ invocationId: callId, status: 'success', value: receipt });
         }
@@ -31,15 +84,32 @@ export function executeInvocation(invocation, input, context, ports = {}) {
     }
     catch (error) {
         reports?.close();
-        diagnostics?.emit('tool.result', () => ({ toolId, invocationId: id, status: activeSignal?.aborted ? 'cancelled' : 'error', durationMs: Date.now() - startedAtMs, ...(diagnostics?.enabled('tool.result', 'content') ? { error: diagnosticError(error) } : {}) }), reports?.debug());
+        diagnostics?.emit('tool.result', () => ({
+            toolId,
+            invocationId: id,
+            status: activeSignal?.aborted ? 'cancelled' : 'error',
+            durationMs: Date.now() - startedAtMs,
+            ...(diagnostics?.enabled('tool.result', 'content')
+                ? { error: diagnosticError(error) }
+                : {}),
+        }), reports?.debug());
         try {
             if (callId)
-                journal.finishTool({ invocationId: callId, status: ports.signal?.(context)?.aborted ? 'cancelled' : 'error', value: ports.receiptError?.(error) });
+                journal.finishTool({
+                    invocationId: callId,
+                    // The signal, not the error shape, decides whether this counts as cancellation.
+                    status: ports.signal?.(context)?.aborted ? 'cancelled' : 'error',
+                    value: ports.receiptError?.(error),
+                });
+        }
+        catch {
+            /* Preserve the invocation failure if receipt recording also fails. */
         }
-        catch { /* Preserve the invocation failure if receipt recording also fails. */ }
         throw error;
     }
     finally {
+        // Closing is idempotent, so a port that throws on the success path still releases the
+        // reporting scope.
         reports?.close();
     }
 }

package/dist/esm/capabilities/model.d.ts

@@ -2,22 +2,89 @@ import type { ModelCapabilityRegistration, RegisteredModelCapability, ModelSelec
 export { modelProtocolError } from '../utils/model-protocol.js';
 /** A request/stage projection is a sealed registry. Hosts filter availability before projection. */
 export declare class ModelCapabilityRegistry {
+    /** Insertion-ordered entries; iteration order is the declaration order of the catalog. */
     private readonly definitionsById;
+    /** Sealing is one-way: stage-time code must never extend the catalog it is executing. */
     private sealed;
+    /**
+     * @param definitions Capabilities to register immediately, in iteration order.
+     * @throws TypeError when a definition is invalid or its id is duplicated (raised by
+     *   `register`).
+     */
     constructor(definitions?: Iterable<ModelCapabilityRegistration>);
+    /**
+     * Register one capability.
+     *
+     * @param capability Declaration with a non-empty unique id, non-empty description, an
+     *   object-rooted JSON schema and a resolver.
+     * @returns This registry, for chaining.
+     * @throws Error when the registry is already sealed.
+     * @throws TypeError when the declaration is invalid or its id is already registered.
+     */
     register<Result>(capability: ModelCapabilityRegistration<Result>): this;
+    /** Frozen snapshot of the registered definitions, in insertion order. */
     get definitions(): readonly Readonly<RegisteredModelCapability>[];
+    /** Registered ids in declaration order. */
     ids(): readonly string[];
+    /** Live iterator over `[id, definition]` pairs; it reflects only entries added before sealing. */
     entries(): IterableIterator<readonly [string, RegisteredModelCapability]>;
+    /**
+     * Register several capabilities.
+     *
+     * @param definitions Declarations applied in iteration order.
+     * @returns This registry, for chaining.
+     * @throws Error or TypeError under the same conditions as `register`.
+     */
     registerAll(definitions: Iterable<ModelCapabilityRegistration>): this;
+    /**
+     * @param id Capability id.
+     * @returns The registered definition.
+     * @throws TypeError when the id is not registered, which usually means a stage projection
+     *   omitted it.
+     */
     require(id: string): RegisteredModelCapability;
+    /**
+     * @param id Capability id.
+     * @returns Whether the id is registered in this registry.
+     */
     has(id: string): boolean;
+    /**
+     * @param id Capability id.
+     * @returns The registered definition, or undefined when absent.
+     */
     get(id: string): RegisteredModelCapability | undefined;
+    /** Live iterator over the registered definitions. */
     values(): IterableIterator<RegisteredModelCapability>;
+    /**
+     * Close the registry to further registration.
+     *
+     * Sealing is idempotent and does not affect existing entries.
+     *
+     * @returns This registry.
+     */
     seal(): this;
+    /**
+     * Derive a sealed sub-catalog for one stage.
+     *
+     * @param ids Capability ids available in the stage, in projection order. Must be non-empty
+     *   and free of duplicates.
+     * @returns A new sealed registry that reuses the immutable entries of this registry.
+     * @throws TypeError when the selection is empty or contains a duplicate id.
+     * @throws Error when an id was never registered.
+     */
     select(ids: readonly string[]): ModelCapabilityRegistry;
+    /**
+     * Parse model-supplied arguments and run the selected capability.
+     *
+     * @param selection Capability id plus the raw `input` object produced by the model. Other
+     *   fields, such as the originating call, are not interpreted here.
+     * @param context Stage identity handed to the resolver.
+     * @returns The resolver output.
+     * @throws ValidationError when the capability is unavailable in this registry or the input
+     *   is not a plain object; parser and resolver failures propagate unchanged.
+     */
     resolve(selection: ModelSelection, context: Readonly<{
         stageId: string;
     }>): unknown;
 }
-export type { ModelCapability, ModelCapabilityRegistration, RegisteredModelCapability, ModelSelection, ModelCapabilitySource, ModelCapabilityCatalog } from '../structs/capabilities/model.js';
+export type { ModelCapability, ModelCapabilityRegistration, RegisteredModelCapability, ModelSelection, ModelCapabilitySource, ModelCapabilityCatalog, } from '../structs/capabilities/model.js';

package/dist/esm/capabilities/model.js

@@ -1,43 +1,143 @@
+/**
+ * Declarative catalog of model capabilities for a request or one stage projection.
+ *
+ * A capability pairs an id and description with an input schema and a synchronous resolver,
+ * letting stage code parse model-supplied arguments and produce a typed value. Registration
+ * snapshots the schema and pins the parser and resolver to their defining object, so later
+ * mutation on the host side cannot change what a stage advertises.
+ *
+ * The registry is mutable until `seal()`. `select()` derives a sealed subset for a stage and
+ * shares the already-frozen entries rather than re-validating or re-wrapping them.
+ *
+ * Exports: `ModelCapabilityRegistry`, `modelProtocolError`, and the capability types.
+ */
 import { synchronous } from '../utils/synchronous.js';
 import { modelProtocolError } from '../utils/model-protocol.js';
 import { snapshotSchemaAdapter } from '../utils/schema-adapter.js';
 export { modelProtocolError } from '../utils/model-protocol.js';
 /** A request/stage projection is a sealed registry. Hosts filter availability before projection. */
 export class ModelCapabilityRegistry {
+    /** Insertion-ordered entries; iteration order is the declaration order of the catalog. */
     definitionsById = new Map();
+    /** Sealing is one-way: stage-time code must never extend the catalog it is executing. */
     sealed = false;
+    /**
+     * @param definitions Capabilities to register immediately, in iteration order.
+     * @throws TypeError when a definition is invalid or its id is duplicated (raised by
+     *   `register`).
+     */
     constructor(definitions = []) {
         for (const definition of definitions)
             this.register(definition);
     }
+    /**
+     * Register one capability.
+     *
+     * @param capability Declaration with a non-empty unique id, non-empty description, an
+     *   object-rooted JSON schema and a resolver.
+     * @returns This registry, for chaining.
+     * @throws Error when the registry is already sealed.
+     * @throws TypeError when the declaration is invalid or its id is already registered.
+     */
     register(capability) {
         if (this.sealed)
             throw new Error('Model capability registry is sealed');
+        // Model arguments are always a JSON object, so a non-object root can never validate.
         const schema = capability.inputSchema?.jsonSchema;
-        if (!capability.id?.trim() || !capability.description?.trim() || schema?.type !== 'object'
-            || typeof capability.resolve !== 'function' || this.definitionsById.has(capability.id))
+        if (!capability.id?.trim() ||
+            !capability.description?.trim() ||
+            schema?.type !== 'object' ||
+            typeof capability.resolve !== 'function' ||
+            this.definitionsById.has(capability.id))
             throw new TypeError('Invalid or duplicate model capability');
+        // Clone and freeze the schema, and pin `parse`, so the stored entry is independent of
+        // the definition object the host may keep mutating.
         const inputSchema = snapshotSchemaAdapter(capability.inputSchema, 'Model input parsers must be synchronous');
         const resolver = capability.resolve.bind(capability);
+        // Bind once here: a later caller cannot substitute its own receiver for the resolver.
         const resolve = (value, context) => synchronous(resolver(value, context), 'Model capability resolvers must be synchronous');
-        this.definitionsById.set(capability.id, Object.freeze({ id: capability.id, description: capability.description, inputSchema, resolve }));
+        this.definitionsById.set(capability.id, Object.freeze({
+            id: capability.id,
+            description: capability.description,
+            inputSchema,
+            resolve,
+        }));
         return this;
     }
-    get definitions() { return Object.freeze([...this.definitionsById.values()]); }
-    ids() { return Object.freeze([...this.definitionsById.keys()]); }
-    entries() { return this.definitionsById.entries(); }
-    registerAll(definitions) { for (const definition of definitions)
-        this.register(definition); return this; }
+    /** Frozen snapshot of the registered definitions, in insertion order. */
+    get definitions() {
+        return Object.freeze([...this.definitionsById.values()]);
+    }
+    /** Registered ids in declaration order. */
+    ids() {
+        return Object.freeze([...this.definitionsById.keys()]);
+    }
+    /** Live iterator over `[id, definition]` pairs; it reflects only entries added before sealing. */
+    entries() {
+        return this.definitionsById.entries();
+    }
+    /**
+     * Register several capabilities.
+     *
+     * @param definitions Declarations applied in iteration order.
+     * @returns This registry, for chaining.
+     * @throws Error or TypeError under the same conditions as `register`.
+     */
+    registerAll(definitions) {
+        for (const definition of definitions)
+            this.register(definition);
+        return this;
+    }
+    /**
+     * @param id Capability id.
+     * @returns The registered definition.
+     * @throws TypeError when the id is not registered, which usually means a stage projection
+     *   omitted it.
+     */
     require(id) {
         const capability = this.get(id);
         if (!capability)
             throw new TypeError(`Unknown model capability: ${id}`);
         return capability;
     }
-    has(id) { return this.definitionsById.has(id); }
-    get(id) { return this.definitionsById.get(id); }
-    values() { return this.definitionsById.values(); }
-    seal() { this.sealed = true; return this; }
+    /**
+     * @param id Capability id.
+     * @returns Whether the id is registered in this registry.
+     */
+    has(id) {
+        return this.definitionsById.has(id);
+    }
+    /**
+     * @param id Capability id.
+     * @returns The registered definition, or undefined when absent.
+     */
+    get(id) {
+        return this.definitionsById.get(id);
+    }
+    /** Live iterator over the registered definitions. */
+    values() {
+        return this.definitionsById.values();
+    }
+    /**
+     * Close the registry to further registration.
+     *
+     * Sealing is idempotent and does not affect existing entries.
+     *
+     * @returns This registry.
+     */
+    seal() {
+        this.sealed = true;
+        return this;
+    }
+    /**
+     * Derive a sealed sub-catalog for one stage.
+     *
+     * @param ids Capability ids available in the stage, in projection order. Must be non-empty
+     *   and free of duplicates.
+     * @returns A new sealed registry that reuses the immutable entries of this registry.
+     * @throws TypeError when the selection is empty or contains a duplicate id.
+     * @throws Error when an id was never registered.
+     */
     select(ids) {
         if (!ids.length || new Set(ids).size !== ids.length)
             throw new TypeError('Invalid capability selection');
@@ -53,9 +153,22 @@ export class ModelCapabilityRegistry {
         }
         return selected.seal();
     }
+    /**
+     * Parse model-supplied arguments and run the selected capability.
+     *
+     * @param selection Capability id plus the raw `input` object produced by the model. Other
+     *   fields, such as the originating call, are not interpreted here.
+     * @param context Stage identity handed to the resolver.
+     * @returns The resolver output.
+     * @throws ValidationError when the capability is unavailable in this registry or the input
+     *   is not a plain object; parser and resolver failures propagate unchanged.
+     */
     resolve(selection, context) {
         const { stageId } = context;
-        const capability = this.definitionsById.get(selection.capabilityId) ?? modelProtocolError('Model capability is unavailable in this stage');
+        // Model output is untrusted: unknown ids and non-object arguments are protocol failures,
+        // not ordinary `undefined` results.
+        const capability = this.definitionsById.get(selection.capabilityId) ??
+            modelProtocolError('Model capability is unavailable in this stage');
         if (!selection.input || typeof selection.input !== 'object' || Array.isArray(selection.input))
             modelProtocolError('Model capability input must be an object');
         return synchronous(capability.resolve(capability.inputSchema.parse(selection.input), { stageId }), 'Model capability parsers must be synchronous');

package/dist/esm/capabilities/tool-runtime.d.ts

@@ -1,3 +1,14 @@
 import { ToolRegistry } from './tools.js';
 import type { ToolDefinition, ToolRegistryOptions } from '../structs/capabilities/tools.js';
+/**
+ * Build a sealed tool registry from typed definitions.
+ *
+ * @param definitions Tool declarations in registration order; ids must be unique.
+ * @param context App context captured for every call made through this registry.
+ * @param options Registry ports: the request-lifetime signal, diagnostics, and the error
+ *   mapping used for unavailable tools and failure codes.
+ * @returns The sealed registry.
+ * @throws Error when the registry is sealed already or an id is duplicated.
+ * @throws TypeError when a definition is invalid, raised during registration.
+ */
 export declare function createToolRegistry<Context>(definitions: readonly ToolDefinition<unknown, unknown, Context>[], context: Context, options: ToolRegistryOptions): ToolRegistry;

package/dist/esm/capabilities/tool-runtime.js

@@ -1,33 +1,85 @@
+/**
+ * Bridge from typed tool definitions to the Core `ToolRegistry`.
+ *
+ * A `ToolDefinition` is the App-facing declaration: a schema adapter plus authorize, execute
+ * and parseOutput handlers. This module pins those handlers to their definition and adapts
+ * them to the lower-level `ExecutableTool` contract, while keeping the synchronous and
+ * asynchronous boundaries explicit: `invokeAsync` awaits authorization and execution,
+ * `invoke` rejects a promise from either.
+ *
+ * Exports: `createToolRegistry`.
+ */
 import { assertion, synchronous, isPromiseLike } from '../utils/synchronous.js';
 import { ToolRegistry } from './tools.js';
-/** Preserve synchronous tools; asynchronous authorization/I/O remain awaited by Core invokeAsync. */
+/**
+ * Run authorization and execution for one call, in that order.
+ *
+ * Authorization must resolve to undefined; a discarded boolean is treated as a contract
+ * violation instead of being silently ignored. Cancellation is checked before and after each
+ * phase so an aborted request never produces a successful value.
+ */
 function execute(definition, input, context, execution) {
     const { signal, mode, diagnostics, report, createSubFlowLogger } = execution;
     signal.throwIfAborted();
-    const complete = (value) => { signal.throwIfAborted(); return value; };
+    // Re-check after the handler returned: work that completed during cancellation must not be
+    // reported as a success.
+    const complete = (value) => {
+        signal.throwIfAborted();
+        return value;
+    };
     const operation = { app: context, signal, diagnostics, report, createSubFlowLogger };
     const authorized = (result) => {
         assertion(result, 'Tool authorization must return void');
         signal.throwIfAborted();
         const value = definition.execute(input, operation);
-        return mode === 'sync' ? complete(synchronous(value, 'Synchronous tools must not return a Promise'))
-            : isPromiseLike(value) ? Promise.resolve(value).then(complete) : complete(value);
+        return mode === 'sync'
+            ? complete(synchronous(value, 'Synchronous tools must not return a Promise'))
+            : isPromiseLike(value)
+                ? Promise.resolve(value).then(complete)
+                : complete(value);
     };
     const allowed = definition.authorize(input, operation);
-    return mode === 'sync' ? authorized(synchronous(allowed, 'Synchronous tool authorization must not return a Promise'))
-        : isPromiseLike(allowed) ? Promise.resolve(allowed).then(authorized) : authorized(allowed);
+    return mode === 'sync'
+        ? authorized(synchronous(allowed, 'Synchronous tool authorization must not return a Promise'))
+        : isPromiseLike(allowed)
+            ? Promise.resolve(allowed).then(authorized)
+            : authorized(allowed);
 }
+/**
+ * Build a sealed tool registry from typed definitions.
+ *
+ * @param definitions Tool declarations in registration order; ids must be unique.
+ * @param context App context captured for every call made through this registry.
+ * @param options Registry ports: the request-lifetime signal, diagnostics, and the error
+ *   mapping used for unavailable tools and failure codes.
+ * @returns The sealed registry.
+ * @throws Error when the registry is sealed already or an id is duplicated.
+ * @throws TypeError when a definition is invalid, raised during registration.
+ */
 export function createToolRegistry(definitions, context, options) {
     const registry = new ToolRegistry(options);
-    registry.registerAll(definitions.map(definition => {
+    registry.registerAll(definitions.map((definition) => {
         // Every entry point pins the same canonical handlers, including callers
         // that use this creator directly rather than defineToolCatalog.
-        const { id, kind, description, inputSchema, authorize, execute: handle, parseOutput, debugSteps } = definition;
-        const bound = Object.freeze({ id, kind, description, inputSchema,
-            authorize: authorize.bind(definition), execute: handle.bind(definition), parseOutput: parseOutput.bind(definition),
+        const { id, kind, description, inputSchema, authorize, execute: handle, parseOutput, debugSteps, } = definition;
+        const bound = Object.freeze({
+            id,
+            kind,
+            description,
+            inputSchema,
+            authorize: authorize.bind(definition),
+            execute: handle.bind(definition),
+            parseOutput: parseOutput.bind(definition),
         });
-        return { id, kind, description, debugSteps: debugSteps?.bind(definition),
-            parseInput: inputSchema.parse.bind(inputSchema), parseOutput: bound.parseOutput,
+        return {
+            id,
+            kind,
+            description,
+            debugSteps: debugSteps?.bind(definition),
+            // Bind to the adapter captured above, so a later replacement of the property on the
+            // definition cannot change what this registry validates.
+            parseInput: inputSchema.parse.bind(inputSchema),
+            parseOutput: bound.parseOutput,
             execute: (input, execution) => execute(bound, input, context, execution),
         };
     }));

package/dist/esm/capabilities/tools.d.ts

@@ -1,29 +1,122 @@
 import type { ToolResult } from '../structs/invocation.js';
 import type { ExecutableTool, RegisteredTool, ToolExecutionEvent, ToolRegistryPorts, ToolRegistryOptions, ToolInvocationRequest } from '../structs/capabilities/tools.js';
-/** Mechanism only. Visibility, authorization, schemas and semantic metadata are host registrations. */
+/**
+ * Registry mechanism only: visibility, authorization policy, schemas and semantic metadata
+ * are host registrations. A registry is mutable until sealed and keeps its own call log.
+ */
 export declare class ToolRegistry<Tool extends ExecutableTool = ExecutableTool> {
+    /** Insertion order is the declaration order and is preserved by every enumeration below. */
     private readonly tools;
+    /** Sealing is one-way: a running stage must not add tools to the registry it executes. */
     private sealed;
+    /** In-memory execution facts for this registry's lifetime, one entry per completed call. */
     private readonly executionEvents;
+    /** Frozen snapshot of the recorded execution facts. */
     get events(): readonly Readonly<ToolExecutionEvent<Tool['kind']>>[];
     private diagnostics;
     private readonly ports;
+    /**
+     * @param options.execution Request-lifetime signal plus the diagnostics/observer source the
+     *   registry starts from.
+     * @param options.errors Factories for the unknown-tool error and for failure codes.
+     */
     constructor({ execution, errors }?: ToolRegistryOptions);
+    /**
+     * Replace the diagnostics scope used by subsequent calls.
+     *
+     * Calls already in flight keep the scope they started with.
+     *
+     * @param diagnostics New diagnostics context, or undefined to stop emitting events.
+     */
     setDiagnostics(diagnostics: ToolRegistryPorts['diagnostics']): void;
+    /**
+     * Register one executable tool.
+     *
+     * The stored entry is frozen and its parsers are bound to the tool, so later changes on the
+     * caller's object cannot alter validation or execution.
+     *
+     * @param tool Executable tool; `id` and `kind` must be non-empty, and the parse and execute
+     *   handlers must all be functions.
+     * @returns This registry, for chaining.
+     * @throws Error when the registry is sealed or the id is already registered.
+     * @throws TypeError when the tool shape is invalid.
+     */
     register(tool: Tool): this;
+    /**
+     * Invoke a registered tool synchronously.
+     *
+     * @param request Single request object carrying `toolId`, `input`, and optional signal and
+     *   diagnostics. Exactly one argument is accepted; the arity check is runtime-enforced
+     *   because callers may bypass the type system.
+     * @returns The tool result, with frozen invocation metadata.
+     * @throws TypeError when the request shape is wrong, the diagnostics belong to another run,
+     *   or the tool returns a promise.
+     * @throws Error when the tool is unknown or the tool itself fails; the abort reason
+     *   surfaces when the signal is cancelled.
+     */
     invoke(request: ToolInvocationRequest): ToolResult<unknown>;
+    /**
+     * Invoke a registered tool and await its result.
+     *
+     * @param request Single request object, identical to `invoke`.
+     * @returns The tool result once the tool settles.
+     * @throws TypeError or Error under the same conditions as `invoke`; rejections from an
+     *   asynchronous tool are propagated unchanged.
+     */
     invokeAsync(request: ToolInvocationRequest): Promise<ToolResult<unknown>>;
+    /**
+     * Run one call: validate, parse input, execute, parse output, then record the outcome.
+     *
+     * @param name Registered tool id.
+     * @param input Untrusted caller input, parsed before the tool sees it.
+     * @param asynchronous Whether promises returned by the tool are awaited.
+     * @param parentDiagnostics Scope the call is recorded under; defaults to the registry's.
+     * @param requestSignal Per-call signal, combined with the request-lifetime signal.
+     * @returns The frozen result on success; every failure path throws.
+     */
     private execute;
+    /**
+     * Register several tools.
+     *
+     * @param tools Executable tools applied in iteration order.
+     * @returns This registry, for chaining.
+     * @throws Error or TypeError under the same conditions as `register`.
+     */
     registerAll(tools: Iterable<Tool>): this;
+    /**
+     * @param name Tool id.
+     * @returns The registered tool, or undefined when absent.
+     */
     get(name: string): RegisteredTool<Tool> | undefined;
+    /** Frozen snapshot of the registered tools, in declaration order. */
     get definitions(): readonly Readonly<RegisteredTool<Tool>>[];
+    /** Registered tool ids in declaration order. */
     ids(): readonly string[];
+    /** Live iterator over `[id, tool]` pairs; it reflects only entries added before sealing. */
     entries(): IterableIterator<[string, RegisteredTool<Tool>]>;
+    /**
+     * @param id Tool id.
+     * @returns The registered tool.
+     * @throws Error when the tool is unknown; the App-supplied `unavailable` factory can
+     *   replace the default message.
+     */
     require(id: string): RegisteredTool<Tool>;
+    /**
+     * @param name Tool id.
+     * @returns Whether the id is registered in this registry.
+     */
     has(name: string): boolean;
+    /** Live iterator over the registered tools. */
     values(): IterableIterator<RegisteredTool<Tool>>;
+    /**
+     * Close the registry to further registration.
+     *
+     * Sealing is idempotent and does not affect existing tools.
+     *
+     * @returns This registry.
+     */
     seal(): this;
 }
-export type { ToolDefinition, ToolExecutionContext, ExecutableTool, RegisteredTool, ToolExecutionEvent, ToolRegistryPorts, ToolRegistryOptions, ToolInvocationRequest } from '../structs/capabilities/tools.js';
+export type { ToolDefinition, ToolExecutionContext, ExecutableTool, RegisteredTool, ToolExecutionEvent, ToolRegistryPorts, ToolRegistryOptions, ToolInvocationRequest, } from '../structs/capabilities/tools.js';
 export { executeInvocation } from './invocation.js';
-export type { InvocationHandler, ToolInvocationPorts, ToolJournal } from '../structs/capabilities/invocation.js';
+export type { InvocationHandler, ToolInvocationPorts, ToolJournal, } from '../structs/capabilities/invocation.js';