ton-mesh-harness 0.13.0

package/dist/sdk/dns.d.ts

@@ -0,0 +1,125 @@
+/**
+ * SDK DNS-write integration. Pulls the substance of `cli/dns.ts` into the
+ * SDK so `deploy()` can emit `awaiting_signature → dns_signing →
+ * dns_confirmed → verifying` and the MCP server's `mesh_deploy`
+ * tool can complete a `domain`-bearing deploy without the CLI.
+ *
+ * Spec: docs/v0.8/mcp-core-requirements.md §F3 (event ordering),
+ * §F4 (cancellation), §F5 (ERR_DNS_*).
+ *
+ * NO `console.*` ANYWHERE IN THIS FILE — lint-enforced.
+ */
+import type { DeployEvent } from './schemas';
+export interface DnsWriteOptions {
+    /** `.ton` domain (e.g. `"myprotocol.ton"`). */
+    domain: string;
+    /** Bag id to publish in the `storage` DNS record. */
+    bag_id: string;
+    /** Optional 64-hex ADNL to publish as the `site` DNS record. */
+    site_adnl?: string | null;
+    /** Default false → mainnet. */
+    testnet?: boolean;
+    /**
+     * `Tonkeeper`, `MyTonWallet`, etc. — substring match against the
+     * TonConnect manifest's wallet list. Defaults to `Tonkeeper`.
+     */
+    connector_name?: string;
+    /**
+     * Optional Toncenter API key for the tx-hash resolve. The agentic path
+     * sources this from `~/.config/ton/config.json`; the TonConnect path has no
+     * such config, so without a key the resolve hits the public per-IP rate
+     * limit and `dns_tx_hash` may come back null even on a landed write. (#120)
+     */
+    toncenter_api_key?: string;
+}
+export interface DnsWriteControl {
+    signal?: AbortSignal;
+}
+/** Outcome the caller surfaces to the user / consumer. */
+export interface DnsWriteResult {
+    /**
+     * The signed message BOC returned by TonConnect. NOT the on-chain tx
+     * hash — that requires a follow-up TONAPI lookup. Surface as
+     * `message_boc` in `next_actions`, not as `dns_tx_hash`.
+     */
+    message_boc: string | null;
+    /**
+     * Real on-chain transaction hash, resolved via Toncenter v3's
+     * `transactionsByMessage` lookup (computed from the BOC cell hash).
+     * `null` if Toncenter's index hadn't caught up by the time the DNS
+     * poll succeeded — `message_boc` is still the indexable identifier.
+     */
+    tx_hash: string | null;
+    /**
+     * True when the tx-hash resolve was rate-limited / unauthorized by Toncenter
+     * (so `tx_hash` is null because the resolver never had a fair chance, not
+     * because the tx isn't indexed). Lets the caller hint "supply a Toncenter
+     * API key" rather than a silent null. (#120)
+     */
+    tx_resolve_throttled: boolean;
+    /**
+     * Whether a Toncenter API key backed the tx-hash resolve. When false and
+     * `tx_hash` is null, the public per-IP rate limit / slow index is the likely
+     * cause (not a hard 429), so the caller should advise setting a key — the
+     * #120 throttle flag only catches hard rate-limits, missing the common
+     * no-key case. (#132)
+     */
+    resolver_api_key_used: boolean;
+}
+/**
+ * Drive the TonConnect-mediated `.ton` DNS record write. Yields F3 event
+ * phases in order:
+ *   awaiting_signature (with signing_url) → dns_signing (after wallet
+ *   returns the signed message) → dns_confirmed (after TONAPI polling
+ *   sees the record) → verifying (TONAPI bag accessibility probe).
+ *
+ * The caller (deploy()) tracks `phase_at_cancel` / `bag_id` for F4
+ * cancellation accuracy; this generator throws bare ERR_CANCELLED on
+ * abort and the caller decorates with F4 `data`. `wallet.dispose()`
+ * always runs via finally so the TonConnect bridge listener never leaks.
+ */
+export declare function writeDnsRecord(opts: DnsWriteOptions, control?: DnsWriteControl): AsyncGenerator<DeployEvent, DnsWriteResult, void>;
+export interface DnsWriteAgenticOptions {
+    domain: string;
+    bag_id: string;
+    site_adnl?: string | null;
+    testnet?: boolean;
+    /** Optional override for the config file location. */
+    config_path?: string;
+    /** Optional wallet selector (id, name, or address). */
+    wallet_label?: string;
+}
+export interface DnsWriteAgenticControl {
+    signal?: AbortSignal;
+}
+export interface DnsWriteAgenticResult {
+    /** Normalized message hash (`0x<hex>`) returned by Toncenter. */
+    message_hash: string;
+    /** Wallet address that sent the batch (user-friendly). */
+    from_address: string;
+    /**
+     * Real on-chain transaction hash (`0x<hex>`), resolved via Toncenter's
+     * `transactionsByMessage` lookup. `null` if Toncenter's index hadn't
+     * caught up to the broadcast by the time the DNS poll succeeded —
+     * the message_hash is still the indexable identifier explorers use
+     * and is surfaced in `next_actions`.
+     */
+    tx_hash: string | null;
+    /** True when the tx-hash resolve was rate-limited / unauthorized (#120). */
+    tx_resolve_throttled: boolean;
+    /** Whether a Toncenter API key backed the tx-hash resolve (#132). */
+    resolver_api_key_used: boolean;
+}
+/**
+ * Drive the agentic-wallet-signed `.ton` DNS record write. No human in
+ * the loop — `awaiting_signature` is emitted informationally (so the
+ * F3 phase contract stays consistent across paths) and resolves in
+ * milliseconds because the signing key is read from disk.
+ *
+ * F4 cancellation: cancellation BEFORE `dns_signing` is safe
+ * (`may_have_published: false`); cancellation AFTER `dns_signing`
+ * implies the broadcast already left this process, so the caller
+ * decorates with `may_have_published: true` (same as the TonConnect
+ * path's post-awaiting_signature semantics).
+ */
+export declare function writeDnsRecordAgentic(opts: DnsWriteAgenticOptions, control?: DnsWriteAgenticControl): AsyncGenerator<DeployEvent, DnsWriteAgenticResult, void>;

