tirtc-devtools-cli 0.1.2 → 0.2.1

package/README.md

@@ -6,9 +6,9 @@
 
 - `token issue` / `license qrcode`：本地联调的凭据与二维码工具。
 - `assets prepare`：把默认资产或任意 MP4 准备成 native role driver 使用的媒体资产。
-- `send start`：作为标准上行端启动 native DevTools driver，送出音视频，产出 `bootstrap.json` 与 execution evidence。
-- `receive start`：作为标准下行端消费本机 `bootstrap.json` 或显式 `remote/token`，产出 `frame_dump` 与 summary。
-- CLI 负责参数、环境变量、token 签发、JSON envelope、artifact 摘要与打包定位；真实 TiRTC lifecycle 由 `products/devtools/driver/` 承接。
+- `device start`：作为标准上行 device 启动 native DevTools driver，送出音视频，按需产出本机 `bootstrap.json` 与 execution evidence。
+- `client start`：作为标准下行 client 消费本机 `bootstrap.json` 或显式 device/token，产出 `frame_dump` 与 summary。
+- CLI 负责参数、环境变量、token 签发、JSON envelope、artifact 摘要与打包定位；真实 TiRTC lifecycle 由 `products/devtools/driver/` 承接。native role 失败且 runtime logging 已初始化时，driver 会在退出前尝试上传日志，CLI JSON 会透出 `log_id` 与 `log_upload` 结果。
 
 ## 不负责什么
 
@@ -21,7 +21,7 @@
 ## 依赖方向
 
 - token/license 工具由 CLI 自己承接；仓库级 token helper 入口为 `./script/issue_devtools_token.sh`。
-- send/receive 通过本地 native driver executable 执行，默认查找 `.build/devtools-driver/bin/<platform>/devtools_driver_probe` 或 `vendor/devtools/driver/<platform>/devtools_driver_probe`。
+- device/client 通过本地 native driver executable 执行，默认查找 `.build/devtools-driver/bin/<platform>/devtools_driver_probe` 或 `vendor/devtools/driver/<platform>/devtools_driver_probe`。
 - runtime bundle 默认查找 `.build/products/runtime/<platform>` 或 `vendor/runtime/<platform>`。
 
 ## 常用命令
@@ -38,7 +38,7 @@ node products/cli/bin/tirtc-devtools-cli.js --help
 ./script/issue_devtools_token.sh --token-only
 ```
 
-真实 send/receive 闭环优先走：
+真实 device/client 闭环优先走：
 
 ```sh
 products/devtools/driver/script/run_capability_probe.sh
@@ -50,16 +50,20 @@ products/devtools/driver/script/run_capability_probe.sh
 node products/cli/bin/tirtc-devtools-cli.js --json assets prepare \
   --source ./movie.mp4 \
   --output-root .build/tirtc-assets
-node products/cli/bin/tirtc-devtools-cli.js --json send start \
+node products/cli/bin/tirtc-devtools-cli.js --json device start \
   --source .build/tirtc-assets/manifest.json \
   --video-codec h264 \
-  --artifact-root .build/devtools-cli/send-movie-h264
+  --artifact-root .build/devtools-cli/device-movie-h264
 ```
 
-`send start` 默认持续运行直到用户结束进程；需要自动化限时时再显式传
+`device start` 默认持续运行直到用户结束进程；需要自动化限时时再显式传
 `--duration-ms <ms>`。prepared asset 会按完整音视频轨循环，任一轨到达源文件末尾时
 audio/video 同步回到源头并保持 PTS 继续递增。
 
+native role 失败时，`reason_code` 与 `failed_stage` 仍是主失败事实；`log_upload`
+只说明失败现场日志是否已上传。上传成功时，CLI JSON 与 `summary.json` 会包含
+可用于后续抓取的 `log_id`。
+
 打包入口：
 
 ```sh

package/USAGE.md

@@ -15,8 +15,8 @@ node products/cli/bin/tirtc-devtools-cli.js --help
 
 ## Platform Support
 
-- `macos-arm64`: supported for token, assets prepare, send, receive, package smoke, and native send+receive qualification.
-- `linux-x64`: supported for token, assets prepare, send, receive, package smoke, and native driver packaging. Linux native send/receive runs through the packaged headless driver on Linux hosts or `linux/amd64` containers.
+- `macos-arm64`: supported for token, assets prepare, device, client, package smoke, and native device+client qualification.
+- `linux-x64`: supported for token, assets prepare, device, client, package smoke, and native driver packaging. Linux native device/client runs through the packaged headless driver on Linux hosts or `linux/amd64` containers.
 
 ## Token
 
@@ -71,7 +71,7 @@ node products/cli/bin/tirtc-devtools-cli.js --json assets prepare
 node products/cli/bin/tirtc-devtools-cli.js --json assets prepare --source runtime/assets/source.mp4
 ```
 
-Prepare any MP4 and use the returned `data.manifest_path` as `send start --source`:
+Prepare any MP4 and use the returned `data.manifest_path` as `device start --source`:
 
 ```sh
 node products/cli/bin/tirtc-devtools-cli.js --json assets prepare \
@@ -79,61 +79,78 @@ node products/cli/bin/tirtc-devtools-cli.js --json assets prepare \
   --output-root .build/tirtc-assets
 ```
 
-## Send
+## Device
 
-Required environment:
+Device startup requires:
 
 ```sh
 export TIRTC_DEVICE_ID="<DEVICE_ID>"
 export TIRTC_DEVICE_SECRET_KEY="<DEVICE_SECRET_KEY>"
