@jangts/agent-core 0.1.0 → 0.2.0

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

@@ -0,0 +1,99 @@
+import { createToolCallCollector } from './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 = 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');
+            },
+        };
+    },
+};
+export const sessionCompletionPolicy = Object.freeze(policy);

package/dist/esm/support/model/index.d.ts

@@ -1,7 +1,21 @@
+/**
+ * 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.
+ */
 export * from './transports.js';
 export * from './compatible-provider.js';
+export * from './completion/index.js';
 export * from './interactions/index.js';
 export * from './chat-completions.js';
+export type * from '../../structs/support/model/completion.js';
+export type * from '../../structs/support/model/messages.js';
 export type * from '../../structs/support/model/interactions.js';
 export type * from '../../structs/support/model/provider.js';
 export * from './capabilities.js';

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

@@ -1,5 +1,17 @@
+/**
+ * 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.
+ */
 export * from './transports.js';
 export * from './compatible-provider.js';
+export * from './completion/index.js';
 export * from './interactions/index.js';
 export * from './chat-completions.js';
 export * from './capabilities.js';

package/dist/esm/support/model/interactions/index.d.ts

@@ -1,6 +1,6 @@
 export { nativeFunctionInteraction } from './native-functions.js';
 export { jsonObjectInteraction } from './json-object.js';
