indusagi-coding-agent 0.1.58 → 0.1.60

package/dist/types/briefing/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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";
+export { SKILL_NAME_LIMIT, SKILL_DESCRIPTION_LIMIT, SGR_INITIAL_STATE, FALLBACK_EXPORT_THEME, SHELL_SLOTS, briefingFault, } from "./contract";
+export { BRIEFING_SECTIONS, composeBriefing } from "./compose";
+export { scanMacroBody, resolveTokens, applyMacros, buildMacroScope, expandInvocation, loadMacros, readMacroFile, splitFrontmatter, } from "./macros";
+export type { LoadMacrosOptions, FrontmatterSplit } from "./macros";
+export { loadSkillCards, gatherSkillCards, modelInvocableCards, } from "./skills";
+export type { SkillRoot } from "./skills";

package/dist/types/briefing/macros.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Macro loader + single-pass argument-template scanner.
+ *
+ * A macro is a named prompt body discovered from a `*.md` file under the user,
+ * project, or an explicit path root. Invoking `/<name> rest-of-line` resolves
+ * the body against the line's arguments, substituting the indus argument
+ * placeholders.
+ *
+ * # Indus template format
+ *
+ * Indus's own placeholders use a double-curly `{{arg.…}}` form so they stand
+ * out from ordinary shell-style text and never collide with stray `$` in prose.
+ * Every placeholder is introduced with `{{arg.`, names one of a small set of
+ * accessors, and closes with `}}`. Whitespace inside the braces is permitted
+ * around the accessor and its numeric arguments but not required.
+ *
+ *   - `{{arg.1}}`, `{{arg.2}}`, …   — one positional argument (1-based).
+ *   - `{{arg.all}}`                  — every positional argument, re-joined
+ *                                      with single spaces (equivalent to the
+ *                                      verbatim raw argument string for the
+ *                                      common case where neither quoting nor
+ *                                      runs of whitespace matter).
+ *   - `{{arg.slice N L}}`            — at most `L` positionals starting at the
+ *                                      1-based offset `N`, re-joined with
+ *                                      single spaces.
+ *   - `{{arg.slice N}}`              — positionals from `N` onward (1-based,
+ *                                      inclusive).
+ *   - `{{arg.rest N}}`               — positionals from `N` onward; an alias
+ *                                      for `{{arg.slice N}}` that reads more
+ *                                      naturally when "everything after the
+ *                                      first few" is meant. `N` defaults to
+ *                                      `2` (i.e. everything after `arg.1`)
+ *                                      when omitted: `{{arg.rest}}`.
+ *
+ * A literal `{{` is written `{{{{` (doubled), so author-controlled body text
+ * can still contain double-brace runs verbatim when needed.
+ *
+ * # Compatibility shim
+ *
+ * For backward compatibility with templates authored against the older
+ * `$arg`-style syntax, a single-pass shim still recognises the legacy forms
+ * and rewrites them on the fly:
+ *
+ *   - `$1`, `$2`, …    — one positional argument (1-based).
+ *   - `$@`             — every positional, re-joined with single spaces.
+ *   - `$ARGUMENTS`     — the whole original argument string, verbatim.
+ *   - `${@:N}`         — positionals from N onward (1-based, inclusive).
+ *   - `${@:N:L}`       — at most L positionals starting at N.
+ *
+ * Using any of these legacy forms invokes {@link reportLegacyUsage} so callers
+ * can surface a deprecation notice in their UI; the expansion still produces
+ * the expected text so existing macro files keep working.
+ *
+ * # Implementation discipline
+ *
+ * Substitution is **one left-to-right scan**, not a sequence of regex passes:
+ * {@link scanMacroBody} walks the body character by character, emitting a flat
+ * {@link MacroToken} stream (literal runs interleaved with positional / all /
+ * slice references), and {@link applyMacros} resolves that stream against a
+ * {@link MacroScope} and concatenates. A single scan means a character produced
+ * by expanding one token can never be re-interpreted as the start of another —
+ * the classic multi-pass footgun — and the tokenization is reusable (cache the
+ * tokens, resolve many times).
+ *
+ * Loading mirrors the same discipline: {@link loadMacros} walks a directory's
+ * direct `*.md` children (non-recursively, the slash-macro convention), splits
+ * off optional YAML-ish frontmatter, derives a one-line description, and
+ * returns {@link Macro}s tagged with their {@link MacroOrigin}.
+ */
+import type { Macro, MacroOrigin, MacroScope, MacroToken } from "./contract";
+/** Install (or clear) the legacy-syntax reporter; used by hosts for warnings. */
+export declare function setLegacyMacroReporter(fn: ((kind: string, source: string) => void) | undefined): void;
+/**
+ * Scan a macro body into a flat {@link MacroToken} stream in a single
+ * left-to-right pass.
+ *
+ * The scanner accumulates ordinary characters into a pending literal run and
+ * flushes that run whenever it recognises a placeholder. Placeholders use the
+ * indus `{{arg.…}}` form by default and the compatibility `$arg` form via the
+ * shim; see the module JSDoc for the full grammar.
+ *
+ * Any apparent placeholder that fails to parse (e.g. `${foo}`, a dangling `$`
+ * at end of input, or a stray `{{` that does not open `{{arg.`) is treated as
+ * literal text so the body survives untouched. The returned stream merges
+ * adjacent literal characters into a single token.
+ *
+ * @param body the macro body text to tokenize
+ * @returns the ordered token stream; resolve it with {@link applyMacros}
+ */
+export declare function scanMacroBody(body: string): MacroToken[];
+/**
+ * Build the argument environment a macro body resolves against from the raw
+ * text that followed the command name.
+ *
+ * `raw` is kept verbatim; `args` is the whitespace-split positional vector;
+ * `all` is the positionals re-joined with single spaces (the `{{arg.all}}`
+ * expansion). The split is quote-aware: single- or double-quoted runs become
+ * one argument with their surrounding quotes removed, so
+ * `deploy "the staging box"` yields two args.
+ *
+ * @param raw the verbatim argument text following the command name
+ * @returns a {@link MacroScope} ready for {@link applyMacros}
+ */
+export declare function buildMacroScope(raw: string): MacroScope;
+/**
+ * Resolve a token stream against a {@link MacroScope} and concatenate to the
+ * expanded text.
+ *
+ * Each token contributes its resolved text:
+ *
+ *   - `literal`    → its verbatim run.
+ *   - `positional` → the matching `args[index - 1]`, or empty when out of range.
+ *   - `all`        → the full `scope.all` string.
+ *   - `slice`      → `args` from the 1-based `start` for up to `length`,
+ *     re-joined with single spaces; out-of-range or zero-length slices yield
+ *     empty.
+ *
+ * Because resolution happens after the single scan, expanded argument text is
+ * inserted as-is and is never re-scanned for further placeholders.
+ *
+ * @param tokens a stream from {@link scanMacroBody}
+ * @param scope  the argument environment to resolve against
+ * @returns the fully expanded macro text
+ */
+export declare function resolveTokens(tokens: readonly MacroToken[], scope: MacroScope): string;
+/**
+ * Expand a macro body against a raw argument line in one shot: scan, then
+ * resolve.
+ *
+ * Convenience over {@link scanMacroBody} + {@link buildMacroScope} +
+ * {@link resolveTokens} for callers that do not retain the token stream.
+ *
+ * @param body the macro body containing indus or legacy placeholders
+ * @param raw  the verbatim argument text following the command name
+ * @returns the expanded text
+ */
+export declare function applyMacros(body: string, raw: string): string;
+/**
+ * Expand an invocation line of the form `/<name> rest…` against a set of
+ * loaded macros.
+ *
+ * If the line opens with `/` and names a known macro, the macro's body is
+ * expanded against the remainder of the line. Otherwise the line is returned
+ * unchanged — ordinary user turns pass straight through.
+ *
+ * @param line   the raw input line
+ * @param macros the macros to resolve against (later entries do not override
+ *               earlier ones; the first match by name wins)
+ * @returns the expanded text, or the original line when no macro matches
+ */
+export declare function expandInvocation(line: string, macros: readonly Macro[]): string;
+/** Options for {@link loadMacros}. */
+export interface LoadMacrosOptions {
+    /** Where the directory's macros are tagged as having come from. */
+    readonly origin?: MacroOrigin;
+    /** A label for the source, woven into derived descriptions (e.g. `"project"`). */
+    readonly label?: string;
+}
+/**
+ * Load the macros defined by the direct `*.md` children of a directory.
+ *
+ * Non-recursive by design: slash macros live as flat files in their root, unlike
+ * skills which nest. A missing directory yields an empty list (a perfectly normal
+ * "no user macros configured" case); a present-but-unreadable file raises a
+ * `macro_invalid` {@link briefingFault} via {@link readMacroFile}.
+ *
+ * @param dir  the directory to scan for `*.md` macro files
+ * @param opts origin tag and source label for the produced macros
+ * @returns the loaded macros, in directory order, deduped by name (first wins)
+ */
+export declare function loadMacros(dir: string, opts?: LoadMacrosOptions): Macro[];
+/**
+ * Read and parse a single macro file into a {@link Macro}.
+ *
+ * The macro `name` is the file's basename without its `.md` suffix. Optional
+ * leading frontmatter (a `---` fenced block) supplies a `description`; absent
+ * that, a description is derived from the first non-blank body line, capped and
+ * suffixed with the source `label`.
+ *
+ * @param path   absolute path of the macro file
+ * @param origin origin tag to stamp on the macro
+ * @param label  source label used when deriving a description
+ * @returns the parsed macro
+ * @throws a `macro_invalid` {@link briefingFault} when the file cannot be read
+ */
+export declare function readMacroFile(path: string, origin: MacroOrigin, label: string): Macro;
+/** A parsed frontmatter block plus the body that followed it. */
+export interface FrontmatterSplit {
+    /** Flat key/value pairs read from the leading `---` block (empty when absent). */
+    readonly frontmatter: Record<string, unknown>;
+    /** The document body after the closing fence (or the whole text when absent). */
+    readonly body: string;
+}
+/**
+ * Split a leading `---`-fenced frontmatter block off a markdown document.
+ *
+ * Recognises a block only when the very first line is exactly `---` and a later
+ * line is exactly `---`. Inside, each `key: value` line becomes a flat string
+ * entry (a small subset of YAML — enough for the `name`/`description`/`license`
+ * keys these documents carry). When no well-formed block leads the text, the
+ * frontmatter is empty and the body is the whole input.
+ *
+ * @param text the raw document text
+ * @returns the parsed `{ frontmatter, body }`
+ */
+export declare function splitFrontmatter(text: string): FrontmatterSplit;

