dero-mcp-server 0.1.1 → 0.2.2

package/dist/citations.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Citation helper for DERO MCP tool responses.
+ *
+ * The wedge for this server is the combination of live chain reads and the
+ * in-process bundled docs index (145+ pages across derod, tela, hologram,
+ * deropay). Citations let agents link their responses back to authoritative
+ * docs without a second tool call, and they give downstream composite tools
+ * a uniform shape to compose.
+ *
+ * Design contract:
+ *   - One shape, used by primitives and composites alike.
+ *   - URLs are produced by the same builder used by `dero_docs_*` so the
+ *     citation always points at the same canonical page the agent would
+ *     reach via dero_docs_get_page.
+ *   - The slug is duplicated as `page_id` to give composites a stable join
+ *     key across tools (mirrors the FoodNearMe COMPOSITES.md citation pattern).
+ *   - The map of related docs per tool is hand-maintained and validated by
+ *     `scripts/check-citations.ts` (added alongside this helper) so a docs
+ *     reorganization cannot silently produce 404 citations in production.
+ */
+import { type DeroDocProduct } from './docs-parse.js';
+export type DeroCitation = {
+    /** Always `'dero_docs'` for now; future sources (e.g. `'dero_chain'`) can extend this. */
+    source: 'dero_docs';
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+    canonical_url: string;
+    /** Alias of `slug` so composites can use a single join key across tools. */
+    page_id: string;
+};
+/**
+ * Build a DeroCitation pointing at one bundled docs page.
+ *
+ * The title is required (not derived from the bundled index) so this helper
+ * stays synchronous and zero-IO. It must match the docs page title; the
+ * citation guard validates this against the bundled index in CI.
+ */
+export declare function buildDeroCitation(product: DeroDocProduct, slug: string, title: string): DeroCitation;
+/**
+ * Map of MCP tool name → hand-curated related docs pages.
+ *
+ * Keep this list tight — only add entries when a tool's response is
+ * meaningfully improved by linking the agent at a specific page. The CI
+ * guard verifies every slug resolves against the bundled docs index, so any
+ * docs reorganization will fail the build before it ships.
+ *
+ * Adding a tool here:
+ *   1. Use `dero_docs_search` to find the right slug(s).
+ *   2. Add an entry with product + slug + exact page title.
+ *   3. Run `npm run check:citations` to confirm slugs resolve.
+ */
+type RelatedDocsEntry = {
+    product: DeroDocProduct;
+    slug: string;
+    title: string;
+};
+export declare const RELATED_DOCS_BY_TOOL: Record<string, readonly RelatedDocsEntry[]>;
+/**
+ * Resolve the hand-curated related docs list for a tool name and return it
+ * as fully-built `DeroCitation` objects. Returns `undefined` when the tool
+ * has no related docs configured.
+ *
+ * Use in tool handlers like:
+ *   const related_docs = relatedDocsFor('dero_get_sc')
+ *   return { ...rpcResult, ...(related_docs ? { related_docs } : {}) }
+ */
+export declare function relatedDocsFor(toolName: string): DeroCitation[] | undefined;
+export {};
+//# sourceMappingURL=citations.d.ts.map

package/dist/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../src/citations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEpE,MAAM,MAAM,YAAY,GAAG;IACzB,0FAA0F;IAC1F,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAQD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,YAAY,CASd;AAED;;;;;;;;;;;;GAYG;AACH,KAAK,gBAAgB,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAqGnE,CAAA;AAEV;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,SAAS,CAI3E"}

package/dist/citations.js

