@lloyal-labs/lloyal-agents 1.2.2 → 1.4.0

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.
package/dist/context.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.ScratchpadParent = exports.TraceParent = exports.Trace = exports.Events = exports.Store = exports.Ctx = void 0;
3
+ exports.CallingAgent = exports.ScratchpadParent = exports.TraceParent = exports.Trace = exports.Events = exports.Store = exports.Ctx = void 0;
4
4
  const effection_1 = require("effection");
5
5
  /**
6
6
  * Effection context holding the active {@link SessionContext}
@@ -60,4 +60,18 @@ exports.TraceParent = (0, effection_1.createContext)('lloyal.traceParent');
60
60
  * @category Agents
61
61
  */
62
62
  exports.ScratchpadParent = (0, effection_1.createContext)('lloyal.scratchpadParent');
63
+ /**
64
+ * Effection context holding the calling agent during DISPATCH
65
+ *
66
+ * Set by the pool before each tool execution in `scoped()`. Tools and
67
+ * recursive `withSharedRoot` calls read this to access the calling
68
+ * agent's branch (for Continuous Context forking) and tool history
69
+ * (for deduplication guards).
70
+ *
71
+ * Scope-isolated: each `scoped()` DISPATCH sees only its own agent.
72
+ * Nested pools (web_research) shadow the parent's context correctly.
73
+ *
74
+ * @category Agents
75
+ */
76
+ exports.CallingAgent = (0, effection_1.createContext)('lloyal.callingAgent');
63
77
  //# sourceMappingURL=context.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":";;;AAAA,yCAA0C;AAQ1C;;;;;;;;GAQG;AACU,QAAA,GAAG,GAAG,IAAA,yBAAa,EAAiB,YAAY,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACU,QAAA,KAAK,GAAG,IAAA,yBAAa,EAAc,cAAc,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACU,QAAA,MAAM,GAAG,IAAA,yBAAa,EAA4B,eAAe,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACU,QAAA,KAAK,GAAG,IAAA,yBAAa,EAAc,cAAc,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACU,QAAA,WAAW,GAAG,IAAA,yBAAa,EAAU,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACU,QAAA,gBAAgB,GAAG,IAAA,yBAAa,EAAS,yBAAyB,CAAC,CAAC"}
1
+ {"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":";;;AAAA,yCAA0C;AAS1C;;;;;;;;GAQG;AACU,QAAA,GAAG,GAAG,IAAA,yBAAa,EAAiB,YAAY,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACU,QAAA,KAAK,GAAG,IAAA,yBAAa,EAAc,cAAc,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACU,QAAA,MAAM,GAAG,IAAA,yBAAa,EAA4B,eAAe,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACU,QAAA,KAAK,GAAG,IAAA,yBAAa,EAAc,cAAc,CAAC,CAAC;AAEhE;;;;;;;;GAQG;AACU,QAAA,WAAW,GAAG,IAAA,yBAAa,EAAU,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACU,QAAA,gBAAgB,GAAG,IAAA,yBAAa,EAAS,yBAAyB,CAAC,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACU,QAAA,YAAY,GAAG,IAAA,yBAAa,EAAQ,qBAAqB,CAAC,CAAC"}
package/dist/diverge.js CHANGED
@@ -81,7 +81,7 @@ function* diverge(opts) {
81
81
  catch { /* already gone */ }
82
82
  }
83
83
  });
84
- branch.reseedSampler(2000 + i);
84
+ branch.reseedSampler((opts.seedBase ?? 2000) + i);
85
85
  live.push({ branch, output: '', done: false, tokenCount: 0, ppl: Infinity });
86
86
  }
87
87
  // Batched generation — produceSync/commit loop
