@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/kits/family.js

@@ -1,36 +1,89 @@
+/**
+ * Family Kit: version App state that hangs off Core branches, with fork, merge and promote.
+ *
+ * Place in the package: an optional App-side library. A family is a bounded, expiring record
+ * of immutable versions; each version pairs a branch snapshot with App state. The Kit owns
+ * revision checks, capacity, retention and lineage rules; the store, authorization, validation
+ * and merge policy stay with the App. No executable function or authority is restored here.
+ *
+ * Exports: `defineAgentFamily`, `Family`, the family record/version/operation types and
+ * `familyOperations`.
+ */
 import { invocationId } from '../utils/invocation.js';
 import { awaitWithSignal, awaitAssertion } from '../utils/cancellation.js';
 import { booleanResult } from '../utils/synchronous.js';
 import { breakWhile } from '../utils/rules.js';
 import { snapshotBranch as branchSnapshot } from '../execution/branch.js';
-/** Versioned App data around existing Engine branches. No executable functions or authority are restored. */
+/**
+ * Compile a versioned family backed by an App-owned compare-and-swap store.
+ *
+ * Every mutation reads the record, verifies the caller's expected revision, then commits with
+ * a compare-and-swap, so concurrent writers fail with a revision conflict rather than
+ * overwriting each other. Reads are also treated as policy checks because the App binds its
+ * read rules into the store it supplies.
+ *
+ * @param definition - Store, authorization, validation, state predicate, branch/state snapshots
+ *   and optional merge handler, clock and bounds.
+ * @returns A frozen family with `read`, `create`, `fork`, `merge` and `promote`.
+ * @throws A configured error (often `TypeError`) for an invalid id, expired or unknown record,
+ *   revision conflict, exhausted capacity, lineage mismatch, missing merge configuration,
+ *   invalid merge result, or changed active version.
+ */
 export function defineAgentFamily(definition) {
-    const store = { load: definition.store.load.bind(definition.store), compareAndSwap: definition.store.compareAndSwap.bind(definition.store) };
+    const store = {
+        load: definition.store.load.bind(definition.store),
+        compareAndSwap: definition.store.compareAndSwap.bind(definition.store),
+    };
     const authorize = definition.authorize.bind(definition), validate = definition.validate.bind(definition);
     const isState = definition.isState.bind(definition), merge = definition.merge?.bind(definition), now = definition.now?.bind(definition) ?? Date.now;
+    // Bounds are encoded in the record itself: 32 versions and seven days of retention keep the
+    // snapshot small enough to clone and compare on every operation.
     const maxVersions = definition.maxVersions ?? 32, retentionMs = definition.retentionMs ?? 7 * 86400_000;
-    breakWhile(!Number.isSafeInteger(maxVersions) || maxVersions < 1 || !Number.isSafeInteger(retentionMs) || retentionMs < 1, 'Invalid family bounds');
+    breakWhile(!Number.isSafeInteger(maxVersions) ||
+        maxVersions < 1 ||
+        !Number.isSafeInteger(retentionMs) ||
+        retentionMs < 1, 'Invalid family bounds');
     const validId = (id) => typeof id === 'string' && !!id.trim() && id.length <= 200;
     const stateSnapshot = (value) => {
         breakWhile(!booleanResult(isState(value), 'Family state predicates must be synchronous'), 'Invalid family state');
         return structuredClone(value);
     };
+    /**
+     * Load, validate and clone a family record.
+     *
+     * @param id - Family id, at most 200 characters.
+     * @param context - Operation context supplying the abort signal.
+     * @returns A cloned record whose versions, branches and states all passed validation.
+     * @throws A configured error for an invalid id, a missing/expired record, or an inconsistent
+     *   version.
+     */
     const read = async (id, context) => {
         context.signal.throwIfAborted();
         breakWhile(!validId(id), 'Invalid family id');
         const record = structuredClone(await awaitWithSignal(store.load(id), context.signal));
         context.signal.throwIfAborted();
-        breakWhile(!record || record.id !== id || !Number.isFinite(record.expiresAtMs) || record.expiresAtMs <= now() || !Number.isSafeInteger(record.revision) || record.revision < 1
-            || !Array.isArray(record.versions) || !record.versions.length || record.versions.length > maxVersions || !record.versions.some(version => version.id === record.activeId), 'Family unavailable');
-        const ids = new Set(record.versions.map(version => version.id));
+        breakWhile(!record ||
+            record.id !== id ||
+            !Number.isFinite(record.expiresAtMs) ||
+            record.expiresAtMs <= now() ||
+            !Number.isSafeInteger(record.revision) ||
+            record.revision < 1 ||
+            !Array.isArray(record.versions) ||
+            !record.versions.length ||
+            record.versions.length > maxVersions ||
+            !record.versions.some((version) => version.id === record.activeId), 'Family unavailable');
+        const ids = new Set(record.versions.map((version) => version.id));
         breakWhile(ids.size !== record.versions.length, 'Duplicate family version');
         for (const item of record.versions) {
-            breakWhile(!validId(item.id) || !Number.isFinite(item.createdAtMs) || item.createdAtMs < 0
-                || [item.parentId, item.baseId, item.mergeSourceId].some(value => value !== undefined && !ids.has(value)), 'Invalid family version');
+            breakWhile(!validId(item.id) ||
+                !Number.isFinite(item.createdAtMs) ||
+                item.createdAtMs < 0 ||
+                [item.parentId, item.baseId, item.mergeSourceId].some((value) => value !== undefined && !ids.has(value)), 'Invalid family version');
             branchSnapshot(item.branch);
             stateSnapshot(item.state);
         }
-        // Reading policy is part of the App's bound store. Mutations also require their explicit operation grant.
+        // Reading policy is part of the App's bound store. Mutations also require their explicit
+        // operation grant.
         context.signal.throwIfAborted();
         return structuredClone(record);
     };
@@ -50,7 +103,7 @@ export function defineAgentFamily(definition) {
         return record;
     };
     const version = (record, id) => {
-        const selected = record.versions.find(item => item.id === id);
+        const selected = record.versions.find((item) => item.id === id);
         breakWhile(!selected, 'Unknown family version');
         return selected;
     };
@@ -60,49 +113,126 @@ export function defineAgentFamily(definition) {
         return commit({ ...record, revision: record.revision + 1, versions: [...record.versions, candidate] }, record.revision, context);
     };
     return Object.freeze({
+        /** Clone and validate one family record through the same read path used by mutations. */
         read,
+        /**
+         * Create a family with one initial version.
+         *
+         * @param request - Family id plus its first branch and state.
+         * @param context - Operation context; authorization receives `'create'` and no record.
+         * @returns The committed record at revision 1.
+         * @throws A configured error for an invalid or existing id, or failed authorization or
+         *   validation.
+         */
         async create(request, context) {
             context.signal.throwIfAborted();
             const { id } = request;
             breakWhile(!validId(id), 'Invalid family id');
             const branch = branchSnapshot(request.branch), state = structuredClone(request.state);
-            breakWhile(!!await awaitWithSignal(store.load(id), context.signal), 'Family already exists');
+            breakWhile(!!(await awaitWithSignal(store.load(id), context.signal)), 'Family already exists');
             await awaitAssertion(() => authorize('create', undefined, context), context.signal, 'Family authorization must return void');
-            const candidate = { id: invocationId(), branch, state: stateSnapshot(state), createdAtMs: now() };
+            const candidate = {
+                id: invocationId(),
+                branch,
+                state: stateSnapshot(state),
+                createdAtMs: now(),
+            };
             await awaitAssertion(() => validate(structuredClone(candidate), context), context.signal, 'Family validation must return void');
-            return commit({ id, revision: 1, activeId: candidate.id, expiresAtMs: now() + retentionMs, versions: [candidate] }, undefined, context);
+            return commit({
+                id,
+                revision: 1,
+                activeId: candidate.id,
+                expiresAtMs: now() + retentionMs,
+                versions: [candidate],
+            }, undefined, context);
         },
+        /**
+         * Add a child version derived from one existing version.
+         *
+         * @param request - Family id, expected revision, parent version id, new branch and state.
+         * @param context - Operation context; authorization receives `'fork'` and the record.
+         * @returns The committed record with the new version appended.
+         * @throws A configured error for a stale revision, unknown parent, broken lineage or full
+         *   capacity.
+         */
         async fork(request, context) {
             context.signal.throwIfAborted();
             const { id, revision, parentId } = request, state = structuredClone(request.state);
             const branch = branchSnapshot(request.branch);
             const record = await check('fork', id, revision, context), parent = version(record, parentId);
-            breakWhile(branch.agentId !== parent.branch.agentId || branch.parentBranchId !== parent.branch.branchId
-                || branch.parentAgentVersionId !== parent.branch.agentVersionId || branch.branchId === parent.branch.branchId, 'Fork lineage mismatch');
-            return add(record, { id: invocationId(), parentId: parent.id, baseId: parent.id, branch, state: stateSnapshot(state), createdAtMs: now() }, context);
+            breakWhile(branch.agentId !== parent.branch.agentId ||
+                branch.parentBranchId !== parent.branch.branchId ||
+                branch.parentAgentVersionId !== parent.branch.agentVersionId ||
+                branch.branchId === parent.branch.branchId, 'Fork lineage mismatch');
+            return add(record, {
+                id: invocationId(),
+                parentId: parent.id,
+                baseId: parent.id,
+                branch,
+                state: stateSnapshot(state),
+                createdAtMs: now(),
+            }, context);
         },
+        /**
+         * Merge a source version into a target version over their shared base.
+         *
+         * Conflicts are reported, never resolved here: a non-empty conflict list returns
+         * `saved: false` with the unchanged record, so the App decides how to reconcile.
+         *
+         * @param request - Family id, expected revision and the base, target and source version ids.
+         * @param context - Operation context; authorization receives `'merge'` and the record.
+         * @returns `{ saved, record, conflicts }`.
+         * @throws A configured error for a stale revision, missing versions, no merge handler, a
+         *   missing shared base, or an invalid merge result.
+         */
         async merge(request, context) {
             const { id, revision, baseId, targetId, sourceId } = request;
             const record = await check('merge', id, revision, context);
             breakWhile(!merge, 'Family merge is not configured');
             const base = version(record, baseId), target = version(record, targetId), source = version(record, sourceId);
-            breakWhile(source.baseId !== base.id || target.id !== base.id && target.baseId !== base.id, 'Merge requires a shared base');
-            const result = await awaitWithSignal(merge({ base: stateSnapshot(base.state), target: stateSnapshot(target.state), source: stateSnapshot(source.state) }, context), context.signal);
-            breakWhile(!result || !Array.isArray(result.conflicts) || result.conflicts.some(value => typeof value !== 'string'), 'Invalid merge result');
+            breakWhile(source.baseId !== base.id || (target.id !== base.id && target.baseId !== base.id), 'Merge requires a shared base');
+            const result = await awaitWithSignal(merge({
+                base: stateSnapshot(base.state),
+                target: stateSnapshot(target.state),
+                source: stateSnapshot(source.state),
+            }, context), context.signal);
+            breakWhile(!result ||
+                !Array.isArray(result.conflicts) ||
+                result.conflicts.some((value) => typeof value !== 'string'), 'Invalid merge result');
             if (result.conflicts.length)
                 return { saved: false, record, conflicts: [...result.conflicts] };
-            const candidate = { id: invocationId(), parentId: target.id, baseId: target.id, mergeSourceId: source.id,
-                branch: branchSnapshot(source.branch), state: stateSnapshot(result.value), createdAtMs: now() };
+            const candidate = {
+                id: invocationId(),
+                parentId: target.id,
+                baseId: target.id,
+                mergeSourceId: source.id,
+                branch: branchSnapshot(source.branch),
+                state: stateSnapshot(result.value),
+                createdAtMs: now(),
+            };
             return { saved: true, record: await add(record, candidate, context), conflicts: [] };
         },
+        /**
+         * Make an existing version the active one.
+         *
+         * @param request - Family id, expected revision, candidate id and the active id the caller
+         *   believes is current.
+         * @param context - Operation context; authorization receives `'promote'` and the record.
+         * @returns The committed record pointing at the candidate.
+         * @throws A configured error for a stale revision or active id, an unrelated candidate, or
+         *   failed validation.
+         */
         async promote(request, context) {
             const { id, revision, candidateId, expectedActiveId } = request;
             const record = await check('promote', id, revision, context), candidate = version(record, candidateId);
-            breakWhile(record.activeId !== expectedActiveId || candidate.id !== record.activeId && candidate.baseId !== record.activeId, 'Active family version changed');
+            breakWhile(record.activeId !== expectedActiveId ||
+                (candidate.id !== record.activeId && candidate.baseId !== record.activeId), 'Active family version changed');
             await awaitAssertion(() => validate(structuredClone(candidate), context), context.signal, 'Family validation must return void');
             return commit({ ...record, revision: record.revision + 1, activeId: candidate.id }, record.revision, context);
         },
     });
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 export const Family = Object.freeze({ defineAgentFamily });
+/** Operation names accepted by the family `authorize` hook. */
 export { familyOperations } from '../structs/kits/family.js';

package/dist/esm/kits/index.d.ts

@@ -1,4 +1,15 @@
-/** Explicit bulk Kit entry; applications normally import the individual Kit path. */
+/**
+ * Explicit bulk Kit entry.
+ *
+ * Kits are optional, App-side business libraries. An application may consume a single Kit
+ * path; this file only exists for callers that prefer one import for the whole set. Core
+ * never imports from this directory, so nothing here becomes a runtime requirement.
+ *
+ * Exports: the Kit namespaces (`Interaction`, `Intents`, `Tools`, `Knowledge`, `Answering`,
+ * `Presentation`, `Normalization`, `Delivery`, `Projection`, `Aggregation`, `Retrieval`,
+ * `Evidence`, `Policies`, `Candidates`, `TextSkills`, `TextSearch`, `ModelCalls`,
+ * `VectorSearch`) plus every Kit type. Individual Kit paths stay the default.
+ */
 export { Interaction } from './interaction/index.js';
 export { Intents } from './intents/index.js';
 export { Tools } from './tools.js';

package/dist/esm/kits/index.js

@@ -1,4 +1,15 @@
-/** Explicit bulk Kit entry; applications normally import the individual Kit path. */
+/**
+ * Explicit bulk Kit entry.
+ *
+ * Kits are optional, App-side business libraries. An application may consume a single Kit
+ * path; this file only exists for callers that prefer one import for the whole set. Core
+ * never imports from this directory, so nothing here becomes a runtime requirement.
+ *
+ * Exports: the Kit namespaces (`Interaction`, `Intents`, `Tools`, `Knowledge`, `Answering`,
+ * `Presentation`, `Normalization`, `Delivery`, `Projection`, `Aggregation`, `Retrieval`,
+ * `Evidence`, `Policies`, `Candidates`, `TextSkills`, `TextSearch`, `ModelCalls`,
+ * `VectorSearch`) plus every Kit type. Individual Kit paths stay the default.
+ */
 export { Interaction } from './interaction/index.js';
 export { Intents } from './intents/index.js';
 export { Tools } from './tools.js';

package/dist/esm/kits/inference.d.ts

@@ -1,21 +1,45 @@
+/**
+ * Inference Kit: a bounded, cancellable catalog of App-registered model bindings.
+ *
+ * Place in the package: an optional App-side wrapper for calling model providers. A binding
+ * owns the provider call; this module owns id/identity registration, input and output
+ * assertions, attempt-budget accounting, timeout composition and diagnostics. It does not
+ * choose prompts, retries or fallbacks, and Core does not import it.
+ *
+ * Exports: `ModelCalls`, `ModelBinding`, `ModelInvocationContext`, `ModelInvocationRequest`.
+ */
 import type { ExecutionContext, MaybePromise } from '../structs/common.js';
 import type { AttemptBudget } from '../execution/workflow.js';
 import type { ModelResult } from '../structs/invocation.js';
 /** App-defined I/O. Registered literal IDs determine input and output types. */
 export interface ModelBinding<Input, Output> {
+    /** Catalog key used in requests; must be unique within one `ModelCalls` instance. */
     readonly id: string;
+    /** Non-blank implementation identity (provider plus model name) reported in diagnostics. */
     readonly identity: string;
+    /** Performs the provider call. May be async; the Kit applies the caller's signal. */
     invoke(input: Input, context: ModelInvocationContext): MaybePromise<Output>;
+    /** Optional synchronous assertion run before the budget is consumed or the call starts. */
     assertInput?(input: Input): void;
+    /** Optional synchronous assertion run after the call, before the result is reported. */
     assertOutput?(output: Output): void;
 }
 /** One take consumes one binding invocation attempt, independent of batch size or chat tokens. */
 export interface ModelInvocationContext extends ExecutionContext {
+    /** Shared attempt budget; a refusal fails the call with `BudgetError` before invoking. */
     readonly attemptBudget?: Pick<AttemptBudget, 'take'>;
 }
+/**
+ * One model call: registered binding id, the input to hand over and its timeout.
+ *
+ * @typeParam Input - Input type of the addressed binding.
+ */
 export interface ModelInvocationRequest<Input> {
+    /** Registered binding id; unknown ids fail before any provider work happens. */
     readonly modelId: string;
+    /** Input handed to the binding unchanged; Core never clones App objects here. */
     readonly input: Input;
+    /** Per-call timeout in milliseconds, 1..2147483647 (the platform timer ceiling). */
     readonly timeoutMs: number;
 }
 type BindingFor<Bindings extends readonly ModelBinding<any, any>[], Id extends string> = Bindings[number] extends infer Binding ? Binding extends {
@@ -28,18 +52,58 @@ type OutputFor<Bindings extends readonly ModelBinding<any, any>[], Id extends st
     invoke(...args: any[]): infer Output;
 } ? Awaited<Output> : unknown : unknown;
 type RegisteredBinding<Binding extends ModelBinding<any, any>> = Readonly<Pick<Binding, Extract<keyof Binding, keyof ModelBinding<any, any>>>>;
+/**
+ * Frozen catalog of model bindings plus a checked invocation entry point.
+ *
+ * Registration happens once in the constructor; the catalog is never mutated afterwards, so a
+ * caller cannot swap a provider in the middle of a run.
+ */
 export declare class ModelCalls<Input = unknown, Output = unknown, const Bindings extends readonly ModelBinding<any, any>[] = readonly ModelBinding<Input, Output>[]> {
     private sequence;
     private readonly bindings;
+    /**
+     * @param bindings - Bindings to register; each needs a non-blank `identity` and an `invoke`.
+     * @throws TypeError When a binding is malformed or two bindings share an id.
+     */
     constructor(bindings: Bindings);
+    /** Registered bindings in declaration order, with methods already bound to their owner. */
     get definitions(): readonly RegisteredBinding<Bindings[number]>[];
+    /** Registered binding ids in declaration order. */
     ids(): readonly string[];
+    /** Whether a binding id is registered. */
     has(id: string): boolean;
+    /** Registered binding for `id`, or `undefined` when it is absent. */
     get(id: string): RegisteredBinding<Bindings[number]> | undefined;
+    /**
+     * Registered binding for `id`.
+     *
+     * @throws TypeError When the id is not registered.
+     */
     require(id: string): RegisteredBinding<Bindings[number]>;
+    /** Iterate the registered bindings. */
     values(): IterableIterator<RegisteredBinding<Bindings[number]>>;
+    /** Iterate `[id, binding]` pairs. */
     entries(): IterableIterator<[string, RegisteredBinding<Bindings[number]>]>;
+    /**
+     * Implementation identity of one binding.
+     *
+     * @throws TypeError When the id is not registered.
+     */
     identity(id: string): string;
+    /**
+     * Invoke one registered binding under the caller's signal, timeout and attempt budget.
+     *
+     * Order matters: the binding id is resolved, input is asserted, the budget take happens
+     * before the provider call, and the output assertion runs before a result is reported. Any
+     * failure emits a diagnostic and rethrows unchanged, so callers see the provider's own error.
+     *
+     * @param request - Binding id, input and per-call timeout.
+     * @param context - Execution context; `signal` is combined with a timeout signal.
+     * @returns The provider output wrapped with invocation metadata.
+     * @throws TypeError For a malformed request, unknown id, missing signal/context, invalid
+     *   timeout or failed input/output assertion; `BudgetError` when the attempt budget refuses;
+     *   the provider's own error otherwise, including abort and timeout.
+     */
     invoke<const Id extends string>(request: ModelInvocationRequest<InputFor<Bindings, Id>> & {
         readonly modelId: Id;
     }, context: ModelInvocationContext): Promise<ModelResult<OutputFor<Bindings, Id>>>;

package/dist/esm/kits/inference.js

@@ -5,35 +5,97 @@ import { awaitWithSignal, combineSignals } from '../utils/cancellation.js';
 import { invocationId, invocationResult } from '../utils/invocation.js';
 import { getErrorInfo } from '../errors.js';
 import { ProtocolRegistry } from '../utils/protocol-registry.js';
+/**
+ * Frozen catalog of model bindings plus a checked invocation entry point.
+ *
+ * Registration happens once in the constructor; the catalog is never mutated afterwards, so a
+ * caller cannot swap a provider in the middle of a run.
+ */
 export class ModelCalls {
     sequence = 0;
     bindings = new ProtocolRegistry();
+    /**
+     * @param bindings - Bindings to register; each needs a non-blank `identity` and an `invoke`.
+     * @throws TypeError When a binding is malformed or two bindings share an id.
+     */
     constructor(bindings) {
         for (const binding of bindings) {
             if (!binding.identity?.trim() || typeof binding.invoke !== 'function')
                 throw new TypeError('Invalid model binding');
-            this.bindings.set(binding.id, Object.freeze({ id: binding.id, identity: binding.identity, invoke: binding.invoke.bind(binding),
-                assertInput: binding.assertInput?.bind(binding), assertOutput: binding.assertOutput?.bind(binding) }));
+            this.bindings.set(binding.id, Object.freeze({
+                id: binding.id,
+                identity: binding.identity,
+                invoke: binding.invoke.bind(binding),
+                assertInput: binding.assertInput?.bind(binding),
+                assertOutput: binding.assertOutput?.bind(binding),
+            }));
         }
     }
-    get definitions() { return Object.freeze([...this.bindings.values()]); }
-    ids() { return this.bindings.ids(); }
-    has(id) { return this.bindings.has(id); }
-    get(id) { return this.bindings.get(id); }
-    require(id) { return this.bindings.require(id); }
-    values() { return this.bindings.values(); }
-    entries() { return this.bindings.entries(); }
-    identity(id) { return this.require(id).identity; }
+    /** Registered bindings in declaration order, with methods already bound to their owner. */
+    get definitions() {
+        return Object.freeze([...this.bindings.values()]);
+    }
+    /** Registered binding ids in declaration order. */
+    ids() {
+        return this.bindings.ids();
+    }
+    /** Whether a binding id is registered. */
+    has(id) {
+        return this.bindings.has(id);
+    }
+    /** Registered binding for `id`, or `undefined` when it is absent. */
+    get(id) {
+        return this.bindings.get(id);
+    }
+    /**
+     * Registered binding for `id`.
+     *
+     * @throws TypeError When the id is not registered.
+     */
+    require(id) {
+        return this.bindings.require(id);
+    }
+    /** Iterate the registered bindings. */
+    values() {
+        return this.bindings.values();
+    }
+    /** Iterate `[id, binding]` pairs. */
+    entries() {
+        return this.bindings.entries();
+    }
+    /**
+     * Implementation identity of one binding.
+     *
+     * @throws TypeError When the id is not registered.
+     */
+    identity(id) {
+        return this.require(id).identity;
+    }
     async invoke(request, context) {
         if (!request || typeof request !== 'object' || !('input' in request))
             throw new TypeError('Use one model request and execution context');
         const { modelId: id, input, timeoutMs } = request;
-        if (!context?.signal || typeof id !== 'string' || !id.trim() || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)
+        if (!context?.signal ||
+            typeof id !== 'string' ||
+            !id.trim() ||
+            !Number.isSafeInteger(timeoutMs) ||
+            timeoutMs < 1 ||
+            // 2147483647 is the largest delay `setTimeout`/`AbortSignal.timeout` accept reliably.
+            timeoutMs > 2147483647)
             throw new TypeError('A modelId, signal and positive supported timeoutMs are required');
         const sourceBudget = context.attemptBudget;
         const take = sourceBudget?.take.bind(sourceBudget);
         const callId = invocationId(), startedAtMs = Date.now();
-        const diagnostics = context.diagnostics?.child(callId, { invocationId: callId, modelId: id, nodeRole: 'invocation', definitionKind: 'model-binding', definitionId: id, nodeId: id, nodeName: id, nodeKind: 'model-binding' });
+        const diagnostics = context.diagnostics?.child(callId, {
+            invocationId: callId,
+            modelId: id,
+            nodeRole: 'invocation',
+            definitionKind: 'model-binding',
+            definitionId: id,
+            nodeId: id,
+            nodeName: id,
+            nodeKind: 'model-binding',
+        });
         const signal = combineSignals(context.signal, AbortSignal.timeout(timeoutMs));
         let phase = 'input';
         try {
@@ -48,7 +110,12 @@ export class ModelCalls {
             }
             const callSequence = ++this.sequence;
             phase = 'invoke';
-            diagnostics?.emit('model.binding', () => ({ modelId: id, invocationId: callId, status: 'running', phase }));
+            diagnostics?.emit('model.binding', () => ({
+                modelId: id,
+                invocationId: callId,
+                status: 'running',
+                phase,
+            }));
             // Hand off checked inputs before yielding. Arbitrary App inputs may be
             // class instances or services, so Core must not silently clone them.
             signal.throwIfAborted();
@@ -57,11 +124,32 @@ export class ModelCalls {
             phase = 'output';
             assertion(binding.assertOutput?.(output), 'Model output assertions must be synchronous');
             signal.throwIfAborted();
-            diagnostics?.emit('model.binding', () => ({ modelId: id, invocationId: callId, status: 'success', phase, durationMs: Date.now() - startedAtMs }));
-            return invocationResult(output, { ...diagnostics?.identity, invocationId: callId, modelId: id, startedAtMs, durationMs: Date.now() - startedAtMs, callSequence, status: 'success' });
+            diagnostics?.emit('model.binding', () => ({
+                modelId: id,
+                invocationId: callId,
+                status: 'success',
+                phase,
+                durationMs: Date.now() - startedAtMs,
+            }));
+            return invocationResult(output, {
+                ...diagnostics?.identity,
+                invocationId: callId,
+                modelId: id,
+                startedAtMs,
+                durationMs: Date.now() - startedAtMs,
+                callSequence,
+                status: 'success',
+            });
         }
         catch (error) {
-            diagnostics?.emit('model.binding', () => ({ modelId: id, invocationId: callId, status: signal.aborted ? 'cancelled' : 'error', phase, durationMs: Date.now() - startedAtMs, errorCode: getErrorInfo(error).code }));
+            diagnostics?.emit('model.binding', () => ({
+                modelId: id,
+                invocationId: callId,
+                status: signal.aborted ? 'cancelled' : 'error',
+                phase,
+                durationMs: Date.now() - startedAtMs,
+                errorCode: getErrorInfo(error).code,
+            }));
             throw error;
         }
     }

package/dist/esm/kits/intents/catalog.d.ts

@@ -1,5 +1,17 @@
 import type { AgentCatalogPorts, CatalogIntent, CatalogScope } from '../../structs/kits/intents/catalog.js';
-/** The actual registries determine availability and relationships. No parallel capability list. */
+/**
+ * Compile a catalog projection over the App's live registries.
+ *
+ * The actual registries determine availability and relationships. No parallel capability list
+ * exists: `intentIds` filters by tool support, `modelCatalog` narrows to the currently accepted
+ * task when `restrictToTask` is enabled, and scope tool ids are filtered to tools that exist.
+ *
+ * @param ports - Sources for intent ids, intents, scopes, the current task, the tool registry
+ *   and the `restrictToTask` switch.
+ * @returns A frozen projection with `intentIds`, `intentSteps`, `intentCatalog`,
+ *   `scopeCatalog` and `modelCatalog`.
+ * @throws TypeError When a supplied predicate does not return a boolean synchronously.
+ */
 export declare function defineAgentCatalog<App, Id extends string, Intent extends CatalogIntent<Id>, Scope extends CatalogScope>(ports: AgentCatalogPorts<App, Id, Intent, Scope>): Readonly<{
     intentIds: (app: App) => Id[];
     intentSteps: (app?: App) => Map<Id, string[]>;