@jangts/agent-core 0.2.5 → 0.3.5

package/development/docs/api/decorators.md

@@ -0,0 +1,108 @@
+# 装饰器与定义池
+
+装饰器与读取池从 `@jangts/agent-core/support/decorators` 导入，仅支持 TypeScript 标准装饰器语义。启用了 experimentalDecorators 的 NestJS 编译单元不能直接使用。普通对象、define、构造与 bind 入口保持可用。无新增运行时依赖，不使用 reflect-metadata 或自动 DI。
+
+类装饰器代办定义实例化与 id 注入；实例方法装饰器将原方法绑定为 handler，保留原对象及 this。产物仍是原合同的定义或配置，不创建 Engine／ModelRunner，不改变预算、取消、授权、状态提交与工具回执。
+
+## 类：处理单元与内部协作
+
+从同一子路径导入 Node、Tool、Fragment、Workflow、Agent、Model 类型，描述类应提供的原字段与方法；id 由装饰器补齐，无需重复写 Omit。Agent 保留原配置的联合类型分支，由装饰器检查，不要求 class implements 联合类型。
+
+```ts
+import { AgentCoreEngine, defineWorkflow } from '@jangts/agent-core';
+import { node, nodePool } from '@jangts/agent-core/support/decorators';
+import type { Node } from '@jangts/agent-core/support/decorators';
+
+type State = { text: string; answer?: string };
+
+@node<State, string>('greet', { ns: 'chat' })
+class Greeting implements Node<State, string> {
+  readonly description = '问候';
+  readonly routes = [{ complete: (state: Readonly<State>) => state.answer! }];
+  #prefix = '你好，';
+  run(state: Readonly<State>) {
+    return { answer: this._format(state.text) };
+  }
+  private _format(text: string) { return this.#prefix + text.trim(); }
+}
+
+const workflow = defineWorkflow<State, string>({
+  id: 'greeting', nodes: nodePool.getAll('chat'),
+});
+console.log(await new AgentCoreEngine({ workflow }).run({ text: '访客' }));
+```
+
+id 只来自装饰器；类中重复声明 id 会拒绝。定义类必须可无参构造，在静态初始化完成后构造一次；池读取不再构造。配置字段、handler 及内部方法由类提供，不在装饰器中重复 metadata。私有字段、getter 和原型方法保留真实接收者。构造函数只初始化定义，不执行业务操作。
+
+## 命名空间与读取
+
+每种定义各有一个共享读取池：nodePool、toolPool、fragmentPool、workflowPool、agentPool、modelPool。调用方无需创建池或手动登记。所有装饰器接受可选的 `{ ns: string | readonly string[] }`，缺省为 `'default'`。
+
+```ts
+nodePool.get('greet', 'chat');            // 单个定义，缺失为 undefined
+nodePool.getAll('chat');                  // 此命名空间全部定义
+nodePool.pick(['greet', 'answer'], 'chat'); // 按指定顺序选取，缺失或重复 id 抛错
+nodePool.get('greet');                    // 等价于 get('greet', 'default')
+nodePool.getAll();                        // 只读 default，不跨命名空间合并
+nodePool.pick(['greet']);                 // 在 default 中选取
+```
+
+同一类型、同一命名空间内 id 唯一；不同命名空间或不同类型可同名。ns 精确匹配，不支持层级、通配或隐式回退，空白名称与空数组拒绝。数组中的重复命名空间去重。`ns: ['chat', 'assistant']` 将同一已构造定义登记到两个空间，不重复构造、不复制实例；任一目标重名则整次登记拒绝，不留下部分写入。
+
+getAll 返回登记顺序的只读数组快照；未知命名空间返回空数组。pick 返回入参顺序的只读数组快照，空 id 数组返回空数组。读取方法可使用原定义类型泛型，如 `nodePool.get<WorkflowNode<State, string>>('greet', 'chat')`；泛型描述调用方预期合同，不是运行时类型证明。
+
+ns 仅用于辅助登记，不进入 Core options；取出的 id 仍为原 id。把不同命名空间的同名定义装入同一 Workflow／ToolRegistry 时，原入口仍拒绝重名。Workflow 节点顺序与路由由 App 明确组织，不把模块导入顺序当成业务执行顺序。池不公开创建、写入、清空或封存接口，不支持 tags 或 owner 查询。
+
+## 已有实例：保留业务方法名
+
+```ts
+class GreetingService {
+  constructor(private readonly prefix: string) {}
+  @node<State, string>('reply', {
+    ns: 'chat-service',
+    description: '调用已有服务',
+    routes: [{ complete: (state: Readonly<State>) => state.answer! }],
+  })
+  answer(state: Readonly<State>) {
+    return { answer: this._format(state.text) };
+  }
+  private _format(text: string) { return this.prefix + text; }
+}
+const service = new GreetingService('你好，'); // 创建原宿主，自动绑定与登记
+const definition = nodePool.get('reply', 'chat-service');
+```
+
+方法装饰器用标准实例初始化钩子绑定并登记，不需要 registerFrom、手写 bind 或额外类装饰器。该钩子先于实例字段与构造函数体运行，因此只绑定、不执行 handler，不访问未初始化的业务字段。调用方必须等待宿主构造成功后再读取并运行定义；构造失败不回滚已完成的初始化登记，应视为装配失败。池持有真实宿主的绑定引用，适用于长期存活的定义／服务实例，不是请求级实例工厂。同命名空间同 id 的第二个实例拒绝登记，不覆盖第一个绑定。
+
+metadata 中的直接回调同样绑定到宿主；嵌套 schema 与 routes 保留原合同接收者，箭头函数保留词法 this。仅支持公开实例方法，不支持静态／私有方法、普通顶层函数的 @ 语法或隐式继承合并。
+
+## getter 与按状态选路
+
+```ts
+get routes(): Node<State, string>['routes'] {
+  return [
+    { when: state => this._hasAnswer(state), complete: state => state.answer! },
+    { complete: () => '没有可交付的回答' },
+  ];
+}
+private _hasAnswer(state: Readonly<State>) {
+  return Boolean(state.answer?.trim());
+}
+```
+
+Workflow 装配时读取并固定路由表；getter 应无副作用，不依赖调用次数，也不读取本次请求状态。每次 run 提交补丁后，when／complete 获得最新 state，并可调用原类辅助方法。getter 不会每轮重建路由；不要把请求 state 存在共享节点 this 上。
+
+## 定义类型与原入口
+
+| 装饰器 | 类的结构 | 方法适配 | 读取池 | 后续入口 |
+| --- | --- | --- | --- | --- |
+| node | Node<State, Result, App> | run | nodePool | defineWorkflow |
+| tool | Tool<Input, Output, App> | execute | toolPool | defineTool／defineToolCatalog |
+| fragment | Fragment<Input> | format | fragmentPool | defineContextFragments |
+| workflow | Workflow<State, Result, App> | 不提供 | workflowPool | defineWorkflow |
+| agent | Agent<State, Result, App> | 不提供 | agentPool | App 创建 Engine |
+| model | Model | 不提供 | modelPool | App 创建 ModelRunner |
+
+agent／model 的 id 是辅助登记键，不覆盖 Core 分支、模型或 transport 身份。工具复用原 defineTool 校验；Workflow 复用原图校验，节点在完整图中验证；fragment 复用原 builder 的 formatter 检查，数据、信任与预算保持原合同；model 复用原配置快照验证，不消耗模型调用。辅助层不公开 metadata＋普通函数转换入口，顶层函数直接填入原 options。
+
+同一 JavaScript realm 内 ESM／CJS 副本共享池；不同进程、Worker 或独立 realm 不共享。两次独立加载并装饰同命名空间同 id 的类仍会重名拒绝，不自动合并。定义模块必须被打包图明确保留；被 tree-shaking 删除的纯副作用导入不能保证登记。共享定义不能保存请求身份、signal 或请求预算；池读取不是执行或授权。