package/dist/types/briefing/skills.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Capability-card loader — `SKILL.md` discovery, validation, and parsing.
+ *
+ * A capability card is *documentation the model reads*: a markdown file in the
+ * Agent-Skills format whose frontmatter names a skill and one-line-describes when
+ * it applies, with a body of on-demand instructions. The model decides from the
+ * `description` whether a task matches, then loads the file's `location` to read
+ * the full body. This module turns a set of directory roots into validated
+ * {@link SkillCard}s plus a diagnostic stream.
+ *
+ * Discovery follows the format's two shapes, with a generic directory walk rather
+ * than a special-cased recursion:
+ *
+ *   - At a *root* level, a direct `*.md` child is a single-file skill.
+ *   - In any *subdirectory*, a `SKILL.md` file is a packaged skill whose name is
+ *     expected to match its enclosing directory.
+ *
+ * The walk yields candidate file descriptors; a separate validation stage turns
+ * each candidate into one {@link SkillDiagnostic} (and, on success, one
+ * {@link SkillCard}). Validation prose and field policy are the briefing's own;
+ * only the *format* (frontmatter keys, the ≤64 / ≤1024 limits, lowercase-hyphen
+ * names) is the shared public spec. Names are deduped across roots — the first
+ * card to claim a name wins and later claimants are reported as collisions.
+ */
+import type { MacroOrigin, SkillCard, SkillLoad } from "./contract";
+/** One root directory to load skill cards from, with its origin tag. */
+export interface SkillRoot {
+    /** The directory to walk. */
+    readonly dir: string;
+    /** How cards discovered under this root are tagged. */
+    readonly origin: MacroOrigin;
+}
+/**
+ * Load and validate the capability cards under one directory root.
+ *
+ * Walks the root for candidates, parses each, and accumulates the diagnostics.
+ * Name deduplication is *not* applied here (a single root rarely collides with
+ * itself in a way worth reporting); use {@link gatherSkillCards} to merge several
+ * roots with collision reporting. Symlink cycles within the root are broken by
+ * realpath tracking.
+ *
+ * @param dir    the root directory to scan
+ * @param origin the origin tag for cards found here
+ * @returns the cards and diagnostics produced from this root
+ */
+export declare function loadSkillCards(dir: string, origin?: MacroOrigin): SkillLoad;
+/**
+ * Load and merge capability cards from several roots, deduping by name.
+ *
+ * Roots are processed in order; the first card to claim a name wins, and any
+ * later card with the same name is dropped with a `collision` diagnostic (its
+ * own per-root `loaded` line is rewritten to the collision outcome). The merged
+ * card list is the deduped survivors, in discovery order.
+ *
+ * @param roots the roots to load, in precedence order (earliest wins)
+ * @returns the merged cards and the combined diagnostic stream
+ */
+export declare function gatherSkillCards(roots: readonly SkillRoot[]): SkillLoad;
+/**
+ * Filter cards down to those the model may auto-invoke (i.e. that are not marked
+ * `disable-model-invocation`). The hidden cards remain available as explicit
+ * commands but do not appear in the briefing's skill block.
+ *
+ * @param cards the full card set
+ * @returns the subset eligible for model invocation
+ */
+export declare function modelInvocableCards(cards: readonly SkillCard[]): SkillCard[];

package/dist/types/capability-deck/bridge-ledger/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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";
+export type { BridgeLedger, EnrollRequest } from "./ledger";
+export { emptyBridgeLedger, bridgeLedgerFromLog, enrollBridgeCard, retire, withdrawServer, liveCapabilities, liveCapabilitiesForServer, } from "./ledger";
+export type { AttachResult } from "./network";
+export { attachBridgeCapabilities, detachBridge, bridgeBoxToCapabilities, bridgeCapabilityCard, bridgeConfig, } from "./network";

package/dist/types/capability-deck/bridge-ledger/key.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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";
+/**
+ * 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/dist/types/capability-deck/bridge-ledger/ledger.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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";
+/**
+ * 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/dist/types/capability-deck/bridge-ledger/network.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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";
+import { type BridgeConfig, type ServerConfig, type ServerFleet, type FleetStatus } from "indusagi/interop";
+import type { ToolBox } from "indusagi/runtime";
+import { type BridgeLedger } from "./ledger";
+/**
+ * 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;