@jangts/agent-core 0.2.1 → 0.3.5

package/dist/esm/execution/cache.js

@@ -0,0 +1,156 @@
+import { awaitWithSignal } from '../utils/cancellation.js';
+/** Validate the small cache-specific boundary; business permissions remain App-owned. */
+function textKey(value) {
+    if (typeof value !== 'string' || !value.length)
+        throw new TypeError('Cache keys must be nonempty strings');
+    return value;
+}
+/** Reject accidental cross-partition writes and unknown options instead of ignoring them. */
+function optionsOf(value, allowed) {
+    if (value !== undefined &&
+        (!value ||
+            typeof value !== 'object' ||
+            Reflect.ownKeys(value).some((key) => typeof key !== 'string' || !allowed.includes(key))))
+        throw new TypeError('Invalid cache options');
+}
+/** Bounded LRU for one Engine; forks get new memory, and values are deliberately not cloned. */
+export class EngineCache {
+    entries = new Map();
+    limit;
+    ttl;
+    constructor(options = {}) {
+        this.limit = options.maxEntries ?? 1024;
+        this.ttl = options.ttlMs ?? Infinity;
+        if (!Number.isSafeInteger(this.limit) ||
+            this.limit < 1 ||
+            (this.ttl !== Infinity && (!Number.isSafeInteger(this.ttl) || this.ttl < 1)))
+            throw new TypeError('Invalid Engine cache bounds');
+    }
+    /** Remove expired entries lazily, without timers or background tasks. */
+    prune() {
+        const now = Date.now();
+        for (const [key, item] of this.entries)
+            if (item.expires <= now)
+                this.entries.delete(key);
+    }
+    /** Capture an immutable partition and visit signal; no per-run cache is introduced. */
+    view(nodeId, signal) {
+        textKey(nodeId);
+        const prefix = JSON.stringify([nodeId]).slice(0, -1) + ',';
+        const address = (key, node = nodeId) => JSON.stringify([textKey(node), textKey(key)]);
+        const read = (key, node = nodeId) => {
+            signal.throwIfAborted();
+            const id = address(key, node);
+            const item = this.entries.get(id);
+            if (item && item.expires <= Date.now()) {
+                this.entries.delete(id);
+                return undefined;
+            }
+            if (item) {
+                this.entries.delete(id);
+                this.entries.set(id, item);
+            }
+            return item;
+        };
+        return Object.freeze({
+            get: (key, options) => {
+                optionsOf(options, ['nodeId']);
+                return read(key, options?.nodeId)?.value;
+            },
+            has: (key) => read(key) !== undefined,
+            set: (key, value) => {
+                signal.throwIfAborted();
+                const id = address(key);
+                this.prune();
+                this.entries.delete(id);
+                this.entries.set(id, { value, expires: Date.now() + this.ttl });
+                if (this.entries.size > this.limit)
+                    this.entries.delete(this.entries.keys().next().value);
+            },
+            delete: (key) => {
+                signal.throwIfAborted();
+                return this.entries.delete(address(key));
+            },
+            clear: () => {
+                signal.throwIfAborted();
+                for (const key of this.entries.keys())
+                    if (key.startsWith(prefix))
+                        this.entries.delete(key);
+            },
+        });
+    }
+}
+/** Snapshot port callbacks with their receiver, rejecting incomplete App storage early. */
+export function cachePort(port) {
+    if (port === undefined)
+        return undefined;
+    const handlers = ['get', 'has', 'set', 'delete', 'clear'];
+    if (!port ||
+        handlers.some((key) => typeof port[key] !== 'function') ||
+        (port.supportsPersistence !== undefined && typeof port.supportsPersistence !== 'boolean'))
+        throw new TypeError('Invalid Agent cache port');
+    return Object.freeze({
+        supportsPersistence: port.supportsPersistence === true,
+        get: port.get.bind(port),
+        has: port.has.bind(port),
+        set: port.set.bind(port),
+        delete: port.delete.bind(port),
+        clear: port.clear.bind(port),
+    });
+}
+/** Build visit-local views. Persistent writes remain external side effects owned by the App. */
+export function cacheContext(memory, port, nodeId, signal) {
+    const partition = (options, crossRead = false) => {
+        signal.throwIfAborted();
+        optionsOf(options, crossRead ? ['nodeId', 'persistence'] : ['persistence']);
+        const persistence = options?.persistence ?? false;
+        if (typeof persistence !== 'boolean')
+            throw new TypeError('Invalid cache persistence');
+        if (persistence && !port?.supportsPersistence)
+            throw new TypeError('Agent cache persistence is unsupported');
+        return Object.freeze({
+            nodeId: textKey(crossRead ? (options?.nodeId ?? nodeId) : nodeId),
+            persistence,
+            signal,
+        });
+    };
+    const address = (key, options, crossRead = false) => Object.freeze({ ...partition(options, crossRead), key: textKey(key) });
+    const call = async (invoke) => {
+        signal.throwIfAborted();
+        const value = await awaitWithSignal(invoke(), signal);
+        signal.throwIfAborted();
+        return value;
+    };
+    return {
+        cache: memory.view(nodeId, signal),
+        ...(port
+            ? {
+                agentCache: Object.freeze({
+                    get: (key, options) => call(() => port.get(address(key, options, true))),
+                    has: (key, options) => call(async () => {
+                        const result = await port.has(address(key, options));
+                        if (typeof result !== 'boolean')
+                            throw new TypeError('Agent cache has must return boolean');
+                        return result;
+                    }),
+                    set: (key, value, options) => call(async () => {
+                        const result = await port.set(address(key, options), value);
+                        if (result !== undefined)
+                            throw new TypeError('Agent cache set must return void');
+                    }),
+                    delete: (key, options) => call(async () => {
+                        const result = await port.delete(address(key, options));
+                        if (typeof result !== 'boolean')
+                            throw new TypeError('Agent cache delete must return boolean');
+                        return result;
+                    }),
+                    clear: (options) => call(async () => {
+                        const result = await port.clear(partition(options));
+                        if (result !== undefined)
+                            throw new TypeError('Agent cache clear must return void');
+                    }),
+                }),
+            }
+            : {}),
+    };
+}

