@eir-labs/coltrane 0.4.0

package/dist/src/test_honest_broker.d.ts

@@ -0,0 +1,34 @@
+export interface DivergenceReport {
+    path: string;
+    primary: string;
+    secondary: string;
+    reason: string;
+}
+export interface HonestBrokerComparison<T> {
+    primary: T;
+    secondary: T;
+    agreement: boolean;
+    divergence: DivergenceReport | null;
+}
+export type Comparator<T> = (a: T, b: T) => boolean;
+/**
+ * Walk two JSON-serialisable values in parallel. Returns null when structurally
+ * equal, or a DivergenceReport pinpointing the first mismatch. Arrays are
+ * length-checked then compared positionally; objects are key-set-checked then
+ * compared by key. Primitives use strict equality (NaN is treated as unequal).
+ */
+export declare function findDivergence(a: unknown, b: unknown, path?: string): DivergenceReport | null;
+/**
+ * Run two independent code paths that should produce the same result under the
+ * same contract; compare structurally. The comparator defaults to deep
+ * structural equality on JSON-serialisable objects. When a custom comparator is
+ * supplied, the DivergenceReport will still be produced via findDivergence so
+ * the failure is locatable.
+ */
+export declare function compareHonestBroker<T>(primary: () => Promise<T> | T, secondary: () => Promise<T> | T, comparator?: Comparator<T>): Promise<HonestBrokerComparison<T>>;
+/**
+ * Returns a new object with the named keys removed RECURSIVELY at any depth.
+ * Used to scrub volatile fields (uuids, timestamps, derived fingerprints)
+ * before comparison so two structurally-equivalent runs match.
+ */
+export declare function scrubKeys<T>(value: T, keys: readonly string[]): T;

package/dist/src/test_honest_broker.js