+export TIRTC_ENDPOINT="<SERVICE_ENTRY>"
+```
+
+These can also be passed explicitly with `--device-id`, `--device-secret-key`,
+and `--endpoint`. Missing values fail during CLI preflight before the native
+driver starts.
+
+If the local `client start --bootstrap` flow is needed, issue a fresh client
+token first:
+
+```sh
 export TIRTC_ACCESS_KEY_ID="<ACCESS_KEY_ID>"
 export TIRTC_SECRET_KEY_ID="<SECRET_KEY_ID>"
 export TIRTC_APP_ID="<APP_ID>"
-export TIRTC_ENDPOINT="<SERVICE_ENTRY>"
 export TIRTC_OPEN_API_ENDPOINT="<OPENAPI_ENDPOINT>"
+
+node products/cli/bin/tirtc-devtools-cli.js --json token issue "$TIRTC_DEVICE_ID" \
+  --endpoint "$TIRTC_ENDPOINT" \
+  --openapi-endpoint "$TIRTC_OPEN_API_ENDPOINT" \
+  > .build/devtools-client-token.json
 ```
 
-Run one send role with the default prepared asset:
+Run one device with the default prepared asset:
 
 ```sh
-node products/cli/bin/tirtc-devtools-cli.js --json send start \
+node products/cli/bin/tirtc-devtools-cli.js --json device start \
   --video-codec h264 \
-  --artifact-root .build/devtools-cli/send-h264
+  --artifact-root .build/devtools-cli/device-h264
 ```
 
-Run one send role from a prepared MP4:
+Run one device from a prepared MP4 and write a local client bootstrap:
 
 ```sh
-node products/cli/bin/tirtc-devtools-cli.js --json send start \
+node products/cli/bin/tirtc-devtools-cli.js --json device start \
   --source .build/tirtc-assets/manifest.json \
   --video-codec h264 \
-  --artifact-root .build/devtools-cli/send-movie-h264
+  --client-token-json .build/devtools-client-token.json \
+  --artifact-root .build/devtools-cli/device-movie-h264
 ```
 
-By default `send start` keeps running until the process is stopped. Use
+By default `device start` keeps running until the process is stopped. Use
 `--duration-ms <ms>` only for bounded automation. Prepared assets loop over the
 full audio/video source cycle; when either track reaches the source end, both
 tracks restart from offset 0 while PTS keeps increasing.
 
-The send role writes `bootstrap.json`. That file is a local handoff artifact for
-CLI receive, runtime sample smoke, and validation automation. The token in that
-bootstrap is intended for one receive connection.
+`device start` writes `bootstrap.json` only when `--client-token-json` is
+provided. That file is a local handoff artifact for CLI client, runtime sample
+smoke, and validation automation. The token in that bootstrap is intended for
+one client connection.
 
 `bootstrap.json` is not a mobile SDK connection protocol. For phone debugging,
 use token/license QR today; a full session QR or deeplink is a separate product
 slice.
 
-## Receive
+## Client
 
 ```sh
-node products/cli/bin/tirtc-devtools-cli.js --json receive start \
-  --bootstrap .build/devtools-cli/send-h264/bootstrap.json \
-  --artifact-root .build/devtools-cli/receive-h264
+node products/cli/bin/tirtc-devtools-cli.js --json client start \
+  --bootstrap .build/devtools-cli/device-h264/bootstrap.json \
+  --artifact-root .build/devtools-cli/client-h264
 ```
 
-Receive writes `summary.json`, `events.jsonl`, runtime logs, and `render/first-video-frame.*` for `frame_dump`.
+Client writes `summary.json`, `events.jsonl`, runtime logs, and `render/first-video-frame.*` for `frame_dump`.
 
-`receive start --bootstrap` is meant for the local computer-to-computer DevTools
+`client start --bootstrap` is meant for the local computer-to-computer DevTools
 flow. Mobile clients should not be required to fetch a local JSON file from the
 developer machine.
 
@@ -145,4 +162,4 @@ For the current macOS gate, use the native capability runner:
 products/devtools/driver/script/run_capability_probe.sh
 ```
 
-It runs H264, H265, and MJPEG send+receive with a fresh token per case.
+It runs H264, H265, and MJPEG device+client with a fresh token per case.

package/dist/cli/src/index.js

@@ -106,48 +106,53 @@ program.name('tirtc-devtools-cli')
 const assets = program.command('assets').description('准备 DevTools driver 使用的媒体资产');
 assets.command('prepare')
     .description('准备默认 runtime assets 或把显式 source 写入 output root')
-    .option('--source <path>', '输入 MP4 路径；send start 使用输出的 manifest_path')
+    .option('--source <path>', '输入 MP4 路径；device start 使用输出的 manifest_path')
     .option('--output-root <dir>', 'prepared assets 输出根目录')
     .addHelpText('after', `
 Examples:
   $ tirtc-devtools-cli --json assets prepare --source ./movie.mp4 --output-root .build/tirtc-assets
-  $ tirtc-devtools-cli --json send start --source .build/tirtc-assets/manifest.json --video-codec h264
+  $ tirtc-devtools-cli --json device start --source .build/tirtc-assets/manifest.json --video-codec h264
 `)
     .action((commandOptions) => {
     runAndExit(runAssetsPrepare(commandOptions, getCliOptions()));
 });
-const send = program.command('send').description('作为标准上行端运行 native DevTools driver');
-send.command('start')
-    .description('启动 send role，产出 bootstrap.json 与 summary.json')
-    .option('--execution-id <id>', 'runtime validation execution id')
-    .option('--case-id <id>', 'runtime validation case id')
-    .option('--app-id <id>', 'runtime validation app id')
+const device = program.command('device').description('作为标准上行 device 运行 native DevTools driver');
+device.command('start')
+    .description('启动上行 device，读取 prepared asset 并送出音视频')
     .option('--artifact-root <dir>', 'artifact 输出目录')
