@lloyal-labs/lloyal-agents 2.1.0 → 3.0.1

package/dist/app-types.d.ts

@@ -0,0 +1,309 @@
+/**
+ * App protocol types — what a third-party app developer declares + what
+ * the framework consumes when registering and rendering apps.
+ *
+ * Three groups of types live here:
+ *
+ * 1. **Declarative manifest** ({@link AppManifest}, {@link AppProtocol},
+ *    {@link AppHints}). Authored in `app.json` and imported into the
+ *    factory; describes what the app *is* without any runtime values.
+ *
+ * 2. **Runtime App object** ({@link App}, {@link SkillTemplateFn},
+ *    {@link ExamplesTemplateFn}). Constructed by `defineApp(...)` inside
+ *    the app's factory; bundles the manifest with the live `Source`,
+ *    `Tool[]`, and template renderers.
+ *
+ * 3. **Per-spawn render context** ({@link AgentRenderCtx},
+ *    {@link ExamplesRenderCtx}). Passed by the framework to template
+ *    renderers when constructing a per-spawn preamble.
+ *
+ * Plus {@link AppFactory} (what the registry runs to construct an App)
+ * and {@link ConfigFlow} for the optional credential handoff.
+ *
+ * @packageDocumentation
+ * @category Protocol
+ */
+import type { Operation } from 'effection';
+import type { Source } from './source';
+import type { Tool } from './Tool';
+import type { JsonSchema } from './types';
+/**
+ * The model-facing identity of an app — three fields under
+ * `manifest.protocol` in `app.json`. The framework renders these into
+ * the boundary marker, the spine catalog entry,
+ * and the auth-guard allowed-tools set.
+ *
+ * Constraints (enforced synchronously by `defineApp`):
+ * - `name` matches `[a-z][a-z0-9_-]{1,63}`.
+ * - `tools` is a non-empty array of tool-name strings, each matching the
+ *   same regex as `name`. Must cover exactly the keys of the app's
+ *   `tools` map supplied to `defineApp`.
+ * - `useWhen` is a single sentence of printable characters, bounded in
+ *   length, with no chat-role markers (`SYSTEM:`/`USER:`/etc.), no
+ *   markdown code fences, and no newlines.
+ */
+export interface AppProtocol {
+    /** Model-facing protocol identifier (e.g., `"web_research"`). */
+    readonly name: string;
+    /** Single-sentence routing hint rendered into the catalog `Use when:` line. */
+    readonly useWhen: string;
+    /** Tool names exposed by this protocol; must match the app's `tools` map keys. */
+    readonly tools: readonly string[];
+}
+/**
+ * Optional UX/marketplace metadata. Not part of the model-facing surface;
+ * surfaced to harness UI, marketplace listings, and capability disclosure
+ * at install time.
+ */
+export interface AppHints {
+    /** Short display name for chips/tabs (e.g., `"web"`, `"jira"`). */
+    readonly shortName?: string;
+    /** Long-form description for marketplace listings. */
+    readonly description?: string;
+    /** URL to an icon (svg/png) the harness may display. */
+    readonly iconUrl?: string;
+    /** Coarse capability disclosure for install-time review. */
+    readonly authKind?: 'oauth' | 'apikey' | 'path' | 'token' | 'none';
+}
+/**
+ * The declarative app manifest — content of `app.json` plus the
+ * `appProtocolVersion` declaration. Imported into the app's factory
+ * and passed to `defineApp(...)`.
+ *
+ * `manifest.name` is the **app identifier** used in code paths
+ * (`SpawnSpec.assignedApp`, `registry.byName(...)`, the AppConfigStore
+ * key, filesystem paths). The model never sees this — it only sees
+ * `manifest.protocol.name`. One app, one protocol.
+ */
+export interface AppManifest {
+    /** App identifier used for routing, config storage, and registry lookup. */
+    readonly name: string;
+    /**
+     * Which codified App protocol version this app targets. The framework
+     * refuses to register apps whose declared version is not in
+     * `SUPPORTED_APP_PROTOCOL_VERSIONS` (currently `['3.0']`).
+     */
+    readonly appProtocolVersion?: string;
+    /** The model-facing identity. */
+    readonly protocol: AppProtocol;
+    /** Optional UX/marketplace metadata. */
+    readonly hints?: AppHints;
+    /**
+     * JSON Schema declaring what config the app needs. The framework
+     * validates the app's stored config against it at enable time (when the
+     * factory's constructed manifest is available). The `x-secret: true`
+     * field annotation signals sensitive values (harness UX masks them, may
+     * prefer secure storage backend).
+     */
+    readonly configSchema?: JsonSchema;
+}
+/**
+ * Variables the framework provides to `skill.eta` template renderers
+ * at per-spawn render time. Apps reference these as `it.agentCount`,
+ * `it.maxTurns`, etc. inside their Eta templates.
+ *
+ * App-specific additional variables (e.g., corpus apps' TOC) can be
+ * supplied by extending the render context inside the App's factory —
+ * the framework spreads `params` into the Eta template's render data.
+ */
+export interface AgentRenderCtx {
+    /** Total number of agents spawned in the current fan-out. */
+    readonly agentCount: number;
+    /** Task descriptions of the *other* agents in this fan-out. */
+    readonly siblingTasks: readonly string[];
+    /** Tool-call budget for this spawn. */
+    readonly maxTurns: number;
+    /** Today's date in ISO format. */
+    readonly date: string;
+    /** Position in a chain orchestrator (0-indexed); 0 for parallel fan-outs. */
+    readonly taskIndex: number;
+}
+/**
+ * Variables provided to `examples.eta` renderers in addition to all
+ * fields of {@link AgentRenderCtx}. Apps can reference `it.name`
+ * (protocol name) and `it.tools` (the protocol's tool-name list) when
+ * authoring discipline content.
+ */
+export interface ExamplesRenderCtx extends AgentRenderCtx {
+    /** The protocol's name (same as `app.manifest.protocol.name`). */
+    readonly name: string;
+    /** The protocol's tool-name list (same as `app.manifest.protocol.tools`). */
+    readonly tools: readonly string[];
+}
+/**
+ * Function alternative to a string `skill.eta` template — for apps whose
+ * per-spawn prompt needs runtime parameterization beyond what Eta covers.
+ *
+ * The returned string is the per-spawn body; the framework prepends
+ * `BOUNDARY_MARKER(protocol.name)` and (optionally) appends the rendered
+ * `examples.eta`. The function MUST NOT return content containing the
+ * literal `Apply the **` substring (the framework prepends it and
+ * `defineApp` cannot statically validate function outputs — the first-render
+ * check on canonical apps catches it).
+ */
+export type SkillTemplateFn = (params: AgentRenderCtx) => string;
+/**
+ * Function alternative to a string `examples.eta` template.
+ *
+ * Per-spawn only — examples are rendered into the
+ * preamble of agents assigned to *this* app, never into the shared spine.
+ */
+export type ExamplesTemplateFn = (params: ExamplesRenderCtx) => string;
+/**
+ * Interactive config-acquisition flow for OAuth-like protocols the app
+ * drives. This is credential **acquisition**, not lifecycle: it obtains
+ * config (tokens) and the harness writes the result to `AppConfigStore`.
+ * It is unrelated to enable/disable — the actual authentication happens
+ * at the provider, not in the framework.
+ *
+ * Harness calls `initiate` → app returns a handoff URL + optional
+ * callback param validator → harness opens the URL → user completes auth
+ * → harness captures callback params → harness validates via
+ * `callbackValidator` (if provided) → harness calls `complete` → app
+ * returns the full config object → framework validates against
+ * `manifest.configSchema` → harness writes the whole-replace config to
+ * `AppConfigStore`.
+ *
+ * Both steps run inside the harness's Effection scope; if a flow needs
+ * to read existing config it does `yield* AppConfigStoreCtx.expect()`
+ * directly — there is no separate context parameter.
+ */
+export interface ConfigFlow {
+    /** Initiates the auth flow; returns a handoff URL the harness opens. */
+    initiate(): Operation<{
+        handoffUrl?: string;
+        callbackValidator?: (params: unknown) => boolean;
+    }>;
+    /** Receives callback params from the harness; returns the full config. */
+    complete(callbackParams: unknown): Operation<Record<string, unknown>>;
+}
+/**
+ * The runtime artifact returned by `defineApp(...)` inside an app's
+ * factory. Combines the declarative {@link AppManifest} with the live
+ * `Source`, `Tool[]`, and prompt templates the framework needs at
+ * spawn time.
+ *
+ * Apps are constructed inside zero-arg `Operation<App>` factories
+ * (typically `createWebApp`, `createJiraApp`, etc.) that read config
+ * from `AppConfigStoreCtx` and the shared reranker from `RerankerCtx`.
+ * Both npm-distributed apps and signed-bundle apps use the identical
+ * factory signature.
+ */
+export interface App {
+    /** Same as `manifest.name` — routing key. */
+    readonly name: string;
+    /** The declarative manifest. */
+    readonly manifest: AppManifest;
+    /** The app's Source (provides per-domain chunking + tools). */
+    readonly source: Source;
+    /**
+     * The tool instances exposed by this app. Their names must match
+     * `manifest.protocol.tools` exactly. The framework concatenates all
+     * registered apps' `tools` into the spine prefill (one shared decode
+     * of all schemas, amortized across every spawn in the pool).
+     */
+    readonly tools: readonly Tool[];
+    /**
+     * The per-spawn `skill.eta` template (string) or function. The
+     * framework prepends the boundary marker; `skill.eta` MUST NOT
+     * contain the literal `Apply the **` substring.
+     */
+    readonly skill: string | SkillTemplateFn;
+    /**
+     * Optional discipline content (GOOD/BAD examples, anti-patterns)
+     * rendered into the per-spawn preamble of agents assigned to this
+     * app. Not surfaced in the shared spine.
+     */
+    readonly examples?: string | ExamplesTemplateFn;
+    /** Optional config schema (same as `manifest.configSchema`). */
+    readonly configSchema?: JsonSchema;
+    /** Optional UX hints (same as `manifest.hints`). */
+    readonly hints?: AppHints;
+    /** Optional interactive config flow. */
+    readonly configFlow?: ConfigFlow;
+}
+/**
+ * A zero-arg Operation that constructs an {@link App}. This — not a
+ * constructed `App` — is what the registry consumes (`createAppRegistry({
+ * apps })` at boot, or `registry.enable(factory)` dynamically): the
+ * registry runs the factory inside a per-app **detached** Effection scope
+ * that it seeds with `AppConfigStoreCtx` / `AppRegistryCtx` / `RerankerCtx`,
+ * so the factory reads its config and reranker, does any setup, and returns
+ * the App.
+ *
+ * **Setup and teardown are structured, not hooks.** The factory body *is*
+ * the setup. For resources that need teardown (a connection, a watcher),
+ * the factory is a `resource()` that allocates, registers cleanup with
+ * `ensure(...)`, and `provide(...)`s the App — the cleanup fires when the
+ * app's detached scope is torn down (`registry.disable(name)`, or registry
+ * scope exit). Apps with no external resources are a plain
+ * `function* () { return defineApp(...) }`. There are no
+ * `install`/`uninstall`/`enable`/`disable` hooks.
+ *
+ * Apps installed via `harness.dev install` (signed npm tarballs from
+ * the canonical channel) export a factory of this exact shape from
+ * their package entry point — the harness imports it with a plain
+ * `import { createXxxApp } from '@lloyal-labs/<name>-app'` and passes
+ * it to `createAppRegistry({ apps: [...] })`.
+ */
+export type AppFactory = () => Operation<App>;
+/**
+ * The framework-tracked runtime state of an app: `'enabled'` once its
+ * factory has run and it sits in the registry, `'disabled'` otherwise.
+ * Binary by design — richer states (configured, authenticated, ready) are
+ * harness UX rollups or app-internal runtime concerns, not framework
+ * state.
+ */
+export type AppState = 'enabled' | 'disabled';
+/**
+ * The harness-owned registry of enabled apps. Lives behind
+ * `AppRegistryCtx`; the auth-guard consults it at
+ * tool-dispatch time to resolve the allowed-tools set for an
+ * App-assigned spawn (`SpawnSpec.assignedApp`). The concrete factory
+ * `createAppRegistry(...)` lives in `@lloyal-labs/rig`; dynamic
+ * enable/disable are methods on this interface.
+ *
+ * Registry state is the single source of truth for which apps are
+ * enabled within a harness scope. The harness declares its boot set
+ * via `createAppRegistry({ apps })`; each app runs in its own detached
+ * Effection scope. `disable` (or registry scope-exit) tears that scope
+ * down, firing the app factory's `ensure(...)` teardown. There are no
+ * install/uninstall hooks.
+ */
+export interface AppRegistry {
+    /**
+     * Look up an enabled app by `manifest.name` (the routing key —
+     * **not** `manifest.protocol.name`). Returns `undefined` if no app
+     * with that name is enabled.
+     */
+    byName(name: string): App | undefined;
+    /**
+     * Snapshot of currently-enabled apps in registration order. The
+     * spine renderer walks this list to compose the catalog;
+     * order is observable to the model.
+     */
+    enabled(): readonly App[];
+    /**
+     * Binary state of an app: `'enabled'` if it's in the registry,
+     * `'disabled'` otherwise. Convenience over `byName(name) !==
+     * undefined` for harness UX.
+     */
+    stateOf(name: string): AppState;
+    /**
+     * Enable an app dynamically (the mid-session enable path). Runs
+     * the factory in a fresh per-app detached scope (seeded with `App*Ctx`),
+     * validates the manifest, and adds it. Returns the constructed App.
+     * Throws — and tears down the partial scope — if the factory
+     * throws, validation fails, or the name is already enabled. The boot
+     * set is enabled the same way via `createAppRegistry({ apps })`.
+     */
+    enable(factory: AppFactory): Operation<App>;
+    /**
+     * Disable an app dynamically: remove it and tear down its detached
+     * scope, firing the factory's `ensure(...)` teardown. A throwing
+     * teardown is logged but the app is removed regardless. No-op for an
+     * unknown name.
+     */
+    disable(name: string): Operation<void>;
+}
+//# sourceMappingURL=app-types.d.ts.map

