indusagi-coding-agent 0.2.8 → 0.2.10

package/src/briefing/index.ts

@@ -0,0 +1,31 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Briefing subsystem — public barrel.
+ *
+ * Re-exports the FROZEN prompt-and-presentation contract: the declarative
+ * system-prompt pipeline ({@link BriefingSection} over a {@link BriefingContext},
+ * composed by `composeBriefing`), the single-pass `$arg` macro model
+ * ({@link Macro}, {@link MacroScope}, {@link MacroToken}), the Agent-Skills
+ * capability cards ({@link SkillCard} parsed from a `SKILL.md`), the table-driven
+ * SGR machine ({@link SgrState}, {@link SgrToken}, {@link SgrMutation}), and the
+ * HTML-transcript color layer ({@link ExportTheme} behind a {@link ThemeBridge}
+ * with a {@link LuminanceLut}) plus the publish surface.
+ *
+ * Behavior modules land in this barrel as they are written. Currently exported:
+ * the declarative section composer (`composeBriefing` over `BRIEFING_SECTIONS`),
+ * the single-pass `$arg` macro scanner + loader (`loadMacros`, `applyMacros`,
+ * and friends), and the Agent-Skills capability-card loader (`loadSkillCards`,
+ * `gatherSkillCards`). The SGR painter, theme bridge, and transcript publisher
+ * are added here as they land. Consumers import the briefing surface from
+ * `src/briefing` rather than reaching into individual modules.
+ */
+export type { BriefingContext, BriefingSection, Briefing, BriefingInputs, SubagentBrief, ContextDoc, MacroOrigin, Macro, MacroScope, MacroTokenKind, MacroToken, SkillFrontmatter, SkillCard, SkillOutcomeKind, SkillDiagnostic, SkillLoad, SgrState, SgrToken, SgrMutation, ExportTheme, Rgb, LuminanceLut, ThemeMode, ThemeBridge, TranscriptPart, WidgetRender, PublishOptions, ShellSlot, BriefingFaultKind, BriefingFault, AgentState, AgentTool, TextContent, ImageContent, } from "./contract.js";
+export { SKILL_NAME_LIMIT, SKILL_DESCRIPTION_LIMIT, SGR_INITIAL_STATE, FALLBACK_EXPORT_THEME, SHELL_SLOTS, briefingFault, } from "./contract.js";
+export { BRIEFING_SECTIONS, composeBriefing, joinBlocks, bullets, escapeXml, TOOL_SUMMARIES } from "./compose.js";
+export { scanMacroBody, resolveTokens, applyMacros, buildMacroScope, expandInvocation, loadMacros, readMacroFile, splitFrontmatter, } from "./macros.js";
+export type { LoadMacrosOptions, FrontmatterSplit } from "./macros.js";
+export { loadSkillCards, gatherSkillCards, modelInvocableCards, } from "./skills.js";
+export type { SkillRoot } from "./skills.js";
+export { gatherContextDocs } from "./context-docs.js";
+export type { GatherContextDocsOptions } from "./context-docs.js";

package/src/briefing/macros.ts