-    .option('--remote-id <id>', 'server remote id；默认读取 TIRTC_DEVICE_ID')
+    .option('--device-id <id>', 'device id；不传时读取 TIRTC_DEVICE_ID')
+    .option('--device-secret-key <key>', 'device secret key；不传时读取 TIRTC_DEVICE_SECRET_KEY')
+    .option('--endpoint <url>', 'TiRTC endpoint；不传时读取 TIRTC_ENDPOINT')
     .option('--source <path>', 'prepared asset root、manifest_path 或 encoded track；MP4 先运行 assets prepare')
     .option('--video-codec <codec>', 'h264|h265|mjpeg', 'h264')
     .option('--duration-ms <ms>', '可选自动结束时长；默认持续运行直到用户结束进程')
     .option('--connect-timeout-ms <ms>', 'service ready / connect 最大等待')
     .option('--first-packet-timeout-ms <ms>', '首包最大等待')
-    .option('--bootstrap-token-json <path>', 'script/issue_devtools_token.sh --json 输出文件')
+    .option('--client-token-json <path>', 'token issue --json 输出文件；传入时写出本机 bootstrap.json')
     .addHelpText('after', `
 Examples:
   $ tirtc-devtools-cli --json assets prepare --source ./movie.mp4 --output-root .build/tirtc-assets
-  $ tirtc-devtools-cli --json send start --source .build/tirtc-assets/manifest.json --artifact-root .build/tirtc-send
+  $ tirtc-devtools-cli --json device start --source .build/tirtc-assets/manifest.json --artifact-root .build/tirtc-device
 
-bootstrap.json is a local handoff artifact for receive/sample/validation automation.
+device start requires device id, device secret key, and endpoint.
+Missing flags are read from TIRTC_DEVICE_ID, TIRTC_DEVICE_SECRET_KEY, and TIRTC_ENDPOINT.
+
+bootstrap.json is a local handoff artifact for client/sample/validation automation.
+It is only written when --client-token-json is provided.
 It is not a mobile SDK connection protocol.
 `)
     .action((commandOptions) => {
-    runAndExit((0, role_driver_1.runSendStart)(commandOptions, getCliOptions()));
+    runAndExit((0, role_driver_1.runDeviceStart)(commandOptions, getCliOptions()));
 });
-const receive = program.command('receive').description('作为标准下行端运行 native DevTools driver');
-receive.command('start')
-    .description('启动 receive role，消费 bootstrap 或显式 identity 并产出 frame_dump')
+const client = program.command('client').description('作为标准下行 client 运行 native DevTools driver');
+client.command('start')
+    .description('启动下行 client，消费 bootstrap 或显式 token 并产出 frame_dump')
     .option('--artifact-root <dir>', 'artifact 输出目录')
-    .option('--bootstrap <path>', 'send role 产出的 bootstrap.json')
-    .option('--remote-id <id>', '显式 remote id；优先于 bootstrap')
+    .option('--bootstrap <path>', 'device start 产出的 bootstrap.json')
+    .option('--target-device-id <id>', '目标 device id；优先于 bootstrap')
     .option('--token <token>', '显式 token；优先于 bootstrap')
+    .option('--endpoint <url>', 'TiRTC endpoint；优先于 bootstrap')
+    .option('--app-id <id>', 'client connect app id；不传时读取 bootstrap 或 TIRTC_APP_ID')
     .option('--audio-stream-id <id>', '音频 stream id')
     .option('--video-stream-id <id>', '视频 stream id')
     .option('--consumer <consumer>', 'packet_dump|frame_dump', 'frame_dump')
@@ -158,12 +163,12 @@ receive.command('start')
     .option('--first-output-timeout-ms <ms>', '首帧输出最大等待')
     .addHelpText('after', `
 Examples:
-  $ tirtc-devtools-cli --json receive start --bootstrap .build/tirtc-send/bootstrap.json
+  $ tirtc-devtools-cli --json client start --bootstrap .build/tirtc-device/bootstrap.json
 
-bootstrap.json is expected to come from a local send start run.
+bootstrap.json is expected to come from a local device start run.
 For mobile device debugging, use token/license QR or a future session QR/deeplink.
 `)
     .action((commandOptions) => {
-    runAndExit((0, role_driver_1.runReceiveStart)(commandOptions, getCliOptions()));
+    runAndExit((0, role_driver_1.runClientStart)(commandOptions, getCliOptions()));
 });
 program.parse(process.argv);

package/dist/cli/src/role_driver.d.ts

@@ -1,24 +1,25 @@
 export type CliOptions = {
     json?: boolean;
 };