package/dist/app-types.d.ts.map

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

package/dist/app-types.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * App protocol types — what a third-party app developer declares + what
+ * the framework consumes when registering and rendering apps.
+ *
+ * Three groups of types live here:
+ *
+ * 1. **Declarative manifest** ({@link AppManifest}, {@link AppProtocol},
+ *    {@link AppHints}). Authored in `app.json` and imported into the
+ *    factory; describes what the app *is* without any runtime values.
+ *
+ * 2. **Runtime App object** ({@link App}, {@link SkillTemplateFn},
+ *    {@link ExamplesTemplateFn}). Constructed by `defineApp(...)` inside
+ *    the app's factory; bundles the manifest with the live `Source`,
+ *    `Tool[]`, and template renderers.
+ *
+ * 3. **Per-spawn render context** ({@link AgentRenderCtx},
+ *    {@link ExamplesRenderCtx}). Passed by the framework to template
+ *    renderers when constructing a per-spawn preamble.
+ *
+ * Plus {@link AppFactory} (what the registry runs to construct an App)
+ * and {@link ConfigFlow} for the optional credential handoff.
+ *
+ * @packageDocumentation
+ * @category Protocol
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=app-types.js.map

package/dist/app-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-types.js","sourceRoot":"","sources":["../src/app-types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/chunk.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Chunk / Reranker abstraction types.
+ *
+ * These interfaces live in `@lloyal-labs/lloyal-agents` (not rig) so that
+ * agent-pool code, app factories, and harness contexts can refer to a
+ * common Reranker shape without depending on rig's concrete chunking
+ * implementation. Concrete chunking utilities (`chunkResources`,
+ * `chunkHtml`, `chunkFetchedPages`) and the cross-encoder-backed
+ * `createReranker(...)` factory live in `@lloyal-labs/rig`.
+ *
+ * The pattern mirrors `Source` and `Tool`: abstract type in agents,
+ * concrete subclasses/factories in rig.
+ *
+ * @packageDocumentation
+ * @category Contract
+ */
+/**
+ * A loaded document available for search, read, and grep operations.
+ *
+ * Represents a single file (typically Markdown) loaded into memory.
+ * Resources are chunked into {@link Chunk} instances for reranking.
+ */
+export interface Resource {
+    /** File name (basename, not full path) used as the resource identifier. */
+    name: string;
+    /** Full text content of the file. */
+    content: string;
+}
+/**
+ * A scored passage within a {@link Resource}, used for reranking and retrieval.
+ *
+ * The `tokens` array is populated lazily by {@link Reranker.tokenizeChunks}
+ * before scoring. Once tokenized, a chunk is bound to that reranker's
+ * cross-encoder vocabulary — re-binding requires re-tokenization.
+ */
+export interface Chunk {
+    /** Resource identifier (file name or URL) this chunk belongs to. */
+    resource: string;
+    /** Leaf section heading (e.g. "Recovery loop"). */
+    heading: string;
+    /** Hierarchical section path (e.g. "Agents > Lifecycle > Recovery loop"). Empty for web chunks. */
+    section: string;
+    /** Raw text content of the chunk. */
+    text: string;
+    /** Pre-tokenized representation for the reranker — empty until {@link Reranker.tokenizeChunks} runs. */
+    tokens: number[];
+    /** First line number (1-based) in the source resource. */
+    startLine: number;
+    /** Last line number (1-based) in the source resource. */
+    endLine: number;
+}
+/**
+ * A single chunk scored by the {@link Reranker} against a query.
+ */
+export interface ScoredChunk {
+    /** Source filename containing the chunk. */
+    file: string;
+    /** Leaf section heading (e.g. "Recovery loop"). */
+    heading: string;
+    /** Hierarchical section path (e.g. "Agents > Lifecycle > Recovery loop"). Empty for web chunks. */
+    section: string;
+    /** First ~200 chars of chunk text — gives agents content at search time. */
+    snippet: string;
+    /** Relevance score (higher = more relevant). */
+    score: number;
+    /** Start line in the source file (1-indexed). */
+    startLine: number;
+    /** End line in the source file (1-indexed). */
+    endLine: number;
+}
+/**
+ * Progressive reranker output emitted during scoring.
+ *
+ * Streamed from {@link Reranker.score} as an async iterable, allowing
+ * callers to report progress while scoring is in flight.
+ */
+export interface ScoredResult {
+    /** Scored chunks accumulated so far, ordered by relevance. */
+    results: ScoredChunk[];
+    /** Number of chunks scored so far. */
+    filled: number;
+    /** Total number of chunks to score. */
+    total: number;
+}
+/**
+ * Cross-encoder reranker for scoring corpus chunks against a query.
+ *
+ * Apps obtain the harness-wide reranker via `RerankerCtx.expect()` at
+ * factory time — `source.bind({reranker})` is no longer the mechanism.
+ * Implementations tokenize chunks up front via {@link tokenizeChunks},
+ * then stream progressive results from {@link score}.
+ */
+export interface Reranker {
+    /** Score chunks against a query, streaming progressive results. */
+    score(query: string, chunks: Chunk[]): AsyncIterable<ScoredResult>;
+    /**
+     * Score raw text strings against a query in one batch.
+     *
+     * Returns logit-diff scores (`logit("yes") - logit("no")`, unbounded) in
+     * input order. This is the log-odds of the reranker's ABSOLUTE yes/no
+     * relevance judgment — `P(yes) = sigmoid(score)`, so 0 ≡ P 0.5 — the
+     * monotone equivalent of the official Qwen3-Reranker two-token softmax.
+     * Scores are thresholdable and comparable across queries to the extent of
+     * the model's calibration (quantization adds noise at the extremes).
+     */
+    scoreBatch(query: string, texts: string[]): Promise<number[]>;
+    /** Pre-tokenize chunks for subsequent scoring calls. */
+    tokenizeChunks(chunks: Chunk[]): Promise<void>;
+    /**
+     * Tokenize an arbitrary text string through the reranker's tokenizer.
+     * Use when consumers need to operate on tokens from the same vocabulary
+     * as the chunks (e.g. BM25 first-stage scoring at query time).
+     */
+    tokenize(text: string): Promise<number[]>;
+    /** Release reranker resources. */
+    dispose(): void;
+}
+//# sourceMappingURL=chunk.d.ts.map