@@ -0,0 +1,162 @@
+/**
+ * Citation helper for DERO MCP tool responses.
+ *
+ * The wedge for this server is the combination of live chain reads and the
+ * in-process bundled docs index (145+ pages across derod, tela, hologram,
+ * deropay). Citations let agents link their responses back to authoritative
+ * docs without a second tool call, and they give downstream composite tools
+ * a uniform shape to compose.
+ *
+ * Design contract:
+ *   - One shape, used by primitives and composites alike.
+ *   - URLs are produced by the same builder used by `dero_docs_*` so the
+ *     citation always points at the same canonical page the agent would
+ *     reach via dero_docs_get_page.
+ *   - The slug is duplicated as `page_id` to give composites a stable join
+ *     key across tools (mirrors the FoodNearMe COMPOSITES.md citation pattern).
+ *   - The map of related docs per tool is hand-maintained and validated by
+ *     `scripts/check-citations.ts` (added alongside this helper) so a docs
+ *     reorganization cannot silently produce 404 citations in production.
+ */
+import { DOC_BASE_URLS } from './docs-parse.js';
+function buildCanonicalUrl(product, slug) {
+    const trimmed = slug.replace(/^\/+|\/+$/g, '');
+    if (!trimmed)
+        return `${DOC_BASE_URLS[product]}/`;
+    return `${DOC_BASE_URLS[product]}/${trimmed}`;
+}
+/**
+ * Build a DeroCitation pointing at one bundled docs page.
+ *
+ * The title is required (not derived from the bundled index) so this helper
+ * stays synchronous and zero-IO. It must match the docs page title; the
+ * citation guard validates this against the bundled index in CI.
+ */
+export function buildDeroCitation(product, slug, title) {
+    return {
+        source: 'dero_docs',
+        product,
+        slug,
+        title,
+        canonical_url: buildCanonicalUrl(product, slug),
+        page_id: slug,
+    };
+}
+export const RELATED_DOCS_BY_TOOL = {
+    dero_get_info: [
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'basics/daemon',
+            title: 'DERO Daemon: Backbone of the Privacy Blockchain | DERO Blockchain',
+        },
+    ],
+    dero_get_sc: [
+        {
+            product: 'derod',
+            slug: 'dvm/smart-contract-fundamentals',
+            title: 'Smart Contract Fundamentals: Understanding DERO Contracts | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dero-virtual-machine',
+            title: 'DERO Virtual Machine (DVM): Private Smart Contract Platform | DERO Blockchain',
+        },
+    ],
+    dero_get_gas_estimate: [
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/create-deploy-use-smart-contract',
+            title: 'Create, Deploy & Use a Smart Contract on DERO | Step-by-Step Tutorial',
+        },
+    ],
+    diagnose_chain_health: [
+        {
+            product: 'derod',
+            slug: 'basics/daemon',
+            title: 'DERO Daemon: Backbone of the Privacy Blockchain | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+    ],
+    trace_transaction_with_context: [
+        {
+            product: 'derod',
+            slug: 'rpc-api/daemon-rpc-api',
+            title: 'DERO Daemon RPC API: Complete Reference Guide | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/smart-contract-fundamentals',
+            title: 'Smart Contract Fundamentals: Understanding DERO Contracts | DERO Blockchain',
+        },
+    ],
+    estimate_deploy_cost: [
+        {
+            product: 'derod',
+            slug: 'dvm/create-deploy-use-smart-contract',
+            title: 'Create, Deploy & Use a Smart Contract on DERO | Step-by-Step Tutorial',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dvm-basic',
+            title: "DVM-BASIC: DERO's Smart Contract Language Guide | DERO Blockchain",
+        },
+    ],
+    // Composite #2 (`explain_smart_contract`) curates all four DVM docs so its
+    // heuristic can elevate whichever page best matches the detected surface
+    // (token / registry / minimal / generic). The composite re-orders this
+    // array at runtime; the static ordering here is the fallback when the
+    // heuristic returns the same slug already at index 0 (the universal
+    // "fundamentals" default).
+    explain_smart_contract: [
+        {
+            product: 'derod',
+            slug: 'dvm/smart-contract-fundamentals',
+            title: 'Smart Contract Fundamentals: Understanding DERO Contracts | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dvm-basic',
+            title: "DVM-BASIC: DERO's Smart Contract Language Guide | DERO Blockchain",
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/dero-virtual-machine',
+            title: 'DERO Virtual Machine (DVM): Private Smart Contract Platform | DERO Blockchain',
+        },
+        {
+            product: 'derod',
+            slug: 'dvm/create-deploy-use-smart-contract',
+            title: 'Create, Deploy & Use a Smart Contract on DERO | Step-by-Step Tutorial',
+        },
+    ],
+};
+/**
+ * Resolve the hand-curated related docs list for a tool name and return it
+ * as fully-built `DeroCitation` objects. Returns `undefined` when the tool
+ * has no related docs configured.
+ *
+ * Use in tool handlers like:
+ *   const related_docs = relatedDocsFor('dero_get_sc')
+ *   return { ...rpcResult, ...(related_docs ? { related_docs } : {}) }
+ */
+export function relatedDocsFor(toolName) {
+    const entries = RELATED_DOCS_BY_TOOL[toolName];
+    if (!entries || entries.length === 0)
+        return undefined;
+    return entries.map((entry) => buildDeroCitation(entry.product, entry.slug, entry.title));
+}
+//# sourceMappingURL=citations.js.map

package/dist/citations.js.map

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

package/dist/composites/_shared.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared utilities for DERO MCP composite tools.
+ *
+ * A composite tool stitches several primitives (daemon RPC reads + bundled
+ * docs lookups) into one intent-shaped response. These utilities exist so
+ * every composite handles failures, latency tracking, and citation
+ * attachment the same way.
+ *
+ * Anything reused by more than one composite belongs here. Composite-local
+ * helpers (e.g. narrative builders specific to one composite's response
+ * shape) should live next to that composite, not in this file.
+ *
+ * See `docs/composites.md` for the design contract that governs which
+ * utilities live here and the gate every composite must satisfy before it
+ * lands on main.
+ */
+import { type DeroCitation } from '../citations.js';
+/**
+ * One step in a composite's internal chain.
+ *
+ * `required: true` aborts the chain if the step throws (use for liveness
+ * gates like `DERO.Ping`). `required: false` lets the chain continue with
+ * a degraded payload (use for enrichments like a mempool snapshot).
+ */
+export type ChainStep<T = unknown> = {
+    name: string;
+    required?: boolean;
+    fn: () => Promise<T>;
+};
+export type ChainStepResult = {
+    name: string;
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        message: string;
+    };
+    latencyMs: number;
+};
+export type ChainResult = {
+    results: ChainStepResult[];
+    haltedAt: string | null;
+    totalMs: number;
+};
+/**
+ * Run a chain of named primitive calls sequentially. Required-step
+ * failures halt the chain and record `haltedAt`; non-required failures
+ * are recorded and the chain continues. Step latencies are captured so
+ * composites can attach diagnostics to a degraded response.
+ */
+export declare function runChain(steps: readonly ChainStep[]): Promise<ChainResult>;
+/**
+ * Extract a single step's successful return value from a ChainResult.
+ * Returns null when the step was skipped (chain halted earlier), failed,
+ * or simply was not part of the chain.
+ */
+export declare function stepValue<T = unknown>(chain: ChainResult, name: string): T | null;
+/**
+ * Per-step latency map suitable for embedding in a composite's response
+ * under a `_diagnostics` field. Lets agents and operators see which step
+ * was slow without needing to instrument the host.
+ */
+export declare function stepLatencies(chain: ChainResult): Record<string, number>;
+/**
+ * Attach curated `related_docs` citations to a composite's payload.
+ * Mirrors how primitives attach citations so the response shape stays
+ * uniform across primitives and composites. Returns the payload
+ * unchanged when no curated docs are configured for the tool name.
+ */
+export declare function attachCitations<T extends Record<string, unknown>>(payload: T, toolName: string): T & {
+    related_docs?: DeroCitation[];
+};
+/**
+ * Shape used by the JSON-RPC `rpc` closure created in `src/server.ts`.
+ * Re-declared here so composites can take it as a dependency without
+ * importing from the server module (keeps the composite layer free of
+ * `McpServer` coupling).
+ */
+export type DeroDaemonRpc = <T = unknown>(method: string, params?: unknown) => Promise<T>;
+/**
+ * Loose representation of a `DERO.GetSC` response. Field names match the
+ * daemon's actual JSON keys observed on the public node. `uint64keys` is
+ * frequently absent (the daemon omits empty maps), so it is optional.
+ */
+export type DeroGetScResult = {
+    code?: string;
+    status?: string;
+    balance?: number;
+    balances?: Record<string, number>;
+    stringkeys?: Record<string, unknown>;
+    uint64keys?: Record<string, unknown>;
+    [k: string]: unknown;
+};
+export type DvmFunctionSignature = {
+    name: string;
+    args: string[];
+    returns: string;
+};
+export type DeroScSurface = {
+    functions: DvmFunctionSignature[];
+    stringkeys: string[];
+    uint64keys: string[];
+    balances: Record<string, number | string>;
+    raw_code_length: number;
+    has_code: boolean;
+};
+/**
+ * Convert a raw DERO.GetSC payload into a stable, agent-friendly surface.
+ *
+ * Behavior:
+ *  - Returns `functions: []` when `code` is missing or the regex finds
+ *    no Function declarations. Never throws on malformed code.
+ *  - Sorts `stringkeys` / `uint64keys` alphabetically for deterministic
+ *    output across invocations.
+ *  - `balances` is passed through unchanged so callers can render asset
+ *    balances; native DERO balance lives under `balance` on the raw
+ *    payload and is left for callers to decide whether to surface.
+ */
+export declare function extractScSurface(raw: DeroGetScResult | null | undefined): DeroScSurface;
+//# sourceMappingURL=_shared.d.ts.map