-type SendCommandOptions = {
-    executionId?: string;
-    caseId?: string;
-    appId?: string;
+type DeviceCommandOptions = {
     artifactRoot?: string;
-    remoteId?: string;
+    deviceId?: string;
+    deviceSecretKey?: string;
+    endpoint?: string;
     source?: string;
     videoCodec?: string;
     durationMs?: string;
     connectTimeoutMs?: string;
     firstPacketTimeoutMs?: string;
-    bootstrapTokenJson?: string;
+    clientTokenJson?: string;
 };
-type ReceiveCommandOptions = {
+type ClientCommandOptions = {
     artifactRoot?: string;
     bootstrap?: string;
-    remoteId?: string;
+    targetDeviceId?: string;
     token?: string;
+    endpoint?: string;
+    appId?: string;
     audioStreamId?: string;
     videoStreamId?: string;
     consumer?: string;
@@ -28,6 +29,6 @@ type ReceiveCommandOptions = {
     firstPacketTimeoutMs?: string;
     firstOutputTimeoutMs?: string;
 };
-export declare function runSendStart(commandOptions: SendCommandOptions, options: CliOptions): Promise<number>;
-export declare function runReceiveStart(commandOptions: ReceiveCommandOptions, options: CliOptions): Promise<number>;
+export declare function runDeviceStart(commandOptions: DeviceCommandOptions, options: CliOptions): Promise<number>;
+export declare function runClientStart(commandOptions: ClientCommandOptions, options: CliOptions): Promise<number>;
 export {};

package/dist/cli/src/role_driver.js

@@ -3,15 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runSendStart = runSendStart;
-exports.runReceiveStart = runReceiveStart;
+exports.runDeviceStart = runDeviceStart;
+exports.runClientStart = runClientStart;
 const child_process_1 = __importDefault(require("child_process"));
 const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const embedded_paths_1 = require("./embedded_paths");
-const token_tool_1 = require("./token_tool");
 const defaultAudioStreamId = 10;
 const defaultVideoStreamId = 11;
 const defaultConnectTimeoutMs = 10000;
@@ -142,13 +141,6 @@ function parseOptionalPositiveInt(raw, name) {
     }
     return parsePositiveInt(raw, 1, name);
 }
-function requireEnv(name) {
-    const value = process.env[name]?.trim();
-    if (!value) {
-        throw rolePreflightError('missing_env', 'missing environment: ' + name);
-    }
-    return value;
-}
 function executionSuffix() {
     return new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14);
 }
@@ -211,10 +203,30 @@ function readTokenIssueJson(filePath) {
         appId: trimOptional(parsed.data?.payload?.app_id),
     };
 }
+function resolveDeviceIdentity(options) {
+    const deviceId = trimOptional(options.deviceId) ?? trimOptional(process.env.TIRTC_DEVICE_ID);
+    const deviceSecretKey = trimOptional(options.deviceSecretKey) ??
+        trimOptional(process.env.TIRTC_DEVICE_SECRET_KEY);
+    const endpoint = trimOptional(options.endpoint) ?? trimOptional(process.env.TIRTC_ENDPOINT);
+    const missing = [];
+    if (!deviceId) {
+        missing.push('device id (pass --device-id or set TIRTC_DEVICE_ID)');
+    }
+    if (!deviceSecretKey) {
+        missing.push('device secret key (pass --device-secret-key or set TIRTC_DEVICE_SECRET_KEY)');
+    }
+    if (!endpoint) {
+        missing.push('endpoint (pass --endpoint or set TIRTC_ENDPOINT)');
+    }
+    if (missing.length > 0 || !deviceId || !deviceSecretKey || !endpoint) {
+        throw rolePreflightError('missing_env', 'device start requires ' + missing.join(' and '));
+    }
+    return { deviceId, deviceSecretKey, endpoint };
+}
 function readBootstrap(bootstrapPath) {
     const resolved = path_1.default.resolve(bootstrapPath);
     const parsed = readJson(resolved);
-    if (parsed.schema_version !== 1 || !parsed.remote_id || !parsed.token) {
+    if (parsed.schema_version !== 1 || !(parsed.device_id || parsed.remote_id) || !parsed.token) {
         throw roleUsageError('bootstrap_invalid');
     }
     return parsed;
@@ -277,62 +289,27 @@ function printEnvelope(options, code, message, data) {
         }
     }
 }