@@ -0,0 +1,97 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { briefingFault } from "./contract.js";
+import type { Macro, MacroOrigin, MacroScope, MacroToken } from "./contract.js";
+
+export interface LoadMacrosOptions { readonly origin?: MacroOrigin; readonly label?: string; }
+export interface FrontmatterSplit { readonly frontmatter: Record<string, unknown>; readonly body: string; }
+
+const decimal = (ch: string): boolean => ch.charCodeAt(0) >= 48 && ch.charCodeAt(0) <= 57;
+const bareword = (ch: string): boolean => { const c = ch.charCodeAt(0); return (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c === 95; };
+export const LEGACY_ALL_BAREWORD = ["A", "R", "G", "U", "M", "E", "N", "T", "S"].join("");
+export const DERIVED_DESCRIPTION_BUDGET = 72;
+let legacyReporter: ((kind: string, source: string) => void) | undefined;
+
+export function setLegacyMacroReporter(fn: ((kind: string, source: string) => void) | undefined): void { legacyReporter = fn; }
+export function reportLegacyUsage(kind: string, source: string): void { legacyReporter?.(kind, source); }
+export function readNumber(text: string, i: number): { value: number; next: number } { let j = i; while (j < text.length && decimal(text[j])) j++; return { value: Number.parseInt(text.slice(i, j), 10), next: j }; }
+export function readBareword(text: string, i: number): number { let j = i; while (j < text.length && bareword(text[j])) j++; return j; }
+export function skipInlineSpace(text: string, i: number): number { let j = i; while (j < text.length && (text[j] === " " || text[j] === "\t")) j++; return j; }
+
+type Scan = { token: MacroToken; next: number };
+type LegacyScan = { token: MacroToken | null; literal?: string; next: number };
+
+export function scanMacroBody(body: string): MacroToken[] {
+  const tokens: MacroToken[] = []; let literal = ""; let i = 0;
+  const flush = (): void => { if (literal) { tokens.push({ kind: "literal", text: literal }); literal = ""; } };
+  while (i < body.length) {
+    const ch = body[i];
+    if (ch === "{" && body[i + 1] === "{") {
+      if (body[i + 2] === "{" && body[i + 3] === "{") { literal += "{{"; i += 4; continue; }
+      const parsed = scanIndusForm(body, i);
+      if (parsed) { flush(); tokens.push(parsed.token); i = parsed.next; continue; }
+    } else if (ch === "$") {
+      const parsed = scanLegacyForm(body, i);
+      if (parsed) { flush(); if (parsed.token) tokens.push(parsed.token); else literal += parsed.literal ?? ""; i = parsed.next; continue; }
+    }
+    literal += ch; i++;
+  }
+  flush(); return tokens;
+}
+
+export function scanIndusForm(text: string, start: number): Scan | null {
+  let i = skipInlineSpace(text, start + 2); if (text.slice(i, i + 4) !== "arg.") return null; i += 4;
+  const end = readBareword(text, i); const accessor = text.slice(i, end); i = end;
+  if (!accessor && decimal(text[i] ?? "")) { const num = readNumber(text, i); i = skipInlineSpace(text, num.next); return text[i] === "}" && text[i + 1] === "}" && num.value >= 1 ? { token: { kind: "positional", index: num.value }, next: i + 2 } : null; }
+  if (accessor === "all") { i = skipInlineSpace(text, i); return text[i] === "}" && text[i + 1] === "}" ? { token: { kind: "all" }, next: i + 2 } : null; }
+  if (accessor === "slice") {
+    i = skipInlineSpace(text, i); if (!decimal(text[i] ?? "")) return null; const startNum = readNumber(text, i); i = skipInlineSpace(text, startNum.next); let length: number | undefined;
+    if (decimal(text[i] ?? "")) { const len = readNumber(text, i); length = len.value; i = skipInlineSpace(text, len.next); }
+    if (text[i] !== "}" || text[i + 1] !== "}") return null;
+    return { token: length === undefined ? { kind: "slice", start: startNum.value } : { kind: "slice", start: startNum.value, length }, next: i + 2 };
+  }
+  if (accessor === "rest") { i = skipInlineSpace(text, i); let value = 2; if (decimal(text[i] ?? "")) { const num = readNumber(text, i); value = num.value; i = skipInlineSpace(text, num.next); } return text[i] === "}" && text[i + 1] === "}" ? { token: { kind: "slice", start: value }, next: i + 2 } : null; }
+  return null;
+}
+
+export function scanLegacyForm(text: string, start: number): LegacyScan | null {
+  const next = text[start + 1];
+  if (next === "$") return { token: null, literal: "$", next: start + 2 };
+  if (next && decimal(next)) { const num = readNumber(text, start + 1); if (num.value < 1) return null; reportLegacyUsage("positional", text.slice(start, num.next)); return { token: { kind: "positional", index: num.value }, next: num.next }; }
+  if (next === "@") { reportLegacyUsage("all", text.slice(start, start + 2)); return { token: { kind: "all" }, next: start + 2 }; }
+  if (next === "{") return scanLegacyBraceForm(text, start);
+  if (next && bareword(next)) { const end = readBareword(text, start + 1); if (text.slice(start + 1, end) === LEGACY_ALL_BAREWORD) { reportLegacyUsage("all", text.slice(start, end)); return { token: { kind: "all" }, next: end }; } }
+  return null;
+}
+
+export function scanLegacyBraceForm(text: string, start: number): LegacyScan | null {
+  let i = start + 2; if (text[i++] !== "@") return null;
+  if (text[i] === "}") { reportLegacyUsage("all", text.slice(start, i + 1)); return { token: { kind: "all" }, next: i + 1 }; }
+  if (text[i++] !== ":" || !decimal(text[i] ?? "")) return null; const startNum = readNumber(text, i); i = startNum.next; let length: number | undefined;
+  if (text[i] === ":") { i++; if (!decimal(text[i] ?? "")) return null; const len = readNumber(text, i); length = len.value; i = len.next; }
+  if (text[i] !== "}") return null; reportLegacyUsage("slice", text.slice(start, i + 1));
+  return { token: length === undefined ? { kind: "slice", start: startNum.value } : { kind: "slice", start: startNum.value, length }, next: i + 1 };
+}
+
+export function splitArguments(raw: string): string[] {
+  const out: string[] = []; let current = ""; let inWord = false; let quote: string | null = null;
+  for (const ch of raw) { if (quote) { if (ch === quote) quote = null; else current += ch; inWord = true; } else if (ch === '"' || ch === "'") { quote = ch; inWord = true; } else if (/\s/.test(ch)) { if (inWord) { out.push(current); current = ""; inWord = false; } } else { current += ch; inWord = true; } }
+  if (inWord) out.push(current); return out;
+}
+export function buildMacroScope(raw: string): MacroScope { const args = splitArguments(raw); return { args, all: args.join(" "), raw }; }
+export function resolveTokens(tokens: readonly MacroToken[], scope: MacroScope): string { return tokens.map((token) => { if (token.kind === "literal") return token.text; if (token.kind === "positional") return scope.args[token.index - 1] ?? ""; if (token.kind === "all") return scope.all; const from = Math.max(0, token.start - 1); return (token.length === undefined ? scope.args.slice(from) : scope.args.slice(from, from + Math.max(0, token.length))).join(" "); }).join(""); }
+export function applyMacros(body: string, raw: string): string { return resolveTokens(scanMacroBody(body), buildMacroScope(raw)); }
+export function firstSpaceIndex(value: string): number { for (let i = 0; i < value.length; i++) if (/\s/.test(value[i])) return i; return -1; }
+export function expandInvocation(line: string, macros: readonly Macro[]): string { if (!line.startsWith("/")) return line; const sliced = line.slice(1); const space = firstSpaceIndex(sliced); const name = space < 0 ? sliced : sliced.slice(0, space); const macro = macros.find((item) => item.name === name); return macro ? applyMacros(macro.body, space < 0 ? "" : sliced.slice(space + 1)) : line; }
+
+export function loadMacros(dir: string, opts: LoadMacrosOptions = {}): Macro[] {
+  const origin = opts.origin ?? "path"; const label = opts.label ?? origin; let entries: string[];
+  try { entries = readdirSync(dir); } catch { return []; }
+  const seen = new Set<string>(); const macros: Macro[] = [];
+  for (const entry of entries.sort()) { if (entry.startsWith(".") || !entry.toLowerCase().endsWith(".md")) continue; const path = join(dir, entry); try { if (!statSync(path).isFile()) continue; } catch { continue; } const macro = readMacroFile(path, origin, label); if (!seen.has(macro.name)) { seen.add(macro.name); macros.push(macro); } }
+  return macros;
+}
+export function readMacroFile(path: string, origin: MacroOrigin, label: string): Macro { let text: string; try { text = readFileSync(path, "utf8"); } catch (cause) { throw briefingFault("macro_invalid", `could not read macro file at ${path}`, cause); } const { frontmatter, body } = splitFrontmatter(text); const name = basename(path).replace(/\.md$/i, ""); const declared = typeof frontmatter.description === "string" ? frontmatter.description.trim() : ""; return { name, description: declared ? `${declared} (${label})` : deriveDescription(body, label), body, origin, source: path }; }
+export function deriveDescription(body: string, label: string): string { const first = body.split("\n").find((line) => line.trim())?.trim() ?? ""; const trimmed = first.length > DERIVED_DESCRIPTION_BUDGET ? `${first.slice(0, DERIVED_DESCRIPTION_BUDGET).trimEnd()}…` : first; return `${trimmed || "custom macro"} (${label})`; }
+export function splitFrontmatter(text: string): FrontmatterSplit { const lines = text.split("\n"); if (lines[0]?.trim() !== "---") return { frontmatter: {}, body: text }; const close = lines.findIndex((line, i) => i > 0 && line.trim() === "---"); if (close < 0) return { frontmatter: {}, body: text }; const frontmatter: Record<string, unknown> = {}; for (const line of lines.slice(1, close)) { if (!line.trim() || line.trimStart().startsWith("#")) continue; const colon = line.indexOf(":"); if (colon > 0) frontmatter[line.slice(0, colon).trim()] = unquoteScalar(line.slice(colon + 1).trim()); } return { frontmatter, body: lines.slice(close + 1).join("\n").replace(/^\n+/, "") }; }
+export function unquoteScalar(value: string): string { if (value.length >= 2 && ((value[0] === '"' && value.at(-1) === '"') || (value[0] === "'" && value.at(-1) === "'"))) return value.slice(1, -1); return value; }

package/src/briefing/skills.ts

@@ -0,0 +1,47 @@
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { SKILL_DESCRIPTION_LIMIT, SKILL_NAME_LIMIT } from "./contract.js";
+import type { MacroOrigin, SkillCard, SkillDiagnostic, SkillFrontmatter, SkillLoad } from "./contract.js";
+import { splitFrontmatter } from "./macros.js";
+
+export interface SkillRoot { readonly dir: string; readonly origin: MacroOrigin; }
+interface Candidate { path: string; dirName: string; }
+
+export const SKILL_MANIFEST = "SKILL.md";
+export const PRUNED_DIRS = new Set(["node_modules", ".git"]);
+export const KNOWN_FRONTMATTER_KEYS = new Set(["name", "description", "license", "compatibility", "metadata", "allowed-tools", "disable-model-invocation"]);
+
+function* walkCandidates(root: string, seen: Set<string>): Generator<Candidate> { yield* walkLevel(root, true, seen); }
+function* walkLevel(dir: string, atRoot: boolean, seen: Set<string>): Generator<Candidate> {
+  let entries: string[]; try { entries = readdirSync(dir).sort(); } catch { return; }
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue; const full = join(dir, entry); let stats: import("node:fs").Stats;
+    try { stats = statSync(full); } catch { continue; }
+    if (stats.isDirectory()) { if (PRUNED_DIRS.has(entry)) continue; let real: string; try { real = realpathSync(full); } catch { continue; } if (!seen.has(real)) { seen.add(real); yield* walkLevel(full, false, seen); } }
+    else if (stats.isFile() && ((atRoot && entry.toLowerCase().endsWith(".md")) || (!atRoot && entry === SKILL_MANIFEST))) yield { path: full, dirName: basename(dirname(full)) };
+  }
+}
+
+export function checkName(name: string, dirName: string, fromDir: boolean): string | null { if (!name) return "a skill must declare a non-empty name"; if (name.length > SKILL_NAME_LIMIT) return `the name exceeds the ${SKILL_NAME_LIMIT}-character limit`; if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) return "the name must be lowercase words joined by single hyphens"; if (!fromDir && name !== dirName) return `the declared name "${name}" does not match its directory "${dirName}"`; return null; }
+export function checkDescription(description: string): string | null { if (!description) return "a skill must declare a description so the model can gate it"; return description.length > SKILL_DESCRIPTION_LIMIT ? `the description exceeds the ${SKILL_DESCRIPTION_LIMIT}-character limit` : null; }
+export function checkFrontmatterKeys(frontmatter: Record<string, unknown>): string | null { for (const key of Object.keys(frontmatter)) if (!KNOWN_FRONTMATTER_KEYS.has(key)) return `unrecognised frontmatter key "${key}"`; return null; }
+export function projectFrontmatter(raw: Record<string, unknown>): SkillFrontmatter {
+  const out: { name?: string; description?: string; license?: string; compatibility?: string; metadata?: Readonly<Record<string, unknown>>; allowedTools?: readonly string[]; disableModelInvocation?: boolean } = {};
+  for (const key of ["name", "description", "license", "compatibility"] as const) if (typeof raw[key] === "string") out[key] = raw[key].trim();
+  if (typeof raw.metadata === "object" && raw.metadata !== null) out.metadata = raw.metadata as Record<string, unknown>;
+  const tools = raw["allowed-tools"]; if (typeof tools === "string") { const list = tools.split(/[\s,]+/).filter(Boolean); if (list.length) out.allowedTools = list; } else if (Array.isArray(tools)) out.allowedTools = tools.map(String);
+  if (raw["disable-model-invocation"] === true || raw["disable-model-invocation"] === "true") out.disableModelInvocation = true;
+  return out;
+}
+export function diag(kind: SkillDiagnostic["kind"], location: string, detail: string): SkillDiagnostic { return { kind, location, detail }; }
+export function describeCause(cause: unknown): string { return cause instanceof Error ? cause.message : String(cause); }
+export function parseCandidate(candidate: Candidate, origin: MacroOrigin): { card: SkillCard | null; diagnostic: SkillDiagnostic } {
+  let text: string; try { text = readFileSync(candidate.path, "utf8"); } catch (cause) { return { card: null, diagnostic: diag("invalid", candidate.path, `could not read the skill file (${describeCause(cause)})`) }; }
+  const { frontmatter, body } = splitFrontmatter(text); const keyProblem = checkFrontmatterKeys(frontmatter); if (keyProblem) return { card: null, diagnostic: diag("invalid", candidate.path, keyProblem) };
+  const fm = projectFrontmatter(frontmatter); const fromDir = !(fm.name ?? ""); const name = fromDir ? candidate.dirName : fm.name!; const nameProblem = checkName(name, candidate.dirName, fromDir); if (nameProblem) return { card: null, diagnostic: diag("invalid", candidate.path, nameProblem) };
+  const description = fm.description ?? ""; const descriptionProblem = checkDescription(description); if (descriptionProblem) return { card: null, diagnostic: diag("invalid", candidate.path, descriptionProblem) };
+  return { card: { name, description, body, location: candidate.path, origin, frontmatter: fm }, diagnostic: diag("loaded", candidate.path, `loaded skill "${name}"`) };
+}
+export function loadSkillCards(dir: string, origin: MacroOrigin = "path"): SkillLoad { const cards: SkillCard[] = []; const diagnostics: SkillDiagnostic[] = []; for (const candidate of walkCandidates(dir, new Set())) { const parsed = parseCandidate(candidate, origin); diagnostics.push(parsed.diagnostic); if (parsed.card) cards.push(parsed.card); } return { cards, diagnostics }; }
+export function gatherSkillCards(roots: readonly SkillRoot[]): SkillLoad { const cards: SkillCard[] = []; const diagnostics: SkillDiagnostic[] = []; const claimed = new Map<string, string>(); for (const root of roots) { const loaded = loadSkillCards(root.dir, root.origin); diagnostics.push(...loaded.diagnostics.filter((item: SkillDiagnostic) => item.kind !== "loaded")); for (const card of loaded.cards) { const winner = claimed.get(card.name); if (winner) diagnostics.push(diag("collision", card.location, `the name "${card.name}" was already claimed by ${winner}; this card is dropped`)); else { claimed.set(card.name, card.location); cards.push(card); diagnostics.push(diag("loaded", card.location, `loaded skill "${card.name}"`)); } } } return { cards, diagnostics }; }
+export function modelInvocableCards(cards: readonly SkillCard[]): SkillCard[] { return cards.filter((card) => card.frontmatter.disableModelInvocation !== true); }

