@lloyal-labs/lloyal-agents 1.0.0 → 1.2.0

package/dist/generate.d.ts

@@ -3,14 +3,19 @@ import type { GenerateOptions, GenerateResult } from './types';
 /**
  * Single-branch grammar-constrained generation as an Effection operation
  *
- * Creates a fresh branch at position 0, prefills the prompt, generates
- * to EOG, and prunes the branch. Uses {@link Branch}'s async iterator
- * — single-branch generation doesn't need batched commit.
+ * Creates a fresh branch (or forks from `opts.parent`), prefills the prompt,
+ * generates to EOG, and prunes the branch. Uses {@link Branch}'s async
+ * iterator — single-branch generation doesn't need batched commit.
+ *
+ * When `parent` is provided, the prompt is prefilled as a delta (with turn
+ * separator) on a fork of the parent. This is the attention scratchpad
+ * pattern: the fork sees the parent's context, attends to the prompt
+ * content, generates a result, and is pruned — zero net KV cost.
  *
  * The branch is always cleaned up via try/finally, even on error or
  * scope cancellation.
  *
- * @param opts - Generation options (prompt, grammar, params, parse)
+ * @param opts - Generation options (prompt, grammar, params, parse, parent)
  * @returns Generated text, token count, and optionally parsed result
  *
  * @example Grammar-constrained JSON generation
@@ -21,7 +26,17 @@ import type { GenerateOptions, GenerateResult } from './types';
  *   params: { temperature: 0.3 },
  *   parse: output => JSON.parse(output),
  * });
- * console.log(plan.parsed); // typed result from parse()
+ * ```
+ *
+ * @example Attention scratchpad — fork, attend, extract, prune
+ * ```typescript
+ * const extracted = yield* generate({
+ *   prompt: contentToAttend,
+ *   grammar: extractionGrammar,
+ *   parse: output => JSON.parse(output),
+ *   parent: agentBranch,
+ * });
+ * // Fork is pruned — parent's KV unchanged
  * ```
  *
  * @category Agents

package/dist/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAiB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA0B1F"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAI3C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAiB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAoF1F"}

package/dist/generate.js

@@ -4,17 +4,23 @@ exports.generate = generate;
 const effection_1 = require("effection");
 const sdk_1 = require("@lloyal-labs/sdk");
 const context_1 = require("./context");
+const trace_scope_1 = require("./trace-scope");
 /**
  * Single-branch grammar-constrained generation as an Effection operation
  *
- * Creates a fresh branch at position 0, prefills the prompt, generates
- * to EOG, and prunes the branch. Uses {@link Branch}'s async iterator
- * — single-branch generation doesn't need batched commit.
+ * Creates a fresh branch (or forks from `opts.parent`), prefills the prompt,
+ * generates to EOG, and prunes the branch. Uses {@link Branch}'s async
+ * iterator — single-branch generation doesn't need batched commit.
+ *
+ * When `parent` is provided, the prompt is prefilled as a delta (with turn
+ * separator) on a fork of the parent. This is the attention scratchpad
+ * pattern: the fork sees the parent's context, attends to the prompt
+ * content, generates a result, and is pruned — zero net KV cost.
  *
  * The branch is always cleaned up via try/finally, even on error or
  * scope cancellation.
  *
- * @param opts - Generation options (prompt, grammar, params, parse)
+ * @param opts - Generation options (prompt, grammar, params, parse, parent)
  * @returns Generated text, token count, and optionally parsed result
  *
  * @example Grammar-constrained JSON generation
@@ -25,18 +31,72 @@ const context_1 = require("./context");
  *   params: { temperature: 0.3 },
  *   parse: output => JSON.parse(output),
  * });
- * console.log(plan.parsed); // typed result from parse()
+ * ```
+ *
+ * @example Attention scratchpad — fork, attend, extract, prune
+ * ```typescript
+ * const extracted = yield* generate({
+ *   prompt: contentToAttend,
+ *   grammar: extractionGrammar,
+ *   parse: output => JSON.parse(output),
+ *   parent: agentBranch,
+ * });
+ * // Fork is pruned — parent's KV unchanged
  * ```
  *
  * @category Agents
  */
 function* generate(opts) {
     const ctx = yield* context_1.Ctx.expect();
+    const tw = yield* context_1.Trace.expect();
     const samplerParams = opts.params ?? {};
-    const branch = sdk_1.Branch.create(ctx, 0, samplerParams, undefined, opts.grammar);
+    const hasParent = !!opts.parent;
+    const role = hasParent ? 'scratchpad' : 'root';
+    const scope = (0, trace_scope_1.traceScope)(tw, null, 'generate', { role, hasGrammar: !!opts.grammar });
+    let branch;
+    if (opts.parent) {
+        branch = yield* (0, effection_1.call)(() => opts.parent.fork());
+    }
+    else {
+        branch = sdk_1.Branch.create(ctx, 0, samplerParams, undefined, opts.grammar);
+    }
+    tw.write({
+        traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
+        type: 'branch:create', branchHandle: branch.handle,
+        parentHandle: opts.parent?.handle ?? null,
+        position: 0, role: hasParent ? 'scratchpad' : 'root',
+    });
     try {
-        const tokens = ctx.tokenizeSync(opts.prompt);
-        yield* (0, effection_1.call)(() => branch.prefill(tokens));
+        let prefillCount;
+        if (opts.parent) {
+            if (opts.grammar)
+                branch.setGrammar(opts.grammar);
+            const sep = ctx.getTurnSeparator();
+            const delta = yield* (0, effection_1.call)(() => ctx.tokenize(opts.prompt, false));
+            const tokens = [...sep, ...delta];
+            prefillCount = tokens.length;
+            yield* (0, effection_1.call)(() => branch.prefill(tokens));
+        }
+        else {
+            const tokens = ctx.tokenizeSync(opts.prompt);
+            prefillCount = tokens.length;
+            yield* (0, effection_1.call)(() => branch.prefill(tokens));
+        }
+        tw.write({
+            traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
+            type: 'prompt:format', promptText: opts.prompt, tokenCount: prefillCount,
+            messages: '', role: 'generate', grammar: opts.grammar,
+        });
+        tw.write({
+            traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
+            type: 'branch:prefill', branchHandle: branch.handle, tokenCount: prefillCount,
+            role: hasParent ? 'scratchpad' : 'sharedPrefix',
+        });
+        tw.write({
+            traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
+            type: 'generate:start', branchHandle: branch.handle,
+            hasGrammar: !!opts.grammar, hasParent, role,
+        });
         // Consume async iterator inside call() — generators can't use for-await
         const { output, tokenCount } = yield* (0, effection_1.call)(async () => {
             let output = '';
@@ -48,11 +108,22 @@ function* generate(opts) {
             return { output, tokenCount };
         });
         const parsed = opts.parse ? opts.parse(output) : undefined;
+        tw.write({
+            traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
+            type: 'generate:end', branchHandle: branch.handle, tokenCount, output,
+            parsed: parsed !== undefined ? parsed : undefined,
+        });
         return { output, tokenCount, parsed };
     }
     finally {
-        if (!branch.disposed)
+        if (!branch.disposed) {
+            tw.write({
+                traceId: tw.nextId(), parentTraceId: scope.traceId, ts: performance.now(),
+                type: 'branch:prune', branchHandle: branch.handle, position: 0,
+            });
             branch.pruneSync();
+        }
+        scope.close();
     }
 }
 //# sourceMappingURL=generate.js.map

package/dist/generate.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate.js","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":";;AAgCA,4BA0BC;AA1DD,yCAAiC;AAEjC,0CAA0C;AAC1C,uCAAgC;AAGhC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,QAAe,CAAC,CAAC,QAAQ,CAAc,IAAqB;IAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,aAAG,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,YAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAE7E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAE1C,wEAAwE;QACxE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,KAAK,IAAI,EAAE;YACpD,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,UAAU,GAAG,CAAC,CAAC;YACnB,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;gBACpC,MAAM,IAAI,IAAI,CAAC;gBACf,UAAU,EAAE,CAAC;YACf,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAChC,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACxC,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC3C,CAAC;AACH,CAAC"}
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { Ctx, Store, Events } from './context';
+export { Ctx, Store, Events, Trace, TraceParent, ScratchpadParent } from './context';
 export { Tool } from './Tool';
+export { Source } from './source';
 export { buildUserDelta, buildToolResultDelta } from '@lloyal-labs/sdk';
 export { generate } from './generate';
 export { diverge } from './diverge';
@@ -8,7 +9,11 @@ export { runAgents } from './run-agents';
 export { createToolkit } from './toolkit';
 export { initAgents } from './init';
 export { withSharedRoot } from './shared-root';
+export { NullTraceWriter, JsonlTraceWriter } from './trace-writer';
+export { traceScope } from './trace-scope';
 export type { Toolkit } from './toolkit';
+export type { TraceWriter } from './trace-writer';
+export type { TraceEvent, TraceId } from './trace-types';
 export type { AgentHandle } from './init';
 export type { SharedRootOptions } from './shared-root';
 export type { TraceToken, JsonSchema, ToolSchema, ToolContext, PressureThresholds, AgentTaskSpec, AgentPoolOptions, AgentResult, AgentPoolResult, GenerateOptions, GenerateResult, DivergeOptions, DivergeAttempt, DivergeResult, AgentEvent, } from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,YAAY,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACrF,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,YAAY,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withSharedRoot = exports.initAgents = exports.createToolkit = exports.runAgents = exports.ContextPressure = exports.useAgentPool = exports.diverge = exports.generate = exports.buildToolResultDelta = exports.buildUserDelta = exports.Tool = exports.Events = exports.Store = exports.Ctx = void 0;
+exports.traceScope = exports.JsonlTraceWriter = exports.NullTraceWriter = exports.withSharedRoot = exports.initAgents = exports.createToolkit = exports.runAgents = exports.ContextPressure = exports.useAgentPool = exports.diverge = exports.generate = exports.buildToolResultDelta = exports.buildUserDelta = exports.Source = exports.Tool = exports.ScratchpadParent = exports.TraceParent = exports.Trace = exports.Events = exports.Store = exports.Ctx = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "Ctx", { enumerable: true, get: function () { return context_1.Ctx; } });
 Object.defineProperty(exports, "Store", { enumerable: true, get: function () { return context_1.Store; } });
 Object.defineProperty(exports, "Events", { enumerable: true, get: function () { return context_1.Events; } });
