@jangts/agent-core 0.3.6 → 0.5.0

package/dist/esm/index.d.ts

@@ -1,18 +1,16 @@
 /**
  * Aggregate public entry of `@jangts/agent-core`: Core runtime contracts, one `Support`
- * namespace with a few named Support helpers, and the declaration helpers of optional Kits.
+ * namespace, and the optional Kit declaration helpers.
  *
- * Layering. Core owns the runtime contracts Apps call (engine, model runner, capabilities,
- * context, diagnostics) and the handler contracts Core calls back into the App. Support only
- * supplies recommended implementations of those same contracts, so it is published as a single
- * namespace instead of a second dispatch layer. Kits are optional business libraries reached
- * through their own subpath entries; the Kit entries re-exported here are declaration helpers
- * and standalone modules, not additional Core guarantees. Shared utilities are re-exported
- * because they are needed alongside these contracts, and they carry no Agent semantics.
+ * Layering. Core owns the runtime contracts Apps call (engine, model runner, tools,
+ * context, diagnostics) and the handler contracts Core calls back into. Support supplies
+ * recommended implementations of those contracts. Kits are optional App-side libraries;
+ * they are available from this root convenience surface and from `/kits` / `/kits/*`
+ * subpaths. Importing a Kit is a choice, never a requirement.
  *
  * Exports are grouped by responsibility, not by dependency order. Deep subpath entries
  * (`/engine`, `/model`, `/tools`, `/context`, `/journal`, `/diagnostics`, `/kits/...`)
- * resolve to the same implementations, so this file is a convenience surface only.
+ * resolve to the same implementations.
  */
 export * from './execution/engine.js';
 export { getErrorInfo } from './errors.js';
@@ -23,13 +21,21 @@ export * from './model/index.js';
 export * from './capabilities/index.js';
 export * from './context/fragments.js';
 export * from './context/journal.js';
-export { assembleFragments } from './context/assembly.js';
+export * from './context/assembly.js';
 export * from './support/context/assembly.js';
 export { defineEvidenceChecklist, defineEvidenceProjection } from './kits/evidence.js';
 export type { EvidenceRequirement, EvidenceProvider, EvidenceProjectionDefinition, EvidenceProjectionProvider, } from './structs/kits/evidence.js';
+export { defineCommand, commandSchema } from './kits/interaction/command.js';
+export type { Command, CommandDefinition, ProtocolCheck, ProtocolField, ProtocolReason, ProtocolPredicate, ProtocolShape, RegisteredProtocol, } from './structs/kits/interaction.js';
+export * from './kits/interaction/commands.js';
+export * from './kits/interaction/transfer.js';
+export * from './kits/interaction/handlers.js';
 export * from './kits/presentation/events.js';
 export * from './support/transport/index.js';
 export * from './support/model/chat-completions.js';
+export * from './support/model/compatible-provider.js';
+export * from './support/model/transports.js';
+export * from './support/model/interactions/index.js';
 export * from './utils/index.js';
 export * from './kits/presentation/templates.js';
 export { defineRetrieval } from './kits/retrieval.js';
@@ -37,11 +43,11 @@ export type * from './structs/kits/retrieval.js';
 export { defineTextSkillLoader } from './kits/text-skills.js';
 export type * from './structs/kits/text-skills.js';
 export * from './diagnostics/index.js';
-export * from './kits/intents/registry.js';
-export * from './kits/intents/scopes.js';
+export * from './kits/domains/registry.js';
+export * from './kits/domains/scopes.js';
 export { ToolLifecycleRegistry } from './kits/tools.js';
 export type * from './structs/kits/tools.js';
-export * from './kits/intents/catalog.js';
+export * from './kits/domains/catalog.js';
 export * from './support/registration.js';
 export { defineCandidateSelection } from './kits/candidates.js';
 export type * from './structs/kits/candidates.js';

package/dist/esm/index.js

