@jangts/agent-core 0.3.5 → 0.5.0

package/dist/esm/kits/policies.js

@@ -7,6 +7,7 @@
  *
  * Exports: `definePolicySet`, `defineRecoveryChain`, `Policies`, and the policy types.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { readonlyCatalog } from '../utils/catalog.js';
 import { synchronous, booleanResult } from '../utils/synchronous.js';
 import { breakWhile } from '../utils/rules.js';
@@ -65,9 +66,9 @@ export function defineRecoveryChain(definitions) {
             },
         });
     });
-    const tryRecover = (input) => {
+    const tryRecover = (input, execution = {}) => {
         for (const policy of catalog) {
-            const result = policy.tryRecover(input);
+            const result = nativeSubFlowSync(execution, 'recovery', policy.id, () => policy.tryRecover(input));
             if (result.handled)
                 return result;
         }

package/dist/esm/kits/presentation/formats.d.ts

@@ -0,0 +1,42 @@
+import type { CompiledReplyFormat, ReplyFormatCheck, ReplyFormatOptions } from '../../structs/kits/presentation/formats.js';
+/**
+ * Checks shared by text replies. Limits stay with the App template; only the comparison lives here.
+ */
+export declare const replyFormatChecks: Readonly<{
+    /**
+     * Every bubble is non-empty and the total (primary text included) stays within the limit.
+     *
+     * @param totalLimit - Maximum bubble count including the primary text.
+     * @returns The reusable `bubbles` check.
+     */
+    bubbles(totalLimit: number): ReplyFormatCheck;
+    /**
+     * The joined reply stays within the app's text budget.
+     *
+     * @param maxChars - Maximum total characters across bubbles.
+     * @returns The reusable `text-budget` check.
+     */
+    textBudget(maxChars: number): ReplyFormatCheck;
+}>;
+/**
+ * Normalize a reply that has no declared format: drop blank bubbles and merge overflow into the
+ * last allowed one. Text content is preserved.
+ *
+ * @param bubbles - Primary text followed by follow-up bubbles.
+ * @param limit - Maximum number of bubbles to keep.
+ * @returns Non-empty bubbles within the limit.
+ */
+export declare function mergeReplyBubbles(bubbles: readonly string[], limit: number): string[];
+/**
+ * Compile reply formats so that checks run only for templates the current turn uses.
+ *
+ * @param options - Declared formats and the checks their ids refer to.
+ * @returns A frozen catalog with `resolve(context)`.
+ * @throws TypeError For duplicate or invalid ids, a format without checks, an unknown check id,
+ *   or a non-function `when`/`accepts`.
+ */
+export declare function defineReplyFormats<Context = unknown>(options: ReplyFormatOptions<Context>): Readonly<{
+    /** The template this turn uses, or `undefined` when it has no output-format requirement. */
+    resolve(context: Context): CompiledReplyFormat | undefined;
+}>;
+export type { CompiledReplyFormat, ReplyFormatCheck, ReplyFormatDefinition, ReplyFormatOptions, } from '../../structs/kits/presentation/formats.js';

package/dist/esm/kits/presentation/formats.js

@@ -0,0 +1,105 @@
+/**
+ * Presentation Kit: template-bound reply formats and their shared checks.
+ *
+ * Place in the package: part of the `presentation` Kit. A format is declared only where the App
+ * owns a template for the final reply; `resolve` returns `undefined` for every other reply, so the
+ * caller has no output-format requirement and does not re-ask the model. Apps keep their own copy,
+ * limits and checks; this module only compiles the declarations and evaluates failures.
+ *
+ * Exports: `defineReplyFormats`, `replyFormatChecks`, `mergeReplyBubbles`, and their types.
+ */
+import { breakWhile } from '../../utils/rules.js';
+const validId = (id) => typeof id === 'string' && /^[a-z][a-z0-9-]*$/.test(id);
+/**
+ * Checks shared by text replies. Limits stay with the App template; only the comparison lives here.
+ */
+export const replyFormatChecks = Object.freeze({
+    /**
+     * Every bubble is non-empty and the total (primary text included) stays within the limit.
+     *
+     * @param totalLimit - Maximum bubble count including the primary text.
+     * @returns The reusable `bubbles` check.
+     */
+    bubbles(totalLimit) {
+        breakWhile(!Number.isSafeInteger(totalLimit) || totalLimit < 1, 'Bubble limit must be a positive integer');
+        return Object.freeze({
+            id: 'bubbles',
+            description: `回复气泡总数不超过 ${totalLimit} 条且每条非空。`,
+            accepts: (bubbles) => bubbles.length >= 1 &&
+                bubbles.length <= totalLimit &&
+                bubbles.every((text) => typeof text === 'string' && !!text.trim()),
+        });
+    },
+    /**
+     * The joined reply stays within the app's text budget.
+     *
+     * @param maxChars - Maximum total characters across bubbles.
+     * @returns The reusable `text-budget` check.
+     */
+    textBudget(maxChars) {
+        breakWhile(!Number.isSafeInteger(maxChars) || maxChars < 1, 'Text budget must be a positive integer');
+        return Object.freeze({
+            id: 'text-budget',
+            description: `回复正文总长不超过 ${maxChars} 字符。`,
+            accepts: (bubbles) => bubbles.reduce((length, text) => length + (typeof text === 'string' ? text.length : 0), 0) <= maxChars,
+        });
+    },
+});
+/**
+ * Normalize a reply that has no declared format: drop blank bubbles and merge overflow into the
+ * last allowed one. Text content is preserved.
+ *
+ * @param bubbles - Primary text followed by follow-up bubbles.
+ * @param limit - Maximum number of bubbles to keep.
+ * @returns Non-empty bubbles within the limit.
+ */
+export function mergeReplyBubbles(bubbles, limit) {
+    breakWhile(!Number.isSafeInteger(limit) || limit < 1, 'Bubble limit must be a positive integer');
+    const kept = bubbles.map((text) => text.trim()).filter(Boolean);
+    // 超出部分按原顺序合并到最后一条允许的气泡，不改变正文内容。
+    if (kept.length > limit)
+        kept.push(kept.splice(limit - 1).join('\n\n'));
+    return kept;
+}
+/**
+ * Compile reply formats so that checks run only for templates the current turn uses.
+ *
+ * @param options - Declared formats and the checks their ids refer to.
+ * @returns A frozen catalog with `resolve(context)`.
+ * @throws TypeError For duplicate or invalid ids, a format without checks, an unknown check id,
+ *   or a non-function `when`/`accepts`.
+ */
+export function defineReplyFormats(options) {
+    const { formats, checks } = options;
+    breakWhile(!formats?.length || !checks?.length, 'Reply formats require formats and checks');
+    const checkMap = new Map();
+    for (const check of checks) {
+        breakWhile(!validId(check.id) || checkMap.has(check.id) || typeof check.accepts !== 'function', 'Invalid reply format check');
+        checkMap.set(check.id, Object.freeze({ ...check, accepts: check.accepts.bind(check) }));
+    }
+    const seen = new Set();
+    const compiled = formats.map((format) => {
+        breakWhile(!validId(format.id) ||
+            seen.has(format.id) ||
+            typeof format.when !== 'function' ||
+            !format.checks?.length ||
+            format.checks.some((id) => !checkMap.has(id)), 'Invalid reply format');
+        seen.add(format.id);
+        const required = Object.freeze([...format.checks]);
+        return Object.freeze({
+            id: format.id,
+            description: format.description,
+            checks: required,
+            when: format.when,
+            inspect(bubbles) {
+                return required.map((id) => checkMap.get(id)).filter((check) => !check.accepts(bubbles));
+            },
+        });
+    });
+    return Object.freeze({
+        /** The template this turn uses, or `undefined` when it has no output-format requirement. */
+        resolve(context) {
+            return compiled.find((format) => format.when(context));
+        },
+    });
+}

package/dist/esm/kits/presentation/index.d.ts

@@ -1,26 +1,35 @@
 /**
- * Presentation Kit entry: output contracts, text templates, semantic slots, variants and the
- * reply/chunk event stream.
+ * Presentation Kit entry: output contracts, text templates, semantic slots, reply formats,
+ * variants and the reply/chunk event stream.
  *
  * Place in the package: an optional App-side library for shaping what the user finally sees.
  * The App owns copy, styling and transport; this directory owns contract validation, template
- * substitution, variant selection and the bubble/chunk protocol.
+ * substitution, format checks, variant selection and the bubble/chunk protocol.
  *
- * Exports: everything from `./outputs.js`, `./variants.js`, `./templates.js` and `./events.js`,
- * plus the `Presentation` namespace object.
+ * Exports: everything from `./outputs.js`, `./formats.js`, `./variants.js`, `./templates.js` and
+ * `./events.js`, plus the `Presentation` namespace object.
  */
 export * from './outputs.js';
+export * from './formats.js';
 export * from './variants.js';
 export type * from '../../structs/kits/presentation/outputs.js';
+export type * from '../../structs/kits/presentation/formats.js';
 export * from './templates.js';
 export * from './events.js';
 import { defineOutputCatalog } from './outputs.js';
+import { defineReplyFormats, mergeReplyBubbles } from './formats.js';
 import { defineTextTemplate, defineSemanticSlots } from './templates.js';
 import { selectVariant, resolvePreference } from './variants.js';
 import { replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents } from './events.js';
 /** Namespace object for callers that prefer one import over named helpers. */
 export declare const Presentation: Readonly<{
     defineOutputCatalog: typeof defineOutputCatalog;
+    defineReplyFormats: typeof defineReplyFormats;
+    replyFormatChecks: Readonly<{
+        bubbles(totalLimit: number): import("./formats.js").ReplyFormatCheck;
+        textBudget(maxChars: number): import("./formats.js").ReplyFormatCheck;
+    }>;
+    mergeReplyBubbles: typeof mergeReplyBubbles;
     defineTextTemplate: typeof defineTextTemplate;
     defineSemanticSlots: typeof defineSemanticSlots;
     selectVariant: typeof selectVariant;

package/dist/esm/kits/presentation/index.js

@@ -1,25 +1,30 @@
 /**
- * Presentation Kit entry: output contracts, text templates, semantic slots, variants and the
- * reply/chunk event stream.
+ * Presentation Kit entry: output contracts, text templates, semantic slots, reply formats,
+ * variants and the reply/chunk event stream.
  *
  * Place in the package: an optional App-side library for shaping what the user finally sees.
  * The App owns copy, styling and transport; this directory owns contract validation, template
- * substitution, variant selection and the bubble/chunk protocol.
+ * substitution, format checks, variant selection and the bubble/chunk protocol.
  *
- * Exports: everything from `./outputs.js`, `./variants.js`, `./templates.js` and `./events.js`,
- * plus the `Presentation` namespace object.
+ * Exports: everything from `./outputs.js`, `./formats.js`, `./variants.js`, `./templates.js` and
+ * `./events.js`, plus the `Presentation` namespace object.
  */
 export * from './outputs.js';
+export * from './formats.js';
 export * from './variants.js';
 export * from './templates.js';
 export * from './events.js';
 import { defineOutputCatalog } from './outputs.js';
+import { defineReplyFormats, mergeReplyBubbles, replyFormatChecks } from './formats.js';
 import { defineTextTemplate, defineSemanticSlots } from './templates.js';
 import { selectVariant, resolvePreference } from './variants.js';
 import { REPLY_BUBBLE_BOUNDARY, replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents, } from './events.js';
 /** Namespace object for callers that prefer one import over named helpers. */
 export const Presentation = Object.freeze({
     defineOutputCatalog,
+    defineReplyFormats,
+    replyFormatChecks,
+    mergeReplyBubbles,
     defineTextTemplate,
     defineSemanticSlots,
     selectVariant,

package/dist/esm/kits/presentation/outputs.js

@@ -7,6 +7,7 @@
  *
  * Exports: `defineOutputCatalog`, and the output definition/field/provider/result types.
  */
+import { nativeSubFlowSync } from '../../diagnostics/native-sub-flow.js';
 import { snapshotSchemaAdapter } from '../../utils/schema-adapter.js';
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { synchronous } from '../../utils/synchronous.js';
@@ -321,7 +322,7 @@ export function defineOutputCatalog(definitions, options = {}) {
                 throw new TypeError('Use a named output request');
             if (!context?.signal)
                 throw new TypeError('Output composition requires OperationContext');
-            return composeInternal(request.outputId, request.input, context);
+            return nativeSubFlowSync(context, 'output', request.outputId, () => composeInternal(request.outputId, request.input, context));
         },
     });
 }

package/dist/esm/kits/reflection.js

@@ -11,7 +11,7 @@
  */
 import { AgentCoreEngine } from '../execution/engine.js';
 import { defineToolCatalog } from '../support/tools.js';
-import { defineModelCapabilities } from '../support/model/capabilities.js';
+import { defineModelTools } from '../support/model/capabilities.js';
 import { createModelTransport } from '../model/selection-transport.js';
 import { jsonObjectInteraction } from '../model/interactions/json-object.js';
 import { coreEventCatalog } from '../diagnostics/catalog.js';
@@ -225,7 +225,7 @@ export function defineReflection(definition) {
                 ...extraTools,
             ];
             const catalog = defineToolCatalog(toolDefinitions);
-            const capabilities = defineModelCapabilities([
+            const modelTools = defineModelTools([
                 ...catalog.definitions.map((tool) => ({
                     id: tool.id,
                     description: tool.description,
@@ -244,7 +244,7 @@ export function defineReflection(definition) {
             ]);
             const transport = createModelTransport({
                 id: 'core:reflection',
-                capabilities,
+                tools: modelTools,
                 adapter: jsonObjectInteraction,
             });
             const child = model.createChild({

package/dist/esm/kits/retrieval.js

@@ -8,6 +8,7 @@
  *
  * Exports: `defineRetrieval`, `retrievalQueryKey`, `Retrieval`, and the retrieval port types.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { assertion, synchronous } from '../utils/synchronous.js';
 import { retrievalQueryKey } from '../utils/query-key.js';
 import { breakWhile } from '../utils/rules.js';
@@ -144,7 +145,12 @@ export function defineRetrieval(definition) {
         }
         return receipt;
     }
-    return Object.freeze({ id, description, effects, run });
+    return Object.freeze({
+        id,
+        description,
+        effects,
+        run: (input, context) => nativeSubFlowSync(context, 'retrieval', id, () => run(input, context)),
+    });
 }
 function reason(value, query, context) {
     return () => (typeof value === 'function' ? value(query, context) : value);

package/dist/esm/kits/text-blocks.d.ts

@@ -0,0 +1,24 @@
+import type { TextBlock, TextBlockOptions } from '../structs/kits/text-blocks.js';
+/**
+ * Split long plain text on structural boundaries.
+ *
+ * Headings and horizontal rules start a new block, blank lines end the current one, and all
+ * other lines break only when the target size would be exceeded. A single line longer than
+ * the target becomes its own block so that paging can cut it into fragments later without
+ * splitting the line into unrelated sections. Concatenating every block reproduces the input
+ * exactly: no truncation, padding or dropped whitespace.
+ *
+ * The input must be plain text; binaries and rich documents are read elsewhere.
+ *
+ * @param text - Decoded source text.
+ * @param options - Target block size in characters.
+ * @returns Blocks in source order, each with one-based `number` and source offsets. Empty
+ *   text returns an empty list.
+ * @throws TypeError When the text is not a string or `targetChars` is not a positive integer.
+ */
+export declare function splitTextBlocks(text: string, options: TextBlockOptions): TextBlock[];
+/** Namespace form of the Kit, for callers that prefer one aggregate entry. */
+export declare const TextBlocks: {
+    readonly split: typeof splitTextBlocks;
+};
+export type { TextBlock, TextBlockOptions } from '../structs/kits/text-blocks.js';

package/dist/esm/kits/text-blocks.js

@@ -0,0 +1,97 @@
+/**
+ * Text Blocks Kit: structure-aware splitting for long plain text.
+ *
+ * Place in the package: an optional App-side helper used before a long document is paged
+ * into a model or indexed for retrieval. The Kit owns boundary selection, block numbering
+ * and exact reassembly; file reading, paging, search, storage and prompt wording stay with
+ * the App. No model call or Core dependency is involved.
+ *
+ * Exports: `splitTextBlocks`, `TextBlocks` and the block option/result types.
+ */
+import { breakWhile } from '../utils/rules.js';
+/**
+ * Whether one line starts a new structural section.
+ *
+ * @param line - A full line including its trailing newline.
+ * @returns `true` for Markdown headings and horizontal rules.
+ */
+function headingLine(line) {
+    return /^\s*#{1,6}\s/.test(line) || /^\s*(?:[-*_]{3,}|={3,})\s*$/.test(line);
+}
+/**
+ * Split long plain text on structural boundaries.
+ *
+ * Headings and horizontal rules start a new block, blank lines end the current one, and all
+ * other lines break only when the target size would be exceeded. A single line longer than
+ * the target becomes its own block so that paging can cut it into fragments later without
+ * splitting the line into unrelated sections. Concatenating every block reproduces the input
+ * exactly: no truncation, padding or dropped whitespace.
+ *
+ * The input must be plain text; binaries and rich documents are read elsewhere.
+ *
+ * @param text - Decoded source text.
+ * @param options - Target block size in characters.
+ * @returns Blocks in source order, each with one-based `number` and source offsets. Empty
+ *   text returns an empty list.
+ * @throws TypeError When the text is not a string or `targetChars` is not a positive integer.
+ */
+export function splitTextBlocks(text, options) {
+    breakWhile(typeof text !== 'string' ||
+        !options ||
+        !Number.isSafeInteger(options.targetChars) ||
+        options.targetChars < 1, 'Text block splitting requires text and a positive integer target size');
+    const targetChars = options.targetChars;
+    const blocks = [];
+    let buffer = '';
+    let bufferStart = 0;
+    let cursor = 0;
+    const flush = () => {
+        if (!buffer)
+            return;
+        const previous = blocks.at(-1);
+        if (!buffer.trim() && previous) {
+            // Whitespace-only blocks carry no section, so they stay attached to the previous block
+            // instead of becoming a block the reader has to page through.
+            blocks[blocks.length - 1] = {
+                ...previous,
+                text: previous.text + buffer,
+                end: previous.end + buffer.length,
+            };
+        }
+        else {
+            blocks.push({ number: blocks.length + 1, text: buffer, start: bufferStart, end: cursor });
+        }
+        buffer = '';
+    };
+    // Keeping a line's trailing newline makes every block reassemble into the original text,
+    // including CRLF input.
+    for (const line of text.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+        if (line.length > targetChars) {
+            flush();
+            blocks.push({
+                number: blocks.length + 1,
+                text: line,
+                start: cursor,
+                end: cursor + line.length,
+            });
+            cursor += line.length;
+            continue;
+        }
+        if (headingLine(line))
+            flush();
+        if (buffer.length + line.length > targetChars)
+            flush();
+        if (!buffer)
+            bufferStart = cursor;
+        buffer += line;
+        cursor += line.length;
+        if ((!line.trim() || headingLine(line)) && buffer.length >= targetChars / 2)
+            flush();
+        else if (buffer.length >= targetChars)
+            flush();
+    }
+    flush();
+    return blocks;
+}
+/** Namespace form of the Kit, for callers that prefer one aggregate entry. */
+export const TextBlocks = { split: splitTextBlocks };