@@ -0,0 +1,155 @@
+// Independent re-measurement layer. For a given contract, run the primary code
+// path and a secondary code path that exercises the SAME contract via a different
+// route, then compare. Agreement = the contract holds across both paths; a
+// divergence is an honest finding — either the public API does work the raw path
+// skips, or the underlying schema is under-specified.
+//
+// Used by tests under tests/honest_broker/. The comparator scrubs known volatile
+// keys (uuids, timestamps, fingerprints derived from uuids) so two structurally
+// equivalent runs match; surviving differences are real.
+const MAX_VALUE_LEN = 200;
+function truncate(v) {
+    let s;
+    try {
+        s = typeof v === "string" ? v : JSON.stringify(v);
+    }
+    catch {
+        s = String(v);
+    }
+    if (s.length > MAX_VALUE_LEN)
+        s = s.slice(0, MAX_VALUE_LEN) + "…";
+    return s;
+}
+/**
+ * Walk two JSON-serialisable values in parallel. Returns null when structurally
+ * equal, or a DivergenceReport pinpointing the first mismatch. Arrays are
+ * length-checked then compared positionally; objects are key-set-checked then
+ * compared by key. Primitives use strict equality (NaN is treated as unequal).
+ */
+export function findDivergence(a, b, path = "$") {
+    if (a === b)
+        return null;
+    // both null/undefined catch-all
+    if (a === null || b === null || a === undefined || b === undefined) {
+        return {
+            path,
+            primary: truncate(a),
+            secondary: truncate(b),
+            reason: `null/undefined on one side`,
+        };
+    }
+    const ta = typeof a;
+    const tb = typeof b;
+    if (ta !== tb) {
+        return {
+            path,
+            primary: truncate(a),
+            secondary: truncate(b),
+            reason: `type mismatch: ${ta} vs ${tb}`,
+        };
+    }
+    if (ta !== "object") {
+        return {
+            path,
+            primary: truncate(a),
+            secondary: truncate(b),
+            reason: `value mismatch (${ta})`,
+        };
+    }
+    const aArr = Array.isArray(a);
+    const bArr = Array.isArray(b);
+    if (aArr !== bArr) {
+        return {
+            path,
+            primary: truncate(a),
+            secondary: truncate(b),
+            reason: `one side is array, other is object`,
+        };
+    }
+    if (aArr && bArr) {
+        const arrA = a;
+        const arrB = b;
+        if (arrA.length !== arrB.length) {
+            return {
+                path,
+                primary: `length=${arrA.length}`,
+                secondary: `length=${arrB.length}`,
+                reason: `array length mismatch`,
+            };
+        }
+        for (let i = 0; i < arrA.length; i++) {
+            const d = findDivergence(arrA[i], arrB[i], `${path}[${i}]`);
+            if (d)
+                return d;
+        }
+        return null;
+    }
+    const objA = a;
+    const objB = b;
+    const keysA = Object.keys(objA).sort();
+    const keysB = Object.keys(objB).sort();
+    if (keysA.length !== keysB.length || keysA.some((k, i) => k !== keysB[i])) {
+        const onlyA = keysA.filter((k) => !keysB.includes(k));
+        const onlyB = keysB.filter((k) => !keysA.includes(k));
+        return {
+            path,
+            primary: `keys: ${keysA.join(",")}`,
+            secondary: `keys: ${keysB.join(",")}`,
+            reason: `key-set mismatch (only-primary: [${onlyA.join(",")}], only-secondary: [${onlyB.join(",")}])`,
+        };
+    }
+    for (const k of keysA) {
+        const d = findDivergence(objA[k], objB[k], `${path}.${k}`);
+        if (d)
+            return d;
+    }
+    return null;
+}
+/**
+ * Run two independent code paths that should produce the same result under the
+ * same contract; compare structurally. The comparator defaults to deep
+ * structural equality on JSON-serialisable objects. When a custom comparator is
+ * supplied, the DivergenceReport will still be produced via findDivergence so
+ * the failure is locatable.
+ */
+export async function compareHonestBroker(primary, secondary, comparator) {
+    const primaryResult = await primary();
+    const secondaryResult = await secondary();
+    const cmp = comparator ?? (defaultDeepEqual);
+    const agreement = cmp(primaryResult, secondaryResult);
+    const divergence = agreement
+        ? null
+        : findDivergence(primaryResult, secondaryResult);
+    return {
+        primary: primaryResult,
+        secondary: secondaryResult,
+        agreement,
+        divergence,
+    };
+}
+function defaultDeepEqual(a, b) {
+    return findDivergence(a, b) === null;
+}
+/**
+ * Returns a new object with the named keys removed RECURSIVELY at any depth.
+ * Used to scrub volatile fields (uuids, timestamps, derived fingerprints)
+ * before comparison so two structurally-equivalent runs match.
+ */
+export function scrubKeys(value, keys) {
+    const skip = new Set(keys);
+    function walk(v) {
+        if (v === null || typeof v !== "object")
+            return v;
+        if (Array.isArray(v))
+            return v.map(walk);
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            if (skip.has(k))
+                continue;
+            out[k] = walk(val);
+        }
+        return out;
+    }
+    return walk(value);
+}
+//# sourceMappingURL=test_honest_broker.js.map

package/dist/src/test_honest_broker.js.map

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

package/dist/src/test_topology.d.ts

@@ -0,0 +1,22 @@
+export type ContextSizeClass = "small" | "medium" | "large" | "overflow";
+export type PersonaClass = "backend-eng" | "oss-maintainer" | "security-eng" | "fresh-contributor" | "non-engineer-tash-shape";
+export interface SubThreadState {
+    parent_turn: number;
+    child_turn: number;
+    context_size_class: ContextSizeClass;
+    persona_class: PersonaClass;
+}
+export interface Transition {
+    from: SubThreadState;
+    to: SubThreadState;
+    kind: "spawn" | "resume" | "context-overflow" | "persona-switch";
+}
+export declare function buildStateSpace(maxParentTurns: number, maxChildTurns: number): SubThreadState[];
+export declare function equivalenceClasses(states: SubThreadState[]): SubThreadState[][];
+export declare function selectRepresentatives(classes: SubThreadState[][]): SubThreadState[];
+export declare function coverageReport(allClasses: SubThreadState[][], testedStates: SubThreadState[]): {
+    covered: number;
+    total: number;
+    missing: SubThreadState[][];
+};
+export declare function adjacentTransitions(states: SubThreadState[]): Transition[];

