orbit-bus 0.1.1

package/dist/src/commands/cell.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { startEchoDaemon } from "../echo/daemon.js";
+import { connectEchoClient } from "../echo/client.js";
+import { ensureDir, randomId } from "../util.js";
+import { runCellGateway } from "../cell/gateway.js";
+import { resolveCellRoutingPlan } from "../cell/routing.js";
+import { buildCellRoutesTemplate } from "../cell/template.js";
+function cellStatusPath(config) {
+    return path.join(config.dataDir, "cell", "status.json");
+}
+function parseChannels(args) {
+    const channels = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === "--channel" && i + 1 < args.length)
+            channels.push(args[i + 1]);
+    }
+    return channels;
+}
+function argValue(args, flag) {
+    const i = args.indexOf(flag);
+    if (i >= 0 && i + 1 < args.length)
+        return args[i + 1];
+    return undefined;
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseMode(value) {
+    if (value === "local_only" || value === "replicate" || value === "global_only")
+        return value;
+    return "replicate";
+}
+function parseProfile(value) {
+    if (value === "high_throughput")
+        return "high_throughput";
+    return "production";
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function fetchEchoStats(socketPath, host, port) {
+    try {
+        const client = await connectEchoClient({ socketPath, host, port });
+        const response = await new Promise((resolve) => {
+            client.onLine((line) => {
+                const msg = JSON.parse(line);
+                if (!msg.ok || msg.type !== "stats") {
+                    resolve(null);
+                    client.close();
+                    return;
+                }
+                resolve(msg.channels ?? []);
+                client.close();
+            });
+            client.send({ type: "stats" });
+        });
+        return response;
+    }
+    catch {
+        return null;
+    }
+}
+export async function cmdCell(config, logger, args) {
+    const sub = args[0];
+    if (!sub || sub === "--help" || sub === "-h") {
+        process.stdout.write(`orbit cell usage:\n  orbit cell init [--out ./examples/cell.routes.production.json] [--profile production|high_throughput] [--subject-prefix orbit] [--force]\n  orbit cell start [--socket /tmp/echocore.sock] [--tcp-port 7777] [--gateway] [--cell-id <id>] [--routes @routes.json] [--channel <name> ...] [--mode local_only|replicate|global_only]\n  orbit cell gateway [--socket /tmp/echocore.sock] [--cell-id <id>] [--routes @routes.json] [--channel <name> ...] [--mode local_only|replicate|global_only]\n  orbit cell status [--socket /tmp/echocore.sock]\n`);
+        return;
+    }
+    if (sub === "init") {
+        const out = argValue(args, "--out") ?? path.join(process.cwd(), "examples", "cell.routes.production.json");
+        const profile = parseProfile(argValue(args, "--profile"));
+        const subjectPrefix = argValue(args, "--subject-prefix") ?? config.routing.subjectPrefix;
+        const force = hasFlag(args, "--force");
+        if (fs.existsSync(out) && !force) {
+            throw new Error(`output exists: ${out} (use --force to overwrite)`);
+        }
+        const template = buildCellRoutesTemplate(profile, subjectPrefix);
+        ensureDir(path.dirname(out));
+        fs.writeFileSync(out, `${JSON.stringify(template, null, 2)}\n`, "utf-8");
+        process.stdout.write(`${JSON.stringify({ ok: true, file: out, profile, routes: Object.keys(template).length }, null, 2)}\n`);
+        return;
+    }
+    if (sub === "start") {
+        const socketPath = argValue(args, "--socket") ?? path.join(config.dataDir, "echocore.sock");
+        const tcpPort = argValue(args, "--tcp-port") ? Number(argValue(args, "--tcp-port")) : undefined;
+        const cellId = argValue(args, "--cell-id") ?? `${os.hostname()}-${randomId().slice(0, 8)}`;
+        const routesFileArg = argValue(args, "--routes");
+        const routesFile = routesFileArg?.startsWith("@") ? routesFileArg.slice(1) : routesFileArg;
+        const channels = parseChannels(args);
+        const mode = parseMode(argValue(args, "--mode"));
+        const gateway = hasFlag(args, "--gateway") || hasFlag(args, "--with-gateway");
+        const routing = resolveCellRoutingPlan(config, { routesFile, channels, defaultMode: mode });
+        const daemon = await startEchoDaemon({ socketPath, tcpPort });
+        const statusPath = cellStatusPath(config);
+        ensureDir(path.dirname(statusPath));
+        const status = {
+            cellId,
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+            socketPath: daemon.socketPath,
+            tcpPort: daemon.tcpPort,
+            gateway,
+            source: routing.source,
+            routes: routing.routes.map((route) => ({ channel: route.channel, mode: route.mode, subject: route.subject }))
+        };
+        fs.writeFileSync(statusPath, `${JSON.stringify(status, null, 2)}\n`, "utf-8");
+        process.stdout.write(`${JSON.stringify({ ok: true, mode: "cell", daemon: { socketPath: daemon.socketPath, tcpPort: daemon.tcpPort }, gateway, cellId }, null, 2)}\n`);
+        if (gateway) {
+            await runCellGateway(config, logger, {
+                socketPath: daemon.socketPath,
+                port: daemon.tcpPort,
+                cellId,
+                routes: routing.routes,
+                fromLatest: true
+            });
+            return;
+        }
+        const shutdown = async () => {
+            await daemon.close();
+            process.exit(0);
+        };
+        process.once("SIGINT", () => {
+            void shutdown();
+        });
+        process.once("SIGTERM", () => {
+            void shutdown();
+        });
+        await new Promise(() => undefined);
+        return;
+    }
+    if (sub === "gateway") {
+        const socketPath = argValue(args, "--socket") ?? path.join(config.dataDir, "echocore.sock");
+        const routesFileArg = argValue(args, "--routes");
+        const routesFile = routesFileArg?.startsWith("@") ? routesFileArg.slice(1) : routesFileArg;
+        const channels = parseChannels(args);
+        const mode = parseMode(argValue(args, "--mode"));
+        const cellId = argValue(args, "--cell-id") ?? `${os.hostname()}-${randomId().slice(0, 8)}`;
+        const host = argValue(args, "--host");
+        const port = argValue(args, "--port") ? Number(argValue(args, "--port")) : undefined;
+        const routing = resolveCellRoutingPlan(config, { routesFile, channels, defaultMode: mode });
+        process.stdout.write(`${JSON.stringify({ ok: true, mode: "gateway", cellId, socketPath, routes: routing.routes.map((route) => ({ channel: route.channel, mode: route.mode, subject: route.subject })) }, null, 2)}\n`);
+        await runCellGateway(config, logger, {
+            socketPath,
+            host,
+            port,
+            cellId,
+            routes: routing.routes,
+            fromLatest: true
+        });
+        return;
+    }
+    if (sub === "status") {
+        const statusPath = cellStatusPath(config);
+        const saved = fs.existsSync(statusPath)
+            ? JSON.parse(fs.readFileSync(statusPath, "utf-8"))
+            : null;
+        const socketPath = argValue(args, "--socket") ?? saved?.socketPath;
+        const host = argValue(args, "--host");
+        const port = argValue(args, "--port") ? Number(argValue(args, "--port")) : saved?.tcpPort;
+        const stats = await fetchEchoStats(socketPath, host, port);
+        process.stdout.write(`${JSON.stringify({
+            ok: true,
+            status: saved
+                ? {
+                    ...saved,
+                    alive: isPidAlive(saved.pid)
+                }
+                : null,
+            echo: {
+                endpoint: socketPath ?? (port ? `${host ?? "127.0.0.1"}:${port}` : null),
+                connected: stats !== null,
+                channels: stats
+            }
+        }, null, 2)}\n`);
+        return;
+    }
+    throw new Error(`unknown cell subcommand: ${sub}`);
+}

package/dist/src/commands/context.d.ts

@@ -0,0 +1,9 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdContext(config: OrbitConfig, _logger: Logger, opts: {
+    subcommand?: string;
+    name?: string;
+    natsUrl?: string;
+    timeoutMs?: number;
+    retries?: number;
+}): void;

package/dist/src/commands/context.js

@@ -0,0 +1,71 @@
+import { USER_CONFIG_PATH, readUserConfigRaw, writeUserConfigRaw } from "../config.js";
+import { OrbitError } from "../errors.js";
+function readContexts(config) {
+    const raw = readUserConfigRaw();
+    const contexts = raw.contexts ?? {
+        default: {
+            natsUrl: config.natsUrl,
+            requestTimeoutMs: config.requestTimeoutMs,
+            retries: config.retries
+        }
+    };
+    const active = raw.activeContext ?? config.activeContext ?? "default";
+    return { active, contexts };
+}
+export function cmdContext(config, _logger, opts) {
+    const { active, contexts } = readContexts(config);
+    const sub = opts.subcommand ?? "current";
+    if (sub === "list") {
+        process.stdout.write(`${JSON.stringify({
+            active,
+            config_file: USER_CONFIG_PATH,
+            contexts
+        }, null, 2)}\n`);
+        return;
+    }
+    if (sub === "current") {
+        process.stdout.write(`${JSON.stringify({
+            active,
+            value: contexts[active]
+        }, null, 2)}\n`);
+        return;
+    }
+    if (sub === "use") {
+        if (!opts.name)
+            throw new OrbitError("BAD_ARGS", "context use requires context name");
+        if (!contexts[opts.name])
+            throw new OrbitError("BAD_ARGS", `context ${opts.name} does not exist`);
+        const raw = readUserConfigRaw();
+        writeUserConfigRaw({
+            ...raw,
+            activeContext: opts.name,
+            contexts
+        });
+        process.stdout.write(`${JSON.stringify({ ok: true, activeContext: opts.name }, null, 2)}\n`);
+        return;
+    }
+    if (sub === "set") {
+        if (!opts.name)
+            throw new OrbitError("BAD_ARGS", "context set requires context name");
+        const base = contexts[opts.name] ?? contexts[active] ?? {
+            natsUrl: config.natsUrl,
+            requestTimeoutMs: config.requestTimeoutMs,
+            retries: config.retries
+        };
+        const next = {
+            natsUrl: opts.natsUrl ?? base.natsUrl,
+            requestTimeoutMs: opts.timeoutMs ?? base.requestTimeoutMs,
+            retries: opts.retries ?? base.retries
+        };
+        const updated = { ...contexts, [opts.name]: next };
+        const raw = readUserConfigRaw();
+        writeUserConfigRaw({
+            ...raw,
+            activeContext: raw.activeContext ?? active,
+            contexts: updated
+        });
+        process.stdout.write(`${JSON.stringify({ ok: true, name: opts.name, value: next }, null, 2)}\n`);
+        return;
+    }
+    throw new OrbitError("BAD_ARGS", `unknown context subcommand: ${sub}`);
+}

package/dist/src/commands/dlq_inspect.d.ts

@@ -0,0 +1,11 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdDlqInspect(config: OrbitConfig, _logger: Logger, opts: {
+    dlqTopic: string;
+    streamName?: string;
+    limit?: number;
+    fromTs?: string;
+    toTs?: string;
+    errorCode?: string;
+    sourceConsumer?: string;
+}): Promise<void>;

package/dist/src/commands/dlq_inspect.js

@@ -0,0 +1,86 @@
+import { closeBus, connectBus, decodeJson } from "../nats.js";
+import { defaultDurableStreamName } from "../jetstream_durable.js";
+import { extractDlqMeta, matchesDlqFilter, parseOptionalIsoTs } from "../dlq.js";
+function asStoredMessage(raw) {
+    const msg = raw?.message ?? raw;
+    if (!msg)
+        return null;
+    const seq = typeof msg.seq === "number" ? msg.seq : undefined;
+    const subject = typeof msg.subject === "string" ? msg.subject : undefined;
+    const data = msg.data;
+    if (seq === undefined || !subject || !data)
+        return null;
+    return {
+        seq,
+        subject,
+        time: typeof msg.time === "string" ? msg.time : undefined,
+        data
+    };
+}
+export async function cmdDlqInspect(config, _logger, opts) {
+    const nc = await connectBus(config.natsUrl);
+    const jsm = await nc.jetstreamManager();
+    const streamName = opts.streamName ?? defaultDurableStreamName(opts.dlqTopic);
+    const limit = Math.max(1, opts.limit ?? 100);
+    const filter = {
+        fromTsMs: parseOptionalIsoTs(opts.fromTs, "--from-ts"),
+        toTsMs: parseOptionalIsoTs(opts.toTs, "--to-ts"),
+        errorCode: opts.errorCode,
+        sourceConsumer: opts.sourceConsumer
+    };
+    let info;
+    try {
+        info = await jsm.streams.info(streamName);
+    }
+    catch {
+        await closeBus(config.natsUrl);
+        process.stdout.write(`${JSON.stringify({ ok: true, stream: streamName, scanned: 0, matched: 0, entries: [] }, null, 2)}\n`);
+        return;
+    }
+    const firstSeq = Number(info?.state?.first_seq ?? 0);
+    const lastSeq = Number(info?.state?.last_seq ?? 0);
+    let scanned = 0;
+    let matched = 0;
+    const entries = [];
+    for (let seq = firstSeq; seq <= lastSeq; seq += 1) {
+        if (entries.length >= limit)
+            break;
+        let storedRaw;
+        try {
+            storedRaw = await jsm.streams.getMessage(streamName, { seq });
+        }
+        catch {
+            continue;
+        }
+        const stored = asStoredMessage(storedRaw);
+        if (!stored)
+            continue;
+        if (stored.subject !== opts.dlqTopic)
+            continue;
+        scanned += 1;
+        let decoded = null;
+        try {
+            decoded = decodeJson(stored.data);
+        }
+        catch {
+            decoded = null;
+        }
+        const meta = extractDlqMeta(decoded, stored.time);
+        if (!matchesDlqFilter(meta, filter))
+            continue;
+        matched += 1;
+        entries.push({
+            seq: stored.seq,
+            subject: stored.subject,
+            failed_at: meta.failedAt,
+            source_topic: meta.sourceTopic,
+            source_stream: meta.sourceStream,
+            source_consumer: meta.sourceConsumer,
+            delivery_count: meta.deliveryCount,
+            error_code: meta.errorCode,
+            error: meta.error
+        });
+    }
+    await closeBus(config.natsUrl);
+    process.stdout.write(`${JSON.stringify({ ok: true, stream: streamName, scanned, matched, entries }, null, 2)}\n`);
+}

package/dist/src/commands/dlq_purge.d.ts

@@ -0,0 +1,12 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdDlqPurge(config: OrbitConfig, _logger: Logger, opts: {
+    dlqTopic: string;
+    streamName?: string;
+    limit?: number;
+    dryRun?: boolean;
+    fromTs?: string;
+    toTs?: string;
+    errorCode?: string;
+    sourceConsumer?: string;
+}): Promise<void>;

package/dist/src/commands/dlq_purge.js

@@ -0,0 +1,84 @@
+import { closeBus, connectBus, decodeJson } from "../nats.js";
+import { defaultDurableStreamName } from "../jetstream_durable.js";
+import { extractDlqMeta, matchesDlqFilter, parseOptionalIsoTs } from "../dlq.js";
+function asStoredMessage(raw) {
+    const msg = raw?.message ?? raw;
+    if (!msg)
+        return null;
+    const seq = typeof msg.seq === "number" ? msg.seq : undefined;
+    const subject = typeof msg.subject === "string" ? msg.subject : undefined;
+    const data = msg.data;
+    if (seq === undefined || !subject || !data)
+        return null;
+    return {
+        seq,
+        subject,
+        time: typeof msg.time === "string" ? msg.time : undefined,
+        data
+    };
+}
+export async function cmdDlqPurge(config, _logger, opts) {
+    const nc = await connectBus(config.natsUrl);
+    const jsm = await nc.jetstreamManager();
+    const streamName = opts.streamName ?? defaultDurableStreamName(opts.dlqTopic);
+    const limit = Math.max(0, opts.limit ?? 0);
+    const filter = {
+        fromTsMs: parseOptionalIsoTs(opts.fromTs, "--from-ts"),
+        toTsMs: parseOptionalIsoTs(opts.toTs, "--to-ts"),
+        errorCode: opts.errorCode,
+        sourceConsumer: opts.sourceConsumer
+    };
+    let info;
+    try {
+        info = await jsm.streams.info(streamName);
+    }
+    catch {
+        await closeBus(config.natsUrl);
+        process.stdout.write(`${JSON.stringify({ ok: true, stream: streamName, scanned: 0, matched: 0, purged: 0, dry_run: Boolean(opts.dryRun) }, null, 2)}\n`);
+        return;
+    }
+    const firstSeq = Number(info?.state?.first_seq ?? 0);
+    const lastSeq = Number(info?.state?.last_seq ?? 0);
+    let scanned = 0;
+    let matched = 0;
+    let purged = 0;
+    for (let seq = firstSeq; seq <= lastSeq; seq += 1) {
+        if (limit > 0 && purged >= limit)
+            break;
+        let storedRaw;
+        try {
+            storedRaw = await jsm.streams.getMessage(streamName, { seq });
+        }
+        catch {
+            continue;
+        }
+        const stored = asStoredMessage(storedRaw);
+        if (!stored)
+            continue;
+        if (stored.subject !== opts.dlqTopic)
+            continue;
+        scanned += 1;
+        let decoded = null;
+        try {
+            decoded = decodeJson(stored.data);
+        }
+        catch {
+            decoded = null;
+        }
+        const meta = extractDlqMeta(decoded, stored.time);
+        if (!matchesDlqFilter(meta, filter))
+            continue;
+        matched += 1;
+        if (opts.dryRun)
+            continue;
+        try {
+            await jsm.streams.deleteMessage(streamName, seq);
+            purged += 1;
+        }
+        catch {
+            // best effort purge
+        }
+    }
+    await closeBus(config.natsUrl);
+    process.stdout.write(`${JSON.stringify({ ok: true, stream: streamName, scanned, matched, purged, dry_run: Boolean(opts.dryRun) }, null, 2)}\n`);
+}

package/dist/src/commands/dlq_replay.d.ts

@@ -0,0 +1,15 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function replayBytesFromDlqPayload(input: unknown, fallback: Uint8Array): Uint8Array;
+export declare function cmdDlqReplay(config: OrbitConfig, _logger: Logger, opts: {
+    dlqTopic: string;
+    targetTopic: string;
+    limit?: number;
+    streamName?: string;
+    durablePublish?: boolean;
+    purgeReplayed?: boolean;
+    fromTs?: string;
+    toTs?: string;
+    errorCode?: string;
+    sourceConsumer?: string;
+}): Promise<void>;

package/dist/src/commands/dlq_replay.js

@@ -0,0 +1,127 @@
+import { closeBus, connectBus, decodeJson, encodeJson, publishSubject } from "../nats.js";
+import { defaultDurableStreamName } from "../jetstream_durable.js";
+import { extractDlqMeta, matchesDlqFilter, parseOptionalIsoTs } from "../dlq.js";
+import { randomId } from "../util.js";
+function asStoredMessage(raw) {
+    const msg = raw?.message ?? raw;
+    if (!msg)
+        return null;
+    const seq = typeof msg.seq === "number" ? msg.seq : undefined;
+    const subject = typeof msg.subject === "string" ? msg.subject : undefined;
+    const data = msg.data;
+    if (seq === undefined || !subject || !data)
+        return null;
+    return {
+        seq,
+        subject,
+        time: typeof msg.time === "string" ? msg.time : undefined,
+        data
+    };
+}
+export function replayBytesFromDlqPayload(input, fallback) {
+    if (!input || typeof input !== "object")
+        return fallback;
+    const raw = input;
+    const original = raw.original;
+    if (original && typeof original.base64 === "string") {
+        return Buffer.from(original.base64, "base64");
+    }
+    if (typeof raw.raw_base64 === "string") {
+        return Buffer.from(raw.raw_base64, "base64");
+    }
+    if ("payload" in raw) {
+        return encodeJson(raw.payload);
+    }
+    return fallback;
+}
+export async function cmdDlqReplay(config, _logger, opts) {
+    const nc = await connectBus(config.natsUrl);
+    const jsm = await nc.jetstreamManager();
+    const streamName = opts.streamName ?? defaultDurableStreamName(opts.dlqTopic);
+    const limit = Math.max(0, opts.limit ?? 0);
+    const durablePublish = opts.durablePublish ?? true;
+    const filter = {
+        fromTsMs: parseOptionalIsoTs(opts.fromTs, "--from-ts"),
+        toTsMs: parseOptionalIsoTs(opts.toTs, "--to-ts"),
+        errorCode: opts.errorCode,
+        sourceConsumer: opts.sourceConsumer
+    };
+    let info;
+    try {
+        info = await jsm.streams.info(streamName);
+    }
+    catch {
+        await closeBus(config.natsUrl);
+        process.stdout.write(`${JSON.stringify({ ok: true, replayed: 0, scanned: 0, matched: 0, stream: streamName }, null, 2)}\n`);
+        return;
+    }
+    const firstSeq = Number(info?.state?.first_seq ?? 0);
+    const lastSeq = Number(info?.state?.last_seq ?? 0);
+    let scanned = 0;
+    let matched = 0;
+    let replayed = 0;
+    let failed = 0;
+    let purged = 0;
+    for (let seq = firstSeq; seq <= lastSeq; seq += 1) {
+        if (limit > 0 && replayed >= limit)
+            break;
+        let storedRaw;
+        try {
+            storedRaw = await jsm.streams.getMessage(streamName, { seq });
+        }
+        catch {
+            continue;
+        }
+        const stored = asStoredMessage(storedRaw);
+        if (!stored)
+            continue;
+        if (stored.subject !== opts.dlqTopic)
+            continue;
+        scanned += 1;
+        let decoded = null;
+        try {
+            decoded = decodeJson(stored.data);
+        }
+        catch {
+            decoded = null;
+        }
+        const meta = extractDlqMeta(decoded, stored.time);
+        if (!matchesDlqFilter(meta, filter))
+            continue;
+        matched += 1;
+        try {
+            const payloadBytes = replayBytesFromDlqPayload(decoded, stored.data);
+            await publishSubject(nc, opts.targetTopic, payloadBytes, {
+                durable: durablePublish,
+                dedupeKey: `replay-${opts.targetTopic}-${seq}-${Date.now()}-${randomId()}`,
+                timeoutMs: config.runtime.publishDurableTimeoutMs
+            });
+            replayed += 1;
+            if (opts.purgeReplayed) {
+                try {
+                    await jsm.streams.deleteMessage(streamName, seq);
+                    purged += 1;
+                }
+                catch {
+                    // best effort purge
+                }
+            }
+        }
+        catch (err) {
+            failed += 1;
+            process.stderr.write(`dlq replay failed (seq=${seq}): ${err.message}\n`);
+        }
+    }
+    await closeBus(config.natsUrl);
+    process.stdout.write(`${JSON.stringify({
+        ok: true,
+        replayed,
+        failed,
+        purged,
+        scanned,
+        matched,
+        dlq_topic: opts.dlqTopic,
+        target_topic: opts.targetTopic,
+        stream: streamName
+    }, null, 2)}\n`);
+}

package/dist/src/commands/inspect.d.ts

@@ -0,0 +1,6 @@
+import { Logger } from "../logger.js";
+import { OrbitConfig } from "../types.js";
+export declare function cmdInspect(config: OrbitConfig, logger: Logger, opts: {
+    service: string;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/src/commands/inspect.js

@@ -0,0 +1,57 @@
+import { createEnvelope, validateEnvelope } from "../envelope.js";
+import { closeBus, connectBus, decodeJson, encodeJson } from "../nats.js";
+import { loadServiceRecordDistributed } from "../registry.js";
+import { canUseAgent, requestAgent } from "../agent_ipc.js";
+import { prefixedSubject } from "../subjects.js";
+export async function cmdInspect(config, logger, opts) {
+    if (canUseAgent(config)) {
+        try {
+            const payload = await requestAgent(config, "inspect", { service: opts.service, timeoutMs: opts.timeoutMs ?? config.requestTimeoutMs }, opts.timeoutMs ?? config.requestTimeoutMs);
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+            return;
+        }
+        catch (err) {
+            logger.warn("agent inspect failed, falling back to direct NATS path", { service: opts.service, err: String(err) });
+        }
+    }
+    try {
+        const nc = await connectBus(config.natsUrl);
+        try {
+            const msg = await nc.request(prefixedSubject(config, "inspect", opts.service), encodeJson(createEnvelope({ kind: "request", payload: {} })), { timeout: opts.timeoutMs ?? config.requestTimeoutMs });
+            const env = validateEnvelope(decodeJson(msg.data), { skipHashCheck: config.performance.trustedLocal });
+            process.stdout.write(`${JSON.stringify(env.payload, null, 2)}\n`);
+            return;
+        }
+        catch {
+            try {
+                const msg = await nc.request(`$SRV.INFO.${opts.service}`, encodeJson({}), {
+                    timeout: opts.timeoutMs ?? config.requestTimeoutMs
+                });
+                const payload = decodeJson(msg.data);
+                process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+                return;
+            }
+            catch {
+                const msg = await nc.request(prefixedSubject(config, "discovery", "query"), encodeJson({ service: opts.service }), {
+                    timeout: opts.timeoutMs ?? config.requestTimeoutMs
+                });
+                const env = validateEnvelope(decodeJson(msg.data), { skipHashCheck: config.performance.trustedLocal });
+                process.stdout.write(`${JSON.stringify(env.payload, null, 2)}\n`);
+                return;
+            }
+        }
+        finally {
+            await closeBus(config.natsUrl);
+        }
+    }
+    catch (err) {
+        logger.warn("inspect live request failed, falling back to local registry", { service: opts.service, err: String(err) });
+    }
+    const local = await loadServiceRecordDistributed(config, opts.service);
+    if (!local) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: `service ${opts.service} not found` }, null, 2)}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(local, null, 2)}\n`);
+}