@jangts/agent-core 0.3.5 → 0.5.0

package/dist/cjs/kits/answering/tasks.js

@@ -11,6 +11,7 @@ exports.defineAnswerTaskCatalog = defineAnswerTaskCatalog;
  *
  * Exports: `defineAnswerReaderCatalog`, `defineAnswerTaskCatalog`, and the task/reader 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 object_js_1 = require("../../utils/object.js");
@@ -54,10 +55,10 @@ function defineAnswerTaskCatalog(definitions, ports) {
             !definition.description?.trim() ||
             !readers.has(definition.readerId) ||
             !outputs.has(definition.outputId) ||
-            !Array.isArray(definition.intentIds) ||
-            !definition.intentIds.length ||
-            definition.intentIds.some((id) => typeof id !== 'string' || !id.trim()) ||
-            new Set(definition.intentIds).size !== definition.intentIds.length ||
+            !Array.isArray(definition.goalIds) ||
+            !definition.goalIds.length ||
+            definition.goalIds.some((id) => typeof id !== 'string' || !id.trim()) ||
+            new Set(definition.goalIds).size !== definition.goalIds.length ||
             !Array.isArray(definition.checkIds) ||
             new Set(definition.checkIds).size !== definition.checkIds.length ||
             definition.checkIds.some((id) => !checkIds.includes(id)))
@@ -71,7 +72,7 @@ function defineAnswerTaskCatalog(definitions, ports) {
             readerId: definition.readerId,
             outputId: definition.outputId,
             scopeId: definition.scopeId,
-            intentIds: Object.freeze([...definition.intentIds]),
+            goalIds: Object.freeze([...definition.goalIds]),
             checkIds: Object.freeze([...definition.checkIds]),
             inputSchema: (0, schema_adapter_js_1.snapshotSchemaAdapter)(definition.inputSchema),
             metadata,
@@ -100,16 +101,18 @@ function defineAnswerTaskCatalog(definitions, ports) {
          * @throws TypeError For an unknown task, a parse failure, or a reader returning a Promise.
          */
         read(request, context) {
-            const { input, task, reader } = prepare(request, context);
-            const value = (0, synchronous_js_1.synchronous)(reader.read(input, {
-                ...context,
-                app: context.app,
-                signal: context.signal,
-                diagnostics: context.diagnostics,
-                task,
-            }), 'Synchronous answer readers must not return a Promise');
-            context.signal.throwIfAborted();
-            return value;
+            return (0, native_sub_flow_js_1.nativeSubFlowSync)(context, 'task', request.taskId, () => {
+                const { input, task, reader } = prepare(request, context);
+                const value = (0, synchronous_js_1.synchronous)(reader.read(input, {
+                    ...context,
+                    app: context.app,
+                    signal: context.signal,
+                    diagnostics: context.diagnostics,
+                    task,
+                }), 'Synchronous answer readers must not return a Promise');
+                context.signal.throwIfAborted();
+                return value;
+            });
         },
         /**
          * Read evidence through a task's registered reader, awaiting an async reader.
@@ -117,16 +120,18 @@ function defineAnswerTaskCatalog(definitions, ports) {
          * @throws TypeError For an unknown task or a parse failure; aborts with the caller's signal.
          */
         async readAsync(request, context) {
-            const { input, task, reader } = prepare(request, context);
-            const value = await (0, cancellation_js_1.awaitWithSignal)(reader.read(input, {
-                ...context,
-                app: context.app,
-                signal: context.signal,
-                diagnostics: context.diagnostics,
-                task,
-            }), context.signal);
-            context.signal.throwIfAborted();
-            return value;
+            return (0, native_sub_flow_js_1.nativeSubFlowAsync)(context, 'task', request.taskId, async () => {
+                const { input, task, reader } = prepare(request, context);
+                const value = await (0, cancellation_js_1.awaitWithSignal)(reader.read(input, {
+                    ...context,
+                    app: context.app,
+                    signal: context.signal,
+                    diagnostics: context.diagnostics,
+                    task,
+                }), context.signal);
+                context.signal.throwIfAborted();
+                return value;
+            });
         },
     });
 }

package/dist/cjs/kits/delivery.js

@@ -2,6 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Delivery = void 0;
 exports.defineDelivery = defineDelivery;