package/src/capability-deck/bridge-ledger/index.ts

@@ -0,0 +1,27 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Bridge-ledger — public barrel for event-sourced MCP tool enrollment.
+ *
+ * Three concerns, one import site:
+ *
+ *   - **Keys** (`./key`) — content-addressed and ULID {@link BridgeKey} minting,
+ *     so re-enrolling the same external tool is an idempotent upsert.
+ *   - **Ledger** (`./ledger`) — the immutable {@link BridgeLedger} value and its
+ *     pure transitions: {@link enrollBridgeCard} (upsert), {@link retire} /
+ *     {@link withdrawServer} (splice), each returning a new ledger folded by the
+ *     contract's {@link reduceLedger}.
+ *   - **Network** (`./network`) — {@link attachBridgeCapabilities}, which mounts
+ *     external MCP servers through the framework's `mountProtocolBridge`, adapts
+ *     the returned `ToolBox` into {@link Capability} objects + {@link
+ *     CapabilityCard}s, and enrolls them into a ledger.
+ *
+ * The frozen shapes ({@link BridgeKey}, {@link BridgeEntry}, {@link
+ * LedgerSnapshot}, {@link reduceLedger}) continue to live in the deck contract;
+ * this module re-exports the behavior that operates on them.
+ */
+export { qualifyBridgeName, bridgeContentKey, bridgeUlidKey, } from "./key.js";
+export type { BridgeLedger, EnrollRequest } from "./ledger.js";
+export { emptyBridgeLedger, bridgeLedgerFromLog, enrollBridgeCard, retire, withdrawServer, liveCapabilities, liveCapabilitiesForServer, } from "./ledger.js";
+export type { AttachResult } from "./network.js";
+export { attachBridgeCapabilities, detachBridge, bridgeBoxToCapabilities, bridgeCapabilityCard, bridgeConfig, } from "./network.js";