package/dist/src/test_topology.js

@@ -0,0 +1,137 @@
+// Topology-based test-coverage helper for sub-thread state-space tests.
+// Saves compute by collapsing the full (parent_turn x child_turn x context_size x persona)
+// product into equivalence classes, then picking 1-2 representatives per class
+// instead of running every multi-turn flow exhaustively.
+const PERSONA_CLASSES = [
+    "backend-eng",
+    "oss-maintainer",
+    "security-eng",
+    "fresh-contributor",
+    "non-engineer-tash-shape",
+];
+// Map child_turn -> context_size_class by accumulation bound.
+// Bands cumulative tokens by integer turn count; overflow at the last threshold.
+function contextSizeForTurn(childTurn) {
+    if (childTurn <= 2)
+        return "small";
+    if (childTurn <= 5)
+        return "medium";
+    if (childTurn <= 8)
+        return "large";
+    return "overflow";
+}
+// Enumerate all reachable sub-thread states up to the given bounds.
+// A state is reachable if there is some parent_turn in [0, maxParentTurns]
+// and child_turn in [0, maxChildTurns] paired with a persona; context_size_class
+// follows from child_turn under the accumulation model above.
+export function buildStateSpace(maxParentTurns, maxChildTurns) {
+    if (maxParentTurns < 0 || maxChildTurns < 0) {
+        throw new Error(`buildStateSpace bounds must be non-negative; got parent=${maxParentTurns}, child=${maxChildTurns}`);
+    }
+    const states = [];
+    for (let p = 0; p <= maxParentTurns; p++) {
+        for (let c = 0; c <= maxChildTurns; c++) {
+            const ctx = contextSizeForTurn(c);
+            for (const persona of PERSONA_CLASSES) {
+                states.push({
+                    parent_turn: p,
+                    child_turn: c,
+                    context_size_class: ctx,
+                    persona_class: persona,
+                });
+            }
+        }
+    }
+    return states;
+}
+// Two states are equivalent modulo (context_size_class, child_turn % 3, persona_class).
+function classKey(s) {
+    return `${s.context_size_class}|${s.child_turn % 3}|${s.persona_class}`;
+}
+export function equivalenceClasses(states) {
+    const buckets = new Map();
+    for (const s of states) {
+        const k = classKey(s);
+        const existing = buckets.get(k);
+        if (existing) {
+            existing.push(s);
+        }
+        else {
+            buckets.set(k, [s]);
+        }
+    }
+    // Stable iteration order by insertion.
+    return Array.from(buckets.values());
+}
+// Pick 1-2 representatives per class.
+// Centroid: the median-child_turn member of the class.
+// Boundary: the maximum-parent_turn member.
+// If the class is singleton, return just the centroid.
+export function selectRepresentatives(classes) {
+    const reps = [];
+    for (const cls of classes) {
+        if (cls.length === 0)
+            continue;
+        const sorted = [...cls].sort((a, b) => a.child_turn - b.child_turn);
+        const centroidIdx = Math.floor(sorted.length / 2);
+        const centroid = sorted[centroidIdx];
+        if (!centroid)
+            continue;
+        reps.push(centroid);
+        if (cls.length > 1) {
+            const boundary = [...cls].sort((a, b) => b.parent_turn - a.parent_turn)[0];
+            if (boundary && !sameState(boundary, centroid)) {
+                reps.push(boundary);
+            }
+        }
+    }
+    return reps;
+}
+function sameState(a, b) {
+    return (a.parent_turn === b.parent_turn &&
+        a.child_turn === b.child_turn &&
+        a.context_size_class === b.context_size_class &&
+        a.persona_class === b.persona_class);
+}
+// Coverage report: which classes are exercised by `testedStates`, which are missed.
+export function coverageReport(allClasses, testedStates) {
+    const testedKeys = new Set();
+    for (const s of testedStates)
+        testedKeys.add(classKey(s));
+    const missing = [];
+    let covered = 0;
+    for (const cls of allClasses) {
+        const first = cls[0];
+        if (!first)
+            continue;
+        if (testedKeys.has(classKey(first))) {
+            covered += 1;
+        }
+        else {
+            missing.push(cls);
+        }
+    }
+    return { covered, total: allClasses.length, missing };
+}
+// Optional convenience: enumerate transitions between adjacent states.
+// Not required by the public spec, but cheap to expose for downstream graph use.
+export function adjacentTransitions(states) {
+    const ts = [];
+    for (let i = 0; i < states.length - 1; i++) {
+        const from = states[i];
+        const to = states[i + 1];
+        if (!from || !to)
+            continue;
+        let kind = "resume";
+        if (from.persona_class !== to.persona_class)
+            kind = "persona-switch";
+        else if (from.context_size_class !== "overflow" &&
+            to.context_size_class === "overflow")
+            kind = "context-overflow";
+        else if (to.child_turn === 0)
+            kind = "spawn";
+        ts.push({ from, to, kind });
+    }
+    return ts;
+}
+//# sourceMappingURL=test_topology.js.map