+Object.defineProperty(exports, "Trace", { enumerable: true, get: function () { return context_1.Trace; } });
+Object.defineProperty(exports, "TraceParent", { enumerable: true, get: function () { return context_1.TraceParent; } });
+Object.defineProperty(exports, "ScratchpadParent", { enumerable: true, get: function () { return context_1.ScratchpadParent; } });
 var Tool_1 = require("./Tool");
 Object.defineProperty(exports, "Tool", { enumerable: true, get: function () { return Tool_1.Tool; } });
+var source_1 = require("./source");
+Object.defineProperty(exports, "Source", { enumerable: true, get: function () { return source_1.Source; } });
 var sdk_1 = require("@lloyal-labs/sdk");
 Object.defineProperty(exports, "buildUserDelta", { enumerable: true, get: function () { return sdk_1.buildUserDelta; } });
 Object.defineProperty(exports, "buildToolResultDelta", { enumerable: true, get: function () { return sdk_1.buildToolResultDelta; } });
@@ -25,4 +30,9 @@ var init_1 = require("./init");
 Object.defineProperty(exports, "initAgents", { enumerable: true, get: function () { return init_1.initAgents; } });
 var shared_root_1 = require("./shared-root");
 Object.defineProperty(exports, "withSharedRoot", { enumerable: true, get: function () { return shared_root_1.withSharedRoot; } });