@@ -1 +1 @@
1
- {"version":3,"file":"diverge.js","sourceRoot":"","sources":["../src/diverge.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"diverge.js","sourceRoot":"","sources":["../src/diverge.ts"],"names":[],"mappings":";;AA0CA,0BAsGC;AAhJD,yCAAyC;AAEzC,0CAA0C;AAC1C,uCAAuC;AACvC,6CAA+C;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,QAAe,CAAC,CAAC,OAAO,CAAC,IAAoB;IAC3C,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,aAAG,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,eAAK,CAAC,MAAM,EAAE,CAAC;IAEpC,mEAAmE;IACnE,IAAI,IAAY,CAAC;IACjB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,YAAoB,CAAC;IAEzB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QACnB,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1F,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,GAAG,YAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAChD,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACxC,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,OAAO,GAAG,IAAI,CAAC;QACf,iDAAiD;QACjD,KAAK,CAAC,CAAC,IAAA,kBAAM,EAAC,GAAG,EAAE;YACjB,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAC9B,IAAI,CAAC;oBAAC,IAAI,CAAC,SAAS,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAyF,EAAE,CAAC;IAEtG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC/B,kEAAkE;QAClE,KAAK,CAAC,CAAC,IAAA,kBAAM,EAAC,GAAG,EAAE;YACjB,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACrB,IAAI,CAAC;oBAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,+CAA+C;IAC/C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,SAAS,CAAC;QACR,MAAM,QAAQ,GAAG,IAAI,4BAAe,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACtB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;gBAAC,IAAI,CAAC,CAAC,CAAC,IAAI;oBAAE,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;YAAC,CAAC;YACrD,MAAM;QACR,CAAC;QAED,MAAM,OAAO,GAAuB,EAAE,CAAC;QACvC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,IAAI,CAAC,CAAC,IAAI;gBAAE,SAAS;YACrB,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACvD,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;gBAC9B,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAC1C,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;gBACd,SAAS;YACX,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;YAChC,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC;YACjB,CAAC,CAAC,UAAU,EAAE,CAAC;QACjB,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAChC,KAAK,CAAC,CAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QACzC,KAAK,EAAE,CAAC;IACV,CAAC;IAED,8CAA8C;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAE7E,4DAA4D;IAC5D,qEAAqE;IACrE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC9C,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,sDAAsD;IACtD,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAqB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,GAAG,EAAE,CAAC,CAAC,GAAG;KACX,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM;QAC1B,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM;QAChC,QAAQ;QACR,WAAW;QACX,KAAK;QACL,YAAY;KACb,CAAC;AACJ,CAAC"}
package/dist/index.d.ts CHANGED
@@ -1,5 +1,11 @@
1
1
  export { Ctx, Store, Events, Trace, TraceParent, ScratchpadParent } from './context';
2
2
  export { Tool } from './Tool';
3
+ export { Agent } from './Agent';
4
+ export type { AgentStatus, FindingsSource, FormatConfig, ToolHistoryEntry } from './Agent';
5
+ export { DefaultAgentPolicy } from './AgentPolicy';
6
+ export type { AgentPolicy, ProduceAction, SettleAction, IdleReason, PolicyConfig, ToolGuard, DefaultAgentPolicyOpts } from './AgentPolicy';
7
+ export { defaultToolGuards } from './AgentPolicy';
8
+ export { CallingAgent } from './context';
3
9
  export { Source } from './source';
4
10
  export { buildUserDelta, buildToolResultDelta } from '@lloyal-labs/sdk';
5
11
  export { prepare, generate } from './generate';
@@ -11,6 +17,10 @@ export { initAgents } from './init';
11
17
  export { withSharedRoot } from './shared-root';
12
18
  export { NullTraceWriter, JsonlTraceWriter } from './trace-writer';
13
19
  export { traceScope } from './trace-scope';
20
+ export { spawnAgents } from './spawn-agents';
21
+ export type { SpawnAgentsOpts, RecursiveOpts } from './spawn-agents';
22
+ export { composePrompt, renderPrompt, renderTemplate } from './prompt';
23
+ export type { PromptState, PromptSection, PromptStep } from './prompt';
14
24
  export type { Toolkit } from './toolkit';
15
25
  export type { TraceWriter } from './trace-writer';
16
26
  export type { TraceEvent, TraceId } from './trace-types';
@@ -1 +1 @@
1
- {"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,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC/C,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"}
1
+ {"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,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC3I,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC/C,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;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACvE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEvE,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 CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.traceScope = exports.JsonlTraceWriter = exports.NullTraceWriter = exports.withSharedRoot = exports.initAgents = exports.createToolkit = exports.runAgents = exports.ContextPressure = exports.useAgentPool = exports.diverge = exports.generate = exports.prepare = exports.buildToolResultDelta = exports.buildUserDelta = exports.Source = exports.Tool = exports.ScratchpadParent = exports.TraceParent = exports.Trace = exports.Events = exports.Store = exports.Ctx = void 0;
3
+ exports.renderTemplate = exports.renderPrompt = exports.composePrompt = exports.spawnAgents = exports.traceScope = exports.JsonlTraceWriter = exports.NullTraceWriter = exports.withSharedRoot = exports.initAgents = exports.createToolkit = exports.runAgents = exports.ContextPressure = exports.useAgentPool = exports.diverge = exports.generate = exports.prepare = exports.buildToolResultDelta = exports.buildUserDelta = exports.Source = exports.CallingAgent = exports.defaultToolGuards = exports.DefaultAgentPolicy = exports.Agent = exports.Tool = exports.ScratchpadParent = exports.TraceParent = exports.Trace = exports.Events = exports.Store = exports.Ctx = void 0;
4
4
  var context_1 = require("./context");
5
5
  Object.defineProperty(exports, "Ctx", { enumerable: true, get: function () { return context_1.Ctx; } });
6
6
  Object.defineProperty(exports, "Store", { enumerable: true, get: function () { return context_1.Store; } });
@@ -10,6 +10,14 @@ Object.defineProperty(exports, "TraceParent", { enumerable: true, get: function
10
10
  Object.defineProperty(exports, "ScratchpadParent", { enumerable: true, get: function () { return context_1.ScratchpadParent; } });
11
11
  var Tool_1 = require("./Tool");
12
12
  Object.defineProperty(exports, "Tool", { enumerable: true, get: function () { return Tool_1.Tool; } });
13
+ var Agent_1 = require("./Agent");
14
+ Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return Agent_1.Agent; } });
15
+ var AgentPolicy_1 = require("./AgentPolicy");
16
+ Object.defineProperty(exports, "DefaultAgentPolicy", { enumerable: true, get: function () { return AgentPolicy_1.DefaultAgentPolicy; } });
17
+ var AgentPolicy_2 = require("./AgentPolicy");
18
+ Object.defineProperty(exports, "defaultToolGuards", { enumerable: true, get: function () { return AgentPolicy_2.defaultToolGuards; } });
19
+ var context_2 = require("./context");
20
+ Object.defineProperty(exports, "CallingAgent", { enumerable: true, get: function () { return context_2.CallingAgent; } });
13
21
  var source_1 = require("./source");
14
22
  Object.defineProperty(exports, "Source", { enumerable: true, get: function () { return source_1.Source; } });
15
23
  var sdk_1 = require("@lloyal-labs/sdk");
@@ -36,4 +44,10 @@ Object.defineProperty(exports, "NullTraceWriter", { enumerable: true, get: funct
36
44
  Object.defineProperty(exports, "JsonlTraceWriter", { enumerable: true, get: function () { return trace_writer_1.JsonlTraceWriter; } });
37
45
  var trace_scope_1 = require("./trace-scope");
38
46
  Object.defineProperty(exports, "traceScope", { enumerable: true, get: function () { return trace_scope_1.traceScope; } });
47
+ var spawn_agents_1 = require("./spawn-agents");
48
+ Object.defineProperty(exports, "spawnAgents", { enumerable: true, get: function () { return spawn_agents_1.spawnAgents; } });
49
+ var prompt_1 = require("./prompt");
50
+ Object.defineProperty(exports, "composePrompt", { enumerable: true, get: function () { return prompt_1.composePrompt; } });
51
+ Object.defineProperty(exports, "renderPrompt", { enumerable: true, get: function () { return prompt_1.renderPrompt; } });
52
+ Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return prompt_1.renderTemplate; } });
39
53
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"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,uCAA+C;AAAtC,mGAAA,OAAO,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAC1B,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"}
1
+ {"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,iCAAgC;AAAvB,8FAAA,KAAK,OAAA;AAEd,6CAAmD;AAA1C,iHAAA,kBAAkB,OAAA;AAE3B,6CAAkD;AAAzC,gHAAA,iBAAiB,OAAA;AAC1B,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AACrB,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,wCAAwE;AAA/D,qGAAA,cAAc,OAAA;AAAE,2GAAA,oBAAoB,OAAA;AAC7C,uCAA+C;AAAtC,mGAAA,OAAO,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAC1B,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;AACnB,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AAEpB,mCAAuE;AAA9D,uGAAA,aAAa,OAAA;AAAE,sGAAA,YAAY,OAAA;AAAE,wGAAA,cAAc,OAAA"}
@@ -0,0 +1,77 @@
1
+ import type { Tool } from './Tool';
2
+ /**
3
+ * A named content section in a composed prompt.
4
+ *
5
+ * @category Agents
6
+ */
7
+ export interface PromptSection {
8
+ heading: string;
9
+ content: string;
10
+ }
11
+ /**
12
+ * Accumulated prompt state built by composing {@link PromptStep}s.
13
+ *
14
+ * - `clauses` — system prompt fragments (joined with double newline)
15
+ * - `sections` — user content sections (each rendered as `heading:\n\ncontent`)
16
+ * - `tools` — tools available to the agent (fed to {@link createToolkit})
17
+ *
18
+ * @category Agents
19
+ */
20
+ export interface PromptState {
21
+ clauses: string[];
22
+ sections: PromptSection[];
23
+ tools: Tool[];
24
+ }
25
+ /**
26
+ * A pure function that transforms prompt state. Return the state
27
+ * unchanged to skip, or return a new state with additional clauses,
28
+ * sections, or tools. Steps are composed left-to-right via
29
+ * {@link composePrompt}.
30
+ *
31
+ * @category Agents
32
+ */
33
+ export type PromptStep = (state: PromptState) => PromptState;
34
+ /**
35
+ * Reduce an array of {@link PromptStep}s over a base {@link PromptState}.
36
+ *
37
+ * Each step can conditionally add system clauses, user content sections,
38
+ * or tools based on inference state. Steps that return the state unchanged
39
+ * are no-ops.
40
+ *
41
+ * @category Agents
42
+ */
43
+ export declare const composePrompt: (base: PromptState, steps: PromptStep[]) => PromptState;
44
+ /**
45
+ * Render a {@link PromptState} into system and user content strings
46
+ * suitable for `formatChatSync()`.
47
+ *
48
+ * @category Agents
49
+ */
50
+ export declare const renderPrompt: (state: PromptState, query: string) => {
51
+ system: string;
52
+ content: string;
53
+ };
54
+ /**
55
+ * Render a template string with Eta. Templates use standard Eta/EJS
56
+ * syntax: `<%= it.var %>` for interpolation, `<% if (it.x) { %>` for
57
+ * conditionals, `<% it.arr.forEach(...) %>` for loops.
58
+ *
59
+ * Auto-escaping is disabled — templates produce prompt text, not HTML.
60
+ *
61
+ * @param template - Eta template string
62
+ * @param data - Variables available as `it.*` in the template
63
+ * @returns Rendered string
64
+ *
65
+ * @example
66
+ * ```typescript
67
+ * const result = renderTemplate(
68
+ * 'Hello <%= it.name %><% if (it.age) { %>, age <%= it.age %><% } %>',
69
+ * { name: 'Alice', age: 30 },
70
+ * );
71
+ * // => "Hello Alice, age 30"
72
+ * ```
73
+ *
74
+ * @category Agents
75
+ */
76
+ export declare const renderTemplate: (template: string, data: Record<string, unknown>) => string;
77
+ //# sourceMappingURL=prompt.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAInC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,WAAW,EACjB,OAAO,UAAU,EAAE,KAClB,WAAmD,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,WAAW,EAClB,OAAO,MAAM,KACZ;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAMlC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,EAChB,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,MAA0C,CAAC"}
package/dist/prompt.js ADDED
@@ -0,0 +1,55 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.renderTemplate = exports.renderPrompt = exports.composePrompt = void 0;
4
+ const eta_1 = require("eta");
5
+ const eta = new eta_1.Eta({ autoEscape: false });
6
+ /**
7
+ * Reduce an array of {@link PromptStep}s over a base {@link PromptState}.
8
+ *
9
+ * Each step can conditionally add system clauses, user content sections,
10
+ * or tools based on inference state. Steps that return the state unchanged
11
+ * are no-ops.
12
+ *
13
+ * @category Agents
14
+ */
15
+ const composePrompt = (base, steps) => steps.reduce((s, fn) => fn(s), base);
16
+ exports.composePrompt = composePrompt;
17
+ /**
18
+ * Render a {@link PromptState} into system and user content strings
19
+ * suitable for `formatChatSync()`.
20
+ *
21
+ * @category Agents
22
+ */
23
+ const renderPrompt = (state, query) => ({
24
+ system: state.clauses.join('\n\n'),
25
+ content: [
26
+ ...state.sections.map((s) => `${s.heading}:\n\n${s.content}`),
27
+ query,
28
+ ].join('\n\n---\n\n'),
29
+ });
30
+ exports.renderPrompt = renderPrompt;
31
+ /**
32
+ * Render a template string with Eta. Templates use standard Eta/EJS
33
+ * syntax: `<%= it.var %>` for interpolation, `<% if (it.x) { %>` for
34
+ * conditionals, `<% it.arr.forEach(...) %>` for loops.
35
+ *
36
+ * Auto-escaping is disabled — templates produce prompt text, not HTML.
37
+ *
38
+ * @param template - Eta template string
39
+ * @param data - Variables available as `it.*` in the template
40
+ * @returns Rendered string
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * const result = renderTemplate(
45
+ * 'Hello <%= it.name %><% if (it.age) { %>, age <%= it.age %><% } %>',
46
+ * { name: 'Alice', age: 30 },
47
+ * );
48
+ * // => "Hello Alice, age 30"
49
+ * ```
50
+ *
51
+ * @category Agents
52
+ */
53
+ const renderTemplate = (template, data) => eta.renderString(template, data);
54
+ exports.renderTemplate = renderTemplate;
55
+ //# sourceMappingURL=prompt.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":";;;AAAA,6BAA0B;AAG1B,MAAM,GAAG,GAAG,IAAI,SAAG,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;AAqC3C;;;;;;;;GAQG;AACI,MAAM,aAAa,GAAG,CAC3B,IAAiB,EACjB,KAAmB,EACN,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAH1C,QAAA,aAAa,iBAG6B;AAEvD;;;;;GAKG;AACI,MAAM,YAAY,GAAG,CAC1B,KAAkB,EAClB,KAAa,EACwB,EAAE,CAAC,CAAC;IACzC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE;QACP,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC;QAC7D,KAAK;KACN,CAAC,IAAI,CAAC,aAAa,CAAC;CACtB,CAAC,CAAC;AATU,QAAA,YAAY,gBAStB;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACI,MAAM,cAAc,GAAG,CAC5B,QAAgB,EAChB,IAA6B,EACrB,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AAHjC,QAAA,cAAc,kBAGmB"}
@@ -19,42 +19,39 @@ export interface SharedRootOptions {
19
19
  * @default false
20
20
  */
21
21
  enableScratchpad?: boolean;
22
+ /**
23
+ * Fork root from this branch instead of creating at position 0.
24
+ *
25
+ * When provided, the root inherits the parent's full KV state —
26
+ * every tool call, tool result, and generated token the parent
27
+ * accumulated. The system prompt is prefilled as a delta on top.
28
+ * Sub-agents forking from this root attend over the parent's
29
+ * complete attention state (Continuous Context).
30
+ *
31
+ * When omitted, creates a fresh root at position 0 (cold start).
32
+ */
33
+ parent?: Branch;
22
34
  }