package/dist/sdk/endpoints.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Single source of truth for external service URLs the SDK + CLI talk to.
+ *
+ * Centralised here so endpoint changes (e.g. Toncenter migrating to a
+ * new domain) flip in one place rather than three.
+ *
+ * NO `console.*` IN THIS FILE — lint-enforced.
+ */
+import type { AgenticNetwork } from './agentic-config';
+/**
+ * Toncenter v3 HTTP API base URLs. Used by `ApiClientToncenter` in
+ * `agentic-sign.ts` (signing path) and `resolve-tx.ts` (tx-hash
+ * lookup). Mirror the defaults `@ton/mcp` itself uses.
+ */
+export declare const TONCENTER_ENDPOINTS: Record<AgenticNetwork, string>;
+/**
+ * Lift our boolean `testnet` flag (the CLI / SDK input convention) to
+ * the string-discriminated `AgenticNetwork` (the config / endpoint
+ * key). `testnet === true` → `'testnet'`; anything else → `'mainnet'`.
+ *
+ * Hoisted so we don't repeat the same ternary in N places.
+ */
+export declare function networkFromTestnetFlag(testnet: boolean | undefined): AgenticNetwork;
+/**
+ * Build a tonviewer.com transaction URL. Accepts hashes with or without
+ * the `0x` prefix; emits the canonical no-prefix form tonviewer expects.
+ *
+ * Note: tonviewer.com is the mainnet UI; testnet.tonviewer.com is the
+ * testnet UI. Caller is expected to know which network the hash belongs
+ * to (we don't smuggle that into the hash itself).
+ */
+export declare function tonviewerTxUrl(txHash: string, testnet?: boolean): string;
+/**
+ * The ton.run SITE gateway URL for a `.ton` domain. The gateway resolves the
+ * domain's `site` record (an ADNL identity) over RLDP, so this opens in an
+ * ordinary browser once that record is on chain AND a reachable rldp-http-proxy
+ * backs the ADNL (verified 2026-06-22: foundation.ton.run → 200). Only
+ * meaningful for a deploy that writes a `site` record — a storage-only domain
+ * has no ADNL to resolve and 404s — so callers must emit it ONLY after a site
+ * record is signed, or label it as a would-be URL for a storage-only deploy
+ * (see `storageOnlyViewabilityHint`). (#70, #118)
+ */
+export declare function siteGatewayUrl(domain: string): string;
+/**
+ * Human/agent-facing breadcrumb for a STORAGE-ONLY domain deploy (the only
+ * kind `deploy()` does — it never writes a `site`/ADNL record). Explains why
+ * `<domain>.ton` is not browser-openable via the ton.run RLDP gateway, what
+ * URL it WOULD resolve at once a site record + reachable gateway exist, and
+ * how to get there. When the bag is no longer seeded (`seed_status==='stopped'`)
+ * it also notes the content is not retrievable until a reachable node seeds it.
+ * (#118 — the deploy result carried no viewability signal, so a "green" deploy
+ * could 404 everywhere with no breadcrumb.)
+ */
+export declare function storageOnlyViewabilityHint(args: {
+    domain: string;
+    seedStatus: 'seeding' | 'stopped';
+    testnet?: boolean;
+}): string;