+var trace_writer_1 = require("./trace-writer");
+Object.defineProperty(exports, "NullTraceWriter", { enumerable: true, get: function () { return trace_writer_1.NullTraceWriter; } });
+Object.defineProperty(exports, "JsonlTraceWriter", { enumerable: true, get: function () { return trace_writer_1.JsonlTraceWriter; } });
+var trace_scope_1 = require("./trace-scope");
+Object.defineProperty(exports, "traceScope", { enumerable: true, get: function () { return trace_scope_1.traceScope; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qCAA+C;AAAtC,8FAAA,GAAG,OAAA;AAAE,gGAAA,KAAK,OAAA;AAAE,iGAAA,MAAM,OAAA;AAC3B,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,wCAAwE;AAA/D,qGAAA,cAAc,OAAA;AAAE,2GAAA,oBAAoB,OAAA;AAC7C,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,qCAAoC;AAA3B,kGAAA,OAAO,OAAA;AAChB,2CAA6D;AAApD,0GAAA,YAAY,OAAA;AAAE,6GAAA,eAAe,OAAA;AACtC,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAClB,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AACtB,+BAAoC;AAA3B,kGAAA,UAAU,OAAA;AACnB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qCAAqF;AAA5E,8FAAA,GAAG,OAAA;AAAE,gGAAA,KAAK,OAAA;AAAE,iGAAA,MAAM,OAAA;AAAE,gGAAA,KAAK,OAAA;AAAE,sGAAA,WAAW,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AACjE,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,wCAAwE;AAA/D,qGAAA,cAAc,OAAA;AAAE,2GAAA,oBAAoB,OAAA;AAC7C,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,qCAAoC;AAA3B,kGAAA,OAAO,OAAA;AAChB,2CAA6D;AAApD,0GAAA,YAAY,OAAA;AAAE,6GAAA,eAAe,OAAA;AACtC,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAClB,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AACtB,+BAAoC;AAA3B,kGAAA,UAAU,OAAA;AACnB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA;AACvB,+CAAmE;AAA1D,+GAAA,eAAe,OAAA;AAAE,gHAAA,gBAAgB,OAAA;AAC1C,6CAA2C;AAAlC,yGAAA,UAAU,OAAA"}

package/dist/init.d.ts

@@ -3,6 +3,7 @@ import { BranchStore } from '@lloyal-labs/sdk';
 import { Session } from '@lloyal-labs/sdk';
 import type { SessionContext } from '@lloyal-labs/sdk';
 import type { AgentEvent } from './types';
+import type { TraceWriter } from './trace-writer';
 /**
  * Handle returned by {@link initAgents} containing all agent resources
  *
@@ -54,5 +55,7 @@ export interface AgentHandle<E = AgentEvent> {
  *
  * @category Agents
  */
-export declare function initAgents<E = AgentEvent>(ctx: SessionContext): Operation<AgentHandle<E>>;
+export declare function initAgents<E = AgentEvent>(ctx: SessionContext, opts?: {
+    traceWriter?: TraceWriter;
+}): Operation<AgentHandle<E>>;
 //# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,UAAU;IACzC,uDAAuD;IACvD,GAAG,EAAE,cAAc,CAAC;IACpB,8DAA8D;IAC9D,KAAK,EAAE,WAAW,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAiB,UAAU,CAAC,CAAC,GAAG,UAAU,EACxC,GAAG,EAAE,cAAc,GAClB,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAe3B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,UAAU;IACzC,uDAAuD;IACvD,GAAG,EAAE,cAAc,CAAC;IACpB,8DAA8D;IAC9D,KAAK,EAAE,WAAW,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAiB,UAAU,CAAC,CAAC,GAAG,UAAU,EACxC,GAAG,EAAE,cAAc,EACnB,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,WAAW,CAAA;CAAE,GACnC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAkB3B"}

package/dist/init.js

@@ -5,6 +5,7 @@ const effection_1 = require("effection");
 const sdk_1 = require("@lloyal-labs/sdk");
 const sdk_2 = require("@lloyal-labs/sdk");
 const context_1 = require("./context");
+const trace_writer_1 = require("./trace-writer");
 /**
  * Bootstrap the agent infrastructure and register structured cleanup
  *
@@ -41,14 +42,17 @@ const context_1 = require("./context");
  *
  * @category Agents
  */
-function* initAgents(ctx) {
+function* initAgents(ctx, opts) {
     const store = new sdk_1.BranchStore(ctx);
     const session = new sdk_2.Session({ ctx, store });
     const events = (0, effection_1.createChannel)();
     yield* context_1.Ctx.set(ctx);
     yield* context_1.Store.set(store);
     yield* context_1.Events.set(events);
+    yield* context_1.Trace.set(opts?.traceWriter ?? new trace_writer_1.NullTraceWriter());
     yield* (0, effection_1.ensure)(function* () {
+        const tw = yield* context_1.Trace.expect();
+        tw.flush();
         yield* (0, effection_1.call)(() => session.dispose());
         ctx.dispose();
     });

package/dist/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":";;AA4DA,gCAiBC;AA7ED,yCAAwD;AAExD,0CAA+C;AAC/C,0CAA2C;AAE3C,uCAA+C;AAmB/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,QAAe,CAAC,CAAC,UAAU,CACzB,GAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,iBAAW,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,aAAO,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAqB,IAAA,yBAAa,GAAW,CAAC;IAE1D,KAAK,CAAC,CAAC,aAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB,KAAK,CAAC,CAAC,eAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,KAAK,CAAC,CAAC,gBAAM,CAAC,GAAG,CAAC,MAA8C,CAAC,CAAC;IAElE,KAAK,CAAC,CAAC,IAAA,kBAAM,EAAC,QAAQ,CAAC;QACrB,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACrC,GAAG,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":";;AA8DA,gCAqBC;AAnFD,yCAAwD;AAExD,0CAA+C;AAC/C,0CAA2C;AAE3C,uCAAsD;AAGtD,iDAAiD;AAkBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,QAAe,CAAC,CAAC,UAAU,CACzB,GAAmB,EACnB,IAAoC;IAEpC,MAAM,KAAK,GAAG,IAAI,iBAAW,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,aAAO,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAqB,IAAA,yBAAa,GAAW,CAAC;IAE1D,KAAK,CAAC,CAAC,aAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB,KAAK,CAAC,CAAC,eAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,KAAK,CAAC,CAAC,gBAAM,CAAC,GAAG,CAAC,MAA8C,CAAC,CAAC;IAClE,KAAK,CAAC,CAAC,eAAK,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,IAAI,IAAI,8BAAe,EAAE,CAAC,CAAC;IAE7D,KAAK,CAAC,CAAC,IAAA,kBAAM,EAAC,QAAQ,CAAC;QACrB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,eAAK,CAAC,MAAM,EAAE,CAAC;QACjC,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACrC,GAAG,CAAC,OAAO,EAAE,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC"}

package/dist/shared-root.d.ts

@@ -1,6 +1,6 @@
-import type { Operation } from 'effection';
-import { Branch } from '@lloyal-labs/sdk';
-import type { SamplingParams } from './types';
+import type { Operation } from "effection";
+import { Branch } from "@lloyal-labs/sdk";
+import type { SamplingParams } from "./types";
 /**
  * Configuration for {@link withSharedRoot}
  *

package/dist/shared-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared-root.d.ts","sourceRoot":"","sources":["../src/shared-root.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAiB,cAAc,CAAC,CAAC,EAC/B,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAC/D,SAAS,CAAC,CAAC,CAAC,CAkBd"}
+{"version":3,"file":"shared-root.d.ts","sourceRoot":"","sources":["../src/shared-root.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAiB,cAAc,CAAC,CAAC,EAC/B,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAC/D,SAAS,CAAC,CAAC,CAAC,CAkFd"}

package/dist/shared-root.js

@@ -4,6 +4,7 @@ exports.withSharedRoot = withSharedRoot;
 const effection_1 = require("effection");
 const sdk_1 = require("@lloyal-labs/sdk");
 const context_1 = require("./context");
+const trace_scope_1 = require("./trace-scope");
 /**
  * Scoped shared root branch with guaranteed cleanup
  *
@@ -43,20 +44,80 @@ const context_1 = require("./context");
  */
 function* withSharedRoot(opts, body) {
     const ctx = yield* context_1.Ctx.expect();
-    const messages = [{ role: 'system', content: opts.systemPrompt }];
-    const fmtOpts = opts.tools
-        ? { tools: opts.tools, addGenerationPrompt: false }
-        : { addGenerationPrompt: false };
+    const tw = yield* context_1.Trace.expect();
+    // Read parent trace ID — connects nested pools to the outer DISPATCH that spawned them
+    let parentTraceId = null;
+    try {
+        const p = yield* context_1.TraceParent.get();
+        if (p != null)
+            parentTraceId = p;
+    }
+    catch {
+        /* no parent — top level */
+    }
+    const scope = (0, trace_scope_1.traceScope)(tw, parentTraceId, "withSharedRoot", {
+        hasTools: !!opts.tools,
+        systemPromptLength: opts.systemPrompt.length,
+    });
+    const messages = [{ role: "system", content: opts.systemPrompt }];
+    const fmtOpts = {
+        addGenerationPrompt: false,
+        enableThinking: false,
+    };
+    if (opts.tools)
+        fmtOpts.tools = opts.tools;
     const fmt = ctx.formatChatSync(JSON.stringify(messages), fmtOpts);
     const sharedTokens = ctx.tokenizeSync(fmt.prompt);
+    tw.write({
+        traceId: tw.nextId(),
+        parentTraceId: scope.traceId,
+        ts: performance.now(),
+        type: "prompt:format",
+        promptText: fmt.prompt,
+        tokenCount: sharedTokens.length,
+        messages: JSON.stringify(messages),
+        tools: opts.tools,
+        grammar: fmt.grammar || undefined,
+        role: "sharedRoot",
+    });
     const root = sdk_1.Branch.create(ctx, 0, opts.params ?? { temperature: 0.5 });
+    tw.write({
+        traceId: tw.nextId(),
+        parentTraceId: scope.traceId,
+        ts: performance.now(),
+        type: "branch:create",
+        branchHandle: root.handle,
+        parentHandle: null,
+        position: 0,
+        role: "sharedRoot",
+    });
     yield* (0, effection_1.call)(() => root.prefill(sharedTokens));
+    tw.write({
+        traceId: tw.nextId(),
+        parentTraceId: scope.traceId,
+        ts: performance.now(),
+        type: "branch:prefill",
+        branchHandle: root.handle,
+        tokenCount: sharedTokens.length,
+        role: "sharedPrefix",
+    });
     try {
+        yield* context_1.ScratchpadParent.set(root);
         return yield* body(root, sharedTokens.length);
     }
     finally {
-        if (!root.disposed)
+        if (!root.disposed) {
+            tw.write({
+                traceId: tw.nextId(),
+                parentTraceId: scope.traceId,
+                ts: performance.now(),
+                type: "branch:prune",
+                branchHandle: root.handle,
+                position: 0,
+            });
             root.pruneSubtreeSync();
+        }
+        scope.close();
     }
 }
 //# sourceMappingURL=shared-root.js.map

package/dist/shared-root.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared-root.js","sourceRoot":"","sources":["../src/shared-root.ts"],"names":[],"mappings":";;AA0DA,wCAqBC;AA/ED,yCAAiC;AAEjC,0CAA0C;AAE1C,uCAAgC;AAiBhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,QAAe,CAAC,CAAC,cAAc,CAC7B,IAAuB,EACvB,IAAgE;IAEhE,MAAM,GAAG,GAAmB,KAAK,CAAC,CAAC,aAAG,CAAC,MAAM,EAAE,CAAC;IAEhD,MAAM,QAAQ,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK;QACxB,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE;QACnD,CAAC,CAAC,EAAE,mBAAmB,EAAE,KAAK,EAAE,CAAC;IACnC,MAAM,GAAG,GAAG,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;IAClE,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAElD,MAAM,IAAI,GAAG,YAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC;IACxE,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC9C,CAAC;AACH,CAAC"}
+{"version":3,"file":"shared-root.js","sourceRoot":"","sources":["../src/shared-root.ts"],"names":[],"mappings":"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"}

package/dist/source.d.ts

@@ -0,0 +1,27 @@
+import type { Operation } from 'effection';
+import type { Tool } from './Tool';
+/**
+ * Abstract base class for data sources usable by the research pipeline
+ *
+ * Each source builds its own atomic research tool — a self-contained
+ * swarm with source-specific prompt, toolkit, and self-referential
+ * recursion. The orchestrator sees only source research tools + report.
+ *
+ * @typeParam TCtx - Runtime context passed to {@link bind} (e.g. parent branch, reranker)
+ * @typeParam TChunk - Chunk type returned by {@link getChunks} for post-research reranking
+ *
+ * @category Agents
+ */
+export declare abstract class Source<TCtx = Record<string, unknown>, TChunk = unknown> {
+    /** Human-readable source name (e.g. 'web', 'corpus') for labeling findings */
+    abstract readonly name: string;
+    /** The configured research tool — atomic swarm with source-specific prompt + toolkit */
+    abstract get researchTool(): Tool;
+    /** Late-bind runtime deps not available at construction. Called before tools are used. */
+    bind(_ctx: TCtx): Operation<void>;
+    /** Post-research chunks for reranking. Called after research completes. */
+    getChunks(): TChunk[];
+    /** Grounding tools for independent verification (e.g. search, read_file, grep). Empty by default. */
+    get groundingTools(): Tool[];
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;;;;;;;;GAWG;AACH,8BAAsB,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAC3E,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,wFAAwF;IACxF,QAAQ,KAAK,YAAY,IAAI,IAAI,CAAC;IAElC,0FAA0F;IACzF,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAClC,2EAA2E;IAC3E,SAAS,IAAI,MAAM,EAAE;IACrB,qGAAqG;IACrG,IAAI,cAAc,IAAI,IAAI,EAAE,CAAe;CAC5C"}

package/dist/source.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Source = void 0;
+/**
+ * Abstract base class for data sources usable by the research pipeline
+ *
+ * Each source builds its own atomic research tool — a self-contained
+ * swarm with source-specific prompt, toolkit, and self-referential
+ * recursion. The orchestrator sees only source research tools + report.
+ *
+ * @typeParam TCtx - Runtime context passed to {@link bind} (e.g. parent branch, reranker)
+ * @typeParam TChunk - Chunk type returned by {@link getChunks} for post-research reranking
+ *
+ * @category Agents
+ */
+class Source {
+    /** Late-bind runtime deps not available at construction. Called before tools are used. */
+    *bind(_ctx) { }
+    /** Post-research chunks for reranking. Called after research completes. */
+    getChunks() { return []; }
+    /** Grounding tools for independent verification (e.g. search, read_file, grep). Empty by default. */
+    get groundingTools() { return []; }
+}
+exports.Source = Source;
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;GAWG;AACH,MAAsB,MAAM;IAM1B,0FAA0F;IAC1F,CAAC,IAAI,CAAC,IAAU,IAAoB,CAAC;IACrC,2EAA2E;IAC3E,SAAS,KAAe,OAAO,EAAE,CAAC,CAAC,CAAC;IACpC,qGAAqG;IACrG,IAAI,cAAc,KAAa,OAAO,EAAE,CAAC,CAAC,CAAC;CAC5C;AAZD,wBAYC"}

package/dist/trace-scope.d.ts

@@ -0,0 +1,25 @@
+import type { TraceWriter } from './trace-writer';
+import type { TraceId } from './trace-types';
+/**
+ * Create matched `scope:open` / `scope:close` pairs for building the trace tree
+ *
+ * Opens a named scope immediately and returns a handle to close it later.
+ * The close callback emits a `scope:close` event with the elapsed duration
+ * and flushes the writer, ensuring scope boundaries are always persisted.
+ *
+ * Used throughout the runtime to bracket agent pools, tool dispatches,
+ * shared-root regions, and generation passes.
+ *
+ * @param writer - Active {@link TraceWriter} to emit events to
+ * @param parentTraceId - Trace ID of the enclosing scope, or `null` for root scopes
+ * @param name - Human-readable scope label (e.g. `"pool"`, `"tool:search"`)
+ * @param meta - Optional key-value metadata attached to the `scope:open` event
+ * @returns Object with the allocated `traceId` and a `close` callback
+ *
+ * @category Agents
+ */
+export declare function traceScope(writer: TraceWriter, parentTraceId: TraceId | null, name: string, meta?: Record<string, unknown>): {
+    traceId: TraceId;
+    close: () => void;
+};
+//# sourceMappingURL=trace-scope.d.ts.map

package/dist/trace-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-scope.d.ts","sourceRoot":"","sources":["../src/trace-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,aAAa,EAAE,OAAO,GAAG,IAAI,EAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAkBzC"}

package/dist/trace-scope.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceScope = traceScope;
+/**
+ * Create matched `scope:open` / `scope:close` pairs for building the trace tree
+ *
+ * Opens a named scope immediately and returns a handle to close it later.
+ * The close callback emits a `scope:close` event with the elapsed duration
+ * and flushes the writer, ensuring scope boundaries are always persisted.
+ *
+ * Used throughout the runtime to bracket agent pools, tool dispatches,
+ * shared-root regions, and generation passes.
+ *
+ * @param writer - Active {@link TraceWriter} to emit events to
+ * @param parentTraceId - Trace ID of the enclosing scope, or `null` for root scopes
+ * @param name - Human-readable scope label (e.g. `"pool"`, `"tool:search"`)
+ * @param meta - Optional key-value metadata attached to the `scope:open` event
+ * @returns Object with the allocated `traceId` and a `close` callback
+ *
+ * @category Agents
+ */
+function traceScope(writer, parentTraceId, name, meta) {
+    const traceId = writer.nextId();
+    const ts = performance.now();
+    writer.write({
+        traceId, parentTraceId, ts,
+        type: 'scope:open', name, meta,
+    });
+    return {
+        traceId,
+        close() {
+            writer.write({
+                traceId: writer.nextId(), parentTraceId: traceId,
+                ts: performance.now(),
+                type: 'scope:close', name, durationMs: performance.now() - ts,
+            });
+            writer.flush();
+        },
+    };
+}
+//# sourceMappingURL=trace-scope.js.map

package/dist/trace-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-scope.js","sourceRoot":"","sources":["../src/trace-scope.ts"],"names":[],"mappings":";;AAqBA,gCAuBC;AAzCD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,UAAU,CACxB,MAAmB,EACnB,aAA6B,EAC7B,IAAY,EACZ,IAA8B;IAE9B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,CAAC,KAAK,CAAC;QACX,OAAO,EAAE,aAAa,EAAE,EAAE;QAC1B,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI;KAC/B,CAAC,CAAC;IACH,OAAO;QACL,OAAO;QACP,KAAK;YACH,MAAM,CAAC,KAAK,CAAC;gBACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,OAAO;gBAChD,EAAE,EAAE,WAAW,CAAC,GAAG,EAAE;gBACrB,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE;aAC9D,CAAC,CAAC;YACH,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}