package/src/capability-deck/bridge-ledger/key.ts

@@ -0,0 +1,67 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Bridge-key minting — stable identifiers for enrolled MCP capabilities.
+ *
+ * An enrolled bridge capability needs a key that is *the same* across sessions
+ * for the same external tool, so re-enrolling is an idempotent upsert rather
+ * than an accumulating duplicate. The catalog already settled this policy in the
+ * contract: a {@link BridgeKey} is "a content hash of the qualified
+ * `<server>__<tool>` name (and its schema) or a fresh ULID" — keyed by the
+ * capability's *identity*, never by a working-directory digest.
+ *
+ * This module implements both halves of that policy and nothing else:
+ *
+ *   - {@link bridgeContentKey} — the default. A deterministic digest of the
+ *     qualified name plus the canonicalized parameter schema. Two enrollments of
+ *     the same remote tool (same name, same schema) collapse to one key, so the
+ *     ledger upsert is naturally idempotent and the live set never duplicates a
+ *     tool just because a server reconnected.
+ *   - {@link bridgeUlidKey} — an opt-in, monotonic, time-sortable ULID for the
+ *     rare case a caller wants every enrollment to be a distinct event (e.g. an
+ *     ephemeral, per-invocation graft) rather than a deduplicated identity.
+ *
+ * Both return a branded {@link BridgeKey}; neither touches the filesystem, the
+ * clock-as-state, or any shared mutable value.
+ */
+import type { TSchema } from "@sinclair/typebox";
+import { type BridgeKey } from "../contract.js";
+/**
+ * The qualified, collision-free name the model sees for a remote tool —
+ * `"<server>__<tool>"`, using the framework's bridge {@link QUALIFIER}.
+ *
+ * The protocol bridge already stamps this exact form onto each grafted tool's
+ * descriptor; we recompute it here only so a key can be minted *before* a
+ * descriptor is in hand (e.g. from a {@link RemoteToolRef}-shaped pair).
+ *
+ * @param server the owning MCP server's id
+ * @param tool   the remote tool's own (unqualified) name
+ */
+export declare function qualifyBridgeName(server: string, tool: string): string;
+/**
+ * Mint a content-addressed {@link BridgeKey} from a remote tool's identity.
+ *
+ * The digest is taken over the qualified `<server>__<tool>` name and the
+ * canonicalized parameter schema, so the key is a pure function of *what the
+ * tool is*. Enrolling the same tool twice yields the same key — the ledger
+ * upsert deduplicates it — while a tool whose schema changed yields a new key,
+ * correctly surfacing it as a distinct capability.
+ *
+ * @param server     the owning MCP server's id
+ * @param tool       the remote tool's own (unqualified) name
+ * @param parameters the tool's parameter schema (TypeBox or raw JSON Schema)
+ */
+export declare function bridgeContentKey(server: string, tool: string, parameters?: TSchema | Record<string, unknown>): BridgeKey;
+/**
+ * Mint a fresh, time-sortable {@link BridgeKey} as a ULID.
+ *
+ * Use when each enrollment must be a *distinct* event rather than a deduplicated
+ * identity — for instance an ephemeral, per-invocation graft, or when two
+ * differently-configured connections to the same server should each get their
+ * own live entry. The ULID is monotonic within a process so ordering is stable.
+ *
+ * @param monotonic when true (default) use the process-monotonic generator so
+ *   keys minted in the same millisecond remain strictly increasing; pass false
+ *   for a plain, independent ULID.
+ */
+export declare function bridgeUlidKey(monotonic?: boolean): BridgeKey;

