@easynet-run/node 0.27.14

package/src/presets/ability_dispatch/bundle.js

@@ -0,0 +1,102 @@
+// EasyNet Axon for AgentNet -- bundle resolution and parsing helpers for ability-dispatch workflow.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { gunzipSync } from "node:zlib";
+export function sha256Prefixed(payload) {
+    const hash = createHash("sha256").update(payload).digest("hex");
+    return `sha256:${hash}`;
+}
+export function parseTarSize(raw) {
+    const text = raw.toString("utf8").replace(/\0.*$/, "").trim();
+    if (!text) {
+        return 0;
+    }
+    const parsed = Number.parseInt(text, 8);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`invalid tar entry size: '${text}'`);
+    }
+    return parsed;
+}
+export function isZeroBlock(block) {
+    for (let i = 0; i < block.length; i += 1) {
+        if (block[i] !== 0) {
+            return false;
+        }
+    }
+    return true;
+}
+export function readBundleVersion(bundleBytes) {
+    const tar = gunzipSync(bundleBytes);
+    let offset = 0;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        if (isZeroBlock(header)) {
+            break;
+        }
+        const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/, "");
+        const prefix = header.subarray(345, 500).toString("utf8").replace(/\0.*$/, "");
+        const fullName = prefix ? `${prefix}/${name}` : name;
+        const typeFlag = String.fromCharCode(header[156] || 0);
+        const size = parseTarSize(header.subarray(124, 136));
+        const dataStart = offset + 512;
+        const dataEnd = dataStart + size;
+        if (dataEnd > tar.length) {
+            throw new Error(`tar entry exceeds archive bounds: ${fullName}`);
+        }
+        const isManifest = fullName === "MANIFEST.json" || fullName.endsWith("/MANIFEST.json");
+        const isRegularFile = typeFlag === "\0" || typeFlag === "0";
+        if (isManifest && isRegularFile && !fullName.includes("/PaxHeader/")) {
+            const manifestRaw = tar.subarray(dataStart, dataEnd).toString("utf8").replace(/\u0000/g, "").trim();
+            const manifest = JSON.parse(manifestRaw);
+            const version = String(manifest["version"] ?? "").trim();
+            if (!version) {
+                throw new Error("bundle MANIFEST.json missing non-empty version");
+            }
+            return version;
+        }
+        const blocks = Math.ceil(size / 512);
+        offset = dataStart + blocks * 512;
+    }
+    throw new Error("bundle MANIFEST.json not found");
+}
+function collectCaseSearchDirs() {
+    const cwd = process.cwd();
+    const ancestors = [];
+    let current = cwd;
+    for (let i = 0; i < 7; i += 1) {
+        ancestors.push(current);
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    const candidates = new Set();
+    for (const root of ancestors) {
+        candidates.add(root);
+        candidates.add(resolve(root, "capability-package", "dist"));
+        candidates.add(resolve(root, "dist"));
+    }
+    return Array.from(candidates).filter((d) => existsSync(d));
+}
+export function resolveBundlePath(raw, cfg) {
+    if (raw.trim()) {
+        const abs = resolve(raw);
+        if (!existsSync(abs)) {
+            throw new Error(`bundle not found: ${abs}`);
+        }
+        return abs;
+    }
+    const searchDirs = collectCaseSearchDirs();
+    const matchesPrefix = (name) => cfg.bundleFilePrefixes.some((prefix) => name.startsWith(prefix));
+    const candidates = searchDirs.flatMap((dir) => readdirSync(dir)
+        .filter((name) => matchesPrefix(name) && name.endsWith(".tar.gz"))
+        .map((name) => resolve(dir, name)));
+    if (candidates.length === 0) {
+        const checked = searchDirs.join(", ");
+        throw new Error(`no pre-built bundle found under search directories: ${checked}`);
+    }
+    candidates.sort((a, b) => statSync(a).mtimeMs - statSync(b).mtimeMs);
+    return candidates[candidates.length - 1];
+}

package/src/presets/ability_dispatch/media.d.ts

@@ -0,0 +1,6 @@
+type JsonMap = Record<string, unknown>;
+export declare function decodeMediaBase64(fieldName: string, raw: string): Buffer;
+export declare function defaultOutputDir(): string;
+export declare function safeFileToken(raw: string): string;
+export declare function persistMediaFile(outputDir: string, mode: "photo" | "video", taskResult: JsonMap, payload: Buffer, extension: string): JsonMap;
+export {};

package/src/presets/ability_dispatch/media.js

@@ -0,0 +1,48 @@
+// EasyNet Axon for AgentNet -- media decode/persist helpers for ability-dispatch workflow.
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { sha256Prefixed } from "./bundle.js";
+export function decodeMediaBase64(fieldName, raw) {
+    const compact = raw.replace(/\s+/g, "");
+    if (!compact) {
+        throw new Error(`${fieldName} is empty`);
+    }
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(compact) || compact.length % 4 !== 0) {
+        throw new Error(`${fieldName} is not valid base64`);
+    }
+    const decoded = Buffer.from(compact, "base64");
+    if (decoded.length === 0) {
+        throw new Error(`${fieldName} decoded to empty payload`);
+    }
+    const normalizedIn = compact.replace(/=+$/, "");
+    const normalizedOut = decoded.toString("base64").replace(/=+$/, "");
+    if (normalizedIn !== normalizedOut) {
+        throw new Error(`${fieldName} is not valid base64`);
+    }
+    return decoded;
+}
+export function defaultOutputDir() {
+    return resolve(process.cwd(), "output");
+}
+export function safeFileToken(raw) {
+    const cleaned = raw
+        .split("")
+        .map((ch) => (/^[A-Za-z0-9_-]$/.test(ch) ? ch : "-"))
+        .join("");
+    const collapsed = cleaned
+        .split("-")
+        .filter((seg) => seg.length > 0)
+        .join("-");
+    return collapsed.slice(0, 80) || "unknown";
+}
+export function persistMediaFile(outputDir, mode, taskResult, payload, extension) {
+    const taskId = safeFileToken(String(taskResult["task_id"] ?? "")) || `${mode}-task`;
+    const fileName = `${mode}-${taskId}.${extension}`;
+    const path = resolve(outputDir, fileName);
+    writeFileSync(path, payload);
+    return {
+        path,
+        size_bytes: payload.length,
+        sha256: sha256Prefixed(payload),
+    };
+}