package/dist/composites/_shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../src/composites/_shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAAI;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAkChF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAIjF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,EAAE,CAAC,EACV,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG;IAAE,YAAY,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,CAIvC;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAUzF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,oBAAoB,EAAE,CAAA;IACjC,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAqBvF"}

package/dist/composites/_shared.js

@@ -0,0 +1,152 @@
+/**
+ * Shared utilities for DERO MCP composite tools.
+ *
+ * A composite tool stitches several primitives (daemon RPC reads + bundled
+ * docs lookups) into one intent-shaped response. These utilities exist so
+ * every composite handles failures, latency tracking, and citation
+ * attachment the same way.
+ *
+ * Anything reused by more than one composite belongs here. Composite-local
+ * helpers (e.g. narrative builders specific to one composite's response
+ * shape) should live next to that composite, not in this file.
+ *
+ * See `docs/composites.md` for the design contract that governs which
+ * utilities live here and the gate every composite must satisfy before it
+ * lands on main.
+ */
+import { relatedDocsFor } from '../citations.js';
+/**
+ * Run a chain of named primitive calls sequentially. Required-step
+ * failures halt the chain and record `haltedAt`; non-required failures
+ * are recorded and the chain continues. Step latencies are captured so
+ * composites can attach diagnostics to a degraded response.
+ */
+export async function runChain(steps) {
+    const results = [];
+    const startedAt = performance.now();
+    let haltedAt = null;
+    for (const step of steps) {
+        const stepStart = performance.now();
+        try {
+            const value = await step.fn();
+            results.push({
+                name: step.name,
+                ok: true,
+                value,
+                latencyMs: Math.round(performance.now() - stepStart),
+            });
+        }
+        catch (error) {
+            results.push({
+                name: step.name,
+                ok: false,
+                error: { message: error instanceof Error ? error.message : String(error) },
+                latencyMs: Math.round(performance.now() - stepStart),
+            });
+            if (step.required) {
+                haltedAt = step.name;
+                break;
+            }
+        }
+    }
+    return {
+        results,
+        haltedAt,
+        totalMs: Math.round(performance.now() - startedAt),
+    };
+}
+/**
+ * Extract a single step's successful return value from a ChainResult.
+ * Returns null when the step was skipped (chain halted earlier), failed,
+ * or simply was not part of the chain.
+ */
+export function stepValue(chain, name) {
+    const entry = chain.results.find((r) => r.name === name);
+    if (!entry || !entry.ok)
+        return null;
+    return entry.value;
+}
+/**
+ * Per-step latency map suitable for embedding in a composite's response
+ * under a `_diagnostics` field. Lets agents and operators see which step
+ * was slow without needing to instrument the host.
+ */
+export function stepLatencies(chain) {
+    const out = {};
+    for (const r of chain.results)
+        out[r.name] = r.latencyMs;
+    return out;
+}
+/**
+ * Attach curated `related_docs` citations to a composite's payload.
+ * Mirrors how primitives attach citations so the response shape stays
+ * uniform across primitives and composites. Returns the payload
+ * unchanged when no curated docs are configured for the tool name.
+ */
+export function attachCitations(payload, toolName) {
+    const related_docs = relatedDocsFor(toolName);
+    if (!related_docs || related_docs.length === 0)
+        return payload;
+    return { ...payload, related_docs };
+}
+// DVM-BASIC function declaration:
+//   Function Name(arg Type, ...) Uint64|String
+//
+// Anchored with `/m` so each line of source is examined independently.
+// Tolerant of leading whitespace and varied spacing inside the parens.
+const DVM_FUNCTION_REGEX = /^[ \t]*Function[ \t]+([A-Za-z_][A-Za-z0-9_]*)[ \t]*\(([^)]*)\)[ \t]*(Uint64|String)\b/gm;
+function parseDvmFunctions(code) {
+    const out = [];
+    const seen = new Set();
+    for (const match of code.matchAll(DVM_FUNCTION_REGEX)) {
+        const name = match[1];
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const argsRaw = (match[2] ?? '').trim();
+        const returns = match[3] ?? '';
+        const args = argsRaw.length === 0
+            ? []
+            : argsRaw
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+        out.push({ name, args, returns });
+    }
+    return out;
+}
+/**
+ * Convert a raw DERO.GetSC payload into a stable, agent-friendly surface.
+ *
+ * Behavior:
+ *  - Returns `functions: []` when `code` is missing or the regex finds
+ *    no Function declarations. Never throws on malformed code.
+ *  - Sorts `stringkeys` / `uint64keys` alphabetically for deterministic
+ *    output across invocations.
+ *  - `balances` is passed through unchanged so callers can render asset
+ *    balances; native DERO balance lives under `balance` on the raw
+ *    payload and is left for callers to decide whether to surface.
+ */
+export function extractScSurface(raw) {
+    const code = typeof raw?.code === 'string' ? raw.code : '';
+    const functions = code.length > 0 ? parseDvmFunctions(code) : [];
+    const stringkeys = raw?.stringkeys ? Object.keys(raw.stringkeys).sort() : [];
+    const uint64keys = raw?.uint64keys ? Object.keys(raw.uint64keys).sort() : [];
+    const balances = {};
+    if (raw?.balances && typeof raw.balances === 'object') {
+        for (const [scid, amount] of Object.entries(raw.balances)) {
+            if (typeof amount === 'number' || typeof amount === 'string') {
+                balances[scid] = amount;
+            }
+        }
+    }
+    return {
+        functions,
+        stringkeys,
+        uint64keys,
+        balances,
+        raw_code_length: code.length,
+        has_code: code.length > 0,
+    };
+}
+//# sourceMappingURL=_shared.js.map