23
35
  /**
24
36
  * Scoped shared root branch with guaranteed cleanup
25
37
  *
26
- * Creates a root branch, prefills the system prompt, and passes it to
27
- * the body function. The root is pruned via try/finally when the body
38
+ * Creates (or forks) a root branch, prefills the system prompt, and passes
39
+ * it to the body function. The root is pruned via try/finally when the body
28
40
  * returns or throws, regardless of whether children still exist.
29
41
  *
30
- * Use this for the cold-path pattern where multiple agents share a
31
- * tokenized system prompt prefix. The `sharedPrefixLength` passed to
32
- * the body enables KV savings calculation.
42
+ * **Cold path** (no `parent`): creates root at position 0, prefills system
43
+ * prompt. Use for top-level research where no prior context exists.
33
44
  *
34
- * @param opts - System prompt, tools, and sampling parameters
45
+ * **Warm path** (`parent` provided): forks from parent branch, prefills
46
+ * system prompt as a delta. Sub-agents inherit the parent's full KV state.
47
+ * Use for recursive tools (web_research, research) where sub-agents should
48
+ * attend over the calling agent's accumulated evidence.
49
+ *
50
+ * @param opts - System prompt, tools, sampling parameters, and optional parent branch
35
51
  * @param body - Operation that receives the root branch and prefix length.
36
52
  * Typically calls {@link runAgents} or {@link useAgentPool} inside.
37
53
  * @returns The body's return value
38
54
  *
39
- * @example Cold-path research with shared prefix
40
- * ```typescript
41
- * const { result, prefixLen } = yield* withSharedRoot(
42
- * { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
43
- * function*(root, prefixLen) {
44
- * const result = yield* runAgents({
45
- * tasks: questions.map(q => ({
46
- * systemPrompt: RESEARCH_PROMPT,
47
- * content: q,
48
- * tools: toolsJson,
49
- * parent: root,
50
- * })),
51
- * tools: toolMap,
52
- * });
53
- * return { result, prefixLen };
54
- * },
55
- * );
56
- * ```
57
- *
58
55
  * @category Agents
59
56
  */
