@jangts/agent-core 0.1.0 → 0.2.0

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),
         };
     }));