@lloyal-labs/lloyal-agents 2.0.0 → 3.0.0

package/dist/source.d.ts

@@ -69,7 +69,21 @@ export declare abstract class Source<TCtx = unknown, TChunk = unknown> {
     abstract get tools(): Tool[];
     /** Reranker instance, set during {@link bind}. Used by {@link createScorer}. */
     protected _reranker: ScorerReranker | null;
-    /** Minimum entailment score for delegation to proceed. */
+    /**
+     * Minimum entailment score for delegation to proceed.
+     *
+     * Reranker scores are logit-diffs (`logit(yes) − logit(no)`); a value
+     * `> 0` means the cross-encoder model prefers "yes" over "no" when
+     * asked whether the document matches the query. Default `0` ⇒ "the
+     * model agrees this passage is relevant"; subclasses may tighten
+     * (e.g. `2` for "confident yes") or loosen (negative, for noisy
+     * corpora where leaning-no hits are still worth investigating).
+     *
+     * The prior softmax-prob default was `0.25`, which corresponded to
+     * logit-diff `≈ −1.1`. The new default is stricter: only hits the
+     * model genuinely leans toward are surfaced. See TICK-002 calibration
+     * notes (`reasoning.run/scripts/inspect-rerank.mjs`) for the data.
+     */
     protected _entailmentFloor: number;
     /**
      * Create an immutable entailment scorer scoped to one invocation.
@@ -85,5 +99,21 @@ export declare abstract class Source<TCtx = unknown, TChunk = unknown> {
     bind(_ctx: TCtx): Operation<void>;
     /** Post-use chunks for reranking. Called after agents have used the tools. */
     getChunks(): TChunk[];
+    /**
+     * App-level prompt data (e.g. a corpus TOC) for the HARNESS to place.
+     *
+     * Identical for every agent in a pool, so it belongs in shared KV —
+     * rendered ONCE, not duplicated per spawn (six 4.8k-token TOC-bearing
+     * suffixes overran a 32k context before this contract existed).
+     *
+     * Placement is a TRUST decision, which is why the framework does not
+     * place it automatically: this is free prose derived from source
+     * content, and the shared spine prefix is read by every agent in the
+     * pool. A harness may append it to its spine prompt for apps it trusts
+     * (first-party corpora); it must not blanket-append data from untrusted
+     * third-party apps — `renderSpine` itself stays prose-free for exactly
+     * this reason.
+     */
+    promptData(): Record<string, unknown>;
 }
 //# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,+EAA+E;IAC/E,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,4EAA4E;IAC5E,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACvC;AAED,sFAAsF;AACtF,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;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,gFAAgF;IAChF,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAQ;IAClD,0DAA0D;IAC1D,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAQ;IAE1C;;;;;;;;OAQG;IACH,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB;IA0BrD,0FAA0F;IACzF,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAElC,8EAA8E;IAC9E,SAAS,IAAI,MAAM,EAAE;CACtB"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,+EAA+E;IAC/E,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,4EAA4E;IAC5E,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACvC;AAED,sFAAsF;AACtF,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;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,gFAAgF;IAChF,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAQ;IAClD;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAK;IAEvC;;;;;;;;OAQG;IACH,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB;IA0BrD,0FAA0F;IACzF,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAElC,8EAA8E;IAC9E,SAAS,IAAI,MAAM,EAAE;IAErB;;;;;;;;;;;;;;OAcG;IACH,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CACtC"}

package/dist/source.js