-export type { ModelResponseCollector, PreparedModelInteraction } from '../../../structs/model/interactions.js';
+export type { ModelResponseCollector, PreparedModelInteraction, } from '../../../structs/model/interactions.js';
 export type { ModelInteractionAdapter } from '../../../structs/support/model/interactions.js';
 /** Registered adapters selected only from explicit App capability metadata. */
 export declare const modelInteractionCatalog: Readonly<{

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

@@ -1,3 +1,12 @@
+/**
+ * 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.
+ */
 import { nativeFunctionInteraction } from './native-functions.js';
 import { jsonObjectInteraction } from './json-object.js';
 import { breakWhile } from '../../../utils/rules.js';
@@ -5,7 +14,9 @@ export { nativeFunctionInteraction } from './native-functions.js';
 export { jsonObjectInteraction } from './json-object.js';
 /** Registered adapters selected only from explicit App capability metadata. */
 export const modelInteractionCatalog = Object.freeze({
-    'native-functions': nativeFunctionInteraction, 'json-object': jsonObjectInteraction,
+    'native-functions': nativeFunctionInteraction,
+    'json-object': 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(modelInteractionCatalog))
     breakWhile(id !== adapter.id, 'Model interaction ID does not match its registered adapter');

package/dist/esm/support/model/interactions/json-object.d.ts

@@ -1 +1,7 @@
+/**
+ * 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.
+ */
 export { jsonObjectInteraction } from '../../../model/interactions/json-object.js';

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

@@ -1 +1,7 @@
+/**
+ * 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.
+ */
 export { jsonObjectInteraction } from '../../../model/interactions/json-object.js';

package/dist/esm/support/model/interactions/native-functions.d.ts

@@ -1 +1,7 @@
+/**
+ * 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.
+ */
 export { nativeFunctionInteraction } from '../../../model/interactions/native-functions.js';

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

@@ -1 +1,7 @@
+/**
+ * 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.
+ */
 export { nativeFunctionInteraction } from '../../../model/interactions/native-functions.js';

package/dist/esm/support/model/observer.d.ts

@@ -1,11 +1,34 @@
+/**
+ * Provider observation support: optional, caller-owned logging around provider calls.
+ *
+ * Observations are best effort and silent: an absent or throwing observer never changes provider
+ * results, cancellation or retry behavior. Payloads are built lazily, so disabled events cost
+ * nothing, and body capture only happens when explicitly accepted.
+ *
+ * Main exports: `providerObservation` and `createProviderObservationScope`.
+ */
 import type { ModelProviderContext } from '../../structs/model/chat-provider.js';
 import type { ProviderEventName, ProviderEventPayloads, ProviderObservation, ProviderObserver } from '../../structs/support/model/provider-observer.js';
-/** 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.
+ */
 export declare function providerObservation(observer: ProviderObserver | undefined, options: ModelProviderContext): {
     enabled: (event: ProviderEventName) => boolean;
     emit<K extends ProviderEventName>(event: K, payload: () => ProviderEventPayloads[K]): void;
 };
-/** 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.
+ */
 export declare function createProviderObservationScope<Owner>(sink: {
     accepts?(owner: Owner, descriptor: import('../../structs/support/model/provider-observer.js').ProviderEventDescriptor): boolean;
     write(owner: Owner, observation: ProviderObservation, spanId: string, content: 'metadata' | 'content'): void | Promise<void>;

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

@@ -1,8 +1,23 @@
+/**
+ * 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.
+ */
 export function providerObservation(observer, options) {
     const enabled = (event) => {
         if (!observer || !Object.hasOwn(events, event))
@@ -24,11 +39,21 @@ export 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.
+ */
 export function createProviderObservationScope(sink) {
     const owners = new WeakMap();
     const accepts = sink.accepts?.bind(sink);
@@ -40,8 +65,9 @@ export 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/esm/support/model/preview-rules.d.ts

@@ -1,17 +1,35 @@
 import type { JsonSchema } from '../../structs/common.js';
 import type { ReplyPreviewRule } from './reply-preview.js';
 export interface ReplyPreviewCapability {
+    /** Capability ID, which must equal the native function wire name used for transport. */
     readonly id: string;
+    /** Input schema used to prove that preview and eligibility paths really exist. */
     readonly jsonSchema: JsonSchema;
-    /** Explicit eligibility; never inferred from arbitrary string fields. */
+    /**
+     * Explicit preview opt-in: `true` uses the default text/bubble paths, an object narrows the
+     * paths and eligibility, and omission means the capability never previews.
+     */
     readonly preview?: true | Omit<ReplyPreviewRule, 'stageId' | 'capabilityId'>;
 }
 export interface ReplyPreviewStage {
+    /** Stage ID used by the workflow and transport projection. */
     readonly id: string;
+    /** Capabilities exposed at this stage; must be unique and registered. */
     readonly capabilityIds?: readonly string[];
+    /** `text` previews plain model text; `capabilities` previews opted-in capability arguments. */
     readonly preview?: 'text' | 'capabilities';
 }
-/** 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.
+ */
 export declare function createReplyPreviewRules(options: {
     readonly stages: readonly ReplyPreviewStage[];
     readonly capabilities: readonly ReplyPreviewCapability[];

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

@@ -1,5 +1,20 @@
+/**
+ * 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.
+ */
 import { breakWhile } from '../../utils/rules.js';
 import { wireName } from '../../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)
@@ -8,20 +23,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);
     };
@@ -30,18 +58,33 @@ function fieldExists(root, path) {
 function stringList(value, label) {
     breakWhile(!Array.isArray(value), `Invalid preview ${label}`);
     const snapshot = Array.from(value);
-    breakWhile(snapshot.some(item => typeof item !== 'string'), `Invalid preview ${label}`);
+    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.
+ */
 export function createReplyPreviewRules(options) {
     const capabilities = new Map();
     for (const capability of options.capabilities) {
@@ -58,7 +101,7 @@ export function createReplyPreviewRules(options) {
         breakWhile(!stageId || stages.has(stageId), 'Duplicate preview stage declaration');
         stages.add(stageId);
         const ids = capabilityIds === undefined ? [] : stringList(capabilityIds, 'capability IDs');
-        breakWhile(new Set(ids).size !== ids.length || ids.some(id => !capabilities.has(id)), 'Preview stage references an unknown capability');
+        breakWhile(new Set(ids).size !== ids.length || ids.some((id) => !capabilities.has(id)), 'Preview stage references an unknown capability');
         breakWhile(preview !== undefined && !['text', 'capabilities'].includes(preview), 'Unknown preview stage mode');
         if (!preview)
             continue;
@@ -73,14 +116,21 @@ export 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));
-            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));
+            breakWhile(!checkedPaths.length ||
+                checkedPaths.some((path) => !fieldExists(capability.jsonSchema, path)), `Invalid preview field: ${id}`);
             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: 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: wireName(id),
+                paths: emittedPaths,
+                ...(emittedWhen ? { when: emittedWhen } : {}),
+            }));
         }
     }
     return Object.freeze(rules);

package/dist/esm/support/model/reply-preview.d.ts

@@ -2,7 +2,9 @@ import type { ModelOutputEvent } from '../../structs/model/runtime.js';
 export interface ReplyPreviewRule {
     /** Native function wire name. Omit only for a registered plain-text stage. */
     capabilityId?: string;
+    /** Restrict the rule to one stage; omitted matches any stage producing this capability. */
     stageId?: string;
+    /** JSON paths to project, where `*` matches any array index; defaults to text/bubble paths. */
     paths?: readonly (readonly string[])[];
     /** Presentation eligibility from a complete string field in the same proposal. */
     when?: {
@@ -14,10 +16,22 @@ export interface ReplyPreviewSettings {
     rules: readonly ReplyPreviewRule[];
     /** Presentation only; must not authorize, persist or execute a proposal. */
     render?(text: string): string;
+    /** Streamed characters tolerated before preview is disabled; default 16000. */
     maxChars?: number;
 }
 export interface ReplyPreviewOptions extends ReplyPreviewSettings {
+    /** Receives the current bubble list; rejection propagates to the event caller. */
     readonly sink: (bubbles: string[]) => void | Promise<void>;
 }
-/** Only explicitly registered prose fields are projected. Tools/reviews are never selected implicitly. */
+/**
+ * Create a model-output event handler that publishes preview bubbles.
+ *
+ * The handler resets on `model.start`, ignores other invocations, disables itself on unexpected
+ * output, and clears the preview when a call ends unsuccessfully. Rules are snapshotted at
+ * creation, and only explicitly registered prose fields are projected.
+ *
+ * @param options Rules, optional renderer, character budget and the bubble sink.
+ * @returns An async handler for `ModelOutputEvent`.
+ * @throws {TypeError} When the sink is missing or `maxChars` is not a positive integer.
+ */
 export declare function createReplyPreview(options: ReplyPreviewOptions): (event: ModelOutputEvent) => Promise<void>;