package/dist/src/test_topology.js.map

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

package/dist/src/tones.d.ts

@@ -0,0 +1,20 @@
+export declare const TONES: readonly ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+export declare const N_TONES = 12;
+export type Tone = number;
+export type Chord = readonly Tone[];
+export declare function toneName(t: Tone): string;
+export declare function intervalClass(a: Tone, b: Tone): number;
+export declare function intervalConsonance(a: Tone, b: Tone): number;
+export type Arity = "silent" | "monotonic" | "bitonic" | "tritonic" | "tetratonic" | "pentatonic" | "polyphonic";
+export declare function classifyArity(toneCount: number): Arity;
+export declare function chordArity(chord: Chord): Arity;
+export declare function chordConsonance(chord: Chord): number;
+export declare function chordTension(chord: Chord): number;
+export interface Resolution {
+    resolves: boolean;
+    tonic: Tone | null;
+    finalConsonance: number;
+    tensionProfile: number[];
+    tensionDropped: boolean;
+}
+export declare function resolve(progression: readonly Chord[]): Resolution;

package/dist/src/tones.js

@@ -0,0 +1,81 @@
+// Song-substrate CORE — the 12 chromatic tones, additive chords, arity (the
+// monotonic…polyphonic primitives = tone-count), interval consonance, and
+// resolution. This is ONE channel's read (the song). Per the directive: it returns
+// STRUCTURE, never a scalar "truth" — the song is one vantage of three
+// (score · output · song); triangulation across them lives above this module.
+// Nothing here collapses to pass/fail; it emits the song-read's shape for the
+// tensor to couple against the other channels.
+export const TONES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+export const N_TONES = 12;
+export function toneName(t) {
+    return TONES[((t % N_TONES) + N_TONES) % N_TONES];
+}
+// Interval class (0..6) = the symmetric semitone distance. Consonance is grounded
+// in just-intonation ratios: unison/octave most consonant, tritone least.
+export function intervalClass(a, b) {
+    const d = Math.abs(a - b) % N_TONES;
+    return Math.min(d, N_TONES - d);
+}
+const IC_CONSONANCE = {
+    0: 1.0, // unison / octave (2:1)
+    5: 0.9, // perfect fifth / fourth (3:2, 4:3)
+    4: 0.7, // major third / minor sixth (5:4)
+    3: 0.6, // minor third / major sixth (6:5)
+    2: 0.35, // major second / minor seventh
+    1: 0.1, // minor second / major seventh
+    6: 0.05, // tritone
+};
+export function intervalConsonance(a, b) {
+    return IC_CONSONANCE[intervalClass(a, b)] ?? 0;
+}
+export function classifyArity(toneCount) {
+    switch (toneCount) {
+        case 0: return "silent";
+        case 1: return "monotonic";
+        case 2: return "bitonic";
+        case 3: return "tritonic";
+        case 4: return "tetratonic";
+        case 5: return "pentatonic";
+        default: return "polyphonic";
+    }
+}
+export function chordArity(chord) {
+    return classifyArity(new Set(chord.map((t) => ((t % N_TONES) + N_TONES) % N_TONES)).size);
+}
+// Chord consonance = the mean of pairwise interval consonances (additive over
+// pairs). A lone tone is maximally consonant (nothing clashes); silence is null.
+export function chordConsonance(chord) {
+    const ts = [...new Set(chord.map((t) => ((t % N_TONES) + N_TONES) % N_TONES))];
+    if (ts.length <= 1)
+        return 1.0;
+    let sum = 0, pairs = 0;
+    for (let i = 0; i < ts.length; i++) {
+        for (let j = i + 1; j < ts.length; j++) {
+            sum += intervalConsonance(ts[i], ts[j]);
+            pairs++;
+        }
+    }
+    return sum / pairs;
+}
+// Tension = the complement of consonance. A dissonant chord wants to resolve.
+export function chordTension(chord) {
+    return 1 - chordConsonance(chord);
+}
+const RESOLVE_CONSONANCE = 0.6; // a final chord at/above this is "at rest"
+export function resolve(progression) {
+    const tensionProfile = progression.map(chordTension);
+    if (progression.length === 0) {
+        return { resolves: false, tonic: null, finalConsonance: 0, tensionProfile, tensionDropped: false };
+    }
+    const last = progression[progression.length - 1];
+    const finalConsonance = chordConsonance(last);
+    const tensionDropped = progression.length >= 2
+        ? tensionProfile[tensionProfile.length - 2] > tensionProfile[tensionProfile.length - 1]
+        : true; // a lone consonant chord is trivially at rest
+    const tonic = last.length ? [...last].sort((a, b) => a - b)[0] : null;
+    return {
+        resolves: finalConsonance >= RESOLVE_CONSONANCE && tensionDropped,
+        tonic, finalConsonance, tensionProfile, tensionDropped,
+    };
+}
+//# sourceMappingURL=tones.js.map