package/development/docs/api/reference.md

@@ -2266,3 +2266,35 @@
 | `sources` | value | [声明](../../../dist/esm/mock/web.d.ts#L8) |
 | `WebOptions` | type | [声明](../../../dist/esm/mock/web.d.ts#L8) |
 | `WebProfile` | type | [声明](../../../dist/esm/mock/web.d.ts#L8) |
+
+## @jangts/agent-core/support/decorators
+
+[合同与行为](support.md) · 25 个导出符号
+
+| 符号 | 类型／值 | 声明与说明 |
+| --- | --- | --- |
+| `agent` | value | [声明](../../../dist/esm/support/decorators/index.d.ts#L35) |
+| `Agent` | type | [声明](../../../dist/esm/support/decorators/types.d.ts#L20) |
+| `AgentOptions` | type | [声明](../../../dist/esm/support/decorators/index.d.ts#L33) |
+| `agentPool` | value | [声明](../../../dist/esm/support/decorators/pool.d.ts#L28) |
+| `ClassDecoration` | type | [声明](../../../dist/esm/support/decorators/definition.d.ts#L13) |
+| `DecorationOptions` | type | [声明](../../../dist/esm/support/decorators/definition.d.ts#L10) |
+| `DefinitionReader` | type | [声明](../../../dist/esm/support/decorators/pool.d.ts#L9) |
+| `fragment` | value | [声明](../../../dist/esm/support/decorators/index.d.ts#L27) |
+| `Fragment` | type | [声明](../../../dist/esm/support/decorators/types.d.ts#L16) |
+| `fragmentPool` | value | [声明](../../../dist/esm/support/decorators/pool.d.ts#L24) |
+| `IdentifiedDefinition` | type | [声明](../../../dist/esm/support/decorators/pool.d.ts#L5) |
+| `MethodDecoration` | type | [声明](../../../dist/esm/support/decorators/definition.d.ts#L14) |
+| `model` | value | [声明](../../../dist/esm/support/decorators/index.d.ts#L39) |
+| `Model` | type | [声明](../../../dist/esm/support/decorators/types.d.ts#L22) |
+| `ModelOptions` | type | [声明](../../../dist/esm/support/decorators/index.d.ts#L37) |
+| `modelPool` | value | [声明](../../../dist/esm/support/decorators/pool.d.ts#L86) |
+| `node` | value | [声明](../../../dist/esm/support/decorators/index.d.ts#L19) |
+| `Node` | type | [声明](../../../dist/esm/support/decorators/types.d.ts#L12) |
+| `nodePool` | value | [声明](../../../dist/esm/support/decorators/pool.d.ts#L20) |
+| `tool` | value | [声明](../../../dist/esm/support/decorators/index.d.ts#L23) |
+| `Tool` | type | [声明](../../../dist/esm/support/decorators/types.d.ts#L14) |
+| `toolPool` | value | [声明](../../../dist/esm/support/decorators/pool.d.ts#L22) |
+| `workflow` | value | [声明](../../../dist/esm/support/decorators/index.d.ts#L31) |
+| `Workflow` | type | [声明](../../../dist/esm/support/decorators/types.d.ts#L18) |
+| `workflowPool` | value | [声明](../../../dist/esm/support/decorators/pool.d.ts#L26) |

package/development/skills/agent-core-app/SKILL.md

@@ -74,3 +74,7 @@ A custom response collector is synchronous and request-local. Its outputChars mu
 ## Node cache ownership
 
 Use context.cache for bounded Engine memory; its default capacity is 1024, partitions are node-local and only get may name another node. The low-level step partition is `$step`. An App may explicitly inject an asynchronous AgentCachePort for context.agentCache. Persistence must be supported explicitly, is separate from volatile storage and never falls back. The App owns user isolation, serialization, capacity and expiry; do not cache authorization decisions. Forks start with empty Engine memory and only regain an App port when resume explicitly supplies agentCache. Keep durable facts in state/App storage, not caches.
+
+## Optional definition decorators
+
+Use the standard-only /support/decorators entry for class-based definitions or existing host methods. Classes supply original options except id; the decorator constructs once and supplies id. Host methods bind and register automatically during standard instance initialization; read and execute only after successful construction. Constructor failures do not roll back initializer registration. Use long-lived service hosts, never request-scoped ones. Keep helper methods/private fields in their real class, never a duplicate options metadata block or empty carrier. Existing Nest legacy compilation keeps object definitions. No public metadata-plus-function adapters, Engine factories, automatic DI or request lifecycle wrappers are provided. Use nodePool/toolPool/fragmentPool/workflowPool/agentPool/modelPool, without creating pools or manually registering. Decorator ns is a string or string array, default 'default'; same-kind ids are unique within a namespace. Read get(id, ns?), getAll(ns?) or pick(ids, ns?); get may return undefined. Multi-namespace registration shares one definition and preflights all conflicts. ESM/CJS copies share readers within one realm. Read api/decorators.md for registration, receivers and type limits.

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classDecoration = classDecoration;
+exports.methodDecoration = methodDecoration;
+/**
+ * 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.
+ */
+const pool_js_1 = require("./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. */
+function classDecoration(kind, id, options, compile) {
+    return (_target, context) => {
+        if (context?.kind !== 'class')
+            throw new TypeError('Use standard class decorator semantics');
+        context.addInitializer(function () {
+            (0, pool_js_1.registerDefinition)(kind, compile(withId(id, new this())), options.ns);
+        });
+    };
+}
+/** Method initializers bind and register automatically; no scanning or caller-side bind is needed. */
+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);
+            }
+            (0, pool_js_1.registerDefinition)(kind, compile(withId(id, value)), options.ns);
+        });
+    };
+}

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

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelPool = exports.agentPool = exports.workflowPool = exports.fragmentPool = exports.toolPool = exports.nodePool = void 0;
+exports.node = node;
+exports.tool = tool;
+exports.fragment = fragment;
+exports.workflow = workflow;
+exports.agent = agent;
+exports.model = model;
+const tools_js_1 = require("../tools.js");
+const workflow_js_1 = require("../../execution/workflow.js");
+const assembly_js_1 = require("../context/assembly.js");
+const binding_js_1 = require("../../model/binding.js");
+const definition_js_1 = require("./definition.js");
+var pool_js_1 = require("./pool.js");
+Object.defineProperty(exports, "nodePool", { enumerable: true, get: function () { return pool_js_1.nodePool; } });
+Object.defineProperty(exports, "toolPool", { enumerable: true, get: function () { return pool_js_1.toolPool; } });
+Object.defineProperty(exports, "fragmentPool", { enumerable: true, get: function () { return pool_js_1.fragmentPool; } });
+Object.defineProperty(exports, "workflowPool", { enumerable: true, get: function () { return pool_js_1.workflowPool; } });
+Object.defineProperty(exports, "agentPool", { enumerable: true, get: function () { return pool_js_1.agentPool; } });
+Object.defineProperty(exports, "modelPool", { enumerable: true, get: function () { return pool_js_1.modelPool; } });
+/** 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') {
+            (0, definition_js_1.classDecoration)(kind, id, options, compile)(value, context);
+        }
+        else {
+            const { ns, ...metadata } = options;
+            (0, definition_js_1.methodDecoration)(kind, id, metadata, key, { ns }, compile)(value, context);
+        }
+    };
+}
+function node(id, options = {}) {
+    return decorate('node', id, options, 'run', (value) => value);
+}
+function tool(id, options = {}) {
+    return decorate('tool', id, options, 'execute', (value) => (0, tools_js_1.defineTool)(value));
+}
+function fragment(id, options = {}) {
+    return decorate('fragment', id, options, 'format', (value) => {
+        (0, assembly_js_1.defineContextFragments)([value]);
+        return value;
+    });
+}
+/** Instantiate and validate workflow options, leaving actual execution with the original Engine. */
+function workflow(id, options = {}) {
+    return (0, definition_js_1.classDecoration)('workflow', id, options, (value) => {
+        (0, workflow_js_1.defineWorkflow)(value);
+        return value;
+    });
+}
+/** Instantiate an Engine configuration class without creating an Engine, budget or request. */
+function agent(id, options = {}) {
+    return (0, definition_js_1.classDecoration)('agent', id, options, (value) => value);
+}
+/** Instantiate and validate model options without creating a Runner or consuming calls. */
+function model(id, options = {}) {
+    return (0, definition_js_1.classDecoration)('model', id, options, (value) => {
+        (0, binding_js_1.snapshotModelBinding)(value);
+        return value;
+    });
+}

package/dist/cjs/support/decorators/pool.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelPool = exports.agentPool = exports.workflowPool = exports.fragmentPool = exports.toolPool = exports.nodePool = exports.definitionKinds = void 0;
+exports.registerDefinition = registerDefinition;
+/**
+ * One process-realm definition registry per kind. The shared symbol makes ESM/CJS copies
+ * consume the same stores; consumers receive frozen read-only views, never pool factories.
+ */
+const protocol_registry_js_1 = require("../../utils/protocol-registry.js");
+/** Enumerable categories drive allocation and lookup; no additional runtime dispatch layer. */
+exports.definitionKinds = ['node', 'tool', 'fragment', 'workflow', 'agent', 'model'];
+const sharedKey = Symbol.for('@jangts/agent-core/decorator-roots/v2');
+const realm = globalThis;
+/** Allocate once per realm, including when another module format initialized the roots first. */
+function sharedPools() {
+    const existing = realm[sharedKey];
+    if (existing) {
+        if (existing.version !== 2 || exports.definitionKinds.some((kind) => !existing.stores[kind]))
+            throw new TypeError('Incompatible decorator root registry');
+        return existing;
+    }
+    const stores = Object.fromEntries(exports.definitionKinds.map((kind) => [kind, new Map()]));
+    const pools = Object.freeze({ version: 2, stores: Object.freeze(stores) });
+    Object.defineProperty(globalThis, sharedKey, { value: pools });
+    return pools;
+}
+/** Namespace is an exact, nonblank key; no trimming, fallback or hierarchy is applied. */
+function namespace(value) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError('Decorator namespace must be a nonempty string');
+    return value;
+}
+/** Preflight every destination so a conflict never leaves partial multi-namespace registration. */
+function registerDefinition(kind, definition, ns = 'default') {
+    if (typeof definition.id !== 'string' || !definition.id.trim())
+        throw new TypeError('Invalid decorator definition id');
+    const requested = typeof ns === 'string' ? [ns] : ns;
+    if (!Array.isArray(requested) || requested.length === 0)
+        throw new TypeError('Decorator ns must be a namespace or a nonempty namespace array');
+    const names = [...new Set(requested.map(namespace))];
+    const store = sharedPools().stores[kind];
+    for (const name of names) {
+        if (store.get(name)?.has(definition.id))
+            throw new Error(`Duplicate ${kind} definition: ${definition.id} (ns: ${name})`);
+    }
+    for (const name of names) {
+        let entries = store.get(name);
+        if (!entries)
+            store.set(name, (entries = new protocol_registry_js_1.ProtocolRegistry()));
+        entries.set(definition.id, definition);
+    }
+}
+/** Root reads never instantiate or execute definitions; array results are immutable snapshots. */
+function reader(kind) {
+    const store = sharedPools().stores[kind];
+    return Object.freeze({
+        get(id, ns = 'default') {
+            return store.get(namespace(ns))?.get(id);
+        },
+        getAll(ns = 'default') {
+            return Object.freeze([...(store.get(namespace(ns))?.values() ?? [])]);
+        },
+        pick(ids, ns = 'default') {
+            const entries = store.get(namespace(ns));
+            const selected = new protocol_registry_js_1.ProtocolRegistry();
+            for (const id of ids) {
+                const definition = entries?.get(id);
+                if (!definition)
+                    throw new TypeError(`Unknown ${kind} definition: ${id} (ns: ${ns})`);
+                selected.set(id, definition);
+            }
+            return Object.freeze([...selected.values()]);
+        },
+    });
+}
+/** Decorated nodes; ids are unique within each namespace. */
+exports.nodePool = reader('node');
+/** Decorated tools; namespaces isolate otherwise identical ids. */
+exports.toolPool = reader('tool');
+/** Decorated fragment configurations; use the original builder to assemble them. */
+exports.fragmentPool = reader('fragment');
+/** Decorated workflow definitions; execution still belongs to the original Engine. */
+exports.workflowPool = reader('workflow');
+/** Decorated Engine options; request-specific App contracts are supplied on typed reads. */
+exports.agentPool = reader('agent');
+/** Decorated Runner options; reading does not create a Runner or spend model calls. */
+exports.modelPool = reader('model');

package/dist/cjs/support/decorators/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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>;