60
57
  export declare function withSharedRoot<T>(opts: SharedRootOptions, body: (root: Branch, sharedPrefixLength: number) => Operation<T>): Operation<T>;
@@ -1 +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;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;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;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"}
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;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;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;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,CAkGd"}
@@ -8,38 +8,23 @@ const trace_scope_1 = require("./trace-scope");
8
8
  /**
9
9
  * Scoped shared root branch with guaranteed cleanup
10
10
  *
11
- * Creates a root branch, prefills the system prompt, and passes it to
12
- * the body function. The root is pruned via try/finally when the body
11
+ * Creates (or forks) a root branch, prefills the system prompt, and passes
12
+ * it to the body function. The root is pruned via try/finally when the body
13
13
  * returns or throws, regardless of whether children still exist.
14
14
  *
15
- * Use this for the cold-path pattern where multiple agents share a
16
- * tokenized system prompt prefix. The `sharedPrefixLength` passed to
17
- * the body enables KV savings calculation.
15
+ * **Cold path** (no `parent`): creates root at position 0, prefills system
16
+ * prompt. Use for top-level research where no prior context exists.
18
17
  *
19
- * @param opts - System prompt, tools, and sampling parameters
18
+ * **Warm path** (`parent` provided): forks from parent branch, prefills
19
+ * system prompt as a delta. Sub-agents inherit the parent's full KV state.
20
+ * Use for recursive tools (web_research, research) where sub-agents should
21
+ * attend over the calling agent's accumulated evidence.
22
+ *
23
+ * @param opts - System prompt, tools, sampling parameters, and optional parent branch
20
24
  * @param body - Operation that receives the root branch and prefix length.
21
25
  * Typically calls {@link runAgents} or {@link useAgentPool} inside.
22
26
  * @returns The body's return value
23
27
  *
24
- * @example Cold-path research with shared prefix
25
- * ```typescript
26
- * const { result, prefixLen } = yield* withSharedRoot(
27
- * { systemPrompt: RESEARCH_PROMPT, tools: toolsJson },
28
- * function*(root, prefixLen) {
29
- * const result = yield* runAgents({
30
- * tasks: questions.map(q => ({
31
- * systemPrompt: RESEARCH_PROMPT,
32
- * content: q,
33
- * tools: toolsJson,
34
- * parent: root,
35
- * })),
36
- * tools: toolMap,
37
- * });
38
- * return { result, prefixLen };
39
- * },
40
- * );
41
- * ```
42
- *
43
28
  * @category Agents
44
29
  */
