@jangts/agent-core 0.2.5 → 0.3.5

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

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+import { ProtocolRegistry } from '../../utils/protocol-registry.js';
+/** Enumerable categories drive allocation and lookup; no additional runtime dispatch layer. */
+export const 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 || definitionKinds.some((kind) => !existing.stores[kind]))
+            throw new TypeError('Incompatible decorator root registry');
+        return existing;
+    }
+    const stores = Object.fromEntries(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. */
+export 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 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 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. */
+export const nodePool = reader('node');
+/** Decorated tools; namespaces isolate otherwise identical ids. */
+export const toolPool = reader('tool');
+/** Decorated fragment configurations; use the original builder to assemble them. */
+export const fragmentPool = reader('fragment');
+/** Decorated workflow definitions; execution still belongs to the original Engine. */
+export const workflowPool = reader('workflow');
+/** Decorated Engine options; request-specific App contracts are supplied on typed reads. */
+export const agentPool = reader('agent');
+/** Decorated Runner options; reading does not create a Runner or spend model calls. */
+export const modelPool = reader('model');

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

@@ -0,0 +1,22 @@
+/**
+ * Class implementation contracts for definition decorators. The decorator supplies id;
+ * classes implement these named contracts instead of repeating Omit at every use site.
+ */
+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';
+import type { AgentCoreEngineSetup } from '../../execution/engine.js';
+import type { ModelRunnerOptions } from '../../structs/model/runtime.js';
+import type { DefinitionBody } from './definition.js';
+/** A node implementation; its public id is supplied by @node. */
+export type Node<State, Result, App = undefined> = DefinitionBody<WorkflowNode<State, Result, App>>;
+/** A tool implementation with the original schema, authorization and execution contracts. */
+export type Tool<Input = unknown, Output = unknown, App = unknown> = DefinitionBody<ToolDefinition<Input, Output, App>>;
+/** A formatter and its original provenance, trust and budget configuration. */
+export type Fragment<Input = unknown> = DefinitionBody<ContextFragmentConfig<Input>>;
+/** A complete graph definition whose workflow id is supplied by @workflow. */
+export type Workflow<State, Result, App = undefined> = DefinitionBody<AgentWorkflowDefinition<State, Result, App>>;
+/** Original Engine configuration; union branches retain their required App/model relationships. */
+export type Agent<State = unknown, Result = unknown, App = undefined> = AgentCoreEngineSetup<State, Result, App>;
+/** Original Runner configuration; the decorator's pool id is not a model identity override. */
+export type Model = ModelRunnerOptions;

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

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jangts/agent-core",
-  "version": "0.2.5",
+  "version": "0.3.5",
   "type": "commonjs",
   "license": "Apache-2.0",
   "description": "Platform-independent agent runtime and configurable modules for evidence, delivery, policies and interactions",
@@ -241,6 +241,11 @@
       "types": "./dist/esm/mock/web.d.ts",
       "import": "./dist/esm/mock/web.js",
       "require": "./dist/cjs/mock/web.js"
+    },
+    "./support/decorators": {
+      "types": "./dist/esm/support/decorators/index.d.ts",
+      "import": "./dist/esm/support/decorators/index.js",
+      "require": "./dist/cjs/support/decorators/index.js"
     }
   },
   "scripts": {
@@ -254,7 +259,8 @@
     "minisearch": "^7.2.0"
   },
   "devDependencies": {
-    "typescript": "~6.0.2"
+    "typescript": "~6.0.2",
+    "esbuild": "0.28.2"
   },
   "keywords": [
     "ai",
@@ -271,6 +277,8 @@
     "openai-compatible",
     "context-management",
     "streaming",
+    "decorators",
+    "typescript-decorators",
     "typescript",
     "nodejs",
     "browser"