package/src/presets/ability_dispatch/orchestrator.d.ts

@@ -0,0 +1,21 @@
+export type Json = Record<string, unknown>;
+export type OrchestratorInstallRef = {
+    mode: string;
+    node_id: string;
+    install_id: string;
+};
+export declare class Orchestrator {
+    private endpoint;
+    private tenant;
+    private connectTimeoutMs;
+    private bridge;
+    constructor(endpoint: string, tenant: string, connectTimeoutMs?: number);
+    listNodes(ownerId?: string): Json[];
+    selectNode(nodes: Json[], explicitNodeId: string): Json;
+    publishInstallActivate(nodeId: string, packageId: string, capabilityName: string, version: string, digest: string, packageBytesBase64: string, metadata: Record<string, string>): Json;
+    sendA2ATask(nodeId: string, skillId: string, inputJson: Json): Json;
+    uninstallCapability(nodeId: string, installId: string): Json;
+    cleanupInstalls(installs: OrchestratorInstallRef[]): Json;
+    close(): void;
+    static deterministicSignatureTokenBase64(packageId: string, capabilityName: string, digest: string): string;
+}

package/src/presets/ability_dispatch/orchestrator.js

@@ -0,0 +1,117 @@
+// Lightweight Orchestrator for case servers (Node)
+import { DendriteBridge } from "../../dendrite_bridge.js";
+import { createHash } from "node:crypto";
+export class Orchestrator {
+    endpoint;
+    tenant;
+    connectTimeoutMs;
+    bridge;
+    constructor(endpoint, tenant, connectTimeoutMs = 5000) {
+        this.endpoint = endpoint;
+        this.tenant = tenant;
+        this.connectTimeoutMs = connectTimeoutMs;
+        this.bridge = new DendriteBridge({ endpoint, connectTimeoutMs });
+    }
+    listNodes(ownerId) {
+        return this.bridge.listNodes(this.tenant, { ownerId });
+    }
+    selectNode(nodes, explicitNodeId) {
+        if (explicitNodeId) {
+            const found = nodes.find((node) => String(node["node_id"] ?? "").trim() === explicitNodeId);
+            if (!found) {
+                throw new Error(`target node not found: ${explicitNodeId}`);
+            }
+            return found;
+        }
+        const online = nodes
+            .filter((node) => Boolean(node["online"]))
+            .sort((a, b) => String(a["node_id"] ?? "").localeCompare(String(b["node_id"] ?? "")));
+        if (online.length === 0) {
+            throw new Error("no online nodes available for dispatch");
+        }
+        return online[0];
+    }
+    publishInstallActivate(nodeId, packageId, capabilityName, version, digest, packageBytesBase64, metadata) {
+        const signatureBase64 = Orchestrator.deterministicSignatureTokenBase64(packageId, capabilityName, digest);
+        const publish = this.bridge.publishCapability(this.tenant, packageId, capabilityName, {
+            version,
+            digest,
+            signatureBase64,
+            metadata,
+            packageBytesBase64,
+        });
+        let publishDigest = digest;
+        const packageRef = publish["package_ref"];
+        if (packageRef && typeof packageRef === "object") {
+            const maybe = String(packageRef["digest"] ?? "").trim();
+            if (maybe)
+                publishDigest = maybe;
+        }
+        const install = this.bridge.installCapability(this.tenant, nodeId, packageId, {
+            version,
+            digest: publishDigest,
+            allowTransferredCode: true,
+            executionMode: "sandbox_first",
+            installTimeoutSeconds: 45,
+        });
+        const installId = String(install["install_id"] ?? "").trim();
+        if (!installId)
+            throw new Error(`install_id missing: ${JSON.stringify(install)}`);
+        const activate = this.bridge.activateCapability(this.tenant, nodeId, installId);
+        return { package_id: packageId, capability_name: capabilityName, package_version: version, publish, install, activate };
+    }
+    sendA2ATask(nodeId, skillId, inputJson) {
+        return this.bridge.sendA2aTask(this.tenant, nodeId, skillId, { inputJson });
+    }
+    uninstallCapability(nodeId, installId) {
+        return this.bridge.uninstallCapability(this.tenant, nodeId, installId, {
+            deactivateFirst: true,
+            deactivateReason: "sdk cleanup",
+            force: false,
+        });
+    }
+    cleanupInstalls(installs) {
+        const results = [];
+        let succeeded = 0;
+        let failed = 0;
+        for (let idx = installs.length - 1; idx >= 0; idx -= 1) {
+            const item = installs[idx];
+            const nodeId = String(item.node_id ?? "").trim();
+            const installId = String(item.install_id ?? "").trim();
+            const mode = String(item.mode ?? "").trim();
+            const row = { mode, node_id: nodeId, install_id: installId };
+            if (!nodeId || !installId) {
+                row["ok"] = false;
+                row["error"] = "missing node_id or install_id";
+                failed += 1;
+                results.push(row);
+                continue;
+            }
+            try {
+                row["ok"] = true;
+                row["response"] = this.uninstallCapability(nodeId, installId);
+                succeeded += 1;
+            }
+            catch (error) {
+                row["ok"] = false;
+                row["error"] = String(error);
+                failed += 1;
+            }
+            results.push(row);
+        }
+        return {
+            attempted: installs.length,
+            succeeded,
+            failed,
+            ok: failed === 0,
+            results,
+        };
+    }
+    close() {
+        this.bridge.close();
+    }
+    static deterministicSignatureTokenBase64(packageId, capabilityName, digest) {
+        const seed = `${packageId}:${capabilityName}:${digest}`;
+        return createHash("sha256").update(seed, "utf8").digest("base64");
+    }
+}

