@jangts/agent-core 0.1.1 → 0.2.0

package/dist/cjs/support/model/completion/calls.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolCallCollector = createToolCallCollector;
+const model_protocol_js_1 = require("../../../utils/model-protocol.js");
+/**
+ * Create a collector for one response.
+ *
+ * @param fail - Protocol failure factory; defaults to the Core model protocol error.
+ * @returns A collector that keeps its own state and never shares it with another response.
+ */
+function createToolCallCollector(fail = model_protocol_js_1.modelProtocolError) {
+    const pending = new Map();
+    const ids = new Set();
+    const calls = () => [...pending.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([index, call]) => ({ index, ...call }));
+    return {
+        push(part) {
+            if (typeof part === 'string')
+                return;
+            if (!part || typeof part !== 'object' || Array.isArray(part))
+                fail('Expected a native model call');
+            const { type, index, id, name, arguments: args } = part;
+            if (type !== 'function-call-delta')
+                fail('Expected a native model call');
+            if (!Number.isInteger(index) || index < 0)
+                fail('Invalid model call index');
+            if ((id !== undefined && (typeof id !== 'string' || !id)) ||
+                (name !== undefined && typeof name !== 'string') ||
+                (args !== undefined && typeof args !== 'string'))
+                fail('Invalid model call fields');
+            let call = pending.get(index);
+            if (!call) {
+                call = { id: '', name: '', arguments: '' };
+                pending.set(index, call);
+            }
+            if (id !== undefined) {
+                if (call.id && call.id !== id)
+                    fail('Conflicting model call IDs');
+                if (!call.id) {
+                    if (ids.has(id))
+                        fail('Duplicate model call ID');
+                    ids.add(id);
+                    call.id = id;
+                }
+            }
+            call.name += name ?? '';
+            call.arguments += args ?? '';
+        },
+        get calls() {
+            return calls();
+        },
+        complete() {
+            const completed = calls();
+            for (const call of completed)
+                if (!call.id || !call.name)
+                    fail('Incomplete model call');
+            return completed;
+        },
+    };
+}

package/dist/cjs/support/model/completion/default.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultCompletionPolicy = void 0;
+const policy = {
+    id: 'default',
+    begin(facts, fail) {
+        let finished = false;
+        let hasText = false;
+        let hasCall = false;
+        return {
+            part(part) {
+                if (typeof part === 'string') {
+                    hasText = true;
+                    return;
+                }
+                if (!facts.functions)
+                    throw fail('MODEL_PROTOCOL');
+                hasCall = true;
+            },
+            finish(reason) {
+                if (reason !== (facts.functions ? 'tool_calls' : 'stop'))
+                    throw fail(reason === 'length' ? 'MODEL_OUTPUT_LIMIT' : 'MODEL_INCOMPLETE');
+                finished = true;
+            },
+            end() {
+                if (!finished || (facts.functions ? !hasCall : !hasText && !facts.allowEmptyText))
+                    throw fail('MODEL_INCOMPLETE');
+            },
+        };
+    },
+};
+exports.defaultCompletionPolicy = Object.freeze(policy);

package/dist/cjs/support/model/completion/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.completionPolicyCatalog = exports.sessionCompletionPolicy = exports.defaultCompletionPolicy = exports.createToolCallCollector = void 0;
+/**
+ * Completion policy catalog: policies a compatible provider may be configured with.
+ *
+ * Registration is explicit and frozen. The module refuses to load when a key and the policy's own
+ * identifier disagree, so a lookup can never return a policy under a false name.
+ *
+ * Main exports: `completionPolicyCatalog`, the two preset re-exports, the shared call collector
+ * and their contract types.
+ */
+const rules_js_1 = require("../../../utils/rules.js");
+const default_js_1 = require("./default.js");
+const session_js_1 = require("./session.js");
+var calls_js_1 = require("./calls.js");
+Object.defineProperty(exports, "createToolCallCollector", { enumerable: true, get: function () { return calls_js_1.createToolCallCollector; } });
+var default_js_2 = require("./default.js");
+Object.defineProperty(exports, "defaultCompletionPolicy", { enumerable: true, get: function () { return default_js_2.defaultCompletionPolicy; } });
+var session_js_2 = require("./session.js");
+Object.defineProperty(exports, "sessionCompletionPolicy", { enumerable: true, get: function () { return session_js_2.sessionCompletionPolicy; } });
+/** Preset policies selected by an explicit port; the default is used when none is given. */
+exports.completionPolicyCatalog = Object.freeze({
+    default: default_js_1.defaultCompletionPolicy,
+    session: session_js_1.sessionCompletionPolicy,
+});
+for (const [id, policy] of Object.entries(exports.completionPolicyCatalog))
+    (0, rules_js_1.breakWhile)(id !== policy.id, 'Completion policy ID does not match its registered policy');

