@jangts/agent-core 0.1.0 → 0.2.0

package/dist/cjs/model/interactions/native-functions.js

@@ -1,25 +1,58 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nativeFunctionInteraction = void 0;
+/**
+ * Default interaction adapter: native function calling.
+ *
+ * Declarations are sent as provider functions and the streamed function-call delta is
+ * reassembled into exactly one proposal. A call is a proposal, never proof of execution:
+ * this adapter only decodes it, and the core decides what to run.
+ *
+ * Exports: `nativeFunctionInteraction`.
+ */
 const model_protocol_js_1 = require("../../utils/model-protocol.js");
 const arguments_js_1 = require("./arguments.js");
+/**
+ * Adapter that decodes a streamed native function call.
+ *
+ * `strictArguments` is false because declarations are sent with `strict: false`; the
+ * adapter therefore validates the argument payload itself via `parse`.
+ */
 exports.nativeFunctionInteraction = Object.freeze({
     id: 'native-functions',
     features: Object.freeze({ strictArguments: false }),
+    /**
+     * Build native declarations, the instruction and the response collector.
+     *
+     * Wire names are derived from capability ids and must stay unique after mapping;
+     * a collision would make it impossible to resolve the proposed name back to an id.
+     *
+     * @param capabilities - Capabilities registered for this stage; must be non-empty.
+     * @returns Function declarations, the measured instruction and the collector factory.
+     * @throws TypeError When two capability ids map to the same wire name.
+     */
     prepare(capabilities) {
-        const names = new Map(capabilities.map(capability => [(0, arguments_js_1.wireName)(capability.id), capability.id]));
+        const names = new Map(capabilities.map((capability) => [(0, arguments_js_1.wireName)(capability.id), capability.id]));
         if (names.size !== capabilities.length)
             throw new TypeError('Model wire name collision');
-        const functions = capabilities.map(capability => ({ name: (0, arguments_js_1.wireName)(capability.id), description: capability.description,
-            parameters: capability.inputSchema.jsonSchema, strict: false }));
+        const functions = capabilities.map((capability) => ({
+            name: (0, arguments_js_1.wireName)(capability.id),
+            description: capability.description,
+            parameters: capability.inputSchema.jsonSchema,
+            strict: false,
+        }));
         const instruction = 'Submit exactly one registered capability through its tool call. Protocol examples describe call arguments, not assistant prose. A call is a proposal, not proof of execution.';
         return {
-            options: { json: false, functions }, schemaChars: JSON.stringify(functions).length + instruction.length, instruction,
+            options: { json: false, functions },
+            schemaChars: JSON.stringify(functions).length + instruction.length,
+            instruction,
             createResponse() {
                 let raw = '';
                 let call;
                 return {
-                    get outputChars() { return raw.length + (call ? call.id.length + call.name.length + call.arguments.length : 0); },
+                    get outputChars() {
+                        return (raw.length + (call ? call.id.length + call.name.length + call.arguments.length : 0));
+                    },
                     push(part) {
                         if (typeof part === 'string') {
                             raw += part;
@@ -32,9 +65,9 @@ exports.nativeFunctionInteraction = Object.freeze({
                             (0, model_protocol_js_1.modelProtocolError)('Expected a native model call');
                         if (index !== 0)
                             (0, model_protocol_js_1.modelProtocolError)('Expected exactly one model call', 'MODEL_MULTIPLE_CALLS');
-                        if ((id !== undefined && (typeof id !== 'string' || !id))
-                            || (name !== undefined && typeof name !== 'string')
-                            || (args !== undefined && typeof args !== 'string'))
+                        if ((id !== undefined && (typeof id !== 'string' || !id)) ||
+                            (name !== undefined && typeof name !== 'string') ||
+                            (args !== undefined && typeof args !== 'string'))
                             (0, model_protocol_js_1.modelProtocolError)('Invalid native model call fields');
                         call ??= { id: '', name: '', arguments: '' };
                         if (id !== undefined) {
@@ -49,8 +82,17 @@ exports.nativeFunctionInteraction = Object.freeze({
                         if (!call?.id || !call.name || raw.trim())
                             (0, model_protocol_js_1.modelProtocolError)('Expected one complete model call without prose');
                         const completed = call;
-                        const capability = names.get(completed.name) ?? (0, model_protocol_js_1.modelProtocolError)('Model call is not registered for this stage');
-                        return { capabilityId: capability, input: (0, arguments_js_1.parse)(completed.arguments), call: { id: completed.id, name: completed.name, argumentChars: completed.arguments.length } };
+                        const capability = names.get(completed.name) ??
+                            (0, model_protocol_js_1.modelProtocolError)('Model call is not registered for this stage');
+                        return {
+                            capabilityId: capability,
+                            input: (0, arguments_js_1.parse)(completed.arguments),
+                            call: {
+                                id: completed.id,
+                                name: completed.name,
+                                argumentChars: completed.arguments.length,
+                            },
+                        };
                     },
                 };
             },

package/dist/cjs/model/message-diagnostics.js

@@ -1,9 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.modelMessageDiagnostics = modelMessageDiagnostics;
-/** Image bytes are never persisted in model diagnostics, even with full text logging. */
+/**
+ * Replace every image payload with a placeholder.
+ *
+ * Only the `url` is substituted; the `detail` hint is kept because it is small and
+ * explains how the image was interpreted. The input array is not mutated.
+ *
+ * @param messages - Messages about to be reported.
+ * @returns New message objects whose images carry a placeholder URL.
+ */
 function modelMessageDiagnostics(messages) {
-    return messages.map(message => ({ ...message, ...(message.images ? {
-            images: message.images.map(image => ({ ...image, url: '[image omitted]' })),
-        } : {}) }));
+    return messages.map((message) => ({
+        ...message,
+        ...(message.images
+            ? {
+                images: message.images.map((image) => ({ ...image, url: '[image omitted]' })),
+            }
+            : {}),
+    }));
 }

package/dist/cjs/model/options.js

@@ -1,7 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.snapshotModelOptions = snapshotModelOptions;
-/** Read structural options, including prototype getters, while preserving explicit overrides. */
+/**
+ * Copy declared model options, preserving explicit overrides.
+ *
+ * `onUsage` is rebound to the original options object so a method keeps its receiver.
+ * The deletion pass restores absent keys that the explicit reads had materialized.
+ *
+ * @param options - Source options; defaults to an empty object.
+ * @returns A plain options object containing only the keys present on the source.
+ */
 function snapshotModelOptions(options = {}) {
     const snapshot = {
         json: options.json,

package/dist/cjs/model/preparation.js

@@ -2,53 +2,127 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prepareModelTransport = prepareModelTransport;
 exports.preparedInputSize = preparedInputSize;
+/**
+ * One-shot preparation and measurement of a model request.
+ *
+ * Preparation freezes the transport's options, instruction and response factory before
+ * any counting happens; measurement then derives every size from that same snapshot.
+ * Splitting the two phases is what guarantees that the numbers checked against the
+ * budget are the numbers actually sent to the provider.
+ *
+ * Exports: `prepareModelTransport` and `preparedInputSize`.
+ */
 const token_budget_js_1 = require("./token-budget.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const object_js_1 = require("../utils/object.js");
 const options_js_1 = require("./options.js");
 const rules_js_1 = require("../utils/rules.js");
 // Only snapshots owned and frozen by this module are reusable across measurements.
+// Keyed by the frozen options object so a repeated measure of the same prepared call
+// does not re-serialize a large function schema.
 const functionSizes = new WeakMap();
+/**
+ * Validate and freeze one image reference.
+ *
+ * `detail` is restricted to the values understood by every supported provider so the
+ * wire payload never carries an unvalidated hint.
+ *
+ * @param image - Candidate image reference.
+ * @returns A frozen image object without an undefined `detail`.
+ * @throws TypeError When the shape or `detail` value is invalid.
+ */
 function snapshotImage(image) {
     (0, rules_js_1.breakWhile)(!image || typeof image !== 'object' || Array.isArray(image), () => new TypeError('Invalid model image'));
     const { url, detail } = image;
-    (0, rules_js_1.breakWhile)(typeof url !== 'string' || !url || (detail !== undefined && !['auto', 'low', 'high', 'original'].includes(detail)), () => new TypeError('Invalid model image'));
+    (0, rules_js_1.breakWhile)(typeof url !== 'string' ||
+        !url ||
+        (detail !== undefined && !['auto', 'low', 'high', 'original'].includes(detail)), () => new TypeError('Invalid model image'));
     return Object.freeze({ url, ...(detail === undefined ? {} : { detail }) });
 }
-/** Snapshot a dynamic transport once, preserving its collector factory receiver. */
+/**
+ * Snapshot a dynamic transport once, preserving its collector factory receiver.
+ *
+ * The transport gets the stage id so it can specialize its instruction. Its options
+ * are copied, its function declarations cloned, and the whole snapshot frozen before
+ * the response factory is bound to the prepared source.
+ *
+ * @param transport - Registered transport definition.
+ * @param stageId - Stage the call belongs to.
+ * @returns A frozen prepared transport reused for measurement and the provider call.
+ * @throws TypeError When preparation is asynchronous or produces an invalid shape.
+ */
 function prepareModelTransport(transport, stageId) {
     const source = (0, synchronous_js_1.synchronous)(transport.prepare(stageId), 'Model transport preparation must be synchronous');
     if (!source)
         throw new TypeError('Invalid prepared model transport');
     const { schemaChars, instruction, createResponse } = source;
-    if (!Number.isSafeInteger(schemaChars) || schemaChars < 0 || typeof createResponse !== 'function'
-        || (instruction !== undefined && typeof instruction !== 'string'))
+    if (!Number.isSafeInteger(schemaChars) ||
+        schemaChars < 0 ||
+        typeof createResponse !== 'function' ||
+        (instruction !== undefined && typeof instruction !== 'string'))
         throw new TypeError('Invalid prepared model transport');
     const options = (0, options_js_1.snapshotModelOptions)(source.options);
     if (options.functions)
         options.functions = structuredClone(options.functions);
     (0, object_js_1.freezeSchema)(options);
-    const prepared = Object.freeze({ options, schemaChars, instruction, createResponse: createResponse.bind(source) });
+    const prepared = Object.freeze({
+        options,
+        schemaChars,
+        instruction,
+        createResponse: createResponse.bind(source),
+    });
     if (options.functions)
         functionSizes.set(options.functions, JSON.stringify(options.functions).length);
     return prepared;
 }
-/** Message text and declarations are measured once, irrespective of native or in-message schema. */
+/**
+ * Measure a prepared request into its character accounting.
+ *
+ * Each message is read once into a frozen snapshot before any sum is computed, so
+ * caller mutations and extra getters cannot change the request between accounting,
+ * output backpressure and provider I/O.
+ *
+ * The instruction is merged into the effective messages exactly once, mirroring what
+ * the provider receives; `instructionChars` is therefore derived from that merge rather
+ * than measured separately. `transportChars` is the larger of the transport's declared
+ * schema size and the instruction plus in-message schema size, because a transport may
+ * declare native declarations instead of embedding them.
+ *
+ * @param base - Caller messages; must be a message array.
+ * @param prepared - Result of `prepareModelTransport` for the same call.
+ * @returns Frozen effective messages plus per-part and total character counts.
+ * @throws TypeError When the message array or any message is invalid.
+ */
 function preparedInputSize(base, prepared) {
     // Read only protocol fields, once. Caller mutations and extra getters cannot
     // change the request between accounting, output backpressure and Provider I/O.
     (0, rules_js_1.breakWhile)(!Array.isArray(base), () => new TypeError('Model messages must be an array'));
-    const snapshot = Array.from(base, message => {
+    const snapshot = Array.from(base, (message) => {
         (0, rules_js_1.breakWhile)(!message || typeof message !== 'object' || Array.isArray(message), () => new TypeError('Invalid model message'));
         const { role, content, images } = message;
-        (0, rules_js_1.breakWhile)(!['system', 'user', 'assistant'].includes(role) || typeof content !== 'string' || (images !== undefined && !Array.isArray(images)), () => new TypeError('Invalid model message'));
-        return Object.freeze({ role, content, ...(images === undefined ? {} : { images: Object.freeze(Array.from(images, snapshotImage)) }) });
+        (0, rules_js_1.breakWhile)(!['system', 'user', 'assistant'].includes(role) ||
+            typeof content !== 'string' ||
+            (images !== undefined && !Array.isArray(images)), () => new TypeError('Invalid model message'));
+        return Object.freeze({
+            role,
+            content,
+            ...(images === undefined ? {} : { images: Object.freeze(Array.from(images, snapshotImage)) }),
+        });
     });
-    const messages = Object.freeze((0, token_budget_js_1.modelInputMessages)(snapshot, prepared.instruction).map(message => Object.freeze(message)));
+    const messages = Object.freeze((0, token_budget_js_1.modelInputMessages)(snapshot, prepared.instruction).map((message) => Object.freeze(message)));
     const messageChars = snapshot.reduce((sum, message) => sum + message.content.length, 0);
     const instructionChars = messages.reduce((sum, message) => sum + message.content.length, 0) - messageChars;
     const functions = prepared.options.functions;
-    const schemaChars = functions ? functionSizes.get(functions) ?? JSON.stringify(functions).length : 0;
+    const schemaChars = functions
+        ? (functionSizes.get(functions) ?? JSON.stringify(functions).length)
+        : 0;
     const transportChars = Math.max(prepared.schemaChars, instructionChars + schemaChars);
-    return { messages, messageChars, instructionChars, schemaChars, transportChars, inputChars: messageChars + instructionChars + schemaChars };
+    return {
+        messages,
+        messageChars,
+        instructionChars,
+        schemaChars,
+        transportChars,
+        inputChars: messageChars + instructionChars + schemaChars,
+    };
 }