package/src/capability-deck/bridge-ledger/ledger.ts

@@ -0,0 +1,131 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * The immutable bridge ledger — event-sourced enrollment of MCP capabilities.
+ *
+ * MCP tools are grafted in and pulled out over a session's life: a server
+ * connects and contributes a handful of tools, another disconnects, the same
+ * server reconnects after a hot-reload. Rather than mutate a shared module-level
+ * array of live tools (which makes "who's enrolled right now" a function of call
+ * order and hides every past change), enrollment here is an **append-only event
+ * log** folded into a **derived snapshot**.
+ *
+ *   - {@link BridgeLedger} is a plain immutable value: the ordered
+ *     {@link BridgeEntry} log, its already-folded {@link LedgerSnapshot}, and the
+ *     next sequence number to stamp.
+ *   - Every mutation ({@link enrollBridgeCard}, {@link retire},
+ *     {@link withdrawServer}) returns a *new* ledger; the input is never touched.
+ *     `enroll` is an upsert (re-enrolling a key replaces its entry), `retire` is
+ *     a splice (the keyed entry is removed from the live view).
+ *   - The live view is produced solely by the contract's pure
+ *     {@link reduceLedger} fold, so the snapshot can never drift from the log.
+ *
+ * The log is the source of truth; the snapshot is a cache of its fold. Because
+ * both live on the value, callers read `ledger.snapshot.live` directly and never
+ * re-reduce by hand.
+ */
+import { type AnyCapability, type BridgeEntry, type BridgeKey, type LedgerSnapshot } from "../contract.js";
+/**
+ * An immutable, event-sourced view of MCP tool enrollment.
+ *
+ * Holds the append-only {@link BridgeEntry} log, the {@link LedgerSnapshot} that
+ * is its current fold, and the sequence number the next appended entry will
+ * carry. Treat every instance as frozen: the enroll/retire/withdraw helpers
+ * derive a new ledger rather than editing this one in place.
+ */
+export interface BridgeLedger {
+    /** The append-only enrollment event log, in append order. */
+    readonly log: readonly BridgeEntry[];
+    /** The current fold of {@link log} — the live capabilities and per-server counts. */
+    readonly snapshot: LedgerSnapshot;
+    /** The sequence number the next appended {@link BridgeEntry} will carry. */
+    readonly nextSeq: number;
+}
+/**
+ * The fields an enrollment supplies; the ledger stamps `op`, `seq`, and `at`.
+ *
+ * A caller names the capability, the owning server, and optionally a pre-minted
+ * {@link BridgeKey}; when the key is omitted it is content-addressed from the
+ * capability's identity so re-enrolling the same tool is idempotent.
+ */
+export interface EnrollRequest {
+    /** The grafted capability to enroll (its `name` is the qualified tool name). */
+    readonly capability: AnyCapability;
+    /** Id of the external MCP server that owns the capability. */
+    readonly server: string;
+    /**
+     * Optional explicit key. When omitted, a content key is derived from the
+     * capability's qualified name and parameter schema so the enrollment upserts
+     * any prior entry for the same tool instead of duplicating it.
+     */
+    readonly key?: BridgeKey;
+}
+/** An empty ledger: no events, an empty live view, sequence numbering at 1. */
+export declare function emptyBridgeLedger(): BridgeLedger;
+/**
+ * Rebuild a ledger value from a persisted event log.
+ *
+ * The log is authoritative, so a ledger is fully reconstructable from it: fold
+ * it for the snapshot and resume sequence numbering one past its high-water
+ * mark. Use when rehydrating enrollment state across a restart.
+ *
+ * @param log the persisted append-only entries, in any order (sorted on fold)
+ */
+export declare function bridgeLedgerFromLog(log: readonly BridgeEntry[]): BridgeLedger;
+/**
+ * Append an `enroll` event and return the resulting ledger.
+ *
+ * The graft is an **upsert**: the appended entry carries a {@link BridgeKey}, and
+ * because {@link reduceLedger} lets a later sequence win on a repeated key, a
+ * re-enrollment of the same tool transparently replaces its prior live entry
+ * rather than duplicating it. The input ledger is not mutated.
+ *
+ * @param ledger the current ledger (left untouched)
+ * @param req    the capability + server to enroll, with an optional explicit key
+ * @param at     enrollment timestamp; defaults to now (ISO-8601)
+ */
+export declare function enrollBridgeCard(ledger: BridgeLedger, req: EnrollRequest, at?: string): BridgeLedger;
+/**
+ * Append a `retire` event for one capability and return the resulting ledger.
+ *
+ * The withdrawal is a **splice**: the appended `retire` entry names the key, and
+ * the fold drops that key from the live view. Retiring an unknown or
+ * already-retired key is a harmless no-op in the live set (the event is still
+ * recorded for the audit trail). The input ledger is not mutated.
+ *
+ * @param ledger the current ledger (left untouched)
+ * @param key    the stable key of the capability to withdraw
+ * @param server the owning server id, recorded on the event
+ * @param at     retirement timestamp; defaults to now (ISO-8601)
+ */
+export declare function retire(ledger: BridgeLedger, key: BridgeKey, server: string, at?: string): BridgeLedger;
+/**
+ * Retire every capability a given server currently has live, in one batch.
+ *
+ * Appends one `retire` event per live key owned by the server — the disconnect
+ * counterpart to grafting a whole server's tool set. Servers with nothing live
+ * yield the ledger unchanged. The input ledger is not mutated.
+ *
+ * @param ledger the current ledger (left untouched)
+ * @param server the server whose live capabilities should all be withdrawn
+ * @param at     retirement timestamp applied to every event; defaults to now
+ */
+export declare function withdrawServer(ledger: BridgeLedger, server: string, at?: string): BridgeLedger;
+/**
+ * Read the live capabilities a single server currently contributes.
+ *
+ * Pure projection over the snapshot; the per-key→server association is recovered
+ * from the log (each live key's last-touching server). Handy for status panels
+ * and for {@link withdrawServer}'s batch retirement.
+ *
+ * @param ledger the ledger to read
+ * @param server the server id to filter by
+ */
+export declare function liveCapabilitiesForServer(ledger: BridgeLedger, server: string): AnyCapability[];
+/**
+ * The flat list of every live capability, in stable iteration order.
+ *
+ * What a deck assembler grafts onto the static catalog before handing the
+ * conductor its `options.tools`.
+ */
+export declare function liveCapabilities(ledger: BridgeLedger): AnyCapability[];