package/src/presets/ability_dispatch/workflow.d.ts

@@ -0,0 +1,50 @@
+import { Orchestrator, type OrchestratorInstallRef } from "./orchestrator.js";
+export { parseArgs, parsePositiveInt, BOOL_FLAGS } from "./args.js";
+export { readBundleVersion, parseTarSize, isZeroBlock, sha256Prefixed, resolveBundlePath } from "./bundle.js";
+export { decodeMediaBase64, persistMediaFile, safeFileToken, defaultOutputDir } from "./media.js";
+type JsonMap = Record<string, unknown>;
+type InstallRef = OrchestratorInstallRef;
+export interface ModeSpec {
+    capabilityName: string;
+    abilityPrefix: string;
+    mediaField: string;
+    mediaExt: string;
+}
+export declare const MEDIA_CAPTURE_MODE_SPECS: Record<string, ModeSpec>;
+export interface AbilityDispatchConfig {
+    /** Mode specifications mapping mode names to their capability/skill/media details.
+     *  Required at construction -- an error is thrown if not provided. */
+    modeSpecs: Record<string, ModeSpec>;
+    /** Bundle file-name prefixes to match when auto-discovering .tar.gz bundles.
+     *  Default: ["ability-dispatch-media-capability-", "case01-media-capability-"] */
+    bundleFilePrefixes?: string[];
+    /** Custom result validator. Receives (mode, taskResult, requireReal) and should return the validated result_json or throw. */
+    resultValidator?: (mode: string, taskResult: Record<string, unknown>, requireReal: boolean) => Record<string, unknown>;
+    /** Custom metadata builder. Receives (mode, skillId, ts, config) and returns metadata record for publishInstallActivate. */
+    metadataBuilder?: (mode: string, skillId: string, ts: number, config: Record<string, unknown>) => Record<string, string>;
+    /** Custom task payload builder. Receives (mode, config, ts) and returns the task payload for sendA2ATask. */
+    taskPayloadBuilder?: (mode: string, config: Record<string, unknown>, ts: number) => Record<string, unknown>;
+}
+export declare function validateMediaCaptureResult(mode: string, taskResult: Record<string, unknown>, requireReal: boolean): Record<string, unknown>;
+export declare function mediaCaptureMetadataBuilder(mode: string, skillId: string, ts: number, config: Record<string, unknown>): Record<string, string>;
+export declare function mediaCaptureTaskPayload(mode: string, config: Record<string, unknown>, ts: number): Record<string, unknown>;
+export interface RunModeContext {
+    mode: string;
+    spec: ModeSpec;
+    orch: Orchestrator;
+    targetNodeId: string;
+    timestamp: number;
+    bundle: {
+        version: string;
+        digest: string;
+        base64: string;
+    };
+    cfg: Required<AbilityDispatchConfig>;
+    runtimeConfig: JsonMap;
+    requireReal: boolean;
+    writeMediaFiles: boolean;
+    outputDir: string;
+    createdInstalls: InstallRef[];
+}
+export declare function runCaseFromArgs(argv: string[], userConfig?: Partial<AbilityDispatchConfig>): number;
+export declare function runCase(argv: string[], config?: AbilityDispatchConfig): number;