package/dist/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../src/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IACnE;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9D,wDAAwD;IACxD,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/chunk.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Chunk / Reranker abstraction types.
+ *
+ * These interfaces live in `@lloyal-labs/lloyal-agents` (not rig) so that
+ * agent-pool code, app factories, and harness contexts can refer to a
+ * common Reranker shape without depending on rig's concrete chunking
+ * implementation. Concrete chunking utilities (`chunkResources`,
+ * `chunkHtml`, `chunkFetchedPages`) and the cross-encoder-backed
+ * `createReranker(...)` factory live in `@lloyal-labs/rig`.
+ *
+ * The pattern mirrors `Source` and `Tool`: abstract type in agents,
+ * concrete subclasses/factories in rig.
+ *
+ * @packageDocumentation
+ * @category Contract
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=chunk.js.map

package/dist/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../src/chunk.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/context.d.ts

@@ -1,9 +1,13 @@
 import type { SessionContext } from '@lloyal-labs/sdk';
-import type { BranchStore, Branch } from '@lloyal-labs/sdk';
+import type { BranchStore } from '@lloyal-labs/sdk';
 import type { Channel } from 'effection';
 import type { AgentEvent } from './types';
 import type { TraceWriter } from './trace-writer';
 import type { Agent, FormatConfig } from './Agent';
