@jangts/agent-core 0.3.5 → 0.5.0

package/dist/cjs/kits/{intents → domains}/scopes.js

@@ -35,7 +35,7 @@ class ScopeRegistry {
             ...(0, registration_js_1.registrationData)(policy, [
                 'idPattern',
                 'assertDefinition',
-                'acceptsIntent',
+                'acceptsTool',
                 'errors',
                 ...listFields,
             ]),
@@ -47,7 +47,7 @@ class ScopeRegistry {
                     invalid: typeof invalid === 'function' ? invalid.bind(errorPorts) : invalid,
                 }),
             assertDefinition: policy.assertDefinition?.bind(policy),
-            acceptsIntent: policy.acceptsIntent?.bind(policy),
+            acceptsTool: policy.acceptsTool?.bind(policy),
         });
     }
     /**
@@ -56,11 +56,11 @@ class ScopeRegistry {
      * Every name is checked for conflicts before any of them is stored, so a rejected scope
      * leaves no partial alias entry behind.
      *
-     * @param input - Scope declaration; the raw object is retained for `acceptsIntent` overrides
+     * @param input - Scope declaration; the raw object is retained for `acceptsTool` overrides
      *   while the compiled copy serves lookups.
      * @returns This registry, for chaining.
      * @throws A configured error for a sealed registry, an invalid name/description/category,
-     *   a missing required binding, duplicate intent ids or an already-claimed name.
+     *   a missing required binding, duplicate Tool ids or an already-claimed name.
      */
     register(input) {
         const definition = {
@@ -68,7 +68,7 @@ class ScopeRegistry {
                 'id',
                 'description',
                 'category',
-                'intentIds',
+                'goalIds',
                 'queryScopeIds',
                 'knowledgeTopicIds',
                 'toolIds',
@@ -79,7 +79,7 @@ class ScopeRegistry {
             id: input.id,
             description: input.description,
             category: input.category,
-            intentIds: input.intentIds ?? [],
+            goalIds: input.goalIds ?? [],
             queryScopeIds: input.queryScopeIds ?? [],
             knowledgeTopicIds: input.knowledgeTopicIds ?? [],
             toolIds: input.toolIds ?? [],
@@ -114,9 +114,9 @@ class ScopeRegistry {
                 tags: ['identity'],
             },
             {
-                occur: () => policy.requireIntents === true && !definition.intentIds.length,
+                occur: () => policy.requireGoals === true && !definition.goalIds.length,
                 error: invalid,
-                tags: ['intents', 'required'],
+                tags: ['goals', 'required'],
             },
             {
                 occur: [
@@ -130,18 +130,18 @@ class ScopeRegistry {
             },
             {
                 occur: [
-                    () => definition.intentIds.some((intent) => typeof intent !== 'string'),
-                    () => new Set(definition.intentIds).size !== definition.intentIds.length,
+                    () => definition.goalIds.some((intent) => typeof intent !== 'string'),
+                    () => new Set(definition.goalIds).size !== definition.goalIds.length,
                 ],
                 error: invalid,
-                tags: ['intents', 'values'],
+                tags: ['goals', 'values'],
             },
         ], tags);
         (0, synchronous_js_1.assertion)(policy.assertDefinition?.(input), 'Registry definition assertions must return void synchronously');
         (0, rules_js_1.breakWhile)(names.some((name) => this.byId.has(name) || this.aliases.has(name)), invalid, [...tags, 'duplicate']);
         const frozen = Object.freeze({
             ...definition,
-            intentIds: Object.freeze([...definition.intentIds]),
+            goalIds: Object.freeze([...definition.goalIds]),
             toolIds: Object.freeze([...definition.toolIds]),
             queryScopeIds: Object.freeze([...definition.queryScopeIds]),
             knowledgeTopicIds: Object.freeze([...definition.knowledgeTopicIds]),
@@ -207,16 +207,16 @@ class ScopeRegistry {
     /**
      * Whether a scope accepts an intent.
      *
-     * The App may override the declared `intentIds` through `acceptsIntent`; without an
+     * The App may override the declared `goalIds` through `acceptsTool`; without an
      * override the membership check applies.
      */
-    acceptsIntent(scope, goal) {
+    acceptsTool(scope, goal) {
         const definition = this.get(scope);
         if (!definition)
             return false;
-        const ids = definition.intentIds;
-        return this.policy.acceptsIntent
-            ? (0, synchronous_js_1.booleanResult)(this.policy.acceptsIntent(this.sources.get(this.normalize(scope)), goal), 'Scope intent predicates must return boolean synchronously')
+        const ids = definition.goalIds;
+        return this.policy.acceptsTool
+            ? (0, synchronous_js_1.booleanResult)(this.policy.acceptsTool(this.sources.get(this.normalize(scope)), goal), 'Scope intent predicates must return boolean synchronously')
             : ids.includes(goal);
     }
     /** Whether the scope declares this query scope; a null scope accepts nothing. */
@@ -245,18 +245,18 @@ class ScopeRegistry {
         return this.get(scope)?.contextTier;
     }
     /**
-     * Copy the scopes that accept at least one of the given intents.
+     * Copy the scopes that accept at least one of the given goals.
      *
-     * @param goals - Intent ids to filter by; omit to include every registered scope.
+     * @param goals - Goal ids to filter by; omit to include every registered scope.
      * @returns Descriptions whose arrays are copied so callers cannot mutate registry state.
      */
     describe(goals) {
         const selected = goals ? new Set(goals) : undefined;
         return [...this.byId.values()]
-            .filter((item) => !selected || item.intentIds.some((goal) => selected.has(goal)))
+            .filter((item) => !selected || item.goalIds.some((goal) => selected.has(goal)))
             .map((item) => ({
             ...item,
-            intentIds: [...item.intentIds],
+            goalIds: [...item.goalIds],
             queryScopeIds: [...item.queryScopeIds],
             knowledgeTopicIds: [...item.knowledgeTopicIds],
             toolIds: [...item.toolIds],

package/dist/cjs/kits/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reciprocalRankFusion = exports.VectorSearch = exports.ModelCalls = exports.TextSearch = exports.TextSkills = exports.Candidates = exports.Policies = exports.Evidence = exports.Retrieval = exports.Aggregation = exports.Projection = exports.Delivery = exports.Normalization = exports.Presentation = exports.Answering = exports.Knowledge = exports.Tools = exports.Intents = exports.Interaction = void 0;
+exports.reciprocalRankFusion = exports.VectorSearch = exports.ModelCalls = exports.TextBlocks = exports.TextSearch = exports.TextSkills = exports.Candidates = exports.Policies = exports.Evidence = exports.Retrieval = exports.Aggregation = exports.Projection = exports.Delivery = exports.Normalization = exports.Presentation = exports.Answering = exports.Knowledge = exports.Tools = exports.Interaction = void 0;
 /**
  * Explicit bulk Kit entry.
  *
@@ -22,23 +22,22 @@ exports.reciprocalRankFusion = exports.VectorSearch = exports.ModelCalls = expor
  * path; this file only exists for callers that prefer one import for the whole set. Core
  * never imports from this directory, so nothing here becomes a runtime requirement.
  *
- * Exports: the Kit namespaces (`Interaction`, `Intents`, `Tools`, `Knowledge`, `Answering`,
+ * Exports: the Kit namespaces (`Interaction`, `Tools`, `Knowledge`, `Answering`,
  * `Presentation`, `Normalization`, `Delivery`, `Projection`, `Aggregation`, `Retrieval`,
- * `Evidence`, `Policies`, `Candidates`, `TextSkills`, `TextSearch`, `ModelCalls`,
- * `VectorSearch`) plus every Kit type. Individual Kit paths stay the default.
+ * `Evidence`, `Policies`, `Candidates`, `TextSkills`, `TextSearch`, `TextBlocks`,
+ * `ModelCalls`, `VectorSearch`) plus every Kit type. Individual Kit paths stay the default.
  */
 var index_js_1 = require("./interaction/index.js");
 Object.defineProperty(exports, "Interaction", { enumerable: true, get: function () { return index_js_1.Interaction; } });
-var index_js_2 = require("./intents/index.js");
-Object.defineProperty(exports, "Intents", { enumerable: true, get: function () { return index_js_2.Intents; } });
+__exportStar(require("./domains/index.js"), exports);
 var tools_js_1 = require("./tools.js");
 Object.defineProperty(exports, "Tools", { enumerable: true, get: function () { return tools_js_1.Tools; } });
-var index_js_3 = require("./knowledge/index.js");
-Object.defineProperty(exports, "Knowledge", { enumerable: true, get: function () { return index_js_3.Knowledge; } });
-var index_js_4 = require("./answering/index.js");
-Object.defineProperty(exports, "Answering", { enumerable: true, get: function () { return index_js_4.Answering; } });
-var index_js_5 = require("./presentation/index.js");
-Object.defineProperty(exports, "Presentation", { enumerable: true, get: function () { return index_js_5.Presentation; } });
+var index_js_2 = require("./knowledge/index.js");
+Object.defineProperty(exports, "Knowledge", { enumerable: true, get: function () { return index_js_2.Knowledge; } });
+var index_js_3 = require("./answering/index.js");
+Object.defineProperty(exports, "Answering", { enumerable: true, get: function () { return index_js_3.Answering; } });
+var index_js_4 = require("./presentation/index.js");
+Object.defineProperty(exports, "Presentation", { enumerable: true, get: function () { return index_js_4.Presentation; } });
 var normalization_js_1 = require("./normalization.js");
 Object.defineProperty(exports, "Normalization", { enumerable: true, get: function () { return normalization_js_1.Normalization; } });
 var delivery_js_1 = require("./delivery.js");
@@ -60,9 +59,11 @@ Object.defineProperty(exports, "TextSkills", { enumerable: true, get: function (
 var search_js_1 = require("./search.js");
 Object.defineProperty(exports, "TextSearch", { enumerable: true, get: function () { return search_js_1.TextSearch; } });
 __exportStar(require("./search.js"), exports);
+var text_blocks_js_1 = require("./text-blocks.js");
+Object.defineProperty(exports, "TextBlocks", { enumerable: true, get: function () { return text_blocks_js_1.TextBlocks; } });
+__exportStar(require("./text-blocks.js"), exports);
 // Types remain available with either individual or explicit bulk imports.
 __exportStar(require("./interaction/index.js"), exports);
-__exportStar(require("./intents/index.js"), exports);
 __exportStar(require("./tools.js"), exports);
 __exportStar(require("./knowledge/index.js"), exports);
 __exportStar(require("./answering/index.js"), exports);

package/dist/cjs/kits/knowledge/catalog.js

@@ -10,6 +10,7 @@ exports.defineKnowledgeCatalog = defineKnowledgeCatalog;
  *
  * Exports: `defineKnowledgeCatalog`, and the knowledge document/read/snapshot types.
  */
+const native_sub_flow_js_1 = require("../../diagnostics/native-sub-flow.js");
 const catalog_js_1 = require("../../utils/catalog.js");
 const sections_js_1 = require("./sections.js");
 const observer_js_1 = require("../../utils/observer.js");
@@ -68,37 +69,39 @@ function defineKnowledgeCatalog(documents, options = {}) {
         ...(0, catalog_js_1.readonlyCatalog)([...catalog.values()].map((entry) => entry.document), (id) => new TypeError(`Unknown knowledge document: ${id}`)),
         sectionIds,
         assertSelection,
-        read(input) {
-            const { read, entry } = resolve(input), raw = read.selection;
-            const selection = raw.mode === 'document'
-                ? Object.freeze({ mode: 'document' })
-                : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
-            const content = (selection.mode === 'document'
-                ? (0, sections_js_1.knowledgeText)(entry.document.parts)
-                : selection.sectionIds
-                    .map((id) => (0, sections_js_1.knowledgeText)(entry.sections.get(id).parts, selection.mode === 'subtree'))
-                    .join('\n\n')).trim();
-            if (maxChars !== undefined && content.length > maxChars)
-                throw new RangeError('Knowledge selection exceeds its budget');
-            // Preserve the existing opaque snapshot identity format.
-            const identitySelection = selection.mode === 'document'
-                ? selection
-                : { mode: selection.mode, sections: selection.sectionIds };
-            const snapshot = Object.freeze({
-                documentId: read.documentId,
-                selection,
-                revision: entry.document.revision,
-                locale: entry.document.locale,
-                content,
-                id: JSON.stringify([
-                    read.documentId,
-                    entry.document.revision,
-                    entry.document.locale,
-                    identitySelection,
-                ]),
+        read(input, context = {}) {
+            return (0, native_sub_flow_js_1.nativeSubFlowSync)(context, 'knowledge', input.documentId, () => {
+                const { read, entry } = resolve(input), raw = read.selection;
+                const selection = raw.mode === 'document'
+                    ? Object.freeze({ mode: 'document' })
+                    : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
+                const content = (selection.mode === 'document'
+                    ? (0, sections_js_1.knowledgeText)(entry.document.parts)
+                    : selection.sectionIds
+                        .map((id) => (0, sections_js_1.knowledgeText)(entry.sections.get(id).parts, selection.mode === 'subtree'))
+                        .join('\n\n')).trim();
+                if (maxChars !== undefined && content.length > maxChars)
+                    throw new RangeError('Knowledge selection exceeds its budget');
+                // Preserve the existing opaque snapshot identity format.
+                const identitySelection = selection.mode === 'document'
+                    ? selection
+                    : { mode: selection.mode, sections: selection.sectionIds };
+                const snapshot = Object.freeze({
+                    documentId: read.documentId,
+                    selection,
+                    revision: entry.document.revision,
+                    locale: entry.document.locale,
+                    content,
+                    id: JSON.stringify([
+                        read.documentId,
+                        entry.document.revision,
+                        entry.document.locale,
+                        identitySelection,
+                    ]),
+                });
+                (0, observer_js_1.observeSafely)(observe, snapshot);
+                return snapshot;
             });
-            (0, observer_js_1.observeSafely)(observe, snapshot);
-            return snapshot;
         },
     });
 }

package/dist/cjs/kits/policies.js

@@ -12,6 +12,7 @@ exports.defineRecoveryChain = defineRecoveryChain;
  *
  * Exports: `definePolicySet`, `defineRecoveryChain`, `Policies`, and the policy types.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const catalog_js_1 = require("../utils/catalog.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
@@ -70,9 +71,9 @@ function defineRecoveryChain(definitions) {
             },
         });
     });
-    const tryRecover = (input) => {
+    const tryRecover = (input, execution = {}) => {
         for (const policy of catalog) {
-            const result = policy.tryRecover(input);
+            const result = (0, native_sub_flow_js_1.nativeSubFlowSync)(execution, 'recovery', policy.id, () => policy.tryRecover(input));
             if (result.handled)
                 return result;
         }

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

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replyFormatChecks = void 0;
+exports.mergeReplyBubbles = mergeReplyBubbles;
+exports.defineReplyFormats = defineReplyFormats;
+/**
+ * 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.
+ */
+const rules_js_1 = require("../../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.
+ */
+exports.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) {
+        (0, rules_js_1.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) {
+        (0, rules_js_1.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.
+ */
+function mergeReplyBubbles(bubbles, limit) {
+    (0, rules_js_1.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`.
+ */
+function defineReplyFormats(options) {
+    const { formats, checks } = options;
+    (0, rules_js_1.breakWhile)(!formats?.length || !checks?.length, 'Reply formats require formats and checks');
+    const checkMap = new Map();
+    for (const check of checks) {
+        (0, rules_js_1.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) => {
+        (0, rules_js_1.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/cjs/kits/presentation/index.js

@@ -16,27 +16,32 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Presentation = void 0;
 /**
- * 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.
  */
 __exportStar(require("./outputs.js"), exports);
+__exportStar(require("./formats.js"), exports);
 __exportStar(require("./variants.js"), exports);
 __exportStar(require("./templates.js"), exports);
 __exportStar(require("./events.js"), exports);
 const outputs_js_1 = require("./outputs.js");
+const formats_js_1 = require("./formats.js");
 const templates_js_1 = require("./templates.js");
 const variants_js_1 = require("./variants.js");
 const events_js_1 = require("./events.js");
 /** Namespace object for callers that prefer one import over named helpers. */
 exports.Presentation = Object.freeze({
     defineOutputCatalog: outputs_js_1.defineOutputCatalog,
+    defineReplyFormats: formats_js_1.defineReplyFormats,
+    replyFormatChecks: formats_js_1.replyFormatChecks,
+    mergeReplyBubbles: formats_js_1.mergeReplyBubbles,
     defineTextTemplate: templates_js_1.defineTextTemplate,
     defineSemanticSlots: templates_js_1.defineSemanticSlots,
     selectVariant: variants_js_1.selectVariant,

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

@@ -10,6 +10,7 @@ exports.defineOutputCatalog = defineOutputCatalog;
  *
  * Exports: `defineOutputCatalog`, and the output definition/field/provider/result types.
  */
+const native_sub_flow_js_1 = require("../../diagnostics/native-sub-flow.js");
 const schema_adapter_js_1 = require("../../utils/schema-adapter.js");
 const catalog_js_1 = require("../../utils/catalog.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
@@ -324,7 +325,7 @@ 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 (0, native_sub_flow_js_1.nativeSubFlowSync)(context, 'output', request.outputId, () => composeInternal(request.outputId, request.input, context));
         },
     });
 }

package/dist/cjs/kits/reflection.js

@@ -229,7 +229,7 @@ function defineReflection(definition) {
                 ...extraTools,
             ];
             const catalog = (0, tools_js_1.defineToolCatalog)(toolDefinitions);
-            const capabilities = (0, capabilities_js_1.defineModelCapabilities)([
+            const modelTools = (0, capabilities_js_1.defineModelTools)([
                 ...catalog.definitions.map((tool) => ({
                     id: tool.id,
                     description: tool.description,
@@ -248,7 +248,7 @@ function defineReflection(definition) {
             ]);
             const transport = (0, selection_transport_js_1.createModelTransport)({
                 id: 'core:reflection',
-                capabilities,
+                tools: modelTools,
                 adapter: json_object_js_1.jsonObjectInteraction,
             });
             const child = model.createChild({

package/dist/cjs/kits/retrieval.js

@@ -12,6 +12,7 @@ exports.defineRetrieval = defineRetrieval;
  *
  * Exports: `defineRetrieval`, `retrievalQueryKey`, `Retrieval`, and the retrieval port types.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const query_key_js_1 = require("../utils/query-key.js");
 const rules_js_1 = require("../utils/rules.js");
@@ -148,7 +149,12 @@ function defineRetrieval(definition) {
         }
         return receipt;
     }
-    return Object.freeze({ id, description, effects, run });
+    return Object.freeze({
+        id,
+        description,
+        effects,
+        run: (input, context) => (0, native_sub_flow_js_1.nativeSubFlowSync)(context, 'retrieval', id, () => run(input, context)),
+    });
 }
 function reason(value, query, context) {
     return () => (typeof value === 'function' ? value(query, context) : value);

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

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TextBlocks = void 0;
+exports.splitTextBlocks = splitTextBlocks;
+/**
+ * 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.
+ */
+const rules_js_1 = require("../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.
+ */
+function splitTextBlocks(text, options) {
+    (0, rules_js_1.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. */
+exports.TextBlocks = { split: splitTextBlocks };