package/dist/sdk/json-schemas.d.ts

@@ -0,0 +1,38 @@
+/**
+ * JSON Schema export of the public zod schemas — what the MCP `tools/list`
+ * response will surface to agent clients.
+ *
+ * The schemas are generated at module-load time and frozen so a snapshot
+ * test ([V1] #11 / `test/sdk-json-schemas.test.ts`) can lock the contract
+ * shape: any accidental drift in zod definitions fails the snapshot.
+ *
+ * Run `bunx vitest run test/sdk-json-schemas.test.ts -u` to update the
+ * snapshot when an intentional schema change ships.
+ */
+/**
+ * Opaque JSON Schema type. We deliberately don't inline the full structural
+ * type from `zod-to-json-schema` — its inferred shape against our deeply
+ * nested discriminated unions (DeployEventSchema has 9 phase variants)
+ * caused tsc to OOM at type-check time.
+ */
+export type JsonSchema = Record<string, unknown>;
+export interface ToolJsonSchema {
+    /** Stable tool name as it appears in MCP `tools/list`. */
+    name: string;
+    /** Generated JSON Schema for the tool's input. */
+    input: JsonSchema;
+    /** Generated JSON Schema for the tool's output (success path). */
+    output: JsonSchema;
+}
+declare const SCHEMA_VERSION = "0.13.0";
+export declare const MESH_DEPLOY_TOOL: ToolJsonSchema;
+export declare const MESH_CHECK_ENV_TOOL: ToolJsonSchema;
+export declare const MESH_STATUS_TOOL: ToolJsonSchema;
+export declare const MESH_SITE_RECORD_TOOL: ToolJsonSchema;
+export declare const ALL_TOOLS: readonly ToolJsonSchema[];
+export declare const SUPPLEMENTARY_SCHEMAS: {
+    WalletSpec: JsonSchema;
+    DeployEvent: JsonSchema;
+    ErrorPayload: JsonSchema;
+};
+export { SCHEMA_VERSION };

package/dist/sdk/log.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tiny stderr-only structured logger. Honours the `DEBUG` env var with
+ * `debug`-compatible glob grammar so contributors familiar with that
+ * library find it ergonomic, but no runtime dep on `debug` itself.
+ *
+ * Grammar (matches `debug` semantics):
+ *   DEBUG="*"                       — all namespaces enabled
+ *   DEBUG="mesh:*"              — every mesh:<sub> namespace
+ *   DEBUG="mesh:deploy,mesh:dns"
+ *                                   — specific namespaces only
+ *   DEBUG=""  | unset                — fully disabled
+ *   DEBUG="*,-mesh:resolve-tx"  — wildcard with exclusion
+ *
+ * Output always goes to STDERR. Never stdout — the CLI's `--json-output`
+ * mode requires stdout to remain valid JSON, and the MCP server's stdio
+ * transport requires stdout to be JSON-RPC frames only. Both would break
+ * if logger output landed on stdout. Tests cover this invariant.
+ *
+ * NO `console.*` IN THIS FILE — uses `process.stderr.write` directly.
+ */
+export interface SdkLogger {
+    /** Always emitted when the namespace is enabled. */
+    debug(message: string, data?: unknown): void;
+    /** Always emitted when the namespace is enabled. */
+    info(message: string, data?: unknown): void;
+    /** Always emitted when the namespace is enabled. */
+    warn(message: string, data?: unknown): void;
+}
+/**
+ * Build a logger for `namespace`. The enabled state is computed ONCE at
+ * construction time (it doesn't react to runtime env changes). The
+ * returned logger is cheap when disabled — each method short-circuits
+ * without formatting the message.
+ *
+ * Convention: namespaces follow `mesh:<area>` where area mirrors
+ * the SDK module name (`deploy`, `dns`, `agentic-sign`, `resolve-tx`).
+ */
+export declare function createSdkLogger(namespace: string): SdkLogger;
+/**
+ * Probe variant — exposed for tests so they can inject a controlled
+ * `debugVar` instead of mutating `process.env`.
+ */
+export declare function isNamespaceEnabledForTesting(namespace: string, debugVar: string | undefined): boolean;