package/dist/cjs/support/model/completion/session.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionCompletionPolicy = void 0;
+const calls_js_1 = require("./calls.js");
+/** Read the specific-function form: `{ type: 'function', function: { name } }`. */
+function namedTool(choice) {
+    if (!choice || typeof choice !== 'object' || Array.isArray(choice))
+        return undefined;
+    const value = choice;
+    if (value.type !== 'function')
+        return undefined;
+    const fn = value.function;
+    if (!fn || typeof fn !== 'object' || Array.isArray(fn))
+        return undefined;
+    const name = fn.name;
+    return typeof name === 'string' && name ? name : undefined;
+}
+const policy = {
+    id: 'session',
+    begin(facts, fail) {
+        const choice = facts.toolChoice;
+        let mode;
+        let named;
+        if (choice === undefined)
+            mode = 'inherit';
+        else if (choice === 'auto' || choice === 'required' || choice === 'none')
+            mode = choice;
+        else {
+            named = namedTool(choice);
+            if (!named)
+                throw fail('MODEL_CONFIG');
+            mode = 'named';
+        }
+        const collector = (0, calls_js_1.createToolCallCollector)(() => {
+            throw fail('MODEL_PROTOCOL');
+        });
+        let finished = false;
+        let hasText = false;
+        let hasCall = false;
+        const textSatisfied = () => hasText || facts.allowEmptyText;
+        const calls = () => {
+            const completed = collector.complete();
+            if (!completed.length)
+                throw fail('MODEL_INCOMPLETE');
+            if (named && completed.some((call) => call.name !== named))
+                throw fail('MODEL_PROTOCOL');
+            return completed;
+        };
+        return {
+            part(part) {
+                if (typeof part === 'string') {
+                    hasText = true;
+                    return;
+                }
+                hasCall = true;
+                if (mode === 'none')
+                    throw fail('MODEL_PROTOCOL');
+                if (mode === 'inherit' && !facts.functions)
+                    throw fail('MODEL_PROTOCOL');
+                collector.push(part);
+            },
+            finish(reason) {
+                if (mode === 'inherit') {
+                    if (reason !== (facts.functions ? 'tool_calls' : 'stop'))
+                        throw fail(reason === 'length' ? 'MODEL_OUTPUT_LIMIT' : 'MODEL_INCOMPLETE');
+                    finished = true;
+                    return;
+                }
+                if (reason === 'length')
+                    throw fail('MODEL_OUTPUT_LIMIT');
+                if (mode === 'none') {
+                    if (reason !== 'stop' || !textSatisfied())
+                        throw fail('MODEL_INCOMPLETE');
+                }
+                else if (mode === 'auto') {
+                    if (reason === 'tool_calls')
+                        calls();
+                    else if (reason === 'stop') {
+                        if (hasCall)
+                            throw fail('MODEL_PROTOCOL');
+                        if (!textSatisfied())
+                            throw fail('MODEL_INCOMPLETE');
+                    }
+                    else
+                        throw fail('MODEL_INCOMPLETE');
+                }
+                else if (reason === 'tool_calls')
+                    calls();
+                else
+                    throw fail('MODEL_INCOMPLETE');
+                finished = true;
+            },
+            end() {
+                if (!finished)
+                    throw fail('MODEL_INCOMPLETE');
+                if (mode === 'inherit' && (facts.functions ? !hasCall : !textSatisfied()))
+                    throw fail('MODEL_INCOMPLETE');
+            },
+        };
+    },
+};
+exports.sessionCompletionPolicy = Object.freeze(policy);

package/dist/cjs/support/model/index.js

@@ -15,8 +15,20 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.modelBudgetStrategies = exports.createModelStrategy = exports.runChildren = exports.createReplyPreviewRules = exports.createProviderObservationScope = exports.createStageModelTransport = void 0;
+/**
+ * Model support: recommended transports, providers and strategies for Core model calls.
+ *
+ * Applications compose these implementations and hand them to a Core `ModelRunner`. This module
+ * owns wire adaptation and local admission budgets only; credentials, HTTP hosting and business
+ * policy stay with the application, and Core does not import this code.
+ *
+ * Main exports: transport creators, `CompatibleModelProvider`, stage transport projection,
+ * capability/interaction catalogs, child-task execution, reply preview helpers, provider
+ * observation scopes and `createModelStrategy` with its budget presets.
+ */
 __exportStar(require("./transports.js"), exports);
 __exportStar(require("./compatible-provider.js"), exports);