@@ -23,8 +23,22 @@ exports.NULL_SCORER = {
 class Source {
     /** Reranker instance, set during {@link bind}. Used by {@link createScorer}. */
     _reranker = null;
-    /** Minimum entailment score for delegation to proceed. */
-    _entailmentFloor = 0.25;
+    /**
+     * Minimum entailment score for delegation to proceed.
+     *
+     * Reranker scores are logit-diffs (`logit(yes) − logit(no)`); a value
+     * `> 0` means the cross-encoder model prefers "yes" over "no" when
+     * asked whether the document matches the query. Default `0` ⇒ "the
+     * model agrees this passage is relevant"; subclasses may tighten
+     * (e.g. `2` for "confident yes") or loosen (negative, for noisy
+     * corpora where leaning-no hits are still worth investigating).
+     *
+     * The prior softmax-prob default was `0.25`, which corresponded to
+     * logit-diff `≈ −1.1`. The new default is stricter: only hits the
+     * model genuinely leans toward are surfaced. See TICK-002 calibration
+     * notes (`reasoning.run/scripts/inspect-rerank.mjs`) for the data.
+     */
+    _entailmentFloor = 0;
     /**
      * Create an immutable entailment scorer scoped to one invocation.
      *
@@ -62,6 +76,22 @@ class Source {
     *bind(_ctx) { }
     /** Post-use chunks for reranking. Called after agents have used the tools. */
     getChunks() { return []; }
+    /**
+     * App-level prompt data (e.g. a corpus TOC) for the HARNESS to place.
+     *
+     * Identical for every agent in a pool, so it belongs in shared KV —
+     * rendered ONCE, not duplicated per spawn (six 4.8k-token TOC-bearing
+     * suffixes overran a 32k context before this contract existed).
+     *
+     * Placement is a TRUST decision, which is why the framework does not
+     * place it automatically: this is free prose derived from source
+     * content, and the shared spine prefix is read by every agent in the
+     * pool. A harness may append it to its spine prompt for apps it trusts
+     * (first-party corpora); it must not blanket-append data from untrusted
+     * third-party apps — `renderSpine` itself stays prose-free for exactly
+     * this reason.
+     */
+    promptData() { return {}; }
 }
 exports.Source = Source;
 //# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -1 +1 @@
-{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":";;;AA2CA,sFAAsF;AACzE,QAAA,WAAW,GAAqB;IAC3C,oBAAoB,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACzD,mBAAmB,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACxD,oBAAoB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC/D,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI;CAC1B,CAAC;AAYF;;;;;;;;;;;GAWG;AACH,MAAsB,MAAM;IAM1B,gFAAgF;IACtE,SAAS,GAA0B,IAAI,CAAC;IAClD,0DAA0D;IAChD,gBAAgB,GAAW,IAAI,CAAC;IAE1C;;;;;;;;OAQG;IACH,YAAY,CAAC,aAAqB;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,QAAQ,IAAI,CAAC,aAAa;YAAE,OAAO,mBAAW,CAAC;QAEpD,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC;QACpC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvE,OAAO;YACL,KAAK,CAAC,oBAAoB,CAAC,KAAe;gBACxC,OAAO,QAAQ,CAAC,UAAU,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;YACnD,CAAC;YACD,KAAK,CAAC,mBAAmB,CAAC,KAAe,EAAE,UAAkB;gBAC3D,oEAAoE;gBACpE,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;gBACnE,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;gBACjE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrE,CAAC;YACD,KAAK,CAAC,oBAAoB,CAAC,SAAiB,EAAE,KAAe;gBAC3D,OAAO,QAAQ,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YAC/C,CAAC;YACD,aAAa,CAAC,KAAa;gBACzB,OAAO,KAAK,IAAI,KAAK,CAAC;YACxB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,0FAA0F;IAC1F,CAAC,IAAI,CAAC,IAAU,IAAoB,CAAC;IAErC,8EAA8E;IAC9E,SAAS,KAAe,OAAO,EAAE,CAAC,CAAC,CAAC;CACrC;AAnDD,wBAmDC"}
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":";;;AA2CA,sFAAsF;AACzE,QAAA,WAAW,GAAqB;IAC3C,oBAAoB,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACzD,mBAAmB,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACxD,oBAAoB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC/D,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI;CAC1B,CAAC;AAYF;;;;;;;;;;;GAWG;AACH,MAAsB,MAAM;IAM1B,gFAAgF;IACtE,SAAS,GAA0B,IAAI,CAAC;IAClD;;;;;;;;;;;;;;OAcG;IACO,gBAAgB,GAAW,CAAC,CAAC;IAEvC;;;;;;;;OAQG;IACH,YAAY,CAAC,aAAqB;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,QAAQ,IAAI,CAAC,aAAa;YAAE,OAAO,mBAAW,CAAC;QAEpD,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC;QACpC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEvE,OAAO;YACL,KAAK,CAAC,oBAAoB,CAAC,KAAe;gBACxC,OAAO,QAAQ,CAAC,UAAU,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;YACnD,CAAC;YACD,KAAK,CAAC,mBAAmB,CAAC,KAAe,EAAE,UAAkB;gBAC3D,oEAAoE;gBACpE,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;gBACnE,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;gBACjE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrE,CAAC;YACD,KAAK,CAAC,oBAAoB,CAAC,SAAiB,EAAE,KAAe;gBAC3D,OAAO,QAAQ,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YAC/C,CAAC;YACD,aAAa,CAAC,KAAa;gBACzB,OAAO,KAAK,IAAI,KAAK,CAAC;YACxB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,0FAA0F;IAC1F,CAAC,IAAI,CAAC,IAAU,IAAoB,CAAC;IAErC,8EAA8E;IAC9E,SAAS,KAAe,OAAO,EAAE,CAAC,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,UAAU,KAA8B,OAAO,EAAE,CAAC,CAAC,CAAC;CACrD;AAlFD,wBAkFC"}

package/dist/spine.d.ts

@@ -0,0 +1,100 @@
+import type { Operation } from "effection";
+import { Branch } from "@lloyal-labs/sdk";
+import type { Tool } from "./Tool";
+import type { SamplingParams } from "./types";
+/**
+ * Configuration for {@link withSpine}
+ *
+ * @category Agents
+ */
+export interface SpineOptions {
+    /** Sampling parameters for the spine branch */
+    params?: SamplingParams;
+    /**
+     * Fork the spine from this branch instead of creating at position 0.
+     *
+     * When provided, the spine inherits the parent's full KV state —
+     * every tool call, tool result, and generated token the parent
+     * accumulated. Sub-agents forking from this spine attend over the
+     * parent's complete attention state (Continuous Context).
+     *
+     * When omitted, creates a fresh spine at position 0 (cold start).
+     */
+    parent?: Branch;
+    /**
+     * When set, prefill the chat-format `[system + tools]` header onto the
+     * spine once at setup. Every agent forking from the spine inherits these
+     * tokens via `forkSync`'s metadata-only KV prefix-share — the role and
+     * tool schemas appear ONCE in physical KV regardless of how many agents
+     * the pool spawns.
+     *
+     * The resulting `FormatConfig` (parser/grammar/format/triggers) is set
+     * on the {@link SpineFmt} context so `setupAgent` can detect shared mode,
+     * skip its own system+tools formatting, and inherit the dispatch-side
+     * fmt from the spine.
+     *
+     * Use this for orchestrators where every agent shares the same role —
+     * chain-mode research pools, fanout-style same-role pools, etc. Mixed-
+     * role workflows (research → compare → synthesize) keep using per-spec
+     * `SpawnSpec.systemPrompt` and don't pass this option.
+     */
+    systemPrompt?: string;
+    /**
+     * Tools whose schemas embed into the chat-format header prefilled at setup.
+     * Their JSON schemas are decoded into the spine's KV ONCE; every agent
+     * forking from the spine inherits the schema tokens via fork prefix-share
+     * instead of re-emitting them in its own suffix.
+     *
+     * The same `Tool[]` is typically also passed to `agentPool` (where it
+     * becomes the dispatcher registry). Two roles, one input — schemas
+     * decoded once into the spine, instances registered for runtime
+     * `tool.execute()` dispatch.
+     *
+     * Only applied when `systemPrompt` is also set (shared mode); ignored
+     * otherwise.
+     */
+    tools?: Tool[];
+    /**
+     * Whether to enable thinking-mode tokens (e.g. `<think>` blocks) when
+     * formatting the spine's chat-format header. Threaded through to the
+     * chat-format call AND stored on the `SpineFmt` FormatConfig so
+     * `setupAgent`'s shared-mode shortcut copies a parser/grammar/triggers
+     * configuration consistent with the per-agent suffix formatting.
+     *
+     * Should match the `enableThinking` value the caller passes to the agent
+     * pool — divergent values produce inconsistent grammar between the
+     * prefilled spine and per-agent suffixes.
+     *
+     * @default false
+     */
+    enableThinking?: boolean;
+}
+/**
+ * Scoped spine branch with guaranteed cleanup
+ *
+ * Creates (or forks) the pool's spine — the shared KV line that agents
+ * fork from and that `ctx.extendSpine` writes onto between tasks. The
+ * spine is pruned via try/finally when the body returns or throws,
+ * regardless of whether children still exist.
+ *
+ * Each agent's chat format (system + user + generation prompt) is rendered
+ * fresh inside `setupAgent`, so this spine carries no chat context itself —
+ * it exists as the pool's branching point and as the line that
+ * `ctx.extendSpine` writes onto between tasks.
+ *
+ * **Cold path** (no `parent`): creates a spine at position 0 with no prefill.
+ * Agents fork at position 0; their full chat context lives in their own suffix.
+ *
+ * **Warm path** (`parent` provided): forks from parent and prefills a turn
+ * separator so subsequent agent suffixes land on a clean turn boundary.
+ * Sub-agents inherit the parent's full KV state via the fork.
+ *
+ * @param opts - Sampling parameters and optional parent branch
+ * @param body - Operation that receives the spine branch and prefix length.
+ *   Typically calls {@link useAgentPool} inside.
+ * @returns The body's return value
+ *
+ * @category Agents
+ */
+export declare function withSpine<T>(opts: SpineOptions, body: (spine: Branch, prefixLength: number) => Operation<T>): Operation<T>;
+//# sourceMappingURL=spine.d.ts.map

package/dist/spine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine.d.ts","sourceRoot":"","sources":["../src/spine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAK1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAiB,SAAS,CAAC,CAAC,EAC1B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,GAC1D,SAAS,CAAC,CAAC,CAAC,CAyId"}

package/dist/{shared-root.js → spine.js}

@@ -1,23 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withSharedRoot = withSharedRoot;
+exports.withSpine = withSpine;
 const effection_1 = require("effection");
 const sdk_1 = require("@lloyal-labs/sdk");
 const context_1 = require("./context");
 const trace_scope_1 = require("./trace-scope");
+const toolkit_1 = require("./toolkit");
 /**
- * Scoped shared root branch with guaranteed cleanup
+ * Scoped spine branch with guaranteed cleanup
  *
- * Creates (or forks) a root branch for the pool's agents to fork from.
- * The root is pruned via try/finally when the body returns or throws,
+ * Creates (or forks) the pool's spine — the shared KV line that agents
+ * fork from and that `ctx.extendSpine` writes onto between tasks. The
+ * spine is pruned via try/finally when the body returns or throws,
  * regardless of whether children still exist.
  *
  * Each agent's chat format (system + user + generation prompt) is rendered
- * fresh inside `setupAgent`, so this root carries no chat context itself —
- * it exists as the pool's branching point and as the spine that
- * `ctx.extendRoot` writes onto between tasks.
+ * fresh inside `setupAgent`, so this spine carries no chat context itself —
+ * it exists as the pool's branching point and as the line that
+ * `ctx.extendSpine` writes onto between tasks.
  *
- * **Cold path** (no `parent`): creates a root at position 0 with no prefill.
+ * **Cold path** (no `parent`): creates a spine at position 0 with no prefill.
  * Agents fork at position 0; their full chat context lives in their own suffix.
  *
  * **Warm path** (`parent` provided): forks from parent and prefills a turn
@@ -25,13 +27,13 @@ const trace_scope_1 = require("./trace-scope");
  * Sub-agents inherit the parent's full KV state via the fork.
  *
  * @param opts - Sampling parameters and optional parent branch
- * @param body - Operation that receives the root branch and prefix length.
+ * @param body - Operation that receives the spine branch and prefix length.
  *   Typically calls {@link useAgentPool} inside.
  * @returns The body's return value
  *
  * @category Agents
  */
-function* withSharedRoot(opts, body) {
+function* withSpine(opts, body) {
     const ctx = yield* context_1.Ctx.expect();
     const tw = yield* context_1.Trace.expect();
     // Read parent trace ID — connects nested pools to the outer DISPATCH that spawned them
@@ -44,21 +46,21 @@ function* withSharedRoot(opts, body) {
     catch {
         /* no parent — top level */
     }
-    const scope = (0, trace_scope_1.traceScope)(tw, parentTraceId, "withSharedRoot", {
+    const scope = (0, trace_scope_1.traceScope)(tw, parentTraceId, "withSpine", {
         hasParent: !!opts.parent,
     });
     // Warm path: fork from parent branch (inherits full KV state), prefill a
     // turn separator so the next agent's suffix lands on a clean boundary.
-    // Cold path: create fresh root at position 0 with no prefill — agents
+    // Cold path: create fresh spine at position 0 with no prefill — agents
     // fork at 0 and carry their full chat context in their own suffix.
-    let root;
+    let spine;
     let prefillTokens;
     if (opts.parent) {
-        root = opts.parent.forkSync();
+        spine = opts.parent.forkSync();
         prefillTokens = ctx.getTurnSeparator();
     }
     else {
-        root = sdk_1.Branch.create(ctx, 0, opts.params ?? { temperature: 0.5 });
+        spine = sdk_1.Branch.create(ctx, 0, opts.params ?? { temperature: 0.5 });
         prefillTokens = [];
     }
     tw.write({
@@ -66,30 +68,30 @@ function* withSharedRoot(opts, body) {
         parentTraceId: scope.traceId,
         ts: performance.now(),
         type: "branch:create",
-        branchHandle: root.handle,
+        branchHandle: spine.handle,
         parentHandle: opts.parent?.handle ?? null,
         position: opts.parent ? opts.parent.position : 0,
-        role: "sharedRoot",
+        role: "spine",
     });
     if (prefillTokens.length > 0) {
-        yield* (0, effection_1.call)(() => root.prefill(prefillTokens));
+        yield* (0, effection_1.call)(() => spine.prefill(prefillTokens));
         tw.write({
             traceId: tw.nextId(),
             parentTraceId: scope.traceId,
             ts: performance.now(),
             type: "branch:prefill",
-            branchHandle: root.handle,
+            branchHandle: spine.handle,
             tokenCount: prefillTokens.length,
-            role: "sharedPrefix",
+            role: "spineHeader",
         });
     }
     // Shared role+tools mode: format the chat header once and prefill onto
-    // the root. Agents forking from this root inherit system+tools tokens
+    // the spine. Agents forking from this spine inherit system+tools tokens
     // via metadata-only prefix-share (no per-spawn re-prefill). The resulting
-    // FormatConfig is stashed on RootFmt so setupAgent can detect shared
+    // FormatConfig is stashed on SpineFmt so setupAgent can detect shared
     // mode and copy parser/grammar/format/triggers without re-emitting the
     // tool schemas in each agent's suffix.
-    let rootFmt = null;
+    let spineFmt = null;
     if (opts.systemPrompt !== undefined) {
         const enableThinking = opts.enableThinking ?? false;
         const messages = JSON.stringify([{ role: "system", content: opts.systemPrompt }]);
@@ -100,23 +102,42 @@ function* withSharedRoot(opts, body) {
             // trailing assistant generation prompt and corrupt the boundary.
             addGenerationPrompt: false,
         };
-        if (opts.toolsJson)
-            fmtOpts.tools = opts.toolsJson;
+        if (opts.tools && opts.tools.length > 0) {
+            fmtOpts.tools = (0, toolkit_1.createToolkit)(opts.tools).toolsJson;
+        }
         const formatted = ctx.formatChatSync(messages, fmtOpts);
         const headerTokens = ctx.tokenizeSync(formatted.prompt, false);
+        // Spine-seed emission for trace replay (`extractSpineSeed`). Captures
+        // the rendered chat prompt verbatim so a later `reconstructBranch`
+        // can rebuild this exact KV state in a fresh context. The token-count
+        // `branch:prefill` below is informational; the spine seed is the
+        // prompt text on this event.
+        tw.write({
+            traceId: tw.nextId(),
+            parentTraceId: scope.traceId,
+            ts: performance.now(),
+            type: "prompt:format",
+            promptText: formatted.prompt,
+            tokenCount: headerTokens.length,
+            messages,
+            tools: opts.tools && opts.tools.length > 0
+                ? (0, toolkit_1.createToolkit)(opts.tools).toolsJson
+                : undefined,
+            role: "spine",
+        });
         if (headerTokens.length > 0) {
-            yield* (0, effection_1.call)(() => root.prefill(headerTokens));
+            yield* (0, effection_1.call)(() => spine.prefill(headerTokens));
             tw.write({
                 traceId: tw.nextId(),
                 parentTraceId: scope.traceId,
                 ts: performance.now(),
                 type: "branch:prefill",
-                branchHandle: root.handle,
+                branchHandle: spine.handle,
                 tokenCount: headerTokens.length,
-                role: "sharedPrefix",
+                role: "spineHeader",
             });
         }
-        rootFmt = {
+        spineFmt = {
             format: formatted.format,
             reasoningFormat: formatted.reasoningFormat,
             generationPrompt: formatted.generationPrompt,
@@ -128,25 +149,23 @@ function* withSharedRoot(opts, body) {
         };
     }
     try {
-        if (opts.enableScratchpad)
-            yield* context_1.ScratchpadParent.set(root);
-        if (rootFmt)
-            yield* context_1.RootFmt.set(rootFmt);
-        return yield* body(root, prefillTokens.length);
+        if (spineFmt)
+            yield* context_1.SpineFmt.set(spineFmt);
+        return yield* body(spine, prefillTokens.length);
     }
     finally {
-        if (!root.disposed) {
+        if (!spine.disposed) {
             tw.write({
                 traceId: tw.nextId(),
                 parentTraceId: scope.traceId,
                 ts: performance.now(),
                 type: "branch:prune",
-                branchHandle: root.handle,
+                branchHandle: spine.handle,
                 position: 0,
             });
-            root.pruneSubtreeSync();
+            spine.pruneSubtreeSync();
         }
         scope.close();
     }
 }
-//# sourceMappingURL=shared-root.js.map
+//# sourceMappingURL=spine.js.map

package/dist/spine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine.js","sourceRoot":"","sources":["../src/spine.ts"],"names":[],"mappings":"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"}

package/dist/toolkit.d.ts

@@ -1,38 +1,65 @@
 import type { Tool } from './Tool';
 /**
- * Aggregated tool registry for agent pool consumption
+ * The compiled tool set an agent pool operates with: the assembled tool
+ * instances plus the two projections the runtime needs and the name of
+ * the designated terminal (if any).
  *
- * Contains the `toolMap` for dispatch and `toolsJson` for prompt
- * formatting. Created by {@link createToolkit}.
+ * `createToolkit` is the single place a `Tool[]` (plus an optional
+ * terminal) is turned into the shapes the framework consumes. Nothing
+ * downstream consumes a `Toolkit` as a whole — the formatter reads
+ * `toolsJson`, the pool reads `toolMap` and `terminalName` — so this is
+ * internal plumbing, not a developer-facing concept. Harnesses pass
+ * `tools: Tool[]` + `terminal?: Tool` to `agentPool` / `useAgent`; the
+ * wrappers call `createToolkit` for them.
  *
  * @category Agents
  */
 export interface Toolkit {
-    /** Name-to-instance map used by {@link useAgentPool} for tool dispatch */
+    /**
+     * The assembled tool set — the supplied tools plus the designated
+     * terminal (if one was given and wasn't already present), deduped by
+     * name. `toolMap` and `toolsJson` are derived from exactly this list.
+     */
+    tools: Tool[];
+    /** Name-to-instance map used by {@link useAgentPool} for tool dispatch. */
     toolMap: Map<string, Tool>;
-    /** JSON-serialized tool schemas passed to `formatChat()` via task specs */
+    /** JSON-serialized tool schemas passed to `formatChat()` via task specs. */
     toolsJson: string;
+    /**
+     * Name of the terminal tool, when one was designated via the
+     * `terminal` argument. The pool intercepts a call to this tool at the
+     * policy layer and extracts its `result` arg as the agent's return
+     * value (capture-only — the terminal's `execute()` is not run).
+     * Undefined when no terminal was designated (agent ends on
+     * free-text/stop).
+     */
+    terminalName?: string;
 }
 /**
- * Aggregate an array of {@link Tool} instances into a toolkit
+ * Compile a `Tool[]` (and an optional terminal) into a {@link Toolkit}.
  *
- * Builds both the dispatch map and the JSON schema string from the
- * tool array. Pass the result directly to {@link AgentPoolOptions}
- * and {@link AgentTaskSpec}.
+ * The `terminal` is the tool that ends an agent's turn — `report`,
+ * `email`, `persistToDB`, whatever the harness designates. It's passed
+ * by **reference** (not by name), so there's no string to mistype and
+ * no "the terminal must also appear in the array" coupling: the terminal
+ * is merged into the assembled set here (deduped if already present), so
+ * its schema reaches the model and its instance is dispatchable, and its
+ * name is recorded as {@link Toolkit.terminalName}.
  *
- * @param tools - Tool instances to aggregate
- * @returns Toolkit with `toolMap` and `toolsJson`
+ * @param tools - The agent's non-terminal tools (app/source tools, or
+ *   harness-constructed tools).
+ * @param terminal - Optional terminal tool. Omit for pools that end on
+ *   free-text/stop.
  *
  * @example
  * ```typescript
- * const { toolMap, toolsJson } = createToolkit([
- *   new SearchTool(chunks, reranker),
- *   new ReadFileTool(resources),
- *   new GrepTool(resources),
- * ]);
+ * const toolkit = createToolkit(
+ *   [new SearchTool(chunks, reranker), new ReadFileTool(resources)],
+ *   reportTool,
+ * );
  * ```
  *
  * @category Agents
  */
-export declare function createToolkit(tools: Tool[]): Toolkit;
+export declare function createToolkit(tools: Tool[], terminal?: Tool): Toolkit;
 //# sourceMappingURL=toolkit.d.ts.map

package/dist/toolkit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,0EAA0E;IAC1E,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAKpD"}
+{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,2EAA2E;IAC3E,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,QAAQ,CAAC,EAAE,IAAI,GAAG,OAAO,CAWrE"}

package/dist/toolkit.js

@@ -2,30 +2,40 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createToolkit = createToolkit;
 /**
- * Aggregate an array of {@link Tool} instances into a toolkit
+ * Compile a `Tool[]` (and an optional terminal) into a {@link Toolkit}.
  *
- * Builds both the dispatch map and the JSON schema string from the
- * tool array. Pass the result directly to {@link AgentPoolOptions}
- * and {@link AgentTaskSpec}.
+ * The `terminal` is the tool that ends an agent's turn — `report`,
+ * `email`, `persistToDB`, whatever the harness designates. It's passed
+ * by **reference** (not by name), so there's no string to mistype and
+ * no "the terminal must also appear in the array" coupling: the terminal
+ * is merged into the assembled set here (deduped if already present), so
+ * its schema reaches the model and its instance is dispatchable, and its
+ * name is recorded as {@link Toolkit.terminalName}.
  *
- * @param tools - Tool instances to aggregate
- * @returns Toolkit with `toolMap` and `toolsJson`
+ * @param tools - The agent's non-terminal tools (app/source tools, or
+ *   harness-constructed tools).
+ * @param terminal - Optional terminal tool. Omit for pools that end on
+ *   free-text/stop.
  *
  * @example
  * ```typescript
- * const { toolMap, toolsJson } = createToolkit([
- *   new SearchTool(chunks, reranker),
- *   new ReadFileTool(resources),
- *   new GrepTool(resources),
- * ]);
+ * const toolkit = createToolkit(
+ *   [new SearchTool(chunks, reranker), new ReadFileTool(resources)],
+ *   reportTool,
+ * );
  * ```
  *
  * @category Agents
  */
-function createToolkit(tools) {
+function createToolkit(tools, terminal) {
+    const merged = terminal && !tools.some(t => t.name === terminal.name)
+        ? [...tools, terminal]
+        : tools;
     return {
-        toolMap: new Map(tools.map(t => [t.name, t])),
-        toolsJson: JSON.stringify(tools.map(t => t.schema)),
+        tools: merged,
+        toolMap: new Map(merged.map(t => [t.name, t])),
+        toolsJson: JSON.stringify(merged.map(t => t.schema)),
+        terminalName: terminal?.name,
     };
 }
 //# sourceMappingURL=toolkit.js.map

package/dist/toolkit.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolkit.js","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":";;AAsCA,sCAKC;AA1BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,aAAa,CAAC,KAAa;IACzC,OAAO;QACL,OAAO,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7C,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;KACpD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"toolkit.js","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":";;AAiEA,sCAWC;AArCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,aAAa,CAAC,KAAa,EAAE,QAAe;IAC1D,MAAM,MAAM,GACV,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC;QACpD,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,QAAQ,CAAC;QACtB,CAAC,CAAC,KAAK,CAAC;IACZ,OAAO;QACL,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9C,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACpD,YAAY,EAAE,QAAQ,EAAE,IAAI;KAC7B,CAAC;AACJ,CAAC"}