@@ -1,18 +1,16 @@
 /**
  * Aggregate public entry of `@jangts/agent-core`: Core runtime contracts, one `Support`
- * namespace with a few named Support helpers, and the declaration helpers of optional Kits.
+ * namespace, and the optional Kit declaration helpers.
  *
- * Layering. Core owns the runtime contracts Apps call (engine, model runner, capabilities,
- * context, diagnostics) and the handler contracts Core calls back into the App. Support only
- * supplies recommended implementations of those same contracts, so it is published as a single
- * namespace instead of a second dispatch layer. Kits are optional business libraries reached
- * through their own subpath entries; the Kit entries re-exported here are declaration helpers
- * and standalone modules, not additional Core guarantees. Shared utilities are re-exported
- * because they are needed alongside these contracts, and they carry no Agent semantics.
+ * Layering. Core owns the runtime contracts Apps call (engine, model runner, tools,
+ * context, diagnostics) and the handler contracts Core calls back into. Support supplies
+ * recommended implementations of those contracts. Kits are optional App-side libraries;
+ * they are available from this root convenience surface and from `/kits` / `/kits/*`
+ * subpaths. Importing a Kit is a choice, never a requirement.
  *
  * Exports are grouped by responsibility, not by dependency order. Deep subpath entries
  * (`/engine`, `/model`, `/tools`, `/context`, `/journal`, `/diagnostics`, `/kits/...`)
- * resolve to the same implementations, so this file is a convenience surface only.
+ * resolve to the same implementations.
  */
 export * from './execution/engine.js';
 export { getErrorInfo } from './errors.js';
@@ -22,23 +20,28 @@ export * from './model/index.js';
 export * from './capabilities/index.js';
 export * from './context/fragments.js';
 export * from './context/journal.js';
-// Named re-export: the context barrel also forwards its Kit evidence helpers, which the
-// root surface publishes separately below.
-export { assembleFragments } from './context/assembly.js';
+export * from './context/assembly.js';
 export * from './support/context/assembly.js';
 export { defineEvidenceChecklist, defineEvidenceProjection } from './kits/evidence.js';
+export { defineCommand, commandSchema } from './kits/interaction/command.js';
+export * from './kits/interaction/commands.js';
+export * from './kits/interaction/transfer.js';
+export * from './kits/interaction/handlers.js';
 export * from './kits/presentation/events.js';
 export * from './support/transport/index.js';
 export * from './support/model/chat-completions.js';
+export * from './support/model/compatible-provider.js';
+export * from './support/model/transports.js';
+export * from './support/model/interactions/index.js';
 export * from './utils/index.js';
 export * from './kits/presentation/templates.js';
 export { defineRetrieval } from './kits/retrieval.js';
 export { defineTextSkillLoader } from './kits/text-skills.js';
 export * from './diagnostics/index.js';
-export * from './kits/intents/registry.js';
-export * from './kits/intents/scopes.js';
+export * from './kits/domains/registry.js';
+export * from './kits/domains/scopes.js';
 export { ToolLifecycleRegistry } from './kits/tools.js';
-export * from './kits/intents/catalog.js';
+export * from './kits/domains/catalog.js';
 export * from './support/registration.js';
 export { defineCandidateSelection } from './kits/candidates.js';
 /** App-facing helpers and their types are consumed through the root Support namespace. */

package/dist/esm/kits/answering/tasks.d.ts

@@ -36,7 +36,7 @@ export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unk
         readerId: string;
         outputId: string;
         scopeId: string | undefined;
-        intentIds: readonly any[];
+        goalIds: readonly any[];
         checkIds: readonly any[];
         metadata: Data;
     }[];
@@ -64,7 +64,7 @@ export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unk
         readerId: string;
         outputId: string;
         scopeId: string | undefined;
-        intentIds: readonly any[];
+        goalIds: readonly any[];
         checkIds: readonly any[];
         inputSchema: import("../../index.js").SchemaAdapter<Input>;
         metadata: Data;
@@ -76,7 +76,7 @@ export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unk
         readerId: string;
         outputId: string;
         scopeId: string | undefined;
-        intentIds: readonly any[];
+        goalIds: readonly any[];
         checkIds: readonly any[];
         inputSchema: import("../../index.js").SchemaAdapter<Input>;
         metadata: Data;
@@ -87,7 +87,7 @@ export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unk
         readerId: string;
         outputId: string;
         scopeId: string | undefined;