package/dist/sdk/provenance.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Provenance manifest (#34) — a signed claim the deployer publishes inside
+ * the bag at `.well-known/ton-deploy.json`, so a verifier can confirm
+ * "this `.ton` domain was deployed by this wallet, with this kit, on this
+ * date".
+ *
+ * Design notes:
+ *  - The claim deliberately does NOT carry `bag_id` (it lives inside the
+ *    bag, whose id is the content hash — including bag_id would be
+ *    circular) nor `dns_tx_hash` (not known until after the bag exists).
+ *    The bag_id ↔ domain binding is provided by the on-chain DNS record,
+ *    which the deployer's wallet signed in the change_dns_record tx.
+ *  - Signing is feasible only on the agentic path (we hold an Ed25519
+ *    operator/standard key). TonConnect can't sign arbitrary bytes, so a
+ *    TonConnect deploy emits an UNSIGNED manifest (`signed: false`).
+ *
+ * NO `console.*` IN THIS FILE — lint-enforced (src/sdk/*).
+ */
+export declare const PROVENANCE_MANIFEST_VERSION = 1;
+export declare const PROVENANCE_KIT_NAME = "ton-mesh-harness";
+export declare const PROVENANCE_RELPATH = ".well-known/ton-deploy.json";
+/** The signed part of the manifest — the immutable, pre-bag-creation claim. */
+export interface ProvenanceClaim {
+    manifest_version: number;
+    kit: string;
+    kit_version: string;
+    domain: string;
+    /** Deployer wallet address; null when unknown at write time (TonConnect). */
+    deployer_address: string | null;
+    /** ISO-8601 UTC. */
+    deployed_at: string;
+}
+export interface ProvenanceManifest extends ProvenanceClaim {
+    signed: boolean;
+    /** Ed25519 public key (hex) that signed the claim; null when unsigned. */
+    public_key: string | null;
+    /** Ed25519 detached signature over the canonical claim (base64); null when unsigned. */
+    signature: string | null;
+}
+/**
+ * Deterministic serialization of the claim — sorted keys, no insignificant
+ * whitespace — so signer and verifier hash byte-identical input.
+ */
+export declare function canonicalizeClaim(claim: ProvenanceClaim): string;
+/**
+ * Extract a 32-byte Ed25519 seed from a hex private key. Accepts a 32-byte
+ * (64 hex) seed or a 64-byte (128 hex) combined keypair — the seed is the
+ * first 32 bytes either way (matches @ton/mcp's convention).
+ */
+export declare function seedFromHex(privateKeyHex: string): Buffer;
+/** Build a manifest from a claim; sign it if a seed is provided. */
+export declare function buildManifest(claim: ProvenanceClaim, seed?: Buffer | null): ProvenanceManifest;
+export interface ProvenanceVerifyResult {
+    signed: boolean;
+    valid: boolean;
+    claim: ProvenanceClaim;
+    reason?: string;
+}
+/** Verify a manifest's signature (if any) against its embedded public key. */
+export declare function verifyManifest(manifest: ProvenanceManifest): ProvenanceVerifyResult;
+/** Write the manifest into `<sourceDir>/.well-known/ton-deploy.json`. */
+export declare function writeManifest(sourceDir: string, manifest: ProvenanceManifest): string;
+export interface EmitProvenanceParams {
+    sourceDir: string;
+    domain: string;
+    walletKind: 'tonconnect' | 'agentic';
+    testnet: boolean;
+    /** For the agentic path: how to locate the signing wallet. */
+    agentic?: {
+        config_path?: string;
+        wallet_label?: string;
+    };
+}
+export interface EmitProvenanceResult {
+    written: boolean;
+    file?: string;
+    signed?: boolean;
+    /** Set when `written` is false — the (non-fatal) reason emission was skipped. */
+    reason?: string;
+}
+/**
+ * Best-effort provenance emission shared by the SDK deploy() hook and the
+ * CLI adapter. NEVER throws — any failure returns `{ written: false,
+ * reason }`. Signs on the agentic path (operator/standard key); emits an
+ * unsigned claim on TonConnect (no address known, can't sign).
+ */
+export declare function emitProvenanceManifest(params: EmitProvenanceParams): EmitProvenanceResult;

package/dist/sdk/resolve-tx.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Resolve the on-chain transaction hash for a broadcast we already sent.
+ *
+ * `agenticSignAndSend` returns Toncenter's normalized external-in
+ * *message* hash. That's NOT the transaction hash explorers display.
+ * To upgrade `dns_tx_hash` from null → real value, we look up the
+ * resulting tx via Toncenter v3's `/api/v3/transactionsByMessage`
+ * endpoint. Best-effort: returns null on timeout / 404 / network error
+ * rather than throwing — the caller decides whether to surface null
+ * with a fix-hint or wait longer.
+ *
+ * Toncenter's tx index OFTEN catches up within ~5-15s of broadcast, but
+ * NOT always before TONAPI's DNS-record poll succeeds: on 2026-06-25 a
+ * live mainnet deploy saw TONAPI propagate the storage record FIRST, so
+ * the resolve had not finished when the DNS poll returned (#117). The
+ * resolve runs in parallel with the propagation poll and adds latency
+ * only when still pending at the grace cutoff (`TX_HASH_GRACE_MS` in
+ * dns-helpers.ts). Because the order is not guaranteed, `dns_tx_hash` is
+ * best-effort and may be null even on a fully-successful deploy.
+ *
+ * Spec: docs/v0.8/mcp-core-requirements.md §F2 (DeployResult.dns_tx_hash).
+ *
+ * NO `console.*` IN THIS FILE — lint-enforced.
+ */
+import type { AgenticNetwork } from './agentic-config';
+/**
+ * Compute the normalized external-in message hash per TEP-467 — the
+ * `hash_norm` value Toncenter indexes (NOT the raw cell hash). For an
+ * `external-in` message, normalization zeros `src` (→ addr_none) and
+ * `import_fee` (→ 0) before hashing. Other fields (dest, init, body)
+ * are preserved.
+ *
+ * Spec: https://docs.ton.org/ecosystem/ton-connect/message-lookup
+ *
+ * @returns hex (no `0x`), or `null` if the BOC isn't a parseable
+ *   external-in message.
+ */
+export declare function normalizedExternalInHashHex(bocBase64: string): string | null;
+export interface ResolveTxOptions {
+    /** Total time to keep polling. Default 60s. */
+    timeout_ms?: number;
+    /** Pause between polls. Default 2s. */
+    interval_ms?: number;
+    /** Cancel the resolve early. */
+    signal?: AbortSignal;
+    /** Optional Toncenter API key (lifts the per-IP rate limit). */
+    toncenter_api_key?: string;
+}
+/** Outcome of a tx-hash resolve. */
+export interface TxHashResolution {
+    /** Tx hash as `0x<hex>` if Toncenter indexed the message, else null. */
+    txHash: string | null;
+    /**
+     * True when the resolve kept hitting auth / rate-limit / 5xx responses and
+     * never got a fair chance — as opposed to the tx simply not being indexed
+     * yet. Only meaningful when `txHash` is null; lets the caller surface "add a
+     * Toncenter API key" instead of an indistinguishable silent null. (#120)
+     */
+    throttled: boolean;
+}
+/**
+ * Look up the transaction whose inbound message has the given hash.
+ *
+ * @param messageHashHex Normalized message hash returned by
+ *   `ApiClientToncenter.sendBoc()` — either `0x<hex>` or bare hex.
+ * @returns `{ txHash, throttled }` — `txHash` is `0x<hex>` if Toncenter has
+ *   indexed the message, else null (with `throttled` distinguishing a
+ *   rate-limited/unauthorized resolve from a not-yet-indexed one).
+ */
+export declare function resolveTxHashFromMessageHash(messageHashHex: string, network: AgenticNetwork, opts?: ResolveTxOptions): Promise<TxHashResolution>;