Lookup

It admits a fact only when you would look it up mid-task and could not derive it: a signature, an enumeration, a named constant, a threshold, a floor. Everything explaining why stays in the guides; the CLI surface stays in the lloyal-ai README. Each entry names the file it came from — read that file when the two disagree.

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 three roles, and exploit mode is a fourth use of the first: admitChunks scores against the original query with scoreEntailmentBatch and ranks by min(local, original). 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[]>;
  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.

The <Instruct> sentence is bound at construction, not per call. createReranker takes it, and every Ability sharing that instance asks the same question.

interface RerankInstruction {
  readonly text: string;
  readonly smokeTest: 'none' | {
    readonly query: string;
    readonly matching: string;
    readonly nonMatching: string;
    readonly minGap: number;
  };
}

Three gates run at create(). "yes" and "no" must each tokenise to exactly one token; a rendered probe must confirm the tokenizer did not merge across the prompt’s segment seams; and matching must outscore nonMatching by more than minGap, which must be finite and non-negative. Fixtures longer than the per-leaf document budget are rejected, not truncated. smokeTest: 'none' skips the third gate only — the seam probe still runs, against the retrieval fixture.

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/rig/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

From a symptom to the trace event that explains it: Debug with traces.

Where things live

The current home of each symbol a harness imports, checked against the packages' exports on 2026-09-30.

Prompt templates live in src/harness/prompts/ — Eta files, read again on every render, so an edit reaches the next question with no restart. See Prompts.

Continue

• Build your first harness
• Thinking in Lloyal
• harness.yml
• Adaptive compute
• lloyal-ai CLI
• Abilities catalogue
• HDK source