@ddse/acm-sdk 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +50 -1
  2. package/dist/src/context.d.ts +3 -0
  3. package/dist/src/context.d.ts.map +1 -1
  4. package/dist/src/context.js +11 -16
  5. package/dist/src/context.js.map +1 -1
  6. package/dist/src/hash.d.ts +17 -0
  7. package/dist/src/hash.d.ts.map +1 -0
  8. package/dist/src/hash.js +70 -0
  9. package/dist/src/hash.js.map +1 -0
  10. package/dist/src/index.d.ts +1 -0
  11. package/dist/src/index.d.ts.map +1 -1
  12. package/dist/src/index.js +1 -0
  13. package/dist/src/index.js.map +1 -1
  14. package/dist/src/nucleus.d.ts +45 -0
  15. package/dist/src/nucleus.d.ts.map +1 -1
  16. package/dist/src/nucleus.js +363 -33
  17. package/dist/src/nucleus.js.map +1 -1
  18. package/dist/src/registry.d.ts +28 -1
  19. package/dist/src/registry.d.ts.map +1 -1
  20. package/dist/src/registry.js +46 -0
  21. package/dist/src/registry.js.map +1 -1
  22. package/dist/src/task.d.ts +31 -0
  23. package/dist/src/task.d.ts.map +1 -1
  24. package/dist/src/task.js +9 -0
  25. package/dist/src/task.js.map +1 -1
  26. package/dist/src/tool.d.ts +56 -0
  27. package/dist/src/tool.d.ts.map +1 -1
  28. package/dist/src/tool.js +14 -1
  29. package/dist/src/tool.js.map +1 -1
  30. package/dist/src/types.d.ts +7 -1
  31. package/dist/src/types.d.ts.map +1 -1
  32. package/dist/tests/phase4-integration.test.js +5 -2
  33. package/dist/tests/phase4-integration.test.js.map +1 -1
  34. package/dist/tests/query-context.test.d.ts +2 -0
  35. package/dist/tests/query-context.test.d.ts.map +1 -0
  36. package/dist/tests/query-context.test.js +1237 -0
  37. package/dist/tests/query-context.test.js.map +1 -0
  38. package/dist/tsconfig.tsbuildinfo +1 -1
  39. package/package.json +16 -2
  40. package/src/capability.ts +0 -11
  41. package/src/context-provider.ts +0 -136
  42. package/src/context.ts +0 -190
  43. package/src/index.ts +0 -12
  44. package/src/nucleus.ts +0 -341
  45. package/src/policy.ts +0 -9
  46. package/src/registry.ts +0 -7
  47. package/src/stream.ts +0 -24
  48. package/src/task.ts +0 -38
  49. package/src/tool.ts +0 -6
  50. package/src/types.ts +0 -233
  51. package/src/utils.ts +0 -271
  52. package/tests/phase4-integration.test.ts +0 -138
  53. package/tsconfig.json +0 -8
  54. package/tsconfig.tsbuildinfo +0 -1
package/README.md CHANGED
@@ -20,6 +20,8 @@ pnpm add @ddse/acm-sdk
20
20
  - **Task<I, O>**: Base class for logical task units
21
21
  - **CapabilityRegistry**: Interface for task registries
22
22
  - **ToolRegistry**: Interface for tool registries
23
+ - **Nucleus**: Abstract reasoning core with preflight, invoke, and postcheck lifecycle
24
+ - **DeterministicNucleus**: Concrete nucleus with built-in context tools, token budget enforcement, and anti-hallucination grounding
23
25
 
24
26
  ### Types
25
27
 
@@ -30,11 +32,17 @@ pnpm add @ddse/acm-sdk
30
32
  - **LedgerEntry**: Memory ledger entry
31
33
  - **PolicyDecision**: Authorization result
32
34
  - **RunContext**: Execution context passed to tasks
35
+ - **NucleusConfig**: Nucleus configuration including `maxContextTokens`, `maxQueryRounds`, and `contextProvider`
36
+ - **NucleusInvokeResult**: Invoke result with optional `metrics` (rounds, estimatedPromptTokens, budgetExhausted)
33
37
 
34
38
  ### Utilities
35
39
 
36
40
  - **DefaultStreamSink**: Stream multiplexer for real-time updates
37
41
  - **PolicyEngine**: Interface for policy decision points