+__exportStar(require("./completion/index.js"), exports);
 __exportStar(require("./interactions/index.js"), exports);
 __exportStar(require("./chat-completions.js"), exports);
 __exportStar(require("./capabilities.js"), exports);

package/dist/cjs/support/model/interactions/index.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.modelInteractionCatalog = exports.jsonObjectInteraction = exports.nativeFunctionInteraction = void 0;
+/**
+ * Model interaction catalog: adapters that convert model output into Core model parts.
+ *
+ * Adapters are selected only from explicit application capability metadata, never inferred from
+ * arbitrary text. Each adapter is registered under the same ID it reports, and the catalog is
+ * frozen so later imports cannot widen the available interactions.
+ *
+ * Main exports: `modelInteractionCatalog`, the two adapter re-exports and their contract types.
+ */
 const native_functions_js_1 = require("./native-functions.js");
 const json_object_js_1 = require("./json-object.js");
 const rules_js_1 = require("../../../utils/rules.js");
@@ -10,7 +19,9 @@ var json_object_js_2 = require("./json-object.js");
 Object.defineProperty(exports, "jsonObjectInteraction", { enumerable: true, get: function () { return json_object_js_2.jsonObjectInteraction; } });
 /** Registered adapters selected only from explicit App capability metadata. */
 exports.modelInteractionCatalog = Object.freeze({
-    'native-functions': native_functions_js_1.nativeFunctionInteraction, 'json-object': json_object_js_1.jsonObjectInteraction,
+    'native-functions': native_functions_js_1.nativeFunctionInteraction,
+    'json-object': json_object_js_1.jsonObjectInteraction,
 });
+// Fail at module load rather than let a mismatched key register an adapter under a false ID.
 for (const [id, adapter] of Object.entries(exports.modelInteractionCatalog))
     (0, rules_js_1.breakWhile)(id !== adapter.id, 'Model interaction ID does not match its registered adapter');

package/dist/cjs/support/model/interactions/json-object.js

@@ -1,5 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonObjectInteraction = void 0;
+/**
+ * Re-export barrel: the JSON-object model interaction adapter.
+ *
+ * Applications reference it through the Support interaction catalog; the implementation lives in
+ * the Core model layer and is not duplicated here.
+ */
 var json_object_js_1 = require("../../../model/interactions/json-object.js");
 Object.defineProperty(exports, "jsonObjectInteraction", { enumerable: true, get: function () { return json_object_js_1.jsonObjectInteraction; } });

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

@@ -1,5 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nativeFunctionInteraction = void 0;
+/**
+ * Re-export barrel: the native-function-call model interaction adapter.
+ *
+ * Applications reference it through the Support interaction catalog; the implementation lives in
+ * the Core model layer and is not duplicated here.
+ */
 var native_functions_js_1 = require("../../../model/interactions/native-functions.js");
 Object.defineProperty(exports, "nativeFunctionInteraction", { enumerable: true, get: function () { return native_functions_js_1.nativeFunctionInteraction; } });

package/dist/cjs/support/model/observer.js

@@ -2,11 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.providerObservation = providerObservation;
 exports.createProviderObservationScope = createProviderObservationScope;
+/**
+ * Classify each provider event.
+ *
+ * `content` events may contain prompt or response data and need explicit acceptance; `metadata`
+ * events only describe the call.
+ */
 const events = {
-    'provider.request': 'content', 'provider.response': 'metadata', 'provider.frame': 'content',
-    'provider.error-body': 'content', 'provider.end': 'metadata',
+    'provider.request': 'content',
+    'provider.response': 'metadata',
+    'provider.frame': 'content',
+    'provider.error-body': 'content',
+    'provider.end': 'metadata',
 };
-/** Lazy and caller-owned: absent/rejected observers do not evaluate payloads or capture error bodies. */
+/**
+ * Create the emit/enabled pair used inside the provider.
+ *
+ * @param observer Caller-owned observer; when absent, every event is disabled.
+ * @param options Provider context passed to the observer's acceptance check.
+ * @returns `enabled(event)` and `emit(event, payload)`; both never throw.
+ */
 function providerObservation(observer, options) {
     const enabled = (event) => {
         if (!observer || !Object.hasOwn(events, event))
@@ -28,11 +43,21 @@ function providerObservation(observer, options) {
                 if (pending)
                     void Promise.resolve(pending).catch(() => { });
             }
-            catch { /* Observation cannot change provider results, cancellation or retry behavior. */ }
+            catch {
+                /* Observation cannot change provider results, cancellation or retry behavior. */
+            }
         },
     };
 }