package/dist/src/tones.js.map

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

package/dist/src/tool_providers.d.ts

@@ -0,0 +1,45 @@
+/** How a granted tool name resolves to something runnable. */
+export interface ToolProvider {
+    tool: string;
+    kind: "mcp" | "in_house";
+    /** the MCP server slug that hosts this tool (multiple tools may share one server). For kind "mcp"
+     *  it's the external server; for kind "in_house" it's the engine's own server (#204), through which
+     *  the tool is bridged and under whose mcp__<server>__ prefix it is advertised. */
+    server?: string;
+    /** for kind "mcp": the server's --mcp-config entry (command/args/env/url). */
+    config?: Record<string, unknown>;
+}
+export type ToolProviderRegistry = ReadonlyMap<string, ToolProvider>;
+/** The engine's own MCP server slug — the key the repo's .mcp.json ships it under, and the prefix
+ *  its tools are advertised behind (mcp__coltrane__<tool>). In-house engine tools are bridged through
+ *  this server, so an in-house grant resolves to it (#204). */
+export declare const ENGINE_MCP_SERVER = "coltrane";
+/** A scoped grant like `Bash(npx vitest run:*)` resolves on its base tool name (`Bash`). */
+export declare function toolBaseName(grant: string): string;
+export interface ResolvedGrants {
+    /** MCP server slug → its --mcp-config entry, deduped across all grants that share a server. */
+    mcpServers: Record<string, unknown>;
+    /** in-house runtime tools the spawn should expose. */
+    inHouse: string[];
+    /** grants with no resolvable provider — dead names. Dispatch must refuse these. */
+    unknown: string[];
+    /** the grants as the SPAWN will see them, to feed --allowedTools (NOT the raw allowed_tools).
+     *  Host-builtins and `mcp__<server>__*` grants pass through unchanged; a registry tool that
+     *  resolves to an MCP server — INCLUDING an in-house engine tool bridged through the engine's own
+     *  server — is namespaced to `mcp__<server>__<tool>`, because that is the name the server actually
+     *  advertises. A bare slug (e.g. `output_write`) in --allowedTools matches nothing and the agent
+     *  can't seal — #204. An in-house tool with no engine-server config keeps its bare name (no regression). */
+    effectiveAllowed: string[];
+}
+/** Claude Code MCP tools follow the `mcp__<server>__<tool>` naming convention. Extract the server
+ *  slug so an MCP grant resolves to its server by convention — no per-tool registration needed. */
+export declare function mcpServerOf(grant: string): string | null;
+/** Resolve an agent's allowed_tools to providers. In order: a host-builtin passes (no server); an
+ *  explicit registry entry wins; an `mcp__<server>__*` grant resolves by convention to that server's
+ *  config from `mcpServerConfigs` (deployment-registered; coltrane ships its own); everything else —
+ *  including an MCP grant for an unconfigured server — is `unknown` (a dead name). */
+export declare function resolveToolGrants(allowed: readonly string[], registry: ToolProviderRegistry, mcpServerConfigs?: Readonly<Record<string, unknown>>): ResolvedGrants;
+/** Fail closed: an agent that grants an unresolvable tool must not be dispatched — a granted tool
+ *  with no provider is indistinguishable from a real one until the agent tries (and fails) to call
+ *  it. Raising here at dispatch surfaces it as a clear error instead of a confabulated answer. */
+export declare function assertToolGrantsResolvable(agentSlug: string, allowed: readonly string[], registry: ToolProviderRegistry, mcpServerConfigs?: Readonly<Record<string, unknown>>): ResolvedGrants;