-async function buildSendRequest(roots, artifactRoot, options) {
+function buildDeviceRequest(roots, artifactRoot, options) {
     const codec = codecOrDefault(options.videoCodec);
-    const executionId = trimOptional(options.executionId) ?? 'cli-send-' + codec + '-' + executionSuffix();
-    const caseId = trimOptional(options.caseId) ?? 'devtools-cli-send.' + codec;
-    let remoteId = trimOptional(options.remoteId);
-    let endpoint = trimOptional(process.env.TIRTC_ENDPOINT);
-    let appId = trimOptional(options.appId) ?? trimOptional(process.env.TIRTC_APP_ID);
-    let token;
-    try {
-        if (options.bootstrapTokenJson) {
-            const tokenIssue = readTokenIssueJson(options.bootstrapTokenJson);
-            token = tokenIssue.token;
-            remoteId = remoteId ?? tokenIssue.remoteId;
-            endpoint = tokenIssue.endpoint ?? endpoint;
-            appId = appId ?? tokenIssue.appId;
-        }
-        else {
-            remoteId = remoteId ?? requireEnv('TIRTC_DEVICE_ID');
-            appId = appId ?? requireEnv('TIRTC_APP_ID');
-            token = await (0, token_tool_1.issueToken)({
-                accessId: requireEnv('TIRTC_ACCESS_KEY_ID'),
-                secretKey: requireEnv('TIRTC_SECRET_KEY_ID'),
-                appId,
-                remoteId,
-                openapiEndpoint: process.env.TIRTC_OPEN_API_ENDPOINT || process.env.TIRTC_OPENAPI_ENDPOINT,
-                endpoint,
-            });
-        }
-    }
-    catch (error) {
-        if (error instanceof RoleCommandError) {
-            throw error;
-        }
-        const detail = error instanceof Error ? error.message : String(error);
-        throw rolePreflightError('token_issue_failed', detail);
-    }
-    remoteId = remoteId ?? requireEnv('TIRTC_DEVICE_ID');
-    endpoint = endpoint ?? requireEnv('TIRTC_ENDPOINT');
-    appId = appId ?? requireEnv('TIRTC_APP_ID');
-    if (!token) {
-        throw rolePreflightError('token_issue_invalid', 'missing client token');
-    }
+    const executionId = 'cli-device-' + codec + '-' + executionSuffix();
+    const caseId = 'devtools-cli-device.' + codec;
+    const deviceIdentity = resolveDeviceIdentity(options);
+    const tokenIssue = options.clientTokenJson ? readTokenIssueJson(options.clientTokenJson) : undefined;
+    const bootstrap = tokenIssue ? {
+        client_token: tokenIssue.token,
+        token_fingerprint: tokenFingerprint(tokenIssue.token),
+    } : undefined;
     return {
         schema_version: 1,
         execution_id: executionId,
         case_id: caseId,
-        role: 'send',
-        endpoint,
+        role: 'device',
+        endpoint: deviceIdentity.endpoint,
         identity: {
-            license: remoteId + ',' + requireEnv('TIRTC_DEVICE_SECRET_KEY'),
-            remote_id: remoteId,
-        },
-        bootstrap: {
-            client_token: token,
-            token_fingerprint: tokenFingerprint(token),
+            license: deviceIdentity.deviceId + ',' + deviceIdentity.deviceSecretKey,
+            device_id: deviceIdentity.deviceId,
         },
+        bootstrap,
         streams: {
             audio_stream_id: defaultAudioStreamId,
             video_stream_id: defaultVideoStreamId,
@@ -349,30 +326,49 @@ async function buildSendRequest(roots, artifactRoot, options) {
             first_output_timeout_ms: defaultFirstOutputTimeoutMs,
         },
         artifact: { root_dir: artifactRoot },
-        probe: { app_id: appId },
+        probe: { app_id: tokenIssue?.appId ?? '' },
     };
 }
-function buildReceiveRequest(roots, artifactRoot, options) {
+function buildClientRequest(roots, artifactRoot, options) {
     const bootstrap = options.bootstrap ? readBootstrap(options.bootstrap) : undefined;
-    const remoteId = options.remoteId?.trim() || bootstrap?.remote_id || process.env.TIRTC_REMOTE_ID?.trim() || process.env.TIRTC_DEVICE_ID?.trim();
+    const targetDeviceId = trimOptional(options.targetDeviceId) ??
+        trimOptional(bootstrap?.device_id) ??
+        trimOptional(bootstrap?.remote_id) ??
+        trimOptional(process.env.TIRTC_TARGET_DEVICE_ID);
     const token = options.token?.trim() || bootstrap?.token || process.env.TIRTC_TOKEN?.trim();
-    if (!remoteId) {
-        throw rolePreflightError('missing_env', 'missing remote id: pass --remote-id, --bootstrap, or TIRTC_REMOTE_ID');
+    const endpoint = trimOptional(options.endpoint) ??
+        trimOptional(bootstrap?.endpoint) ??
+        trimOptional(process.env.TIRTC_ENDPOINT);
+    const appId = trimOptional(options.appId) ??
+        trimOptional(bootstrap?.app_id) ??
+        trimOptional(process.env.TIRTC_APP_ID);
+    const missing = [];
+    if (!targetDeviceId) {
+        missing.push('target device id (pass --target-device-id, --bootstrap, or set TIRTC_TARGET_DEVICE_ID)');
     }
     if (!token) {
-        throw rolePreflightError('missing_env', 'missing token: pass --token, --bootstrap, or TIRTC_TOKEN');
+        missing.push('token (pass --token, --bootstrap, or set TIRTC_TOKEN)');
     }
-    const executionId = 'cli-receive-' + executionSuffix();
-    const identityOverride = Boolean(bootstrap && (options.remoteId || options.token));
+    if (!endpoint) {
+        missing.push('endpoint (pass --endpoint, --bootstrap, or set TIRTC_ENDPOINT)');
+    }
+    if (!appId) {
+        missing.push('app id (pass --app-id, --bootstrap, or set TIRTC_APP_ID)');
+    }
+    if (missing.length > 0 || !targetDeviceId || !token || !endpoint || !appId) {
+        throw rolePreflightError('missing_env', 'client start requires ' + missing.join(' and '));
+    }
+    const executionId = 'cli-client-' + executionSuffix();
+    const identityOverride = Boolean(bootstrap && (options.targetDeviceId || options.token));
     const videoCodec = codecOrDefault(bootstrap?.video_codec);
     return {
         schema_version: 1,
         execution_id: executionId,
-        case_id: 'devtools-cli-receive',
-        role: 'receive',
-        endpoint: process.env.TIRTC_ENDPOINT?.trim() || bootstrap?.endpoint || '',
+        case_id: 'devtools-cli-client',
+        role: 'client',
+        endpoint,
         identity: {
-            remote_id: remoteId,
+            device_id: targetDeviceId,
             token,
             bootstrap_path: options.bootstrap ? path_1.default.resolve(options.bootstrap) : undefined,
             bootstrap_id: bootstrap?.bootstrap_id,
@@ -397,7 +393,7 @@ function buildReceiveRequest(roots, artifactRoot, options) {
             first_output_timeout_ms: parsePositiveInt(options.firstOutputTimeoutMs, defaultFirstOutputTimeoutMs, '--first-output-timeout-ms'),
         },
         artifact: { root_dir: artifactRoot },
-        probe: { app_id: process.env.TIRTC_APP_ID?.trim() || bootstrap?.app_id || '' },
+        probe: { app_id: appId },
     };
 }
 function runDriver(request, artifactRoot, roots) {
@@ -460,21 +456,23 @@ async function runRole(role, commandOptions, options) {
     const artifactRoot = path_1.default.resolve(commandOptions.artifactRoot ?? defaultRoot);
     ensureDir(artifactRoot);
     try {
-        const request = role === 'send' ?
-            await buildSendRequest(roots, artifactRoot, commandOptions) :
-            buildReceiveRequest(roots, artifactRoot, commandOptions);
+        const request = role === 'device' ?
+            buildDeviceRequest(roots, artifactRoot, commandOptions) :
+            buildClientRequest(roots, artifactRoot, commandOptions);
         const summary = runDriver(request, artifactRoot, roots);
         const summaryPath = path_1.default.join(artifactRoot, 'summary.json');
         const data = {
             status: summary.status,
             exit_code: summary.exit_code,
-            role: summary.role,
+            role,
             execution_id: summary.execution_id,
             artifact_root: artifactRoot,
             summary_path: summaryPath,
             bootstrap_path: summary.bootstrap_path,
             reason_code: summary.reason_code,
             failed_stage: failedStage(summary),
+            log_id: summary.log_upload?.log_id,
+            log_upload: summary.log_upload,
         };
         if (summary.exit_code === 0 && summary.status === 'completed') {
             printEnvelope(options, 0, 'OK', data);
@@ -497,9 +495,9 @@ async function runRole(role, commandOptions, options) {
         return normalized.exitCode;
     }
 }
-function runSendStart(commandOptions, options) {
-    return runRole('send', commandOptions, options);
+function runDeviceStart(commandOptions, options) {
+    return runRole('device', commandOptions, options);
 }
-function runReceiveStart(commandOptions, options) {
-    return runRole('receive', commandOptions, options);
+function runClientStart(commandOptions, options) {
+    return runRole('client', commandOptions, options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-devtools-cli",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "private": false,
   "main": "dist/cli/src/index.js",
   "types": "dist/cli/src/index.d.ts",

package/vendor/runtime/linux-x64/include/tirtc/error.h

@@ -91,6 +91,28 @@ typedef enum TirtcError {
   TIRTC_ERROR_VIDEO_DECODER_INPUT_PENDING = 6081,
   TIRTC_ERROR_VIDEO_DECODER_OUTPUT_PENDING = 6082,
   TIRTC_ERROR_MEDIA_UPLINK_INPUT_MODE_MISMATCH = 6083,
+  TIRTC_ERROR_TRANSPORT_CONNECT_INVOCATION_FAILED = 6084,
+  TIRTC_ERROR_TRANSPORT_DISCONNECT_STATE_UNEXPECTED = 6085,
+  TIRTC_ERROR_HTTP_TRANSPORT_FAILED = 6086,
+  TIRTC_ERROR_LOG_UPLOAD_ENDPOINT_RESPONSE_INVALID = 6087,
+  TIRTC_ERROR_LOG_UPLOAD_TOKEN_RESPONSE_INVALID = 6088,
+  TIRTC_ERROR_TRANSPORT_BACKEND_UNKNOWN_STATUS = 6089,
+  TIRTC_ERROR_TRANSPORT_BACKEND_CONNECTION_OTHER_ERROR = 6090,
+  TIRTC_ERROR_FACADE_HANDLE_UNAVAILABLE = 6091,
+  TIRTC_ERROR_AUDIO_PROCESSING_STATE_INVALID = 6092,
+  TIRTC_ERROR_AUDIO_PROCESSING_CONFIGURATION_FAILED = 6093,
+  TIRTC_ERROR_AUDIO_PROCESSING_PROCESS_FAILED = 6094,
+  TIRTC_ERROR_VIDEO_ENCODER_STATE_INVALID = 6095,
+  TIRTC_ERROR_VIDEO_ENCODER_INPUT_REJECTED = 6096,
+  TIRTC_ERROR_VIDEO_ENCODER_OUTPUT_RETRIEVE_FAILED = 6097,
+  TIRTC_ERROR_VIDEO_ENCODER_OUTPUT_CONVERSION_FAILED = 6098,
+  TIRTC_ERROR_VIDEO_ENCODER_CONTROL_REQUEST_FAILED = 6099,
+  TIRTC_ERROR_VIDEO_DECODER_STATE_INVALID = 6100,
+  TIRTC_ERROR_VIDEO_DECODER_INPUT_REJECTED = 6101,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_RETRIEVE_FAILED = 6102,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_CONVERSION_FAILED = 6103,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_RELEASE_FAILED = 6104,
+  TIRTC_ERROR_TRANSPORT_BACKEND_NOT_INITIALIZED = 6105,
 } TirtcError;
 
 const char* tirtc_error_to_string(TirtcError error);

package/vendor/runtime/linux-x64/manifest.txt

@@ -1,6 +1,6 @@
 platform=linux-x64
 profile=full
-staged_at_utc=2026-04-30T09:51:52Z
+staged_at_utc=2026-04-30T14:53:23Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/linux-x64
 
 bfc096be1484ac2b1c2776ccabfa2a4c6a982e869abf875192ff06fad85e82ca  include/tirtc/audio.h
@@ -14,7 +14,7 @@ c2e1f31dcc75be461c577d18b1cebe32774f212d51cb4dd2a5b5a9bfe62b693e  include/tirtc/
 21f60729117260a44af22c1af986ef17d22673b102b7b7a035f492d0665cce16  include/tirtc/audio_processing.h
 0ca7c3c630b1242f51a0fd8154097c0a332b4c816a5707090e4381719852998c  include/tirtc/audio_sample_rate.h
 58807ba56770f38f47aec995661cadf9d3c1d6ea7bfc940767f1ce67317c7546  include/tirtc/av.h
-0f3e2f454c35e8c2f79bdc93ed77f9f1622751e5a05defa8c9d4213ed8a797c5  include/tirtc/error.h
+b3e110ce04057d3be696b120d1abeaf6141711a1c63ca7f9bdf65ed5ec6e16d7  include/tirtc/error.h
 ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/foundation/build_info.h
 7cf8b372a3d48d4de4a65a04c7f102281a7b42cebb9ec247853d3c53afb63b6a  include/tirtc/http.h
 70bbf93b84d9d1a85f376d9986de570c1f658319e1e5ab6d621f7a4d41033f5c  include/tirtc/logging.h
@@ -33,13 +33,13 @@ cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/
 8cd6b66bea14890a665cc317f8572429b2c3e4463773f8b77c1e4dc30a4a8747  include/tirtc/video_processing.h
 ceb7cdd45efae57e5bd53d4177cb20c4a0cb9917fcdd23127b050d69c8b919ac  lib/libTiRTC.a
 b1f4135025cb8e8520a14268d831b9998920a4239f84bb6b409d0e4909fd5bee  lib/libcrypto.a
-8e3aff3a400fe0971c61511947c0e69d06754002d970e21eaab2339ae38b4a42  lib/libmatrix_runtime_audio.a
-09696896a45a4fab199f0767979471c947b252fc8741a0e803624cdac6953b59  lib/libmatrix_runtime_facade.a
-2c8cc881eeeae679129360df5813dec17d0e33935f196d79cf79671dbd0c8581  lib/libmatrix_runtime_foundation_http.a
-4623c3c72a263f0397e554435e4998551c274b5b40f98f331902a8c0c8a29e3e  lib/libmatrix_runtime_foundation_logging.a
-fe6b5575ce5e80f81e07a7799a05d0a8ee5a338915a28ada86d9009eee952e96  lib/libmatrix_runtime_media.a
-86d9b41f84c6bcc13f8d23a1f9b46d97fe6769573758722f9f6c8d4a130306be  lib/libmatrix_runtime_transport.a
-6ac178f5cd371e9a5be1989dd1e8a3767291f4c4d9d30dcf12ecdd75a2081afa  lib/libmatrix_runtime_video.a
+296ba0b5efa9d2ac49e3bf278c5d467b31436e73fbc608b736e974bcf9759bde  lib/libmatrix_runtime_audio.a
+88f9c545943e4ef80024baf3620e91817ec16a4fea60b0e8c7887a0a41dc9d1b  lib/libmatrix_runtime_facade.a
+ec7bbf8e8744c6645a441a28e24e0645906152cc987d6fcca16af3c3badba940  lib/libmatrix_runtime_foundation_http.a
+c8d9968c3544028f2e800d7f5ab6fa1604c54d5fddc682d65b5885ebac3967a8  lib/libmatrix_runtime_foundation_logging.a
+9c7108b70cb442dee02cfdb4f98891a8a099f15c379e9e48cf53d7b276f6e894  lib/libmatrix_runtime_media.a
+fc498c74804ef35dc3939a6368d9ae908b0e35578db32eb7902ad00107781295  lib/libmatrix_runtime_transport.a
+337d38891e264e76aeb61a4e25a3b0bad56ab26697948805e64dec920874093f  lib/libmatrix_runtime_video.a
 511d521f7972df3993e5976d6e2dbcad7a6fbce9be15071274d0cbd9d51157f5  lib/libssl.a
 a67ec9034848ef24a1b17671e444daa62a8f9e6b8319a1e932593908720ff2a1  lib/libwebrtc_apm.a
 700e455255897e3cffab13ca593a6e4d9d11383ae609215cbbd6043a63d47161  lib/libxlog.a

package/vendor/runtime/macos-arm64/include/tirtc/error.h

@@ -91,6 +91,28 @@ typedef enum TirtcError {
   TIRTC_ERROR_VIDEO_DECODER_INPUT_PENDING = 6081,
   TIRTC_ERROR_VIDEO_DECODER_OUTPUT_PENDING = 6082,
   TIRTC_ERROR_MEDIA_UPLINK_INPUT_MODE_MISMATCH = 6083,
+  TIRTC_ERROR_TRANSPORT_CONNECT_INVOCATION_FAILED = 6084,
+  TIRTC_ERROR_TRANSPORT_DISCONNECT_STATE_UNEXPECTED = 6085,
+  TIRTC_ERROR_HTTP_TRANSPORT_FAILED = 6086,
+  TIRTC_ERROR_LOG_UPLOAD_ENDPOINT_RESPONSE_INVALID = 6087,
+  TIRTC_ERROR_LOG_UPLOAD_TOKEN_RESPONSE_INVALID = 6088,
+  TIRTC_ERROR_TRANSPORT_BACKEND_UNKNOWN_STATUS = 6089,
+  TIRTC_ERROR_TRANSPORT_BACKEND_CONNECTION_OTHER_ERROR = 6090,
+  TIRTC_ERROR_FACADE_HANDLE_UNAVAILABLE = 6091,
+  TIRTC_ERROR_AUDIO_PROCESSING_STATE_INVALID = 6092,
+  TIRTC_ERROR_AUDIO_PROCESSING_CONFIGURATION_FAILED = 6093,
+  TIRTC_ERROR_AUDIO_PROCESSING_PROCESS_FAILED = 6094,
+  TIRTC_ERROR_VIDEO_ENCODER_STATE_INVALID = 6095,
+  TIRTC_ERROR_VIDEO_ENCODER_INPUT_REJECTED = 6096,
+  TIRTC_ERROR_VIDEO_ENCODER_OUTPUT_RETRIEVE_FAILED = 6097,
+  TIRTC_ERROR_VIDEO_ENCODER_OUTPUT_CONVERSION_FAILED = 6098,
+  TIRTC_ERROR_VIDEO_ENCODER_CONTROL_REQUEST_FAILED = 6099,
+  TIRTC_ERROR_VIDEO_DECODER_STATE_INVALID = 6100,
+  TIRTC_ERROR_VIDEO_DECODER_INPUT_REJECTED = 6101,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_RETRIEVE_FAILED = 6102,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_CONVERSION_FAILED = 6103,
+  TIRTC_ERROR_VIDEO_DECODER_OUTPUT_RELEASE_FAILED = 6104,
+  TIRTC_ERROR_TRANSPORT_BACKEND_NOT_INITIALIZED = 6105,
 } TirtcError;
 
 const char* tirtc_error_to_string(TirtcError error);

package/vendor/runtime/macos-arm64/manifest.txt

@@ -1,6 +1,6 @@
 platform=macos-arm64
 profile=full
-staged_at_utc=2026-04-30T09:50:11Z
+staged_at_utc=2026-04-30T14:51:39Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/macos-arm64
 
 bfc096be1484ac2b1c2776ccabfa2a4c6a982e869abf875192ff06fad85e82ca  include/tirtc/audio.h
@@ -14,7 +14,7 @@ c2e1f31dcc75be461c577d18b1cebe32774f212d51cb4dd2a5b5a9bfe62b693e  include/tirtc/
 21f60729117260a44af22c1af986ef17d22673b102b7b7a035f492d0665cce16  include/tirtc/audio_processing.h
 0ca7c3c630b1242f51a0fd8154097c0a332b4c816a5707090e4381719852998c  include/tirtc/audio_sample_rate.h
 58807ba56770f38f47aec995661cadf9d3c1d6ea7bfc940767f1ce67317c7546  include/tirtc/av.h
-0f3e2f454c35e8c2f79bdc93ed77f9f1622751e5a05defa8c9d4213ed8a797c5  include/tirtc/error.h
+b3e110ce04057d3be696b120d1abeaf6141711a1c63ca7f9bdf65ed5ec6e16d7  include/tirtc/error.h
 ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/foundation/build_info.h
 7cf8b372a3d48d4de4a65a04c7f102281a7b42cebb9ec247853d3c53afb63b6a  include/tirtc/http.h
 70bbf93b84d9d1a85f376d9986de570c1f658319e1e5ab6d621f7a4d41033f5c  include/tirtc/logging.h
@@ -35,13 +35,13 @@ cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/
 8db86d6714264047e8fd4086ddd7315722d675749719e6175f89eb5a636b48a1  lib/libTiRTC.a
 b39daee6a3d39bf0ca20c45084601133c4198de8dca848dcff6dd9c70ae99016  lib/libcrypto.a
 c052857ef315e3d61db9c862cad10709a3a6b2487dc41799cbe4d74a805de875  lib/libcrypto.dylib
-d6f03b56a9de8db6b283acbdd9fc2805d23d672f4cb88749f55a627443b2519f  lib/libmatrix_runtime_audio.a
-7524498dba92087ba33853290db0cfaa0ec79b50ffdf22c8e35b0484c24af7cc  lib/libmatrix_runtime_facade.a
-05687add5f3f27adea62568b9d42be52659a494500cce0245d601da566aa45e3  lib/libmatrix_runtime_foundation_http.a
-89af61f8a48b2c7cfa9c80de8b9a708bca4ac2b1b4b2929d1d932a5c4d422501  lib/libmatrix_runtime_foundation_logging.a
-6a61357646112e1427db956ba87766838b51bdd7d8aec43ec07c2aba20570ee7  lib/libmatrix_runtime_media.a
-cc39fbeacd2c8cd6b508cd3300bf8fd5b6a93f6d2d19b160b65ed03deca777c4  lib/libmatrix_runtime_transport.a
-7ab317069e6bdeb3d24d215cd7bb6f298ea47cf1cff43ac36460aaab7effbd8d  lib/libmatrix_runtime_video.a
+33742c05d53b6d7cf5c415ef0cd011a78b800493a02da341d856717fff9ae36a  lib/libmatrix_runtime_audio.a
+30c3ab7aaf27c7de6674ce9a1e41bb381c763e965142ad62acb4fb67d40bc852  lib/libmatrix_runtime_facade.a
+a2e3bdd6b2543e83972c7cc4052b3df1516c8c323208402b7d4cd5e26f4fc86b  lib/libmatrix_runtime_foundation_http.a
+45270e2123ea3f40eb1f20a2909018e3d5e6fb58d11f849ba72f6087c76c9d75  lib/libmatrix_runtime_foundation_logging.a
+9aadb323e7c61ec1a06ae5f50f452d39d4a3180a757b562977e7e000f64a1f06  lib/libmatrix_runtime_media.a
+8ffe6de3e6268d6002ca73c65c9f68968c761a76d0a2bcb2ea0cd70c750e7e0f  lib/libmatrix_runtime_transport.a
+5dfce7599170bba0f14167373b489934f744eb01b8ff12fd491d99d985a9d008  lib/libmatrix_runtime_video.a
 c11c65d373a127028350c41fa58cd2d1223f2b5d70a84e13b115d90daaba25ca  lib/libssl.a
 ef1c1104bbdd2528ed7b958fb7252bd6249875f92300b0c9577d6c4bd6c0d88a  lib/libssl.dylib
 e14e846e43d64e240fa0e5745bf4e702b79d0f2442e7f768beb990610735c71b  lib/libtgrtc.dylib