+/**
+ * Delivery Kit: run an ordered, synchronous stage pipeline that ends with one result.
+ *
+ * Place in the package: an optional App-side delivery pipeline (for example formatting and
+ * sending one reply). The Kit owns ordering, cancellation checks and outcome validation; the
+ * stages, their state and the actual side effects belong to the App.
+ *
+ * Exports: `defineDelivery`, `Delivery`, and the delivery option/outcome types.
+ */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 /**
  * Compile a delivery pipeline from its declared stages.
@@ -42,33 +52,35 @@ function defineDelivery(options) {
          *   handler results.
          */
         deliver(input, execution) {
-            execution.signal.throwIfAborted();
-            const state = (0, synchronous_js_1.synchronous)(createState(input, execution), 'Delivery state creation must be synchronous');
-            const context = {
-                ...execution,
-                signal: execution.signal,
-                diagnostics: execution.diagnostics,
-                app: input,
-            };
-            for (const stage of stages) {
+            return (0, native_sub_flow_js_1.nativeSubFlowSync)(execution, 'delivery', 'delivery', () => {
                 execution.signal.throwIfAborted();
-                (0, synchronous_js_1.synchronous)(beforeStage?.({ stageId: stage.id, state }, context), 'Delivery hooks must be synchronous');
-                execution.signal.throwIfAborted();
-                if (!stage.handle)
-                    continue;
-                const outcome = (0, synchronous_js_1.synchronous)(stage.handle(state, context), 'Delivery handlers must be synchronous');
-                execution.signal.throwIfAborted();
-                if (!outcome ||
-                    !['continue', 'complete'].includes(outcome.type) ||
-                    (outcome.type === 'complete' && !('value' in outcome)))
-                    throw new TypeError('Delivery handlers require explicit continue/complete');
-                if (outcome.type === 'complete') {
-                    const value = outcome.value;
+                const state = (0, synchronous_js_1.synchronous)(createState(input, execution), 'Delivery state creation must be synchronous');
+                const context = {
+                    ...execution,
+                    signal: execution.signal,
+                    diagnostics: execution.diagnostics,
+                    app: input,
+                };
+                for (const stage of stages) {
+                    execution.signal.throwIfAborted();
+                    (0, synchronous_js_1.synchronous)(beforeStage?.({ stageId: stage.id, state }, context), 'Delivery hooks must be synchronous');
+                    execution.signal.throwIfAborted();
+                    if (!stage.handle)
+                        continue;
+                    const outcome = (0, synchronous_js_1.synchronous)(stage.handle(state, context), 'Delivery handlers must be synchronous');
                     execution.signal.throwIfAborted();
-                    return value;
+                    if (!outcome ||
+                        !['continue', 'complete'].includes(outcome.type) ||
+                        (outcome.type === 'complete' && !('value' in outcome)))
+                        throw new TypeError('Delivery handlers require explicit continue/complete');
+                    if (outcome.type === 'complete') {
+                        const value = outcome.value;
+                        execution.signal.throwIfAborted();
+                        return value;
+                    }
                 }
-            }
-            throw (0, synchronous_js_1.synchronous)(missingResult(), 'Delivery errors must be synchronous');
+                throw (0, synchronous_js_1.synchronous)(missingResult(), 'Delivery errors must be synchronous');
+            });
         },
     });
 }

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

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAgentCatalog = defineAgentCatalog;
+/**
+ * Domain Tools Kit: project registered goals, scopes and tools into one task-facing catalog.
+ *
+ * Place in the package: part of the domain Tool Kit. It reads the actual registries supplied by
+ * the App instead of maintaining a parallel capability list, so an intent is only advertised
+ * when its tools, scopes and availability agree.
+ *
+ * Exports: `defineAgentCatalog`, and the catalog intent/scope/port types.
+ */
+const synchronous_js_1 = require("../../utils/synchronous.js");
+const tool_conditions_js_1 = require("../../capabilities/tool-conditions.js");
+/**
+ * Compile a catalog projection over the App's live registries.
+ *
+ * The actual registries determine availability and relationships. No parallel capability list
+ * exists: `goalIds` filters by tool support, `modelCatalog` narrows to the currently accepted
+ * task when `restrictToTask` is enabled, and scope tool ids are filtered to tools that exist.
+ *
+ * @param ports - Sources for Tool ids, goals, scopes, the current task, the tool registry
+ *   and the `restrictToTask` switch.
+ * @returns A frozen projection with `goalIds`, `goalDelegates`, `goalCatalog`,
+ *   `scopeCatalog` and `modelCatalog`.
+ * @throws TypeError When a supplied predicate does not return a boolean synchronously.
+ */
+function defineAgentCatalog(ports) {
+    const ids = ports.goalIds.bind(ports), goals = ports.goals.bind(ports), scopes = ports.scopes.bind(ports), task = ports.currentTask.bind(ports);
+    const tools = {
+        values: ports.tools.values.bind(ports.tools),
+        has: ports.tools.has.bind(ports.tools),
+        supports: ports.tools.supportsGoal.bind(ports.tools),
+        describe: ports.tools.describe.bind(ports.tools),
+    };
+    const restrict = ports.restrictToTask !== false;
+    const boolean = (value) => (0, synchronous_js_1.booleanResult)(value, 'Catalog predicates must be synchronous', 'Catalog predicates must return boolean');
+    /** Whether one goal is active and its demand metadata currently participates. */
+    const goalAvailable = (goal, app) => {
+        const tool = goal;
+        if (!(0, tool_conditions_js_1.toolActive)(tool.active, app))
+            return false;
+        const metadata = tool.asIntent;
+        if (metadata === undefined || metadata === true || typeof metadata === 'string')
+            return true;
+        if (typeof metadata === 'function')
+            return (0, tool_conditions_js_1.toolActive)(metadata, app);
+        return (0, tool_conditions_js_1.toolActive)(metadata.when, app);
+    };
+    const goalIds = (app) => ids(app).filter((id) => boolean(tools.supports(id, app)));
+    const goalDelegates = (app) => new Map(goals().map((goal) => {
+        const metadata = goal.asIntent;
+        const explicit = typeof metadata === 'object' ? metadata.delegates : undefined;
+        return [
+            goal.id,
+            explicit
+                ? [...explicit]
+                : [
+                    ...new Set([
+                        ...goal.delegates,
+                        ...[...tools.values()]
+                            .filter((tool) => tool.lifecycle?.id &&
+                            (app === undefined || (0, tool_conditions_js_1.toolActive)(tool.active, app)) &&
+                            (tool.goalIds === 'all' || tool.goalIds.includes(goal.id)))
+                            .map((tool) => tool.lifecycle.id),
+                    ]),
+                ],
+        ];
+    }));
+    const goalCatalog = (app) => {
+        const selected = goalIds(app), described = tools.describe('model', app), delegates = goalDelegates(app);
+        return goals(selected)
+            .filter((goal) => goalAvailable(goal, app))
+            .map((goal) => {
+            const { inputSchema: _schema, resolve: _resolve, active: _active, asIntent: _asIntent, ...metadata } = goal;
+            const demandDescription = typeof _asIntent === 'string'
+                ? _asIntent
+                : typeof _asIntent === 'object' && _asIntent !== null
+                    ? _asIntent.description
+                    : undefined;
+            return {
+                ...metadata,
+                ...(demandDescription ? { description: demandDescription } : {}),
+                delegates: delegates.get(goal.id) ?? [...goal.delegates],
+                scopeIds: scopes([goal.id]).map((scope) => scope.id),
+                toolIds: described
+                    .filter((tool) => tool.goalIds.includes(goal.id))
+                    .map((tool) => tool.id),
+            };
+        });
+    };
+    const scopeCatalog = (app) => scopes(goalCatalog(app).map((goal) => goal.id)).map((scope) => ({
+        ...scope,
+        toolIds: scope.toolIds.filter(tools.has),
+    }));
+    return Object.freeze({
+        goalIds,
+        goalDelegates,
+        goalCatalog,
+        scopeCatalog,
+        modelCatalog(app) {
+            const accepted = restrict ? task(app) : undefined, selected = goalIds(app).filter((id) => !accepted || id === accepted.goalId), available = goalCatalog(app).filter((intent) => selected.includes(intent.id));
+            return {
+                availableGoalIds: available.map((intent) => intent.id),
+                availableGoals: available.map((intent) => accepted ? { ...intent, scopeIds: accepted.scopeId ? [accepted.scopeId] : [] } : intent),
+                availableScopes: scopeCatalog(app).filter((scope) => !accepted || scope.id === accepted.scopeId),
+                availableTools: tools
+                    .describe('model', app)
+                    .filter((tool) => !accepted || tool.goalIds.includes(accepted.goalId)),
+            };
+        },
+    });
+}