-        intentIds: readonly any[];
+        goalIds: readonly any[];
         checkIds: readonly any[];
         inputSchema: import("../../index.js").SchemaAdapter<Input>;
         metadata: Data;
@@ -99,7 +99,7 @@ export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unk
         readerId: string;
         outputId: string;
         scopeId: string | undefined;
-        intentIds: readonly any[];
+        goalIds: readonly any[];
         checkIds: readonly any[];
         inputSchema: import("../../index.js").SchemaAdapter<Input>;
         metadata: Data;
@@ -110,7 +110,7 @@ export declare function defineAnswerTaskCatalog<Input, Evidence, App, Data = unk
         readerId: string;
         outputId: string;
         scopeId: string | undefined;
-        intentIds: readonly any[];
+        goalIds: readonly any[];
         checkIds: readonly any[];
         inputSchema: import("../../index.js").SchemaAdapter<Input>;
         metadata: Data;

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

@@ -51,10 +51,10 @@ export 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)))
@@ -68,7 +68,7 @@ export 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: snapshotSchemaAdapter(definition.inputSchema),
             metadata,

package/dist/esm/kits/domains/catalog.d.ts

@@ -0,0 +1,42 @@
+import type { ModelTool } from '../../structs/capabilities/model.js';
+import type { AgentCatalogPorts, CatalogGoal, CatalogScope } from '../../structs/kits/domains/catalog.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.
+ */
+export declare function defineAgentCatalog<App, Id extends string, Goal extends CatalogGoal<Id>, Scope extends CatalogScope>(ports: AgentCatalogPorts<App, Id, Goal, Scope>): Readonly<{
+    goalIds: (app: App) => Id[];
+    goalDelegates: (app?: App) => Map<Id, string[]>;
+    goalCatalog: (app: App) => (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & {
+        delegates: string[];
+        scopeIds: string[];
+        toolIds: string[];
+        description?: string | undefined;
+    })[];
+    scopeCatalog: (app: App) => (Scope & {
+        toolIds: string[];
+    })[];
+    modelCatalog(app: App): {
+        availableGoalIds: (Goal & Partial<ModelTool<unknown, unknown, App>>)["id"][];
+        availableGoals: (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & {
+            delegates: string[];
+            scopeIds: string[];
+            toolIds: string[];
+            description?: string | undefined;
+        })[];
+        availableScopes: (Scope & {
+            toolIds: string[];
+        })[];
+        availableTools: import("./catalog.js").DescribedTool[];
+    };
+}>;
+export type * from '../../structs/kits/domains/catalog.js';

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

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+import { booleanResult } from '../../utils/synchronous.js';
+import { toolActive } from '../../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.
+ */
+export 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) => 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 (!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 toolActive(metadata, app);
+        return 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 || 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/esm/kits/domains/index.d.ts

@@ -0,0 +1,4 @@
+/** Optional domain Tool constraints, scope registries and task-facing projections. */
+export * from './registry.js';
+export * from './scopes.js';
+export * from './catalog.js';

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

@@ -0,0 +1,4 @@
+/** Optional domain Tool constraints, scope registries and task-facing projections. */
+export * from './registry.js';
+export * from './scopes.js';
+export * from './catalog.js';

package/dist/esm/kits/domains/registry.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Domain Tools Kit: an ordered, sealable registry of domain Tool declarations.
+ *
+ * Place in the package: part of the domain Tool Kit. Goal semantics and the allowed vocabulary
+ * (scope modes, target modes, context tiers, delegates, actions) are App configuration; this class
+ * owns the common lifecycle — validation, ordering, duplicate detection and sealing.
+ *
+ * Exports: `IntentRegistry`, `createIntentRegistry`, and the domain Tool registry types.
+ */
+import type { IntentTool, IntentToolRegistration, IntentDescription, IntentPolicy, IntentId, RegisteredIntent } from '../../structs/kits/domains/registry.js';
+import { ModelToolRegistry } from '../../capabilities/model.js';
+/**
+ * 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.
+ */
+export declare class IntentRegistry<Definition extends IntentToolRegistration = IntentToolRegistration> {
+    /** Create and seal a complete catalog in one call. */
+    static readonly create: typeof createIntentRegistry;
+    private readonly byId;
+    private sealed;
+    private modelView?;
+    private readonly policy;
+    /**
+     * @param policy - Optional id pattern, vocabulary lists, error wording and assertion hook.
+     *   Lists and the pattern are copied so later mutation of the input cannot weaken checks.
+     */
+    constructor(policy?: IntentPolicy<Definition>);
+    /**
+     * Validate, freeze and add one domain Tool.
+     *
+     * Checks run in a fixed order — sealed, identity, context contract, auxiliary actions,
+     * handoff, plan, delegates — so the reported violation is stable when several rules fail.
+     *
+     * @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 delegates, or a duplicate Tool id.
+     */
+    register(input: Definition): this;
+    /** Register every domain Tool in iteration order. */
+    registerAll(definitions: Iterable<Definition>): this;
+    /** Registered domain Tool for `id`, or `undefined` when it is absent. */
+    get(goal: string): RegisteredIntent<Definition> | undefined;
+    /** Whether a Tool id is registered. */
+    has(goal: string): boolean;
+    /** Registered Tool ids in registration order. */
+    ids(): readonly IntentId<Definition>[];
+    /** Registered goals in registration order. */
+    get definitions(): readonly RegisteredIntent<Definition>[];
+    /** Iterate the registered goals. */
+    values(): MapIterator<Readonly<Omit<Readonly<IntentTool & import("../../utils/registration.js").RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof IntentTool>>>, "resolve" | "inputSchema" | "delegates" | "auxiliaryActions"> & import("../../index.js").ModelTool<any, any, any> & { readonly [Key in keyof Pick<Definition, Extract<keyof Definition, "delegates" | "auxiliaryActions">>]: Readonly<Definition[Key]>; } & {
+        id: Definition["id"];
+        delegates: Readonly<NonNullable<Definition["delegates"]>>;
+    }>>;
+    /** Demand discovery uses tool metadata; domain fields remain attached to these same IDs. */
+    withIntent(context: unknown): ModelToolRegistry;
+    /** Resolve a grouped transport's selected Tool through that Tool's own parser and resolver. */
+    resolve(selection: import('../../structs/capabilities/model.js').ModelSelection, context: Readonly<{
+        stageId: string;
+    }>): unknown;
+    /** Explicit node selection uses the same immutable model projection. */
+    select(ids: readonly string[], ...context: [] | [unknown]): ModelToolRegistry;
+    /** Cache only immutable declarations; request activation is evaluated by each projection. */
+    private models;
+    /** Iterate `[id, tool]` pairs. */
+    entries(): MapIterator<[string, Readonly<Omit<Readonly<IntentTool & import("../../utils/registration.js").RegistrationData<Definition> & Pick<Definition, Extract<keyof Definition, keyof IntentTool>>>, "resolve" | "inputSchema" | "delegates" | "auxiliaryActions"> & import("../../index.js").ModelTool<any, any, any> & { readonly [Key in keyof Pick<Definition, Extract<keyof Definition, "delegates" | "auxiliaryActions">>]: Readonly<Definition[Key]>; } & {
+        id: Definition["id"];
+        delegates: Readonly<NonNullable<Definition["delegates"]>>;
+    }>]>;
+    /**
+     * Registered domain Tool for `id`.
+     *
+     * @throws TypeError When the id is not registered.
+     */
+    require(id: string): RegisteredIntent<Definition>;
+    /** Whether the Tool declares this delegate; unknown goals allow nothing. */
+    allows(goal: string, delegate: string): boolean;
+    /**
+     * 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.
+     */
+    describe(goals?: readonly string[]): IntentDescription<Definition>[];
+    /** Finalize the registry; no registration is accepted afterwards. */
+    seal(): this;
+}
+/**
+ * Create and seal a complete catalog; use the constructor for incremental installation.
+ *
+ * @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.
+ */
+export declare function createIntentRegistry<Definition extends IntentToolRegistration>(definitions: Iterable<Definition>, policy?: IntentPolicy<Definition>): IntentRegistry<Definition>;
+export type { IntentTool, IntentToolRegistration, IntentDescription, IntentPolicy, IntentId, RegisteredIntent, } from '../../structs/kits/domains/registry.js';