package/src/capability-deck/bridge-ledger/network.ts

@@ -0,0 +1,117 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * The bridge network — mounting external MCP servers into the ledger.
+ *
+ * This is the side-effecting half of bridge enrollment. The framework's
+ * {@link mountProtocolBridge} does the protocol work: it connects every
+ * configured server, lists each ready endpoint's tools, and hands back a single
+ * {@link ToolBox} whose `descriptors()` advertise every grafted remote tool
+ * under its qualified `"<server>__<tool>"` name and whose `runner` routes a call
+ * back across the owning endpoint.
+ *
+ * What this module adds on top:
+ *
+ *   - **Adaptation.** A {@link ToolBox} speaks the runtime's descriptor/runner
+ *     contract; the conductor and catalog speak {@link Capability} (the
+ *     framework `AgentTool`). {@link bridgeBoxToCapabilities} bridges the two,
+ *     wrapping each descriptor + the shared runner into an `AgentTool` whose
+ *     `execute` invokes the runner and projects its opaque outcome onto an
+ *     {@link AgentToolResult}.
+ *   - **Enrollment.** {@link attachBridgeCapabilities} folds those adapted
+ *     capabilities into a {@link BridgeLedger} as `enroll` events, returning the
+ *     new ledger, the live fleet (for teardown), and the typed status — never
+ *     mutating a shared array.
+ *   - **Cataloging.** {@link bridgeCapabilityCard} re-presents a grafted
+ *     capability as a {@link CapabilityCard}, so dynamic MCP tools surface in
+ *     help/introspection beside the static catalog rows.
+ *
+ * Failure isolation comes for free from the fleet: a server that faulted on
+ * connect contributes no descriptors and is simply absent from the enrollment.
+ */
+import { type AnyCapability, type CapabilityCard, type DeckFault } from "../contract.js";
+import { type BridgeConfig, type ServerConfig, type ServerFleet, type FleetStatus } from "indusagi/interop";
+import type { ToolBox } from "indusagi/runtime";
+import { type BridgeLedger } from "./ledger.js";
+/**
+ * Adapt every tool a mounted {@link ToolBox} advertises into a list of
+ * {@link Capability} objects the conductor and ledger consume.
+ *
+ * Each box descriptor becomes one `AgentTool`: its qualified name, description,
+ * and parameter schema are carried verbatim, and its `execute` defers to the
+ * box's shared `runner` — passing the abort signal through and projecting the
+ * outcome with {@link projectOutcome}. The runner already knows how to route a
+ * call by name back to the owning endpoint, so the wrapper stays a thin shim.
+ *
+ * @param box the tool box returned by {@link mountProtocolBridge}
+ */
+export declare function bridgeBoxToCapabilities(box: ToolBox): AnyCapability[];
+/**
+ * Re-present a grafted bridge capability as a {@link CapabilityCard}.
+ *
+ * Lets dynamic MCP tools appear in the same catalog/help surface as the static
+ * cards: the card's `build` simply returns the already-live capability (the
+ * graft happened at mount time, so there is nothing further to construct). The
+ * owning server id is recovered from the qualified name for the title.
+ *
+ * @param capability a capability produced by {@link bridgeBoxToCapabilities}
+ */
+export declare function bridgeCapabilityCard(capability: AnyCapability): CapabilityCard;
+/**
+ * The outcome of attaching one or more MCP servers to a ledger.
+ *
+ * Bundles the new {@link BridgeLedger} (with every reachable tool enrolled), the
+ * live {@link ServerFleet} the caller owns and must eventually tear down, the
+ * aggregate {@link FleetStatus} for rendering, the count of tools grafted, and a
+ * non-fatal {@link DeckFault} when the mount itself failed wholesale.
+ */
+export interface AttachResult {
+    /** The ledger after enrolling every grafted capability. */
+    readonly ledger: BridgeLedger;
+    /** The running fleet of endpoints; caller closes it via {@link detachBridge}. */
+    readonly fleet?: ServerFleet;
+    /** Aggregate per-server health, when a fleet came up. */
+    readonly status?: FleetStatus;
+    /** How many remote tools were enrolled. */
+    readonly enrolled: number;
+    /** A wholesale-mount fault, when connecting the bridge threw. */
+    readonly fault?: DeckFault;
+}
+/**
+ * Mount external MCP servers and enroll their tools into the bridge ledger.
+ *
+ * Connects every server in `config` through {@link mountProtocolBridge}, adapts
+ * the resulting box into capabilities, and folds each one into `ledger` as an
+ * `enroll` event — yielding a *new* ledger (the input is untouched). The live
+ * fleet is returned so the caller can read status and later tear it down; a
+ * faulted server simply contributes no tools and is reflected in the status.
+ *
+ * A wholesale failure (the mount call itself rejecting) is caught and reported
+ * as a `bridge` {@link DeckFault} on the result rather than thrown, so a bad MCP
+ * configuration degrades the deck instead of sinking session bootstrap.
+ *
+ * @param ledger the ledger to enroll into (left untouched)
+ * @param config the set of MCP servers to connect and graft
+ */
+export declare function attachBridgeCapabilities(ledger: BridgeLedger, config: BridgeConfig): Promise<AttachResult>;
+/**
+ * Detach one or more servers: retire their ledger entries and close the fleet.
+ *
+ * Withdraws every named server's live capabilities from `ledger` (or, when no
+ * names are given, every server present in the fleet status) and gracefully
+ * tears the fleet down. Returns the new ledger; the fleet is no longer usable
+ * after this resolves. The teardown is best-effort — a close that throws is
+ * swallowed so ledger withdrawal still completes.
+ *
+ * @param ledger  the current ledger (left untouched)
+ * @param fleet   the live fleet to close
+ * @param servers optional subset of server ids to detach; defaults to all
+ */
+export declare function detachBridge(ledger: BridgeLedger, fleet: ServerFleet, servers?: readonly string[]): Promise<BridgeLedger>;
+/**
+ * Convenience: turn a flat list of MCP server descriptions into the
+ * {@link BridgeConfig} {@link attachBridgeCapabilities} expects.
+ *
+ * @param servers the per-server transport configurations, in declaration order
+ */
+export declare function bridgeConfig(servers: readonly ServerConfig[]): BridgeConfig;