-/** Associate provider observations with a caller-owned log destination across child spans. */
+/**
+ * Bind provider observations to a caller-owned destination across diagnostic child spans.
+ *
+ * `attach` returns a scoped diagnostic context; contexts that were not attached through this scope
+ * produce no observations. Child contexts inherit the owner and a `parent/child` span path.
+ *
+ * @param sink Destination implementing optional `accepts` and required `write`.
+ * @returns A frozen `{ attach, observer }` pair to install on a provider.
+ */
 function createProviderObservationScope(sink) {
     const owners = new WeakMap();
     const accepts = sink.accepts?.bind(sink);
@@ -44,8 +69,9 @@ function createProviderObservationScope(sink) {
             emit: context.emit.bind(context),
             deliver: context.deliver.bind(context),
             child: (id, fields) => attach(context.child(id, fields), owner, `${spanId}/${id}`),
-            withObserver: observer => attach(context.withObserver(observer), owner, spanId),
+            withObserver: (observer) => attach(context.withObserver(observer), owner, spanId),
         };
+        // Prefer the real span identity so the log matches diagnostics rather than the local label.
         owners.set(scoped, { owner, spanId: context.identity?.spanId ?? spanId });
         return scoped;
     }

package/dist/cjs/support/model/preview-rules.js

@@ -1,8 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createReplyPreviewRules = createReplyPreviewRules;
+/**
+ * Reply preview rule generation from capability and stage declarations.
+ *
+ * Previews are presentation only: rules are derived from the same capability schemas and stage
+ * references used for transport, so a capability cannot preview a field it does not accept.
+ * Declarations are snapshotted; application objects are never frozen or mutated.
+ *
+ * Main exports: `createReplyPreviewRules` and the capability/stage declaration types.
+ */
 const rules_js_1 = require("../../utils/rules.js");
 const arguments_js_1 = require("../../model/interactions/arguments.js");
