@jangts/agent-core 0.1.1 → 0.2.1

package/dist/cjs/capabilities/invocation.js

@@ -1,31 +1,84 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeInvocation = executeInvocation;
+/**
+ * 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.
+ */
 const invocation_js_1 = require("../utils/invocation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const index_js_1 = require("../diagnostics/index.js");
 const reporting_js_1 = require("../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.
+ */
 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 = (0, invocation_js_1.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 reporting_js_1.NodeReports(diagnostics, signal, 'tool.result');
-        (0, synchronous_js_1.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.
+        (0, synchronous_js_1.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 });
         }
@@ -34,15 +87,32 @@ 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: (0, index_js_1.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: (0, index_js_1.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/cjs/capabilities/model.js

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelCapabilityRegistry = exports.modelProtocolError = void 0;
+/**
+ * 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.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const model_protocol_js_1 = require("../utils/model-protocol.js");
 const schema_adapter_js_1 = require("../utils/schema-adapter.js");
@@ -8,40 +21,127 @@ var model_protocol_js_2 = require("../utils/model-protocol.js");
 Object.defineProperty(exports, "modelProtocolError", { enumerable: true, get: function () { return model_protocol_js_2.modelProtocolError; } });
 /** A request/stage projection is a sealed registry. Hosts filter availability before projection. */
 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 = (0, schema_adapter_js_1.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) => (0, synchronous_js_1.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');
@@ -57,9 +157,22 @@ 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) ?? (0, model_protocol_js_1.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) ??
+            (0, model_protocol_js_1.modelProtocolError)('Model capability is unavailable in this stage');
         if (!selection.input || typeof selection.input !== 'object' || Array.isArray(selection.input))
             (0, model_protocol_js_1.modelProtocolError)('Model capability input must be an object');
         return (0, synchronous_js_1.synchronous)(capability.resolve(capability.inputSchema.parse(selection.input), { stageId }), 'Model capability parsers must be synchronous');

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

@@ -1,36 +1,88 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createToolRegistry = createToolRegistry;
+/**
+ * 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`.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const tools_js_1 = require("./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) => {
         (0, synchronous_js_1.assertion)(result, 'Tool authorization must return void');
         signal.throwIfAborted();
         const value = definition.execute(input, operation);
-        return mode === 'sync' ? complete((0, synchronous_js_1.synchronous)(value, 'Synchronous tools must not return a Promise'))
-            : (0, synchronous_js_1.isPromiseLike)(value) ? Promise.resolve(value).then(complete) : complete(value);
+        return mode === 'sync'
+            ? complete((0, synchronous_js_1.synchronous)(value, 'Synchronous tools must not return a Promise'))
+            : (0, synchronous_js_1.isPromiseLike)(value)
+                ? Promise.resolve(value).then(complete)
+                : complete(value);
     };
     const allowed = definition.authorize(input, operation);
-    return mode === 'sync' ? authorized((0, synchronous_js_1.synchronous)(allowed, 'Synchronous tool authorization must not return a Promise'))
-        : (0, synchronous_js_1.isPromiseLike)(allowed) ? Promise.resolve(allowed).then(authorized) : authorized(allowed);
+    return mode === 'sync'
+        ? authorized((0, synchronous_js_1.synchronous)(allowed, 'Synchronous tool authorization must not return a Promise'))
+        : (0, synchronous_js_1.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.
+ */
 function createToolRegistry(definitions, context, options) {
     const registry = new tools_js_1.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),
         };
     }));