42
+ - **ContextBuilder**: Fluent builder for constructing Context objects with content-addressable refs
43
+ - **InternalContextScopeImpl**: Runtime artifact scope with `sizeBytes` tracking and wide provenance support
44
+ - **ExternalContextProviderAdapter**: Bridges Nucleus retrieval directives to developer-supplied tools
45
+ - **estimateTokens(text)**: Heuristic token estimator with code-aware char/token ratios (aligned with production BudgetManager)
38
46
 
39
47
  ## Usage
40
48
 
@@ -215,7 +223,48 @@ This package implements the core abstractions from ACM v0.5:
215
223
  - **Tool**: Section 2.5
216
224
  - **Context**: Section 4
217
225
  - **Plan**: Section 5.4
226
+ - **Nucleus**: Reasoning core with context tools and token budget
227
+
228
+ ## Nucleus Features
229
+
230
+ ### Built-in Context Tools
231
+
232
+ The `DeterministicNucleus` auto-injects two tools into every LLM call:
233
+
234
+ 1. **`query_context`** — Read data already in scope (`list`, `read_fact`, `read_augmentation`, `read_assumptions`, `read_artifact`).
235
+ 2. **`request_context_retrieval`** — Fetch external data not in scope; fulfilled inline when a `contextProvider` is configured.
236
+
237
+ ### Token Budget Enforcement
238
+
239
+ Set `maxContextTokens` on `NucleusConfig` to pass the model's context window size. The `callLLM` loop estimates cumulative prompt tokens using `estimateTokens()` and forces a final answer (stripping built-in tools) when usage exceeds 85% of the budget.
240
+
241
+ ```typescript
242
+ const config: NucleusConfig = {
243
+ goalId: 'g1',
244
+ goalIntent: 'Analyze the codebase',
245
+ contextRef: 'sha256-abc',
246
+ llmCall: { provider: 'vllm', model: 'Qwen/Qwen3-4B', maxTokens: 4096 },
247
+ maxContextTokens: 20480, // model's context window
248
+ maxQueryRounds: 25, // max tool loop iterations (default 25)
249
+ };
250
+ ```
251
+
252
+ The result includes metrics:
253
+
254
+ ```typescript
255
+ const result = await nucleus.invoke({ input: task, tools: myTools });
256
+ console.log(result.metrics);
257
+ // { rounds: 3, estimatedPromptTokens: 12400, budgetExhausted: false }
258
+ ```
259
+
260
+ ### Anti-Hallucination Grounding
261
+
262
+ All prompts include grounding directives that force the LLM to:
263
+ - Use `query_context` before generating output
264
+ - Cite which fact keys, augmentation indices, or artifact IDs were read
265
+ - Refuse to fabricate information not present in context
266
+ - Call `request_context_retrieval` when needed data is missing
218
267
 
219
268
  ## License
220
269
 
221
- Apache-2.0
270
+ MIT
@@ -22,10 +22,12 @@ export declare class InternalContextScopeImpl implements InternalContextScope {
22
22
  type: string;
23
23
  content: any;
24
24
  digest: string;
25
+ sizeBytes?: number;
25
26
  provenance?: {
26
27
  retrievedAt: number;
27
28
  tool?: string;
28
29
  rationale?: string;
30
+ [key: string]: any;
29
31
  };
30
32
  }>;
31
33
  private ledgerAppend?;