package/dist/composites/_shared.js.map

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

package/dist/composites/diagnose-chain-health.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `diagnose_chain_health` — Phase C composite #1.
+ *
+ * Decorator-style composite that replaces four agent round-trips
+ * (`DERO.Ping` + `DERO.GetInfo` + `DERO.GetHeight` + `DERO.GetTxPool`) and
+ * the "what does this field mean?" docs lookup with a single narrative
+ * response carrying chain metadata, mempool snapshot, narrative summary,
+ * and curated docs citations.
+ *
+ * Design contract: `docs/composites.md` § 1 (lowest-risk composite, ships
+ * first to prove the composite plumbing — shared utils + flow test pattern
+ * + smoke assertions — end-to-end).
+ *
+ * Failure model:
+ *   - `DERO.Ping` is the only required step. Its failure halts the chain
+ *     and the handler throws so `withStructuredErrors` surfaces a
+ *     structured `RPC_UNREACHABLE` error.
+ *   - `DERO.GetInfo`, `DERO.GetHeight`, and `DERO.GetTxPool` are
+ *     non-required. Their failures degrade `status` to `partial` and
+ *     leave the corresponding response field null, but the composite
+ *     still returns a useful payload.
+ */
+import { z } from 'zod';
+import { type DeroDaemonRpc } from './_shared.js';
+export declare const diagnoseChainHealthInputSchema: {
+    readonly include_tx_pool: z.ZodOptional<z.ZodBoolean>;
+};
+type DiagnoseInput = {
+    include_tx_pool?: boolean;
+};
+type DiagnoseStatus = 'healthy' | 'lagging' | 'partial' | 'unreachable';
+type DiagnoseSignal = {
+    key: string;
+    value: string | number;
+    note?: string;
+};
+export declare function diagnoseChainHealth(rpc: DeroDaemonRpc, args: DiagnoseInput): Promise<{
+    status: DiagnoseStatus;
+    narrative: string;
+    signals: DiagnoseSignal[];
+    chain: {
+        topoheight: number;
+        stableheight: number | null;
+        height: number | null;
+        network: string | null;
+        version: string | null;
+        difficulty: string | number | null;
+        total_supply: string | number | null;
+    } | null;
+    mempool: {
+        pending: number;
+        sample: string[];
+    } | null;
+    _diagnostics: {
+        step_latency_ms: Record<string, number>;
+        total_ms: number;
+        halted_at: string | null;
+        include_tx_pool: boolean;
+    };
+} & {
+    related_docs?: import("../citations.js").DeroCitation[];
+}>;
+export {};
+//# sourceMappingURL=diagnose-chain-health.d.ts.map

package/dist/composites/diagnose-chain-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose-chain-health.d.ts","sourceRoot":"","sources":["../../src/composites/diagnose-chain-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AAErB,eAAO,MAAM,8BAA8B;;CAKjC,CAAA;AAEV,KAAK,aAAa,GAAG;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAyBlD,KAAK,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAEvE,KAAK,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AA4E5E,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;GA+DhF"}