Lookup

Runtime and hardware

Node 24 or newer, declared by the CLI and by every scaffolded project. 16 GB of RAM or unified memory is the working recommendation: the recommended trunk model is 2.6 GB of weights, the research template adds a 630 MB reranker, and the remainder covers KV at the recommended 32k context plus the OS and whichever surface is running.

packages/rig/src/models.ts

Concurrent agents do not multiply this. They share one context, so cost tracks KV fullness, not agent count — four agents is not four times the model.

Retrieval and scoring

One cross-encoder serves four roles. Three different queries are in play — the per-call tool query, the per-agent task, and the original research query — and conflating them produces wrong scores.

interface EntailmentScorer {
  scoreEntailmentBatch(texts: string[]): Promise<number[]>;
  scoreRelevanceBatch(texts: string[], localQuery: string): Promise<number[]>;
  scoreSimilarityBatch(reference: string, texts: string[]): Promise<number[]>;
  shouldProceed(score: number): boolean;
}

interface ScorerReranker {
  scoreBatch(query: string, texts: string[]): Promise<number[]>;
}

The score is a logit-diff — logit(yes) − logit(no), unbounded, with the sign carrying the meaning. Source._entailmentFloor defaults to 0: a hit passes when the cross-encoder leans yes. Raise it for noise-heavy corpora, lower it for sparse ones.

abstract class Source<TCtx = unknown, TChunk = unknown> {
  abstract readonly name: string;
  abstract get tools(): Tool[];
  protected _reranker: ScorerReranker | null;
  protected _entailmentFloor: number;          // default 0
  createScorer(originalQuery: string): EntailmentScorer;
  promptData(): Record<string, unknown>;
  getChunks(): TChunk[];
}

promptData() is what the per-spawn skill template reads, so an agent learns what kind of source it holds before it searches.

packages/agents/src/source.ts

Consent and protected tools

The gate for consequential actions runs at DISPATCH, inside the agent runtime — below any application or interface code that could misreport it.

interface GrantStore {
  has(toolName: string): Operation<boolean>;
  grant(toolName: string): Operation<void>;
  revoke(toolName: string): Operation<void>;
}

GrantStoreCtx  // createContext<GrantStore>('lloyal.grantStore')

Fail-closed. A tool marked protected is denied unless the session holds a grant, and no grant store configured means every protected tool is denied. Credentials never enter the model's context — the model can trigger a gated call, never see or replay the secret.

packages/agents/src/grant-store.ts · context.ts

Trace events

Pass a writer to initAgents to capture the inference graph as newline-delimited JSON. With none passed, NullTraceWriter makes every trace call a no-op at zero cost. Events form a tree through parentTraceId; the TraceParent context connects inner pools to the tool dispatch that spawned them without manual wiring.

packages/agents/src/trace-types.ts — the full event union

Six failure modes

Start from the symptom; the trace answers the rest.

Where things live

Wrong import paths were the single most common staleness in older material. These are the current homes.

Prompt templates live in prompts/ beside the harness — .eta for templates with conditionals, loaded as raw strings at startup and rendered at call time.