package/src/presets/ability_dispatch/workflow.js

@@ -0,0 +1,333 @@
+// EasyNet Axon for AgentNet
+// =========================
+//
+// File: sdk/node/src/presets/ability_dispatch/workflow.ts
+// Description: Ability-dispatch Node server orchestration for package lifecycle and selected-client dispatch flow.
+//
+// Protocol Responsibility:
+// - Defines contract/configuration behavior required by this Axon runtime/SDK/gallery workflow surface.
+// - Preserves stable cross-language semantics and interoperability expectations.
+//
+// Implementation Approach:
+// - Keeps declarations, defaults, and orchestration assumptions explicit and auditable.
+// - Uses deterministic structure so behavior stays reproducible across environments.
+//
+// Usage Contract:
+// - Changes here should remain consistent with related runtime/SDK/service definitions.
+// - Validate modifications via protocol checks or scenario smoke tests before release.
+//
+// Architectural Position:
+// - Case-demo Node server control-plane orchestration layer.
+//
+// Author: Silan.Hu
+// Email: silan.hu@u.nus.edu
+// Copyright (c) 2026-2027 easynet. All rights reserved.
+// Node server flow: publish/install/activate media capability on selected client and invoke tasks.
+import { Orchestrator } from "./orchestrator.js";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, parsePositiveInt } from "./args.js";
+import { readBundleVersion, resolveBundlePath, sha256Prefixed } from "./bundle.js";
+import { decodeMediaBase64, defaultOutputDir, persistMediaFile } from "./media.js";
+export { parseArgs, parsePositiveInt, BOOL_FLAGS } from "./args.js";
+export { readBundleVersion, parseTarSize, isZeroBlock, sha256Prefixed, resolveBundlePath } from "./bundle.js";
+export { decodeMediaBase64, persistMediaFile, safeFileToken, defaultOutputDir } from "./media.js";
+export const MEDIA_CAPTURE_MODE_SPECS = {
+    photo: { capabilityName: "desktop_camera_photo", abilityPrefix: "take_photo", mediaField: "image_base64", mediaExt: "jpg" },
+    video: { capabilityName: "desktop_camera_video", abilityPrefix: "record_video", mediaField: "video_base64", mediaExt: "mp4" },
+};
+const DEFAULT_BUNDLE_FILE_PREFIXES = [
+    "ability-dispatch-media-capability-",
+    "case01-media-capability-",
+];
+function resolveConfig(cfg) {
+    if (!cfg?.modeSpecs) {
+        throw new Error("AbilityDispatchConfig.modeSpecs is required");
+    }
+    return {
+        modeSpecs: cfg.modeSpecs,
+        bundleFilePrefixes: cfg?.bundleFilePrefixes ?? [...DEFAULT_BUNDLE_FILE_PREFIXES],
+        resultValidator: cfg?.resultValidator ?? validateMediaCaptureResult,
+        metadataBuilder: cfg?.metadataBuilder ?? mediaCaptureMetadataBuilder,
+        taskPayloadBuilder: cfg?.taskPayloadBuilder ?? mediaCaptureTaskPayload,
+    };
+}
+function defaultBridgeLibName() {
+    if (process.platform === "darwin")
+        return "libaxon_dendrite_bridge.dylib";
+    if (process.platform === "win32")
+        return "axon_dendrite_bridge.dll";
+    return "libaxon_dendrite_bridge.so";
+}
+function findRepoRootForBridge(startDir) {
+    let current = resolve(startDir);
+    for (let steps = 0; steps < 10; steps += 1) {
+        const candidate = resolve(current, "core/runtime-rs/dendrite-bridge/target/release", defaultBridgeLibName());
+        if (existsSync(candidate)) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return "";
+}
+function ensureBridgeLibEnv() {
+    if (process.env.EASYNET_DENDRITE_BRIDGE_LIB)
+        return;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const repoRoot = findRepoRootForBridge(here) || process.cwd();
+    const candidate = resolve(repoRoot, "core/runtime-rs/dendrite-bridge/target/release", defaultBridgeLibName());
+    if (existsSync(candidate)) {
+        process.env.EASYNET_DENDRITE_BRIDGE_LIB = candidate;
+    }
+}
+function extractInstallId(lifecycle) {
+    const install = lifecycle["install"];
+    return String(install?.["install_id"] ?? "").trim();
+}
+export function validateMediaCaptureResult(mode, taskResult, requireReal) {
+    const resultJson = taskResult["result_json"];
+    if (!resultJson || typeof resultJson !== "object") {
+        throw new Error(`task_result.result_json missing for ${mode}: ${JSON.stringify(taskResult)}`);
+    }
+    const captureMode = String(resultJson["capture_mode"] ?? "").trim().toLowerCase();
+    if (captureMode === "real_failed") {
+        let captureError = String(resultJson["capture_error"] ?? "").trim() || `${mode} real capture failed`;
+        const nextAction = String(resultJson["permission_next_action"] ?? "").trim();
+        if (Boolean(resultJson["permission_required"]) && nextAction) {
+            captureError = `${captureError}; next_action: ${nextAction}`;
+        }
+        throw new Error(`${mode} capture failed: ${captureError}`);
+    }
+    const spec = MEDIA_CAPTURE_MODE_SPECS[mode];
+    const mediaField = spec ? spec.mediaField : (mode === "photo" ? "image_base64" : "video_base64");
+    if (!String(resultJson[mediaField] ?? "").trim()) {
+        throw new Error(`${mode} result field '${mediaField}' is empty: ${JSON.stringify(resultJson)}`);
+    }
+    if (requireReal) {
+        if (captureMode !== "real") {
+            throw new Error(`${mode} capture_mode expected real but got ${captureMode}: ${JSON.stringify(resultJson)}`);
+        }
+        if (!Boolean(resultJson["real_capture_confirmed"])) {
+            throw new Error(`${mode} real_capture_confirmed is false: ${JSON.stringify(resultJson)}`);
+        }
+    }
+    else if (!new Set(["real", "mock", "mock_fallback"]).has(captureMode)) {
+        throw new Error(`${mode} capture_mode invalid: ${JSON.stringify(resultJson)}`);
+    }
+    return resultJson;
+}
+export function mediaCaptureMetadataBuilder(mode, skillId, ts, config) {
+    const abilityDisplayName = mode === "photo" ? "Take Photo" : "Record Video";
+    const execTimeout = mode === "photo" ? "120000" : "180000";
+    return {
+        "a2a.skill_id": skillId,
+        "a2a.ability_name": abilityDisplayName,
+        "axon.exec.command": `sh {ability_package_root}/scripts/run.sh ${mode} {node_id}`,
+        "axon.exec.timeout_ms": execTimeout,
+        "axon.package.install_bootstrap_command": "bash {ability_package_root}/scripts/bootstrap.sh",
+        "axon.package.install_bootstrap_timeout_ms": "300000",
+    };
+}
+export function mediaCaptureTaskPayload(mode, config, ts) {
+    if (mode === "photo") {
+        return {
+            camera_id: config.cameraId,
+            resolution: config.photoResolution,
+            require_real: config.requireReal,
+            prefer_real_camera: true,
+            auto_request_permission: config.autoRequestPermission,
+        };
+    }
+    return {
+        camera_id: config.cameraId,
+        resolution: config.videoResolution,
+        duration_seconds: config.durationSeconds,
+        require_real: config.requireReal,
+        prefer_real_camera: true,
+        auto_request_permission: config.autoRequestPermission,
+    };
+}
+function runMode(ctx) {
+    const { mode, spec, orch, targetNodeId, timestamp, bundle, cfg, runtimeConfig, requireReal, writeMediaFiles, outputDir, createdInstalls } = ctx;
+    const skillId = `${spec.abilityPrefix}_${timestamp}`;
+    const capability = spec.capabilityName;
+    const mediaField = spec.mediaField;
+    const mediaExt = spec.mediaExt;
+    const packageId = `pkg.${capability}.${timestamp}`;
+    const metadata = cfg.metadataBuilder(mode, skillId, timestamp, runtimeConfig);
+    const lifecycle = orch.publishInstallActivate(targetNodeId, packageId, capability, bundle.version, bundle.digest, bundle.base64, metadata);
+    const installId = extractInstallId(lifecycle);
+    if (installId) {
+        createdInstalls.push({
+            mode,
+            node_id: targetNodeId,
+            install_id: installId,
+        });
+    }
+    const taskPayload = cfg.taskPayloadBuilder(mode, runtimeConfig, timestamp);
+    const taskResult = orch.sendA2ATask(targetNodeId, skillId, taskPayload);
+    const resultJson = cfg.resultValidator(mode, taskResult, requireReal);
+    const mediaBytes = decodeMediaBase64(`${mode}.${mediaField}`, String(resultJson[mediaField] ?? ""));
+    const savedFile = writeMediaFiles
+        ? persistMediaFile(outputDir, mode, taskResult, mediaBytes, mediaExt)
+        : null;
+    return {
+        ...lifecycle,
+        skill_id: skillId,
+        task_result: taskResult,
+        result_json: resultJson,
+        media_size_bytes: mediaBytes.length,
+        saved_file: savedFile,
+    };
+}
+function executeCase(argv, userConfig) {
+    const cfg = resolveConfig(userConfig);
+    const args = parseArgs(argv);
+    const endpoint = String(args["endpoint"] ?? "http://127.0.0.1:50051");
+    const tenant = String(args["tenant"] ?? "tenant-test");
+    const nodeId = String(args["node-id"] ?? "");
+    const ownerId = String(args["owner-id"] ?? "");
+    const connectTimeoutMs = parsePositiveInt(typeof args["connect-timeout-ms"] === "string" ? args["connect-timeout-ms"] : undefined, 30000, "connect-timeout-ms");
+    const bundlePathRaw = String(args["bundle-path"] ?? "");
+    const modeRaw = String(args["mode"] ?? "both");
+    const cameraId = String(args["camera-id"] ?? "default");
+    const photoResolution = String(args["photo-resolution"] ?? "1280x720");
+    const videoResolution = String(args["video-resolution"] ?? "1280x720");
+    const durationSeconds = parsePositiveInt(typeof args["duration-seconds"] === "string" ? args["duration-seconds"] : undefined, 3, "duration-seconds");
+    const autoRequestPermission = args["auto-request-permission"] === true;
+    const outputDirRaw = String(args["output-dir"] ?? "");
+    const noWriteMediaFiles = args["no-write-media-files"] === true;
+    const keepInstalled = args["keep-installed"] === true;
+    const requireRealFlag = args["require-real"] === true;
+    const allowMockFallback = args["allow-mock-fallback"] === true;
+    const availableModes = Object.keys(cfg.modeSpecs);
+    if (modeRaw !== "both" && !cfg.modeSpecs[modeRaw]) {
+        throw new Error(`--mode must be one of: ${availableModes.join(", ")}, both`);
+    }
+    const modesToRun = modeRaw === "both" ? availableModes : [modeRaw];
+    const requireReal = requireRealFlag || !allowMockFallback;
+    const writeMediaFiles = !noWriteMediaFiles;
+    const outputDir = outputDirRaw.trim() ? resolve(outputDirRaw) : resolve(defaultOutputDir());
+    if (writeMediaFiles) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    ensureBridgeLibEnv();
+    const bundlePath = resolveBundlePath(bundlePathRaw, cfg);
+    const bundleBytes = readFileSync(bundlePath);
+    if (bundleBytes.length === 0) {
+        throw new Error(`bundle is empty: ${bundlePath}`);
+    }
+    const digest = sha256Prefixed(bundleBytes);
+    const bundleVersion = readBundleVersion(bundleBytes);
+    const bundleBase64 = bundleBytes.toString("base64");
+    const orch = new Orchestrator(endpoint, tenant, connectTimeoutMs);
+    const nodes = orch.listNodes(ownerId || undefined);
+    const targetNode = orch.selectNode(nodes, nodeId);
+    const targetNodeId = String(targetNode["node_id"] ?? "").trim();
+    if (!targetNodeId) {
+        throw new Error(`selected node_id is empty: ${JSON.stringify(targetNode)}`);
+    }
+    if (!Boolean(targetNode["online"])) {
+        throw new Error(`target node is offline: ${targetNodeId}`);
+    }
+    const timestamp = Date.now();
+    const runtimeConfig = {
+        cameraId,
+        photoResolution,
+        videoResolution,
+        durationSeconds,
+        requireReal,
+        autoRequestPermission,
+    };
+    const out = {
+        ok: true,
+        endpoint,
+        tenant,
+        selected_node_id: targetNodeId,
+        selected_node: targetNode,
+        nodes_count: nodes.length,
+        owner_id_filter: ownerId,
+        mode: modeRaw,
+        camera_id: cameraId,
+        photo_resolution: photoResolution,
+        video_resolution: videoResolution,
+        duration_seconds: durationSeconds,
+        require_real: requireReal,
+        auto_request_permission: autoRequestPermission,
+        write_media_files: writeMediaFiles,
+        output_dir: writeMediaFiles ? outputDir : "",
+        bundle_path: bundlePath,
+        bundle_digest: digest,
+        bundle_version: bundleVersion,
+        keep_installed: keepInstalled,
+    };
+    const createdInstalls = [];
+    let operationError = null;
+    try {
+        for (const currentMode of modesToRun) {
+            const spec = cfg.modeSpecs[currentMode];
+            out[currentMode] = runMode({
+                mode: currentMode,
+                spec,
+                orch,
+                targetNodeId,
+                timestamp,
+                bundle: { version: bundleVersion, digest, base64: bundleBase64 },
+                cfg,
+                runtimeConfig,
+                requireReal,
+                writeMediaFiles,
+                outputDir,
+                createdInstalls,
+            });
+        }
+    }
+    catch (err) {
+        operationError = err;
+    }
+    try {
+        if (keepInstalled) {
+            out["cleanup"] = {
+                skipped: true,
+                reason: "--keep-installed is set",
+                ok: true,
+                attempted: 0,
+                succeeded: 0,
+                failed: 0,
+                results: [],
+            };
+        }
+        else {
+            const cleanup = orch.cleanupInstalls(createdInstalls);
+            out["cleanup"] = cleanup;
+            if (Number(cleanup["failed"] ?? 0) > 0) {
+                process.stderr.write(`cleanup had ${String(cleanup["failed"])} uninstall failure(s)\n`);
+            }
+        }
+        if (operationError) {
+            throw operationError;
+        }
+        process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+        return 0;
+    }
+    finally {
+        orch.close();
+    }
+}
+export function runCaseFromArgs(argv, userConfig) {
+    return executeCase(argv, {
+        modeSpecs: MEDIA_CAPTURE_MODE_SPECS,
+        metadataBuilder: mediaCaptureMetadataBuilder,
+        taskPayloadBuilder: mediaCaptureTaskPayload,
+        resultValidator: validateMediaCaptureResult,
+        ...userConfig,
+    });
+}
+export function runCase(argv, config) {
+    return executeCase(argv, config);
+}