package/dist/esm/execution/engine.d.ts

@@ -1,3 +1,4 @@
+import type { AgentCachePort } from '../structs/execution/cache.js';
 import { ModelRunner } from '../model/runner.js';
 import type { ModelRunnerOptions } from '../structs/model/runtime.js';
 import type { ToolRegistry } from '../capabilities/tools.js';
@@ -5,6 +6,7 @@ import type { AgentCoreEngineOptions, CoreStep } from '../structs/execution/engi
 import { AgentWorkflow, AttemptBudget, defineWorkflow } from './workflow.js';
 import type { WorkflowExtension } from '../structs/execution/workflow.js';
 export * from './workflow.js';
+export type * from '../structs/execution/cache.js';
 type InvokeTool = (request: import('../structs/capabilities/tools.js').ToolInvocationRequest) => Promise<import('../structs/invocation.js').ToolResult<unknown>>;
 type ToolBinding = {
     invoke: InvokeTool;
@@ -109,6 +111,8 @@ export declare class AgentCoreEngine<Result, State = unknown, App = undefined> {
     static readonly AttemptBudget: typeof AttemptBudget;
     /** Factory for a validated workflow definition. */
     static readonly createWorkflow: typeof defineWorkflow;
+    private readonly cacheMemory;
+    private readonly serviceCache?;
     private readonly maxRounds;
     private readonly exhausted;
     private readonly options;
@@ -264,6 +268,7 @@ export declare class AgentCoreEngine<Result, State = unknown, App = undefined> {
             app?: App;
             tools?: ToolBinding;
             model?: AgentModelRuntime;
+            agentCache?: AgentCachePort;
         };
     }): AgentCoreEngine<Result, State, App>;
     /**

package/dist/esm/execution/engine.js

@@ -9,6 +9,7 @@
  *
  * Exports: `AgentCoreEngine` and the engine option/identity types.
  */