+/**
+ * Check whether a schema path exists, following local `$ref`, composition keywords and `items`.
+ *
+ * Rules are only emitted for declared fields, so a renamed or removed field fails generation
+ * instead of silently producing an empty preview.
+ */
 function fieldExists(root, path) {
     const visit = (schema, remaining, depth) => {
         if (!schema || typeof schema !== 'object' || depth > 64)
@@ -11,20 +26,33 @@ function fieldExists(root, path) {
             return true;
         const current = schema;
         if (typeof current.$ref === 'string' && current.$ref.startsWith('#/')) {
-            const target = current.$ref.slice(2).split('/').reduce((value, part) => value && typeof value === 'object'
-                ? (() => { const key = part.replace(/~1/g, '/').replace(/~0/g, '~'); return Object.hasOwn(value, key) ? value[key] : undefined; })() : undefined, root);
+            const target = current.$ref
+                .slice(2)
+                .split('/')
+                .reduce((value, part) => value && typeof value === 'object'
+                ? (() => {
+                    const key = part.replace(/~1/g, '/').replace(/~0/g, '~');
+                    return Object.hasOwn(value, key)
+                        ? value[key]
+                        : undefined;
+                })()
+                : undefined, root);
             if (visit(target, remaining, depth + 1))
                 return true;
         }
         for (const keyword of ['anyOf', 'oneOf', 'allOf']) {
             const alternatives = current[keyword];
-            if (Array.isArray(alternatives) && alternatives.some(value => visit(value, remaining, depth + 1)))
+            if (Array.isArray(alternatives) &&
+                alternatives.some((value) => visit(value, remaining, depth + 1)))
                 return true;
         }
         const [key, ...rest] = remaining;
         const properties = current.properties;
-        if (key !== '*' && properties && typeof properties === 'object' && Object.hasOwn(properties, key)
-            && visit(properties[key], rest, depth + 1))
+        if (key !== '*' &&
+            properties &&
+            typeof properties === 'object' &&
+            Object.hasOwn(properties, key) &&
+            visit(properties[key], rest, depth + 1))
             return true;
         return (key === '*' || /^\d+$/.test(key)) && visit(current.items, rest, depth + 1);
     };
@@ -33,18 +61,33 @@ function fieldExists(root, path) {
 function stringList(value, label) {
     (0, rules_js_1.breakWhile)(!Array.isArray(value), `Invalid preview ${label}`);
     const snapshot = Array.from(value);
-    (0, rules_js_1.breakWhile)(snapshot.some(item => typeof item !== 'string'), `Invalid preview ${label}`);
+    (0, rules_js_1.breakWhile)(snapshot.some((item) => typeof item !== 'string'), `Invalid preview ${label}`);
     return snapshot;
 }
 function previewSnapshot(preview) {
     if (!preview || preview === true)
         return preview || undefined;
     const { paths, when } = preview;
-    const pathSnapshot = paths === undefined ? undefined : Array.from(paths, path => stringList(path, 'path'));
-    const eligibility = when === undefined ? undefined : { path: stringList(when.path, 'eligibility path'), values: stringList(when.values, 'eligibility values') };
+    const pathSnapshot = paths === undefined ? undefined : Array.from(paths, (path) => stringList(path, 'path'));
+    const eligibility = when === undefined
+        ? undefined
+        : {
+            path: stringList(when.path, 'eligibility path'),
+            values: stringList(when.values, 'eligibility values'),
+        };
     return { paths: pathSnapshot, when: eligibility };
 }
-/** Generate stage rules from the same capability declarations and stage references used for transport. */
+/**
+ * Generate frozen preview rules from capability and stage declarations.
+ *
+ * Capabilities without preview metadata are skipped even when their stage opts in. Default paths
+ * are `text` and `bubbles[*]`, each kept only when the capability schema declares it.
+ *
+ * @param options Stage declarations and the capabilities they may reference.
+ * @returns Frozen rules in stage order, each with deep-frozen paths and eligibility.
+ * @throws {Error} When a capability or stage ID repeats, a stage references an unknown capability,
+ *   a preview mode is unknown, or a preview path or eligibility field is absent from the schema.
+ */
 function createReplyPreviewRules(options) {
     const capabilities = new Map();
     for (const capability of options.capabilities) {
@@ -61,7 +104,7 @@ function createReplyPreviewRules(options) {
         (0, rules_js_1.breakWhile)(!stageId || stages.has(stageId), 'Duplicate preview stage declaration');
         stages.add(stageId);
         const ids = capabilityIds === undefined ? [] : stringList(capabilityIds, 'capability IDs');
-        (0, rules_js_1.breakWhile)(new Set(ids).size !== ids.length || ids.some(id => !capabilities.has(id)), 'Preview stage references an unknown capability');
+        (0, rules_js_1.breakWhile)(new Set(ids).size !== ids.length || ids.some((id) => !capabilities.has(id)), 'Preview stage references an unknown capability');
         (0, rules_js_1.breakWhile)(preview !== undefined && !['text', 'capabilities'].includes(preview), 'Unknown preview stage mode');
         if (!preview)
             continue;
@@ -76,14 +119,21 @@ function createReplyPreviewRules(options) {
                 continue;
             const source = capability.preview === true ? {} : capability.preview;
             const { paths, when } = source;
-            const checkedPaths = paths ?? [['text'], ['bubbles', '*']].filter(path => fieldExists(capability.jsonSchema, path));
-            (0, rules_js_1.breakWhile)(!checkedPaths.length || checkedPaths.some(path => !fieldExists(capability.jsonSchema, path)), `Invalid preview field: ${id}`);
+            const checkedPaths = paths ??
+                [['text'], ['bubbles', '*']].filter((path) => fieldExists(capability.jsonSchema, path));
+            (0, rules_js_1.breakWhile)(!checkedPaths.length ||
+                checkedPaths.some((path) => !fieldExists(capability.jsonSchema, path)), `Invalid preview field: ${id}`);
             (0, rules_js_1.breakWhile)(!!when && !fieldExists(capability.jsonSchema, when.path), `Invalid preview eligibility field: ${id}`);
             // Only generator-owned snapshots are frozen; App declarations remain untouched.
-            const emittedPaths = Object.freeze(checkedPaths.map(path => Object.freeze(path)));
-            const emittedWhen = when && Object.freeze({ path: Object.freeze(when.path), values: Object.freeze(when.values) });
-            rules.push(Object.freeze({ stageId, capabilityId: (0, arguments_js_1.wireName)(id), paths: emittedPaths,
-                ...(emittedWhen ? { when: emittedWhen } : {}) }));
+            const emittedPaths = Object.freeze(checkedPaths.map((path) => Object.freeze(path)));
+            const emittedWhen = when &&
+                Object.freeze({ path: Object.freeze(when.path), values: Object.freeze(when.values) });
+            rules.push(Object.freeze({
+                stageId,
+                capabilityId: (0, arguments_js_1.wireName)(id),
+                paths: emittedPaths,
+                ...(emittedWhen ? { when: emittedWhen } : {}),
+            }));
         }
     }
     return Object.freeze(rules);