@@ -34,6 +36,7 @@ export declare class InternalContextScopeImpl implements InternalContextScope {
34
36
  addArtifact(type: string, content: any, provenance?: {
35
37
  tool?: string;
36
38
  rationale?: string;
39
+ [extra: string]: any;
37
40
  }): string;
38
41
  promote(artifactId: string): Promise<void>;
39
42
  getArtifact(id: string): any;
@@ -1 +1 @@
1
- {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnF,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,UAAU,CAAmC;IAErD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAM1D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAKtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAK1C,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKvC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKrD,aAAa,CAAC,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI;IAK5D,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa;IActC,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,aAAa;IAMrB,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM;CAYzD;AAED,qBAAa,wBAAyB,YAAW,oBAAoB;IACnE,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,GAAG,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE;YACX,WAAW,EAAE,MAAM,CAAC;YACpB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC,CAAM;IAER,OAAO,CAAC,YAAY,CAAC,CAA+B;IACpD,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;IAIvD,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,GAAG,EACZ,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,MAAM;IAmCH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BhD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG;IAK5B,OAAO,CAAC,aAAa;CAKtB"}
1
+ {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnF,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,UAAU,CAAmC;IAErD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAM1D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAKtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAK1C,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKvC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKrD,aAAa,CAAC,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI;IAK5D,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa;IActC,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,aAAa;IAIrB,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM;CAUzD;AAED,qBAAa,wBAAyB,YAAW,oBAAoB;IACnE,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,GAAG,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE;YACX,WAAW,EAAE,MAAM,CAAC;YACpB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;SACpB,CAAC;KACH,CAAC,CAAM;IAER,OAAO,CAAC,YAAY,CAAC,CAA+B;IACpD,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;IAIvD,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,GAAG,EACZ,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC;KACtB,GACA,MAAM;IAsCH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BhD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG;IAK5B,OAAO,CAAC,aAAa;CAGtB"}
@@ -1,5 +1,5 @@
1
1
  // Context orchestration utilities
2
- import { createHash } from 'crypto';
2
+ import { universalDigest } from './hash.js';
3
3
  export class ContextBuilder {
4
4
  sources = [];
5
5
  facts = {};
@@ -44,33 +44,27 @@ export class ContextBuilder {
44
44
  return packet;
45
45
  }
46
46
  computePacketId() {
47
- // Compute SHA-256 hash of the normalized packet
47
+ // Compute digest of the normalized packet
48
48
  const normalized = JSON.stringify({
49
49
  sources: this.sources,
50
50
  facts: this.facts,
51
51
  assumptions: this.assumptions,
52
52
  augmentations: this.augmentations,
53
53
  });
54
- const hash = createHash('sha256');
55
- hash.update(normalized);
56
- return `sha256-${hash.digest('hex')}`;
54
+ return `sha256-${universalDigest(normalized)}`;
57
55
  }
58
56
  computeDigest(content) {
59
- const hash = createHash('sha256');
60
- hash.update(content);
61
- return `sha256-${hash.digest('hex').substring(0, 32)}`;
57
+ return `sha256-${universalDigest(content).substring(0, 32)}`;
62
58
  }
63
59
  static computeContextRef(context) {
64
- // Compute full SHA-256 hash of the normalized context packet
60
+ // Compute digest of the normalized context packet
65
61
  const normalized = JSON.stringify({
66
62
  sources: context.sources,
67
63
  facts: context.facts,
68
64
  assumptions: context.assumptions,
69
65
  augmentations: context.augmentations,
70
66
  });
71
- const hash = createHash('sha256');
72
- hash.update(normalized);
73
- return hash.digest('hex');
67
+ return universalDigest(normalized);
74
68
  }
75
69
  }
76
70
  export class InternalContextScopeImpl {
@@ -82,12 +76,15 @@ export class InternalContextScopeImpl {
82
76
  }
83
77
  addArtifact(type, content, provenance) {
84
78
  const id = `artifact-${Date.now()}-${Math.random().toString(36).substring(7)}`;
85
- const digest = this.computeDigest(JSON.stringify(content));
79
+ const serialized = typeof content === 'string' ? content : JSON.stringify(content);
80
+ const digest = this.computeDigest(serialized);
81
+ const sizeBytes = new TextEncoder().encode(serialized).byteLength;
86
82
  this.artifacts.push({
87
83
  id,
88
84
  type,
89
85
  content,
90
86
  digest,
87
+ sizeBytes,
91
88
  provenance: provenance
92
89
  ? {
93
90
  retrievedAt: Date.now(),
@@ -140,9 +137,7 @@ export class InternalContextScopeImpl {
140
137
  return artifact?.content;
141
138
  }
142
139
  computeDigest(content) {
143
- const hash = createHash('sha256');
144
- hash.update(content);
145
- return hash.digest('hex').substring(0, 32);
140
+ return universalDigest(content).substring(0, 32);
146
141
  }
147
142
  }
148
143
  //# sourceMappingURL=context.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Universal digest function — works in both Node.js and browser environments.
3
+ *
4
+ * Uses Node's crypto.createHash when available (server-side), falls back to a
5
+ * fast synchronous hash for browser contexts where `crypto` is externalized
6
+ * by Vite. These digests are used for ledger entries, dedup, and context
7
+ * packet IDs — NOT for security — so a non-cryptographic hash is acceptable.
8
+ */
9
+ /**
10
+ * Synchronous hex digest of the input string.
11
+ *
12
+ * - Node.js: SHA-256 via `crypto.createHash` (same output as before).
13
+ * - Browser: FNV-1a 128-bit (two 64-bit passes with different offsets)
14
+ * producing a 32-char hex string — sufficient for dedup/ledger IDs.
15
+ */
16
+ export declare function universalDigest(input: string): string;
17
+ //# sourceMappingURL=hash.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD"}
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Universal digest function — works in both Node.js and browser environments.
3
+ *
4
+ * Uses Node's crypto.createHash when available (server-side), falls back to a
5
+ * fast synchronous hash for browser contexts where `crypto` is externalized
6
+ * by Vite. These digests are used for ledger entries, dedup, and context
7
+ * packet IDs — NOT for security — so a non-cryptographic hash is acceptable.
8
+ */
9
+ let _nodeCrypto;
10
+ try {
11
+ // Dynamic require avoids Vite's static-analysis externalization.
12
+ // In Node.js this succeeds; in the browser it throws.
13
+ _nodeCrypto = globalThis.__acm_crypto ??
14
+ (() => {
15
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
16
+ const c = typeof require === 'function'
17
+ ? require('crypto')
18
+ : undefined;
19
+ globalThis.__acm_crypto = c;
20
+ return c;
21
+ })();
22
+ }
23
+ catch {
24
+ _nodeCrypto = undefined;
25
+ }
26
+ /**
27
+ * Synchronous hex digest of the input string.
28
+ *
29
+ * - Node.js: SHA-256 via `crypto.createHash` (same output as before).
30
+ * - Browser: FNV-1a 128-bit (two 64-bit passes with different offsets)
31
+ * producing a 32-char hex string — sufficient for dedup/ledger IDs.
32
+ */
33
+ export function universalDigest(input) {
34
+ if (_nodeCrypto) {
35
+ const hash = _nodeCrypto.createHash('sha256');
36
+ hash.update(input);
37
+ return hash.digest('hex');
38
+ }
39
+ return fnv1aHex128(input);
40
+ }
41
+ // ─── FNV-1a browser fallback ────────────────────────────────────────────────
42
+ /*
43
+ * FNV-1a operating on 32-bit chunks. We run 4 independent lanes with
44
+ * staggered offsets to produce a 128-bit (32-char hex) digest. This is
45
+ * NOT cryptographically secure but has excellent distribution for the
46
+ * short-to-medium strings used in ledger digests and context packet IDs.
47
+ */
48
+ const FNV_PRIME = 0x01000193;
49
+ const FNV_OFFSETS = [
50
+ 0x811c9dc5, // standard FNV-1a 32-bit offset
51
+ 0xa2ca53c9, // custom offset 2
52
+ 0x3b2c1f7d, // custom offset 3
53
+ 0xf5e8d4b1, // custom offset 4
54
+ ];
55
+ function fnv1a32(input, offset) {
56
+ let h = offset >>> 0;
57
+ for (let i = 0; i < input.length; i++) {
58
+ h ^= input.charCodeAt(i);
59
+ h = Math.imul(h, FNV_PRIME) >>> 0;
60
+ }
61
+ return h >>> 0;
62
+ }
63
+ function fnv1aHex128(input) {
64
+ let hex = '';
65
+ for (const offset of FNV_OFFSETS) {
66
+ hex += fnv1a32(input, offset).toString(16).padStart(8, '0');
67
+ }
68
+ return hex;
69
+ }
70
+ //# sourceMappingURL=hash.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,IAAI,WAAgD,CAAC;AACrD,IAAI,CAAC;IACH,iEAAiE;IACjE,sDAAsD;IACtD,WAAW,GAAI,UAAkB,CAAC,YAAY;QAC5C,CAAC,GAAG,EAAE;YACJ,iEAAiE;YACjE,MAAM,CAAC,GAAG,OAAO,OAAO,KAAK,UAAU;gBACrC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;gBACnB,CAAC,CAAC,SAAS,CAAC;YACb,UAAkB,CAAC,YAAY,GAAG,CAAC,CAAC;YACrC,OAAO,CAAC,CAAC;QACX,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAAC,MAAM,CAAC;IACP,WAAW,GAAG,SAAS,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,+EAA+E;AAE/E;;;;;GAKG;AAEH,MAAM,SAAS,GAAG,UAAU,CAAC;AAC7B,MAAM,WAAW,GAAG;IAClB,UAAU,EAAG,gCAAgC;IAC7C,UAAU,EAAG,kBAAkB;IAC/B,UAAU,EAAG,kBAAkB;IAC/B,UAAU,EAAG,kBAAkB;CAChC,CAAC;AAEF,SAAS,OAAO,CAAC,KAAa,EAAE,MAAc;IAC5C,IAAI,CAAC,GAAG,MAAM,KAAK,CAAC,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QACjC,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
@@ -9,4 +9,5 @@ export * from './nucleus.js';
9
9
  export * from './context.js';
10
10
  export * from './context-provider.js';
11
11
  export * from './utils.js';
12
+ export { universalDigest } from './hash.js';
12
13
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}
package/dist/src/index.js CHANGED
@@ -10,4 +10,5 @@ export * from './nucleus.js';
10
10
  export * from './context.js';
11
11
  export * from './context-provider.js';
12
12
  export * from './utils.js';
13
+ export { universalDigest } from './hash.js';
13
14
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}
@@ -1,4 +1,5 @@
1
1
  import type { Context, InternalContextScope, LedgerEntry } from './types.js';
2
+ import type { ExternalContextProviderAdapter } from './context-provider.js';
2
3
  export type NucleusToolDefinition = {
3
4
  name: string;
4
5
  description?: string;
@@ -27,6 +28,15 @@ export type NucleusInvokeResult = {
27
28
  reasoning?: string;
28
29
  toolCalls: StructuredToolCall[];
29
30
  raw?: any;
31
+ /** Token usage metrics from the callLLM loop */
32
+ metrics?: {
33
+ /** Total rounds executed (including query_context/retrieval rounds) */
34
+ rounds: number;
35
+ /** Estimated cumulative prompt tokens across all rounds */
36
+ estimatedPromptTokens: number;
37
+ /** Whether the loop was terminated early due to token budget */
38
+ budgetExhausted: boolean;
39
+ };
30
40
  };
31
41
  export type NucleusConfig = {
32
42
  goalId: string;
@@ -49,6 +59,27 @@ export type NucleusConfig = {
49
59
  };
50
60
  promptTemplate?: string;
51
61
  promptDigest?: string;
62
+ /** Max callLLM rounds the nucleus may execute before forced to answer. Default 3. */
63
+ maxQueryRounds?: number;
64
+ /**
65
+ * Max times request_context_retrieval may be fulfilled per invoke/preflight.
66
+ * After this many fulfillments, the retrieval tool is removed so the LLM
67
+ * must produce a final answer with whatever context it has. Default 1.
68
+ *
69
+ * NOTE: Each fulfillment itself may run multiple inner iterations
70
+ * (e.g. IterativePhasedRetrievalExecution with 6 rounds). This cap
71
+ * prevents the *outer* nucleus loop from re-triggering retrieval.
72
+ */
73
+ maxRetrievalRounds?: number;
74
+ /** External context provider for mid-invoke retrieval. When set, request_context_retrieval calls are fulfilled inline. */
75
+ contextProvider?: ExternalContextProviderAdapter;
76
+ /**
77
+ * Maximum context window tokens the underlying model supports.
78
+ * When set, the callLLM loop estimates cumulative prompt tokens per round
79
+ * and forces a final answer when usage exceeds 85% of this budget.
80
+ * Passed from infrastructure (e.g. LlmConfig.maxContext via BudgetManager).
81
+ */
82
+ maxContextTokens?: number;
52
83
  };
53
84
  export type PreflightResult = {
54
85
  status: 'OK';
@@ -70,6 +101,12 @@ export type LLMCallFn = (prompt: string, tools: NucleusToolDefinition[], config:
70
101
  toolCalls: StructuredToolCall[];
71
102
  raw?: any;
72
103
  }>;
104
+ /**
105
+ * Estimate token count from a text string using char/token ratio heuristics.
106
+ * Aligned with BudgetManager.estimateTokens from aiagent infrastructure.
107
+ * Code and structured text use lower ratios (higher token density).
108
+ */
109
+ export declare function estimateTokens(text: string | undefined | null): number;
73
110
  export declare abstract class Nucleus {
74
111
  protected config: NucleusConfig;
75
112
  constructor(config: NucleusConfig);
@@ -94,6 +131,14 @@ export declare class DeterministicNucleus extends Nucleus {
94
131
  getInternalContext(): InternalContextScope | undefined;
95
132
  setInternalContext(scope: InternalContextScope): void;
96
133
  private callLLM;
134
+ /**
135
+ * Resolve an array of query_context tool calls, returning formatted result strings.
136
+ */
137
+ private resolveQueryCalls;
138
+ /**
139
+ * Execute a query_context tool call against this.config.context and this.internalContext
140
+ */
141
+ private executeQueryContext;
97
142
  private buildPreflightPrompt;
98
143
  private buildInvokePrompt;
99
144
  private buildPostcheckPrompt;
@@ -1 +1 @@
1
- {"version":3,"file":"nucleus.d.ts","sourceRoot":"","sources":["../../src/nucleus.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"nucleus.d.ts","sourceRoot":"","sources":["../../src/nucleus.ts"],"names":[],"mappings":"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"}