+import type { Reranker } from './chunk';
+import type { AppRegistry } from './app-types';
+import type { AppConfigStore } from './app-config';
+import type { GrantStore } from './grant-store';
 /**
  * Effection context holding the active {@link SessionContext}
  *
@@ -51,17 +55,6 @@ export declare const Trace: import("effection").Context<TraceWriter>;
  * @category Agents
  */
 export declare const TraceParent: import("effection").Context<number>;
-/**
- * Effection context holding the scratchpad fork parent branch
- *
- * Set by {@link withSpine} to the current spine branch. Tools that
- * need scratchpad extraction (e.g. BufferingFetchPage, BufferingWebSearch)
- * read this via `yield* ScratchpadParent.expect()` to fork from the
- * innermost active spine — never a stale reference from a prior scope.
- *
- * @category Agents
- */
-export declare const ScratchpadParent: import("effection").Context<Branch>;
 /**
  * Effection context holding the calling agent during DISPATCH
  *
@@ -93,4 +86,67 @@ export declare const CallingAgent: import("effection").Context<Agent>;
  * @category Agents
  */
 export declare const SpineFmt: import("effection").Context<FormatConfig | null>;
+/**
+ * Effection context holding the harness-wide {@link Reranker}.
+ *
+ * Set by the harness once via `RerankerCtx.set(reranker)` after
+ * `createReranker(...)`. App factories (`createWebApp`, `createCorpusApp`,
+ * third-party apps) read this via `yield* RerankerCtx.expect()` at
+ * construction time and pass it to their `Source` / search tools.
+ *
+ * Replaces the per-source `source.bind({reranker})` pattern — chunks
+ * tokenized by one reranker can't be re-bound to another without
+ * re-tokenization, so one cross-encoder per harness
+ * is the invariant.
+ *
+ * @category Contract
+ */
+export declare const RerankerCtx: import("effection").Context<Reranker>;
+/**
+ * Effection context holding the {@link AppRegistry}.
+ *
+ * Set by `createAppRegistry(...)` (lives in `@lloyal-labs/rig`). The
+ * scope-guard reads this at tool-dispatch time to resolve
+ * the allowed-tools set for an App-assigned spawn — looking up
+ * `registry.byName(spawn.assignedApp)` and matching the dispatched
+ * `toolName` against `manifest.protocol.tools`.
+ *
+ * The spine renderer also reads this to compose the catalog in
+ * registration order.
+ *
+ * @category Contract
+ */
+export declare const AppRegistryCtx: import("effection").Context<AppRegistry>;
+/**
+ * Effection context holding the harness's {@link AppConfigStore}.
+ *
+ * Set by `createAppRegistry({ configStore })` from its `configStore`
+ * option, and seeded into each app's detached scope so factories can
+ * read it. App factories read their own config via
+ * `(yield* AppConfigStoreCtx.expect()).get(manifest.name)` at
+ * construction time. The framework validates the stored config against
+ * `app.manifest.configSchema` when the app is enabled.
+ *
+ * Whole-replace semantics on `set`; last-write-wins on concurrent
+ * writes.
+ *
+ * @category Contract
+ */
+export declare const AppConfigStoreCtx: import("effection").Context<AppConfigStore>;
+/**
+ * Effection context holding the session's {@link GrantStore}.
+ *
+ * Seeded by `createAppRegistry({ grantStore })` (lives in `@lloyal-labs/rig`)
+ * alongside {@link AppConfigStoreCtx}. The authGuard
+ * reads it once per pool to resolve which `protected` tools the session is
+ * authorized to call — `protected` tools without a grant reject at dispatch
+ * time (`tool:authReject`). The store holds the consent decision; the
+ * **credential never enters the model's context**.
+ *
+ * Absent context = fail-closed: no grants, every protected tool denied.
+ * Open (non-protected) tools never consult it.
+ *
+ * @category Contract
+ */
+export declare const GrantStoreCtx: import("effection").Context<GrantStore>;
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG,6CAA8C,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,0CAA6C,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,wDAA4D,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,0CAA6C,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,qCAA+C,CAAC;AAExE;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,qCAAmD,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,oCAA8C,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,kDAA8D,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAU,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG,6CAA8C,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,0CAA6C,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,wDAA4D,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,0CAA6C,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,qCAA+C,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,oCAA8C,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,kDAA8D,CAAC;AAEpF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,uCAA6C,CAAC;AAEtE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,0CAAmD,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,6CAAyD,CAAC;AAExF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,yCAAiD,CAAC"}