45
30
  function* withSharedRoot(opts, body) {
@@ -58,6 +43,7 @@ function* withSharedRoot(opts, body) {
58
43
  const scope = (0, trace_scope_1.traceScope)(tw, parentTraceId, "withSharedRoot", {
59
44
  hasTools: !!opts.tools,
60
45
  systemPromptLength: opts.systemPrompt.length,
46
+ hasParent: !!opts.parent,
61
47
  });
62
48
  const messages = [{ role: "system", content: opts.systemPrompt }];
63
49
  const fmtOpts = {
@@ -80,31 +66,46 @@ function* withSharedRoot(opts, body) {
80
66
  grammar: fmt.grammar || undefined,
81
67
  role: "sharedRoot",
82
68
  });
83
- const root = sdk_1.Branch.create(ctx, 0, opts.params ?? { temperature: 0.5 });
69
+ // Warm path: fork from parent branch (inherits full KV state)
70
+ // Cold path: create fresh root at position 0
71
+ let root;
72
+ let prefillTokens;
73
+ if (opts.parent) {
74
+ root = opts.parent.forkSync();
75
+ // Warm path: parent already has system prompt + tools in KV.
76
+ // Only prefill turn separator — the prompt is inherited via fork.
77
+ // This saves ~760 tokens per recursive fork.
78
+ const sep = ctx.getTurnSeparator();
79
+ prefillTokens = sep;
80
+ }
81
+ else {
82
+ root = sdk_1.Branch.create(ctx, 0, opts.params ?? { temperature: 0.5 });
83
+ prefillTokens = sharedTokens;
84
+ }
84
85
  tw.write({
85
86
  traceId: tw.nextId(),
86
87
  parentTraceId: scope.traceId,
87
88
  ts: performance.now(),
88
89
  type: "branch:create",
89
90
  branchHandle: root.handle,
90
- parentHandle: null,
91
- position: 0,
91
+ parentHandle: opts.parent?.handle ?? null,
92
+ position: opts.parent ? opts.parent.position : 0,
92
93
  role: "sharedRoot",
93
94
  });
94
- yield* (0, effection_1.call)(() => root.prefill(sharedTokens));
95
+ yield* (0, effection_1.call)(() => root.prefill(prefillTokens));
95
96
  tw.write({
96
97
  traceId: tw.nextId(),
97
98
  parentTraceId: scope.traceId,
98
99
  ts: performance.now(),
99
100
  type: "branch:prefill",
100
101
  branchHandle: root.handle,
101
- tokenCount: sharedTokens.length,
102
+ tokenCount: prefillTokens.length,
102
103
  role: "sharedPrefix",
103
104
  });
104
105
  try {
105
106
  if (opts.enableScratchpad)
106
107
  yield* context_1.ScratchpadParent.set(root);
107
- return yield* body(root, sharedTokens.length);
108
+ return yield* body(root, prefillTokens.length);
108
109
  }
109
110
  finally {
110
111
  if (!root.disposed) {
@@ -1 +1 @@
1
- {"version":3,"file":"shared-root.js","sourceRoot":"","sources":["../src/shared-root.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"shared-root.js","sourceRoot":"","sources":["../src/shared-root.ts"],"names":[],"mappings":"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"}
package/dist/source.d.ts CHANGED
@@ -1,27 +1,25 @@
1
1
  import type { Operation } from 'effection';
2
2
  import type { Tool } from './Tool';
3
3
  /**
4
- * Abstract base class for data sources usable by the research pipeline
4
+ * Abstract base class for data sources
5
5
  *
6
- * Each source builds its own atomic research tool a self-contained
7
- * swarm with source-specific prompt, toolkit, and self-referential
8
- * recursion. The orchestrator sees only source research tools + report.
6
+ * A source is a named collection of data access tools with a bind
7
+ * lifecycle. It does not orchestrate agents — that is the harness's
8
+ * job via {@link spawnAgents}.
9
9
  *
10
- * @typeParam TCtx - Runtime context passed to {@link bind} (e.g. parent branch, reranker)
11
- * @typeParam TChunk - Chunk type returned by {@link getChunks} for post-research reranking
10
+ * @typeParam TCtx - Runtime context passed to {@link bind} (e.g. reranker)
11
+ * @typeParam TChunk - Chunk type returned by {@link getChunks} for post-use reranking
12
12
  *
13
13
  * @category Agents
14
14
  */
15
- export declare abstract class Source<TCtx = Record<string, unknown>, TChunk = unknown> {
16
- /** Human-readable source name (e.g. 'web', 'corpus') for labeling findings */
15
+ export declare abstract class Source<TCtx = unknown, TChunk = unknown> {
16
+ /** Human-readable source name (e.g. 'web', 'corpus') for labeling output */
17
17
  abstract readonly name: string;
18
- /** The configured research tool atomic swarm with source-specific prompt + toolkit */
19
- abstract get researchTool(): Tool;
18
+ /** Data access tools provided by this source */
19
+ abstract get tools(): Tool[];
20
20
  /** Late-bind runtime deps not available at construction. Called before tools are used. */
21
21
  bind(_ctx: TCtx): Operation<void>;
22
- /** Post-research chunks for reranking. Called after research completes. */
22
+ /** Post-use chunks for reranking. Called after agents have used the tools. */
23
23
  getChunks(): TChunk[];
24
- /** Grounding tools for independent verification (e.g. search, read_file, grep). Empty by default. */
25
- get groundingTools(): Tool[];
26
24
  }
27
25
  //# sourceMappingURL=source.d.ts.map
@@ -1 +1 @@
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"}
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,OAAO,EAAE,MAAM,GAAG,OAAO;IAC3D,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,KAAK,KAAK,IAAI,IAAI,EAAE,CAAC;IAE7B,0FAA0F;IACzF,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAClC,8EAA8E;IAC9E,SAAS,IAAI,MAAM,EAAE;CACtB"}
package/dist/source.js CHANGED
@@ -2,24 +2,22 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.Source = void 0;
4
4
  /**
5
- * Abstract base class for data sources usable by the research pipeline
5
+ * Abstract base class for data sources
6
6
  *
7
- * Each source builds its own atomic research tool a self-contained
8
- * swarm with source-specific prompt, toolkit, and self-referential
9
- * recursion. The orchestrator sees only source research tools + report.
7
+ * A source is a named collection of data access tools with a bind
8
+ * lifecycle. It does not orchestrate agents — that is the harness's
9
+ * job via {@link spawnAgents}.
10
10
  *
11
- * @typeParam TCtx - Runtime context passed to {@link bind} (e.g. parent branch, reranker)
12
- * @typeParam TChunk - Chunk type returned by {@link getChunks} for post-research reranking
11
+ * @typeParam TCtx - Runtime context passed to {@link bind} (e.g. reranker)
12
+ * @typeParam TChunk - Chunk type returned by {@link getChunks} for post-use reranking
13
13
  *
14
14
  * @category Agents
15
15
  */
16
16
  class Source {
17
17
  /** Late-bind runtime deps not available at construction. Called before tools are used. */
18
18
  *bind(_ctx) { }
19
- /** Post-research chunks for reranking. Called after research completes. */
19
+ /** Post-use chunks for reranking. Called after agents have used the tools. */
20
20
  getChunks() { return []; }
21
- /** Grounding tools for independent verification (e.g. search, read_file, grep). Empty by default. */
22
- get groundingTools() { return []; }
23
21
  }
24
22
  exports.Source = Source;
25
23
  //# sourceMappingURL=source.js.map
@@ -1 +1 @@
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"}
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,8EAA8E;IAC9E,SAAS,KAAe,OAAO,EAAE,CAAC,CAAC,CAAC;CACrC;AAVD,wBAUC"}