package/dist/src/tool_providers.js

@@ -0,0 +1,104 @@
+// Tool-grant → provider resolution (#185). An agent's `allowed_tools` is a set of grants, each of
+// which resolves to one of three provider classes:
+//   - host-builtin (Read/Write/Edit/Bash/Glob/Grep/WebFetch/WebSearch/…): provided by the Claude
+//     runtime, governed by --allowedTools + code_tool_access. No MCP server needed.
+//   - mcp: provided by an MCP server (e.g. a browser server) that must be wired into the spawn's
+//     --mcp-config. The OSS engine ships this RESOLUTION machinery; a deployment registers the
+//     actual server config (the server itself is deployment-provided).
+//   - in_house: a runtime primitive (e.g. output_write) the engine provides directly.
+// A grant that resolves to NONE of these is a DEAD NAME — the prompt lists a tool the spawn can't
+// provide, so the model confabulates. resolveToolGrants surfaces those as `unknown` so dispatch can
+// fail closed instead of launching a spawn that advertises tools it cannot back.
+// Host-builtin Claude Code tools — provided by the runtime, not an MCP server. Grants are governed
+// by --allowedTools + code_tool_access; they never need a provider entry and are never "unknown".
+const HOST_BUILTINS = new Set([
+    "Read", "Write", "Edit", "MultiEdit", "NotebookEdit",
+    "Bash", "BashOutput", "KillShell",
+    "Glob", "Grep", "LS",
+    "WebFetch", "WebSearch",
+    "Task", "TodoWrite",
+]);
+/** The engine's own MCP server slug — the key the repo's .mcp.json ships it under, and the prefix
+ *  its tools are advertised behind (mcp__coltrane__<tool>). In-house engine tools are bridged through
+ *  this server, so an in-house grant resolves to it (#204). */
+export const ENGINE_MCP_SERVER = "coltrane";
+/** A scoped grant like `Bash(npx vitest run:*)` resolves on its base tool name (`Bash`). */
+export function toolBaseName(grant) {
+    const paren = grant.indexOf("(");
+    return (paren >= 0 ? grant.slice(0, paren) : grant).trim();
+}
+/** Claude Code MCP tools follow the `mcp__<server>__<tool>` naming convention. Extract the server
+ *  slug so an MCP grant resolves to its server by convention — no per-tool registration needed. */
+export function mcpServerOf(grant) {
+    const m = toolBaseName(grant).match(/^mcp__(.+?)__/);
+    return m ? m[1] : null;
+}
+/** Resolve an agent's allowed_tools to providers. In order: a host-builtin passes (no server); an
+ *  explicit registry entry wins; an `mcp__<server>__*` grant resolves by convention to that server's
+ *  config from `mcpServerConfigs` (deployment-registered; coltrane ships its own); everything else —
+ *  including an MCP grant for an unconfigured server — is `unknown` (a dead name). */
+export function resolveToolGrants(allowed, registry, mcpServerConfigs = {}) {
+    const mcpServers = {};
+    const inHouse = [];
+    const unknown = [];
+    const effectiveAllowed = [];
+    for (const grant of allowed) {
+        const base = toolBaseName(grant);
+        if (HOST_BUILTINS.has(base)) {
+            effectiveAllowed.push(grant); // builtins pass through with their scoping intact
+            continue;
+        }
+        const prov = registry.get(base);
+        if (prov) {
+            if (prov.kind === "mcp" && prov.server) {
+                if (prov.config !== undefined)
+                    mcpServers[prov.server] = prov.config;
+                effectiveAllowed.push(`mcp__${prov.server}__${base}`); // the name the server advertises
+            }
+            else if (prov.kind === "in_house") {
+                inHouse.push(base);
+                // #204 — an in-house engine tool is bridged through the engine's OWN MCP server. Resolving
+                // it as a "runtime primitive" left the server out of the spawn's mcp-config AND advertised
+                // the bare slug, which the server's namespaced surface never matched — so the agent could
+                // never call it (drafts emitted as text, nothing sealed). Wire the engine server in and name
+                // the tool the way the server exposes it. No engine-server config → keep the bare name.
+                if (prov.server && Object.prototype.hasOwnProperty.call(mcpServerConfigs, prov.server)) {
+                    mcpServers[prov.server] = mcpServerConfigs[prov.server];
+                    effectiveAllowed.push(`mcp__${prov.server}__${base}`);
+                }
+                else {
+                    effectiveAllowed.push(base);
+                }
+            }
+            else {
+                effectiveAllowed.push(grant);
+            }
+            continue;
+        }
+        const server = mcpServerOf(base);
+        if (server) {
+            if (Object.prototype.hasOwnProperty.call(mcpServerConfigs, server)) {
+                mcpServers[server] = mcpServerConfigs[server];
+                effectiveAllowed.push(grant); // already in mcp__<server>__<tool> form
+            }
+            else {
+                unknown.push(grant); // an MCP tool whose server has no registered config — a dead name
+            }
+            continue;
+        }
+        unknown.push(grant);
+    }
+    return { mcpServers, inHouse, unknown, effectiveAllowed };
+}
+/** Fail closed: an agent that grants an unresolvable tool must not be dispatched — a granted tool
+ *  with no provider is indistinguishable from a real one until the agent tries (and fails) to call
+ *  it. Raising here at dispatch surfaces it as a clear error instead of a confabulated answer. */
+export function assertToolGrantsResolvable(agentSlug, allowed, registry, mcpServerConfigs = {}) {
+    const resolved = resolveToolGrants(allowed, registry, mcpServerConfigs);
+    if (resolved.unknown.length > 0) {
+        throw new Error(`agent "${agentSlug}" grants unresolvable tool(s) [${resolved.unknown.join(", ")}] — no provider registered ` +
+            `(a granted tool with no provider is a dead name; register a provider or remove the grant)`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=tool_providers.js.map

package/dist/src/tool_providers.js.map

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