+import { EngineCache, cacheContext, cachePort } from './cache.js';
 import { ModelCallBudget, parentModelBudget } from '../model/call-budget.js';
 import { ModelRunner } from '../model/runner.js';
 import { compiledModelBinding, modelBindingId, snapshotModelBinding, } from '../model/binding.js';
@@ -39,6 +40,8 @@ export class AgentCoreEngine {
     static AttemptBudget = AttemptBudget;
     /** Factory for a validated workflow definition. */
     static createWorkflow = defineWorkflow;
+    cacheMemory;
+    serviceCache;
     maxRounds;
     exhausted;
     options;
@@ -289,6 +292,8 @@ export class AgentCoreEngine {
         breakWhile(!!this.invokeTool && !dependencies?.tools, 'Fork requires a restored tool runtime');
         const engine = new AgentCoreEngine({
             maxRounds: this.maxRounds,
+            cache: this.options.cache,
+            agentCache: dependencies?.agentCache,
             errors: { exhausted: this.exhausted },
             execution: {
                 diagnostics: this.options.execution?.diagnostics,
@@ -333,6 +338,8 @@ export class AgentCoreEngine {
             ['maxSteps', 'exhausted', 'signal', 'diagnostics', 'onWorkflowEvent', 'observe'].some((key) => key in settings)) {
             throw new TypeError('Use maxRounds, execution (including observe) and errors');
         }
+        this.cacheMemory = new EngineCache(settings.cache);
+        this.serviceCache = cachePort(settings.agentCache);
         const execution = settings.execution;
         if (settings.branch !== undefined)
             this.branchIdentity = snapshotBranch(settings.branch);
@@ -342,6 +349,7 @@ export class AgentCoreEngine {
             settings.errors?.exhausted?.bind(settings.errors) ??
                 (() => new BudgetError('Agent round budget exhausted'));
         this.options = {
+            cache: { ...settings.cache },
             execution: {
                 signal: execution?.signal,
                 diagnostics: execution?.diagnostics,
@@ -461,6 +469,7 @@ export class AgentCoreEngine {
                 phase = 'run';
                 signal.throwIfAborted();
                 const result = await awaitWithSignal(step(index, {
+                    ...cacheContext(this.cacheMemory, this.serviceCache, '$step', signal),
                     signal,
                     diagnostics,
                     report: reports.report.bind(reports),
@@ -656,6 +665,7 @@ export class AgentCoreEngine {
             });
             const reports = new NodeReports(nodeDiagnostics, signal);
             const context = {
+                ...cacheContext(this.cacheMemory, this.serviceCache, node.id, signal),
                 report: reports.report.bind(reports),
                 createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
                 roundIndex: round,

package/dist/esm/kits/vector-search.js

@@ -77,11 +77,8 @@ export class VectorSearch {
                 (!Number.isFinite(options.minScore) || options.minScore < -1 || options.minScore > 1)), 'Invalid vector query');
         const query = normalize(vector, this.space.dimensions), groups = new Map();
         for (const [id, { document, vector: value }] of this.entries) {
-            // One isolated snapshot per candidate serves filter, grouping and the
-            // returned hit; filters and groupers are typed readonly, so sharing it
-            // removes the redundant clones without exposing the index.
-            const candidate = structuredClone(document);
-            const allowed = booleanResult(options.filter(candidate), 'Vector filters must be synchronous', 'Vector filters must return boolean');
+            // Each callback receives its own snapshot; readonly types cannot prevent runtime mutation.
+            const allowed = booleanResult(options.filter(structuredClone(document)), 'Vector filters must be synchronous', 'Vector filters must return boolean');
             if (!allowed)
                 continue;
             let score = 0;
@@ -90,12 +87,12 @@ export class VectorSearch {
             score = Math.max(-1, Math.min(1, score));
             if (score < (options.minScore ?? -1))
                 continue;
-            const group = synchronous(options.groupBy?.(candidate), 'Vector grouping must be synchronous') ?? id;
+            const group = synchronous(options.groupBy?.(structuredClone(document)), 'Vector grouping must be synchronous') ?? id;
             if (typeof group !== 'string')
                 throw new TypeError('Vector groups must be strings');
             const prior = groups.get(group);
             if (!prior || score > prior.score || (score === prior.score && id < prior.id))
-                groups.set(group, { id, score, document: candidate });
+                groups.set(group, { id, score, document: structuredClone(document) });
         }
         return [...groups.values()]
             .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))

package/dist/esm/structs/execution/cache.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Node-partitioned cache contracts. Engine memory is synchronous; service-owned storage is
+ * asynchronous and explicitly selects volatile or persistent space. Neither is workflow state.
+ */
+/** Optional Engine memory bounds; TTL is measured from the latest write. */
+export interface EngineCacheOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+}
+/** Only reads may name another node. Partition names are not authorization boundaries. */
+export interface CacheReadOptions {
+    readonly nodeId?: string;
+}
+/** Synchronous view of the current node's Engine-owned memory. Values retain identity. */
+export interface NodeCache {
+    get(key: string, options?: CacheReadOptions): unknown;
+    has(key: string): boolean;
+    set(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    clear(): void;
+}
+/** Persistent and volatile storage are independent; there is no implicit fallback or mirroring. */
+export interface AgentCacheOptions {
+    readonly persistence?: boolean;
+}
+/** Exact immutable address passed to the App port, including cancellation for this visit. */
+export interface AgentCacheAddress {
+    readonly nodeId: string;
+    readonly key: string;
+    readonly persistence: boolean;
+    readonly signal: AbortSignal;
+}
+/** App-owned storage. Capacity, expiry, serialization and user isolation belong to the App. */
+export interface AgentCachePort {
+    readonly supportsPersistence?: boolean;
+    get(address: AgentCacheAddress): Promise<unknown>;
+    has(address: AgentCacheAddress): Promise<boolean>;
+    set(address: AgentCacheAddress, value: unknown): Promise<void>;
+    delete(address: AgentCacheAddress): Promise<boolean>;
+    clear(partition: Omit<AgentCacheAddress, 'key'>): Promise<void>;
+}
+/** Async node view. Writes and clear can only address the current partition. */
+export interface NodeAgentCache {
+    get(key: string, options?: AgentCacheOptions & CacheReadOptions): Promise<unknown>;
+    has(key: string, options?: AgentCacheOptions): Promise<boolean>;
+    set(key: string, value: unknown, options?: AgentCacheOptions): Promise<void>;
+    delete(key: string, options?: AgentCacheOptions): Promise<boolean>;
+    clear(options?: AgentCacheOptions): Promise<void>;
+}
+/** Cache access shared by workflow visits and the low-level $step loop. */
+export interface CacheContext {
+    readonly cache: NodeCache;
+    readonly agentCache?: NodeAgentCache;
+}

package/dist/esm/structs/execution/cache.js

@@ -0,0 +1,5 @@
+/**
+ * Node-partitioned cache contracts. Engine memory is synchronous; service-owned storage is
+ * asynchronous and explicitly selects volatile or persistent space. Neither is workflow state.
+ */
+export {};

package/dist/esm/structs/execution/engine.d.ts

@@ -8,6 +8,7 @@
  * Exports: `LoopEvent`, `StepOutcome`, `CoreStep`, `AgentCoreEngineOptions`.
  */
 import type { ExecutionContext, ExecutionOptions, MaybePromise } from '../common.js';
+import type { CacheContext, EngineCacheOptions, AgentCachePort } from './cache.js';
 /** Progress fact for one loop round, correlated with the enclosing diagnostics span. */
 export interface LoopEvent {
     /** Unique id of this fact. */
@@ -31,9 +32,13 @@ export type StepOutcome<Value> =
     readonly value: Value;
 };
 /** One loop iteration. Must be re-entrant: the same step object runs every round. */
-export type CoreStep<Result> = (roundIndex: number, context: ExecutionContext & import('../debug.js').NodeReportingContext) => MaybePromise<StepOutcome<Result>>;
+export type CoreStep<Result> = (roundIndex: number, context: ExecutionContext & import('../debug.js').NodeReportingContext & CacheContext) => MaybePromise<StepOutcome<Result>>;
 /** Engine construction options. */
 export interface AgentCoreEngineOptions {
+    /** Engine-local LRU bounds; not copied as cache data when forking. */
+    cache?: EngineCacheOptions;
+    /** Borrowed App service cache; forks must explicitly provide their own port. */
+    agentCache?: AgentCachePort;
     /** Round budget; must be a positive safe integer. Defaults to 8 rounds. */
     maxRounds?: number;
     /** Cancellation and diagnostics shared by every round. */

package/dist/esm/structs/execution/workflow.d.ts

@@ -10,6 +10,7 @@
  * `AgentWorkflowDefinition`, `WorkflowEvent`, `WorkflowFailure`, `WorkflowExtension`,
  * `WorkflowModel`.
  */
+import type { CacheContext } from './cache.js';
 import type { OperationContext } from '../common.js';
 import type { DiagnosticContext } from '../diagnostics.js';
 import type { ModelTransportDefinition } from '../model/runtime.js';
@@ -20,7 +21,7 @@ type WorkflowModelRequest<Transport> = import('../model/runtime.js').ModelCallRe
     readonly modelId?: string;
 };
 /** Execution facts available to every node of a running workflow. */
-export interface WorkflowContext<Runtime = undefined> extends OperationContext<Runtime>, NodeReportingContext {
+export interface WorkflowContext<Runtime = undefined> extends OperationContext<Runtime>, NodeReportingContext, CacheContext {
     /** Zero-based bounded round; phases within a round do not consume another round. */
     readonly roundIndex: number;
     /** Report progress while this node is active; Core supplies its execution identity. */

package/dist/esm/structs/index.d.ts

@@ -54,3 +54,4 @@ export * from './common.js';
 export type * from './invocation.js';
 export type * from './debug.js';
 export type * from './execution/events.js';
+export type * from './execution/cache.js';

package/dist/esm/support/decorators/definition.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Internal decoration: construct definition classes or bind methods to their real host,
+ * compile through existing entry points and automatically register in the kind's root.
+ */
+import { type DefinitionKind, type IdentifiedDefinition } from './pool.js';
+type Handler = (this: any, ...args: any[]) => any;
+/** Preserve union branches when removing the decorator-owned id. */
+export type DefinitionBody<Definition> = Definition extends unknown ? Omit<Definition, 'id'> : never;
+/** Namespaces group external registration without changing Core options. */
+export interface DecorationOptions {
+    readonly ns?: string | readonly string[];
+}
+export type ClassDecoration<Definition extends IdentifiedDefinition> = <Constructor extends new () => DefinitionBody<Definition>>(target: Constructor, context: ClassDecoratorContext<Constructor>) => void;
+export type MethodDecoration<Method extends Handler> = <This>(method: (this: This, ...args: Parameters<Method>) => ReturnType<Method>, context: ClassMethodDecoratorContext<This, (this: This, ...args: Parameters<Method>) => ReturnType<Method>>) => void;
+/** Class definitions register once after static initialization and successful construction. */
+export declare function classDecoration<Definition extends IdentifiedDefinition>(kind: DefinitionKind, id: string, options: DecorationOptions, compile: (value: Definition) => Definition): ClassDecoration<Definition>;
+/** Method initializers bind and register automatically; no scanning or caller-side bind is needed. */
+export declare function methodDecoration<Definition extends IdentifiedDefinition, Method extends Handler>(kind: DefinitionKind, id: string, metadata: DefinitionBody<Definition>, handlerKey: keyof Definition, options: DecorationOptions, compile: (value: Definition) => Definition): MethodDecoration<Method>;
+export {};

package/dist/esm/support/decorators/definition.js

@@ -0,0 +1,38 @@
+/**
+ * Internal decoration: construct definition classes or bind methods to their real host,
+ * compile through existing entry points and automatically register in the kind's root.
+ */
+import { registerDefinition } from './pool.js';
+/** Restore only the decorator-owned id, preserving instance identity, getters and private state. */
+function withId(id, instance) {
+    if ('id' in instance)
+        throw new TypeError('Decoration supplies id; do not also define it on the class');
+    Object.defineProperty(instance, 'id', { value: id, enumerable: true });
+    return instance;
+}
+/** Class definitions register once after static initialization and successful construction. */
+export function classDecoration(kind, id, options, compile) {
+    return (_target, context) => {
+        if (context?.kind !== 'class')
+            throw new TypeError('Use standard class decorator semantics');
+        context.addInitializer(function () {
+            registerDefinition(kind, compile(withId(id, new this())), options.ns);
+        });
+    };
+}
+/** Method initializers bind and register automatically; no scanning or caller-side bind is needed. */
+export function methodDecoration(kind, id, metadata, handlerKey, options, compile) {
+    return (method, context) => {
+        if (context?.kind !== 'method' || context.static || context.private)
+            throw new TypeError('Use a standard public instance method decorator');
+        context.addInitializer(function () {
+            const value = { ...metadata, [handlerKey]: method.bind(this) };
+            for (const key of Reflect.ownKeys(value)) {
+                const member = value[key];
+                if (typeof member === 'function')
+                    value[key] = member.bind(this);
+            }
+            registerDefinition(kind, compile(withId(id, value)), options.ns);
+        });
+    };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Optional standard decorators. Classes are definition implementations; public instance methods
+ * keep their original host. Only definitions are created here, never Engines or ModelRunners.
+ */
+import type { WorkflowNode, AgentWorkflowDefinition } from '../../structs/execution/workflow.js';
+import type { AgentCoreEngineSetup } from '../../execution/engine.js';
+import type { ToolDefinition } from '../../structs/capabilities/tools.js';
+import type { ContextFragmentConfig } from '../../structs/support/context.js';
+import type { ModelRunnerOptions } from '../../structs/model/runtime.js';
+import { type ClassDecoration, type MethodDecoration, type DecorationOptions } from './definition.js';
+import type { IdentifiedDefinition } from './pool.js';
+export { nodePool, toolPool, fragmentPool, workflowPool, agentPool, modelPool } from './pool.js';
+export type { IdentifiedDefinition, DefinitionReader } from './pool.js';
+export type { ClassDecoration, MethodDecoration, DecorationOptions } from './definition.js';
+export type { Node, Tool, Fragment, Workflow, Agent, Model } from './types.js';
+/** Method metadata describes the adapted handler, with optional external namespaces. */
+type MethodOptions<Definition extends IdentifiedDefinition, Key extends keyof Definition> = Omit<Definition, 'id' | Key> & DecorationOptions;
+/** Instantiate a node definition class once, injecting its id; graph validation stays in Workflow. */
+export declare function node<State = any, Result = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<WorkflowNode<State, Result, App>>;
+/** Bind a named host method as run without renaming or manually binding the original object. */
+export declare function node<State = any, Result = unknown, App = any>(id: string, options: MethodOptions<WorkflowNode<State, Result, App>, 'run'>): MethodDecoration<NonNullable<WorkflowNode<State, Result, App>['run']>>;
+/** Instantiate a tool definition class; schema and authorization stay with existing defineTool. */
+export declare function tool<Input = unknown, Output = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<ToolDefinition<Input, Output, App>>;
+/** Bind an existing host method as the tool's execute callback. */
+export declare function tool<Input = unknown, Output = unknown, App = any>(id: string, options: MethodOptions<ToolDefinition<Input, Output, App>, 'execute'>): MethodDecoration<ToolDefinition<Input, Output, App>['execute']>;
+/** Instantiate a self-describing fragment class; the original builder owns formatting checks. */
+export declare function fragment<Input = unknown>(id: string, options?: DecorationOptions): ClassDecoration<ContextFragmentConfig<Input>>;
+/** Bind a host's formatter method into an original fragment configuration. */
+export declare function fragment<Input = unknown>(id: string, options: MethodOptions<ContextFragmentConfig<Input>, 'format'>): MethodDecoration<ContextFragmentConfig<Input>['format']>;
+/** Instantiate and validate workflow options, leaving actual execution with the original Engine. */
+export declare function workflow<State = any, Result = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<AgentWorkflowDefinition<State, Result, App>>;
+/** Agent id is an external pool identity, not an override of Core branch or request identity. */
+export type AgentOptions<State = unknown, Result = unknown, App = undefined> = AgentCoreEngineSetup<State, Result, App> & IdentifiedDefinition;
+/** Instantiate an Engine configuration class without creating an Engine, budget or request. */
+export declare function agent<State = unknown, Result = unknown, App = undefined>(id: string, options?: DecorationOptions): ClassDecoration<AgentOptions<State, Result, App>>;
+/** Model id is only a pool key; Core still owns the configured model/transport identities. */
+export type ModelOptions = ModelRunnerOptions & IdentifiedDefinition;
+/** Instantiate and validate model options without creating a Runner or consuming calls. */
+export declare function model(id: string, options?: DecorationOptions): ClassDecoration<ModelOptions>;

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

@@ -0,0 +1,48 @@
+import { defineTool } from '../tools.js';
+import { defineWorkflow } from '../../execution/workflow.js';
+import { defineContextFragments } from '../context/assembly.js';
+import { snapshotModelBinding } from '../../model/binding.js';
+import { classDecoration, methodDecoration, } from './definition.js';
+export { nodePool, toolPool, fragmentPool, workflowPool, agentPool, modelPool } from './pool.js';
+/** Internal conversion shared by node/tool/fragment; never a public free-function adapter. */
+function decorate(kind, id, options, key, compile) {
+    return (value, context) => {
+        if (context?.kind === 'class') {
+            classDecoration(kind, id, options, compile)(value, context);
+        }
+        else {
+            const { ns, ...metadata } = options;
+            methodDecoration(kind, id, metadata, key, { ns }, compile)(value, context);
+        }
+    };
+}
+export function node(id, options = {}) {
+    return decorate('node', id, options, 'run', (value) => value);
+}
+export function tool(id, options = {}) {
+    return decorate('tool', id, options, 'execute', (value) => defineTool(value));
+}
+export function fragment(id, options = {}) {
+    return decorate('fragment', id, options, 'format', (value) => {
+        defineContextFragments([value]);
+        return value;
+    });
+}
+/** Instantiate and validate workflow options, leaving actual execution with the original Engine. */
+export function workflow(id, options = {}) {
+    return classDecoration('workflow', id, options, (value) => {
+        defineWorkflow(value);
+        return value;
+    });
+}
+/** Instantiate an Engine configuration class without creating an Engine, budget or request. */
+export function agent(id, options = {}) {
+    return classDecoration('agent', id, options, (value) => value);
+}
+/** Instantiate and validate model options without creating a Runner or consuming calls. */
+export function model(id, options = {}) {
+    return classDecoration('model', id, options, (value) => {
+        snapshotModelBinding(value);
+        return value;
+    });
+}

package/dist/esm/support/decorators/pool.d.ts

@@ -0,0 +1,97 @@
+import type { WorkflowNode, AgentWorkflowDefinition } from '../../structs/execution/workflow.js';
+import type { ToolDefinition } from '../../structs/capabilities/tools.js';
+import type { ContextFragmentConfig } from '../../structs/support/context.js';
+/** Registration identity; ids are unique within one kind and namespace. */
+export interface IdentifiedDefinition {
+    readonly id: string;
+}
+/** Read-only roots. A typed read describes the expected contract, not a static id/type lookup. */
+export interface DefinitionReader<Definition extends IdentifiedDefinition> {
+    get<Value extends Definition = Definition>(id: string, ns?: string): Value | undefined;
+    getAll<Value extends Definition = Definition>(ns?: string): readonly Value[];
+    pick<Value extends Definition = Definition>(ids: readonly string[], ns?: string): readonly Value[];
+}
+/** Enumerable categories drive allocation and lookup; no additional runtime dispatch layer. */
+export declare const definitionKinds: readonly ["node", "tool", "fragment", "workflow", "agent", "model"];
+export type DefinitionKind = (typeof definitionKinds)[number];
+/** Preflight every destination so a conflict never leaves partial multi-namespace registration. */
+export declare function registerDefinition(kind: DefinitionKind, definition: IdentifiedDefinition, ns?: string | readonly string[]): void;
+/** Decorated nodes; ids are unique within each namespace. */
+export declare const nodePool: DefinitionReader<WorkflowNode<any, any, any>>;
+/** Decorated tools; namespaces isolate otherwise identical ids. */
+export declare const toolPool: DefinitionReader<ToolDefinition<any, any, any, string>>;
+/** Decorated fragment configurations; use the original builder to assemble them. */
+export declare const fragmentPool: DefinitionReader<ContextFragmentConfig<any>>;
+/** Decorated workflow definitions; execution still belongs to the original Engine. */
+export declare const workflowPool: DefinitionReader<AgentWorkflowDefinition<any, any, any>>;
+/** Decorated Engine options; request-specific App contracts are supplied on typed reads. */
+export declare const agentPool: DefinitionReader<(Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: import("../../index.js").AgentModelBinding;
+    models?: never;
+} & {
+    workflow?: undefined;
+    app?: never;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition) | (Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: string;
+    models: Readonly<Record<string, import("../../index.js").AgentModelBinding>>;
+    maxModelCalls?: number;
+} & {
+    workflow?: undefined;
+    app?: never;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition) | (Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: import("../../index.js").AgentModelBinding;
+    models?: never;
+} & {
+    readonly workflow: import("../../index.js").AgentWorkflow<any, any, any>;
+} & {
+    readonly app?: undefined;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition) | (Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: string;
+    models: Readonly<Record<string, import("../../index.js").AgentModelBinding>>;
+    maxModelCalls?: number;
+} & {
+    readonly workflow: import("../../index.js").AgentWorkflow<any, any, any>;
+} & {
+    readonly app?: undefined;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition)>;
+/** Decorated Runner options; reading does not create a Runner or spend model calls. */
+export declare const modelPool: DefinitionReader<{
+    provider: import("../../index.js").ChatProvider;
+    execution?: import("../../index.js").ExecutionOptions;
+    transports?: readonly import("../../index.js").ModelTransportDefinition<unknown>[] | undefined;
+    sink?: {
+        output?: import("../../index.js").ModelRunnerPorts["onOutput"];
+    };
+    errors?: {
+        inputBudget?: import("../../index.js").ModelRunnerPorts["inputBudgetError"];
+        outputBudget?: import("../../index.js").ModelRunnerPorts["outputBudgetError"];
+    };
+} & import("../../index.js").ModelRunnerSettings & IdentifiedDefinition>;