package/dist/cjs/kits/domains/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+/** Optional domain Tool constraints, scope registries and task-facing projections. */
+__exportStar(require("./registry.js"), exports);
+__exportStar(require("./scopes.js"), exports);
+__exportStar(require("./catalog.js"), exports);

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

@@ -5,8 +5,9 @@ exports.createIntentRegistry = createIntentRegistry;
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const rules_js_1 = require("../../utils/rules.js");
 const registration_js_1 = require("../../utils/registration.js");
+const model_js_1 = require("../../capabilities/model.js");
 /**
- * Intent semantics and allowed values are configuration; the registry owns their common lifecycle.
+ * Goal semantics and allowed values are configuration; the registry owns their common lifecycle.
  *
  * Registration order is preserved by `ids`, `definitions`, `values` and `entries`; once
  * `seal()` is called the set is final and further registration is rejected.
@@ -16,6 +17,7 @@ class IntentRegistry {
     static create = createIntentRegistry;
     byId = new Map();
     sealed = false;
+    modelView;
     policy;
     /**
      * @param policy - Optional id pattern, vocabulary lists, error wording and assertion hook.
@@ -29,7 +31,7 @@ class IntentRegistry {
             'targetModes',
             'contextTiers',
             'actions',
-            'steps',
+            'delegates',
             'handoffValues',
             'tags',
         ];
@@ -51,16 +53,16 @@ class IntentRegistry {
         });
     }
     /**
-     * Validate, freeze and add one intent.
+     * Validate, freeze and add one domain Tool.
      *
      * Checks run in a fixed order — sealed, identity, context contract, auxiliary actions,
-     * handoff, plan, steps — so the reported violation is stable when several rules fail.
+     * handoff, plan, delegates — so the reported violation is stable when several rules fail.
      *
-     * @param input - Intent declaration; the App's own assertion receives this original object,
+     * @param input - Goal declaration; the App's own assertion receives this original object,
      *   not the compiled copy, so helpers and prototype methods keep working.
      * @returns This registry, for chaining.
      * @throws A configured error for a sealed registry, invalid identity or vocabulary values,
-     *   empty/duplicate steps, or a duplicate intent id.
+     *   empty/duplicate delegates, or a duplicate Tool id.
      */
     register(input) {
         const id = input.id;
@@ -68,7 +70,7 @@ class IntentRegistry {
             ...(0, registration_js_1.registrationData)(input, [
                 'id',
                 'description',
-                'steps',
+                'delegates',
                 'scopePolicy',
                 'targetPolicy',
                 'contextTier',
@@ -78,7 +80,11 @@ class IntentRegistry {
             ]),
             id,
             description: input.description,
-            steps: input.steps,
+            delegates: (typeof input.asIntent === 'object' && input.asIntent !== null
+                ? input.asIntent.delegates
+                : undefined) ??
+                input.delegates ??
+                [],
             scopePolicy: input.scopePolicy,
             targetPolicy: input.targetPolicy,
             contextTier: input.contextTier,
@@ -87,7 +93,7 @@ class IntentRegistry {
             preparedHandoff: input.preparedHandoff,
         };
         const policy = this.policy;
-        const invalid = policy.errors?.invalid ?? 'Invalid intent definition';
+        const invalid = policy.errors?.invalid ?? 'Invalid intent Tool definition';
         const tags = policy.tags ?? [];
         const validName = (name) => {
             if (typeof name !== 'string' || !name.trim())
@@ -145,75 +151,112 @@ class IntentRegistry {
             },
             {
                 occur: [
-                    () => !definition.steps.length,
-                    () => definition.steps.some((step) => policy.steps !== undefined && !policy.steps.includes(step)),
-                    () => new Set(definition.steps).size !== definition.steps.length,
+                    () => (input.delegates !== undefined ||
+                        (typeof input.asIntent === 'object' &&
+                            input.asIntent !== null &&
+                            input.asIntent.delegates !== undefined)) &&
+                        !definition.delegates.length,
+                    () => definition.delegates.some((delegate) => policy.delegates !== undefined && !policy.delegates.includes(delegate)),
+                    () => new Set(definition.delegates).size !== definition.delegates.length,
                 ],
                 error: invalid,
-                tags: ['steps'],
+                tags: ['delegates'],
             },
         ], tags);
         // App assertions may use implementation helpers; never pass a compiled view as the source
         // instance.
         (0, synchronous_js_1.assertion)(policy.assertDefinition?.(input), 'Registry definition assertions must return void synchronously');
-        (0, rules_js_1.breakWhile)(this.byId.has(definition.id), () => policy.errors?.duplicate?.(definition.id) ??
-            new Error(`Duplicate intent: ${definition.id}`), [...tags, 'duplicate']);
+        (0, rules_js_1.breakWhile)(this.byId.has(definition.id), () => policy.errors?.duplicate?.(definition.id) ?? new Error(`Duplicate tool: ${definition.id}`), [...tags, 'duplicate']);
         this.byId.set(definition.id, Object.freeze({
             ...definition,
-            steps: Object.freeze([...definition.steps]),
+            ...new model_js_1.ModelToolRegistry([
+                {
+                    id: input.id,
+                    description: input.description,
+                    active: typeof input.active === 'function' ? input.active.bind(input) : input.active,
+                    asIntent: typeof input.asIntent === 'function' ? input.asIntent.bind(input) : input.asIntent,
+                    inputSchema: input.inputSchema ?? {
+                        jsonSchema: { type: 'object' },
+                        parse(value) {
+                            if (!value || typeof value !== 'object' || Array.isArray(value))
+                                throw new TypeError('Tool input must be an object');
+                            return value;
+                        },
+                    },
+                    resolve: input.resolve?.bind(input) ?? ((value) => ({ toolId: id, input: value })),
+                },
+            ]).require(input.id),
+            delegates: Object.freeze([...definition.delegates]),
             ...(definition.auxiliaryActions
                 ? { auxiliaryActions: Object.freeze([...definition.auxiliaryActions]) }
                 : {}),
         }));
+        this.modelView = undefined;
         return this;
     }
-    /** Register every intent in iteration order. */
+    /** Register every domain Tool in iteration order. */
     registerAll(definitions) {
         for (const definition of definitions)
             this.register(definition);
         return this;
     }
-    /** Registered intent for `goal`, or `undefined` when it is absent. */
+    /** Registered domain Tool for `id`, or `undefined` when it is absent. */
     get(goal) {
         return this.byId.get(goal);
     }
-    /** Whether an intent id is registered. */
+    /** Whether a Tool id is registered. */
     has(goal) {
         return this.byId.has(goal);
     }
-    /** Registered intent ids in registration order. */
+    /** Registered Tool ids in registration order. */
     ids() {
         return Object.freeze([...this.byId.keys()]);
     }
-    /** Registered intents in registration order. */
+    /** Registered goals in registration order. */
     get definitions() {
         return Object.freeze([...this.byId.values()]);
     }
-    /** Iterate the registered intents. */
+    /** Iterate the registered goals. */
     values() {
         return this.byId.values();
     }
-    /** Iterate `[id, intent]` pairs. */
+    /** Demand discovery uses tool metadata; domain fields remain attached to these same IDs. */
+    withIntent(context) {
+        return this.models().withIntent(context);
+    }
+    /** Resolve a grouped transport's selected Tool through that Tool's own parser and resolver. */
+    resolve(selection, context) {
+        return this.models().resolve(selection, context);
+    }
+    /** Explicit node selection uses the same immutable model projection. */
+    select(ids, ...context) {
+        return context.length ? this.models().select(ids, context[0]) : this.models().select(ids);
+    }
+    /** Cache only immutable declarations; request activation is evaluated by each projection. */
+    models() {
+        return (this.modelView ??= new model_js_1.ModelToolRegistry(this.byId.values()).seal());
+    }
+    /** Iterate `[id, tool]` pairs. */
     entries() {
         return this.byId.entries();
     }
     /**
-     * Registered intent for `id`.
+     * Registered domain Tool for `id`.
      *
      * @throws TypeError When the id is not registered.
      */
     require(id) {
         const value = this.byId.get(id);
         if (!value)
-            throw new TypeError(`Unknown intent: ${id}`);
+            throw new TypeError(`Unknown tool: ${id}`);
         return value;
     }
-    /** Whether the intent declares this step; unknown intents allow nothing. */
-    allows(goal, step) {
-        return this.byId.get(goal)?.steps.includes(step) ?? false;
+    /** Whether the Tool declares this delegate; unknown goals allow nothing. */
+    allows(goal, delegate) {
+        return this.byId.get(goal)?.delegates.includes(delegate) ?? false;
     }
     /**
-     * Copy the selected intents out of the registry.
+     * Copy the selected goals out of the registry.
      *
      * @param goals - Ids to include; the default is every registered id, in registry order.
      * @returns Descriptions whose arrays are copied so callers cannot mutate registry state.
@@ -222,7 +265,10 @@ class IntentRegistry {
         const selected = new Set(goals);
         return [...this.byId.values()]
             .filter((item) => selected.has(item.id))
-            .map((item) => ({ ...item, steps: [...item.steps] }));
+            .map((item) => ({
+            ...item,
+            delegates: [...item.delegates],
+        }));
     }
     /** Finalize the registry; no registration is accepted afterwards. */
     seal() {
@@ -234,7 +280,7 @@ exports.IntentRegistry = IntentRegistry;
 /**
  * Create and seal a complete catalog; use the constructor for incremental installation.
  *
- * @param definitions - Intent declarations registered in iteration order.
+ * @param definitions - Goal declarations registered in iteration order.
  * @param policy - Optional registry policy forwarded to the constructor.
  * @returns A sealed registry.
  * @throws A configured error for the first invalid or duplicate declaration.