@myagentroam/node 0.12.0 → 0.12.1

package/dist/marctl/src/i18n/en-US.mjs

@@ -0,0 +1,285 @@
+const configurationHelp = `Authorization:
+  Node access is available only in MAR-launched terminals and Workspace Agent Runs;
+  scheduled runs use the task owner. MAR supplies short-lived user credentials.
+  External terminals and persistent administrator keys are not supported.`;
+
+export default Object.freeze({
+  help: `marctl — MyAgentRoam command-line interface
+
+Usage:
+  marctl [options] <command> [arguments]
+  marctl help [command]
+
+Commands:
+  agents   Inspect and coordinate Sessions in the current Workspace.
+  nodes    List accessible Nodes and their connection status.
+  ssh      Open a Node terminal or execute a remote command.
+  scp      Copy a regular file between this machine and Nodes, or between Nodes.
+  version  Print the installed CLI package version.
+  help     Show help for the CLI or a command.
+
+Options:
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  marctl nodes
+  marctl ssh <node> uname -a
+  marctl scp ./artifact.bin <node>:///tmp/artifact.bin
+  marctl --version
+  marctl help ssh
+
+Aliases:
+  marnodes  Equivalent to the nodes command.
+  marssh    Equivalent to the ssh command.
+  marscp    Equivalent to the scp command.
+
+${configurationHelp}
+
+Notes:
+  Help and version work offline without configuration or authorization.
+  Put local help/version options before a Node or file endpoint.
+  Each alias shows only its own command help. Use marctl help <command> for details.
+  Remote access uses authorized Node Terminal transport, not system SSH or SCP.`,
+  commandHelp: Object.freeze({
+    agents: `{program} — Coordinate Agents in the current MAR Workspace
+
+Usage:
+  {program} start [-m <text> | --message-file <file|->]
+    [--runner <runner>] [--parent <id>] [--model-id <id>] [--effort <value>]
+    [--title <name>] [--goal <objective> | --clear-goal]
+    [--client-message-id <id>] [--json]
+  {program} send <id> [-m <text> | --message-file <file|->]
+    [--steer | --queue] [--goal <objective> | --clear-goal]
+    [--approval <id> --decision <approve|reject>]
+    [--client-message-id <id>] [--json]
+  {program} wait [<id>] [--agent <id> ...] [--mode any|all]
+    [--wait-for message|completion] [--timeout <duration>] [--json]
+  {program} stop <id> [--json]
+  {program} list [--scope tree|active] [--query <title>]
+    [--limit <1..100>] [--json]
+  {program} view [<id>] [--json]
+
+Management:
+  {program} config [<id>] [--model-id <id>] [--effort <value>] [--json]
+  {program} rename [<id>] --title <name> [--json]
+  {program} prompt get|clear [<id>] [--json]
+  {program} prompt set [<id>] (-m <text> | --message-file <file|->) [--json]
+  {program} schedule list [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} schedule get [<id>] [--json]
+  {program} schedule create [<id>] --cron <cron>
+    (-m <text> | --message-file <file|->) [--json]
+  {program} schedule update [<id>] --expected-revision <revision>
+    [--cron <cron>] [-m <text> | --message-file <file|->] [--json]
+  {program} approval decide <id> --run <run-id> --approval <approval-id>
+    --decision <approve|reject> [--json]
+  {program} wait <id> --run <run-id> [--until approval] --timeout <duration>
+  {program} goal get|clear <id> [--json]
+  {program} goal set <id> (-m <text> | --message-file <file|->) [--json]
+  {program} current | show [<id>] | graph [<id>]
+  {program} history [<id>] [--cursor <cursor>] [--limit <1..100>] [--json]
+
+Input and results:
+  Start defaults to the current Session Runner; a terminal without a current
+  Session must specify --runner or --parent. Start returns without waiting.
+  Send appends by default; --steer provides timely input and --queue defers.
+  --goal sets or replaces a Goal; --clear-goal clears it. Send can update a Goal
+  without text; omitted Goal is unchanged. Stop targets the current execution
+  and clears the target Session Goal.
+  Wait defaults to direct-child completion and 30s; 0ms is a snapshot.
+  Positive timeouts use the requested duration; maximum is 5m.
+  Waiting does not stop the task.
+  -m and --message-file are exclusive; files use UTF-8 and - reads stdin.
+  List defaults to the containing tree, including idle Sessions. Without a
+  current Session it defaults to active; explicit tree requires a Session.
+  Active includes running and sleeping Sessions in the current Workspace.
+  List returns currentAgentId (null without a Session), flat sessions and
+  truncated. Limit defaults to 10, maximum 100; no cursor or pagination.
+  Active Sessions come first, then recent activity descending.
+  Configuration and prompt changes apply to future executions.
+  Prefer --steer for timely communication or course correction.
+  Reserve --queue for explicitly requested deferred input: it is consumed after
+  current work and earlier queued inputs finish. With an active Goal it is
+  not consumed until that Goal exits.
+  Acceptance does not guarantee immediate processing.
+  An accepted message normally needs no separate acknowledgment or receipt
+  check.
+  While children run, prefer meaningful, non-overlapping work; wait when needed
+  to unblock or finish and no other meaningful local task work remains.
+
+  show --json includes session.status, session.modelId, session.effort,
+  session.title, session.runId, session.recentTools, session.queuedCount and
+  session.latestMessage. List entries have id, parentSessionId, title and
+  status; wait may include progress. View omits Run and Execution IDs.
+  Status is RUNNING/IDLE/SLEEPING. In history, segments[].items[] with
+  kind === "assistant_message" expose payload.text.
+
+Exit codes: 1 failure, 2 input, 3 authorization, 4 unsupported, 5 timeout,
+  6 unknown outcome, 130 cancelled wait. --json prints one result or error.`,
+    nodes: `{program} — List accessible Nodes
+
+Usage:
+  {program} [options]
+
+Options:
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  {program}
+
+Output:
+  Tab-separated columns: ID, NAME, STATUS, PLATFORM.
+  Includes offline Nodes for which the current user has terminal permission.
+
+${configurationHelp}`,
+    ssh: `{program} — Open a terminal or execute a remote command
+
+Usage:
+  {program} [options] <node> [command [arg...]]
+
+Arguments:
+  <node>          An authorized Node ID or an exact, unique Node name.
+  [command ...]   A command for the remote shell; omit it for an interactive shell.
+
+Options (before <node>):
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  {program} ubuntu-develop
+  {program} ubuntu-develop uname -a
+  {program} ubuntu-develop "echo hello && whoami"
+
+Notes:
+  Names must be unique across accessible Nodes, including offline Nodes; use an ID on conflict.
+  Remote arguments are joined with spaces. Quote shell expressions for your local shell.
+  Remote --help, -h, and --version are not local options. The remote exit code is preserved.
+  Commands run as the Node service account; login accounts, privilege escalation, and SSH
+  connection options such as -t, -p, and -i are unsupported. No SSH port is required.
+  Connection setup has a timeout, but attached commands have no runtime or output-idle timeout.
+  Commands are not retried. Exit or unrecoverable disconnection closes the terminal;
+  this is not a background-job service.
+
+${configurationHelp}`,
+    scp: `{program} — Copy a regular file
+
+Usage:
+  {program} [options] <source> <destination>
+
+Arguments:
+  <source>        A local file or an authorized Node file endpoint.
+  <destination>   A local file/directory or an authorized Node endpoint.
+  Node endpoints: <node>://<absolute-path> or <node>:<absolute-path>.
+  <node> is an ID or an exact, unique name, including offline Nodes.
+  At least one endpoint must be a Node. Linux and Windows paths are supported.
+
+Options:
+  -p              Preserve source permissions and access/modification times.
+  -q              Suppress progress output (already the default).
+  -h, --help       Show help and exit; place before the first endpoint.
+  -V, --version    Print the CLI package version and exit; place before the first endpoint.
+  --              Treat remaining arguments as literal paths.
+
+Examples:
+  {program} ./artifact.bin ubuntu-develop:///tmp/artifact.bin
+  {program} ubuntu-develop:///tmp/artifact.bin ./
+  {program} -p linux:///tmp/artifact.bin "windows://C:/Artifacts/"
+
+Notes:
+  Existing directories receive the source filename; directory paths must already exist.
+  Existing regular files are overwritten, retaining their permissions unless -p is used.
+  Directory sources, symlinks, invalid destination filenames, and directory final targets
+  are rejected. Recursive -r, multiple sources, and SSH connection options are unsupported.
+  Both Server and Node must support binary Terminal pipes; this is not system SCP.
+  File access uses the Node service account's permissions. Checksums are verified before
+  atomic publication; failed transfers leave the original unchanged. Forced termination
+  may leave a temporary file. Transfers are not retried.
+
+${configurationHelp}`,
+    version: `marctl — MyAgentRoam CLI version
+
+Usage:
+  {program} [options]
+  marctl --version
+  marctl -V
+
+Options:
+  -h, --help       Show help and exit.
+  -V, --version    Print the CLI package version and exit.
+
+Examples:
+  {program}
+  marctl --version
+
+Output:
+  marctl <version>
+
+Prints the installed Node package version on one line, followed by a newline.
+No configuration, authorization, or Server connection is required.`
+  }),
+  nodesHeader: 'ID\tNAME\tSTATUS\tPLATFORM',
+  connected: 'connected',
+  disconnected: 'disconnected',
+  errors: Object.freeze({
+    sessionOutcomeUnknown:
+      'The delivery outcome is unknown. Inspect Session state/history before retrying.',
+    sessionMessageInvalid:
+      'The message must be non-empty and within the length limit; input files must be readable UTF-8.',
+    sessionWaitUnknown: 'The specified Run could not be confirmed. Inspect Session state/history.',
+    sessionWaitCancelled: 'Waiting was cancelled; the target Run was not stopped.',
+    sessionWaitTimeout: 'Waiting timed out; the target Run was not stopped.',
+    sessionApprovalUnsupported: 'This Node does not provide pending approval observations.',
+
+    userContextUnavailable: 'This Node session has no valid marctl user authorization.',
+    sessionContextRequired: 'No current Session is available; specify a Session ID explicitly.',
+    serverUrlInvalid: 'MAR_CTL_SERVER_URL is invalid.',
+    serverUrlTransport: 'MAR_CTL_SERVER_URL must use HTTPS or loopback HTTP.',
+    serverUrlOrigin: 'MAR_CTL_SERVER_URL must be an origin without credentials or query data.',
+    fetchUnavailable: 'Fetch is unavailable in this Node.js runtime.',
+    serverInvalidNodes: 'The server returned an invalid node list.',
+    serverInvalidManifest: 'The server returned an invalid node manifest.',
+    terminalCommandInvalid: 'The terminal command is invalid.',
+    terminalSequenceInvalid: 'The terminal sequence is invalid.',
+    terminalTicketInvalid: 'The terminal ticket is invalid.',
+    terminalIdInvalid: 'The terminal identifier is invalid.',
+    nodeIdInvalid: 'The node identifier is invalid.',
+    nodeNameAmbiguous: 'Multiple accessible nodes share that name; use a node ID.',
+    nodeNotFound: 'No accessible node matches this ID or name.',
+    terminalSizeInvalid: 'The terminal size is invalid.',
+    serverInvalidTerminalId: 'The server returned an invalid terminal identifier.',
+    serverInvalidTicket: 'The server returned an invalid terminal ticket.',
+    serverInvalidJson: 'The server returned invalid JSON.',
+    serverTimeout: 'The marctl server did not respond before the control request timeout.',
+    serverUnreachable: 'The marctl server could not be reached.',
+    serverRejected: 'The marctl server rejected the request.',
+    terminalConnectionStart: 'The terminal connection could not be started.',
+    terminalConnectionOpen: 'The terminal connection could not be opened.',
+    terminalAttachTimeout: 'The terminal did not attach before the connection setup timeout.',
+    terminalAttachConnection: 'The terminal connection failed during attachment.',
+    terminalAttachLost: 'The terminal connection was lost during attachment.',
+    terminalRemoteError: 'The remote terminal reported an error.',
+    terminalClosedBeforeAttach: 'The remote terminal closed before attachment.',
+    terminalFrameInvalid: 'The terminal frame was invalid.',
+    terminalInvalidJson: 'The terminal sent invalid JSON.',
+    terminalBinaryFrame: 'The terminal sent an invalid binary frame.',
+    terminalBinaryUnavailable:
+      'Binary copy requires a Server and Node that support pipe terminals.',
+    terminalConnectionFailed: 'The terminal connection failed.',
+    terminalConnectionLost: 'The terminal connection was lost.',
+    terminalUnexpectedFrame: 'The remote terminal sent an unexpected frame.',
+    terminalInputFailed: 'The terminal input could not be sent.',
+    terminalResizeFailed: 'The terminal resize could not be sent.',
+    terminalInteractiveRequired: 'An interactive terminal is required.',
+    terminalInteractiveInit: 'The interactive terminal could not be initialized.',
+    terminalCloseFailed: 'The remote terminal could not be closed.',
+    terminalSessionFailed: 'The terminal session failed.',
+    terminalDirectUnsafeFallback:
+      'Direct terminal setup could not be safely canceled after OPEN; relay fallback was skipped.',
+    invalidArguments: 'Invalid command arguments.',
+    sessionDeliveryRequired: 'Send requires exactly one of --steer or --queue, even when idle.',
+    sshOptionsUnsupported: 'SSH options are not supported; use marssh <host>.',
+    scpOptionsUnsupported: 'This SCP option is not supported by the Node Terminal transport.',
+    commandFailed: 'The command failed.'
+  })
+});

package/dist/marctl/src/i18n/index.mjs

@@ -0,0 +1,20 @@
+import enUS from './en-US.mjs';
+import zhCN from './zh-CN.mjs';
+
+export function localeFromEnv(env = process.env) {
+  const value = String(env.LC_ALL || env.LANG || '').toLowerCase();
+  return value.startsWith('zh_') || value.startsWith('zh-') || value === 'zh' ? 'zh-CN' : 'en-US';
+}
+
+export function createTranslator(env = process.env) {
+  const locale = localeFromEnv(env);
+  const resource = locale === 'zh-CN' ? zhCN : enUS;
+  const translate = (key, params = {}) => {
+    const value = key.split('.').reduce((current, part) => current?.[part], resource);
+    if (typeof value === 'function') return value(params);
+    if (typeof value !== 'string') return key;
+    return value.replace(/\{(\w+)\}/gu, (_match, name) => String(params[name] ?? ''));
+  };
+  translate.locale = locale;
+  return translate;
+}

package/dist/marctl/src/i18n/zh-CN.mjs

@@ -0,0 +1,269 @@
+const configurationHelp = `授权：
+  仅 MAR 打开的终端和普通 Workspace Agent Run 可访问节点，定时任务使用任务 owner 的权限。
+  MAR 自动提供短期用户凭证；不支持外部终端或持久管理员密钥。`;
+
+export default Object.freeze({
+  help: `marctl — MyAgentRoam 命令行工具
+
+用法：
+  marctl [选项] <子命令> [参数]
+  marctl help [子命令]
+
+子命令：
+  agents   查看和协调当前工作区中的会话。
+  nodes    列出有权限的节点及连接状态。
+  ssh      打开节点终端或执行远程命令。
+  scp      在当前机器与节点之间、节点之间复制普通文件。
+  version  显示已安装的 CLI 包版本。
+  help     显示工具或指定子命令的帮助。
+
+选项：
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  marctl nodes
+  marctl ssh <节点> uname -a
+  marctl scp ./artifact.bin <节点>:///tmp/artifact.bin
+  marctl --version
+  marctl help ssh
+
+快捷命令：
+  marnodes  等价于 nodes 子命令。
+  marssh    等价于 ssh 子命令。
+  marscp    等价于 scp 子命令。
+
+${configurationHelp}
+
+说明：
+  帮助和版本查询离线可用，无需配置或授权。
+  本机帮助、版本选项须放在节点或文件端点前。
+  快捷命令仅显示对应操作的帮助。用 marctl help <子命令> 查看详细说明。
+  远程访问使用授权的 Node Terminal 传输，不是系统 SSH 或 SCP 协议。`,
+  commandHelp: Object.freeze({
+    agents: `{program} — 协调当前 MAR 工作区中的 Agent
+
+用法：
+  {program} start [-m <text> | --message-file <file|->]
+    [--runner <runner>] [--parent <id>] [--model-id <id>] [--effort <value>]
+    [--title <name>] [--goal <objective> | --clear-goal]
+    [--client-message-id <id>] [--json]
+  {program} send <id> [-m <text> | --message-file <file|->]
+    [--steer | --queue] [--goal <objective> | --clear-goal]
+    [--approval <id> --decision <approve|reject>]
+    [--client-message-id <id>] [--json]
+  {program} wait [<id>] [--agent <id> ...] [--mode any|all]
+    [--wait-for message|completion] [--timeout <duration>] [--json]
+  {program} stop <id> [--json]
+  {program} list [--scope tree|active] [--query <title>]
+    [--limit <1..100>] [--json]
+  {program} view [<id>] [--json]
+
+管理：
+  {program} config [<id>] [--model-id <id>] [--effort <value>] [--json]
+  {program} rename [<id>] --title <name> [--json]
+  {program} prompt get|clear [<id>] [--json]
+  {program} prompt set [<id>] (-m <text> | --message-file <file|->) [--json]
+  {program} schedule list [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} schedule get [<id>] [--json]
+  {program} schedule create [<id>] --cron <cron>
+    (-m <text> | --message-file <file|->) [--json]
+  {program} schedule update [<id>] --expected-revision <revision>
+    [--cron <cron>] [-m <text> | --message-file <file|->] [--json]
+  {program} approval decide <id> --run <run-id> --approval <approval-id>
+    --decision <approve|reject> [--json]
+  {program} wait <id> --run <run-id> [--until approval] --timeout <duration>
+  {program} goal get|clear <id> [--json]
+  {program} goal set <id> (-m <text> | --message-file <file|->) [--json]
+  {program} current | show [<id>] | graph [<id>]
+  {program} history [<id>] [--cursor <cursor>] [--limit <1..100>] [--json]
+
+输入与结果：
+  start 默认当前会话的 Runner；没有当前会话的终端须指定 --runner 或
+  --parent。start 不等待。
+  send 默认追加；--steer 优先补充，--queue 排队。--goal 设置或替换目标，
+  --clear-goal 清除目标；send 可仅更新目标，省略则不修改。
+  stop 停止目标当前执行并清除 Goal。wait 默认等待直接子会话终态 30 秒，
+  0ms 为快照；正数按传入时长等待，最多 5 分钟。等待不会停止任务。
+  -m 与 --message-file 互斥；文件使用 UTF-8，- 从 stdin 读取。
+  list 默认查询所在会话树，包含空闲会话；
+  没有当前会话时默认 active，显式 tree 须有会话上下文。active 包含当前
+  Workspace 中运行及睡眠的会话。返回 currentAgentId（无会话时为 null）、
+  扁平 sessions 和 truncated。limit 默认 10、上限 100，无 cursor 或分页。
+  活跃会话优先，其后按最近活动时间倒序。
+  配置和持久提示从后续执行生效。
+  即时沟通或纠偏优先使用 --steer。
+  建议仅将 --queue 用于明确要求延后的输入：当前工作及前面的队列项结束后才消费，
+  有活动 Goal 时，必须等到该 Goal 退出才消费。已接收不保证立即处理。
+  消息被接受后，通常无需另行确认收悉或立即查看是否收到。
+  子会话运行时建议并行推进有意义且不重叠的工作；无其他本地工作可做，且需
+  结果解除阻塞或收尾时，再考虑等待。
+
+  show --json 包含 session.status、session.modelId、session.effort、
+  session.title、session.runId、session.recentTools、session.queuedCount 和
+  session.latestMessage。list 每项仅含 id、parentSessionId、title 和 status；
+  wait 可能包含 progress；view 不公开 Run 或 Execution ID。
+  状态为 RUNNING/IDLE/SLEEPING。历史中 segments[].items[] 的
+  kind === "assistant_message" 包含 payload.text。
+
+退出码：1 失败，2 参数，3 授权，4 不支持，5 超时，6 结果未知，
+  130 取消等待。--json 输出单个结果或错误对象。`,
+    nodes: `{program} — 列出有权限的节点
+
+用法：
+  {program} [选项]
+
+选项：
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  {program}
+
+输出：
+  以制表符分隔的节点 ID、名称、状态、平台列。
+  包含当前用户有终端使用权的离线节点。
+
+${configurationHelp}`,
+    ssh: `{program} — 打开终端或执行远程命令
+
+用法：
+  {program} [选项] <节点> [command [arg...]]
+
+参数：
+  <节点>          有权限的节点 ID，或精确、唯一的节点名称。
+  [command ...]   交给远端 Shell 的命令；省略时打开交互 Shell。
+
+选项（放在节点前）：
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  {program} ubuntu-develop
+  {program} ubuntu-develop uname -a
+  {program} ubuntu-develop "echo hello && whoami"
+
+说明：
+  名称须在可访问节点中唯一（包括离线节点），重名时使用 ID。
+  远程参数以空格拼接；Shell 表达式须按本机 Shell 语法引用。
+  远端 --help、-h、--version 不作为本机选项处理；保留远程命令的真实退出码。
+  命令以 Node 服务账号运行，不支持登录账号、提权及 -t、-p、-i 等 SSH 连接选项；无需 SSH 端口。
+  建连有超时，附着后的命令没有运行时长或输出空闲超时。命令不自动重试。
+  退出或连接无法恢复时关闭终端，不提供后台任务托管。
+
+${configurationHelp}`,
+    scp: `{program} — 复制普通文件
+
+用法：
+  {program} [选项] <源> <目标>
+
+参数：
+  <源>            本机文件或有权限的节点文件端点。
+  <目标>          本机文件、目录或有权限的节点端点。
+  节点端点：<节点>://<绝对路径> 或 <节点>:<绝对路径>。
+  节点须使用 ID 或精确、唯一的名称（包括离线节点）。
+  至少一端必须为节点，支持 Linux 和 Windows 路径。
+
+选项：
+  -p              保留源文件权限及访问、修改时间。
+  -q              不显示进度（默认已不显示）。
+  -h, --help       显示帮助后退出，须放在第一个文件端点前。
+  -V, --version    显示 CLI 包版本后退出，须放在第一个文件端点前。
+  --              后续参数按字面路径处理。
+
+示例：
+  {program} ./artifact.bin ubuntu-develop:///tmp/artifact.bin
+  {program} ubuntu-develop:///tmp/artifact.bin ./
+  {program} -p linux:///tmp/artifact.bin "windows://C:/Artifacts/"
+
+说明：
+  已有目标目录自动追加源文件名；目录路径必须已存在。
+  已有普通文件默认覆盖，未使用 -p 时保留其权限。
+  拒绝源目录、符号链接、接收平台不合法的文件名及最终目标目录；不支持递归 -r、多源及 SSH 连接选项。
+  Server 和 Node 均须支持二进制 Terminal pipe；这不是系统 SCP。
+  文件访问遵循 Node 服务账号权限。完整校验后原子发布，失败不替换原文件；
+  强制终止可能留下临时文件，传输不自动重试。
+
+${configurationHelp}`,
+    version: `marctl — MyAgentRoam CLI 版本
+
+用法：
+  {program} [选项]
+  marctl --version
+  marctl -V
+
+选项：
+  -h, --help       显示帮助后退出。
+  -V, --version    显示 CLI 包版本后退出。
+
+示例：
+  {program}
+  marctl --version
+
+输出：
+  marctl <version>
+
+读取已安装的 Node 包版本，输出单行并以换行符结尾。
+无需配置、授权或连接 Server。`
+  }),
+  nodesHeader: '节点 ID\t名称\t状态\t平台',
+  connected: '在线',
+  disconnected: '离线',
+  errors: Object.freeze({
+    sessionOutcomeUnknown: '投递结果未知，请先查看会话状态和历史，不要盲目重试。',
+    sessionMessageInvalid: '消息不能为空或超过长度限制；输入文件必须是可读取的 UTF-8 文本。',
+    sessionWaitUnknown: '无法确认指定 Run，请查看会话状态和历史。',
+    sessionWaitCancelled: '已取消等待，未停止目标 Run。',
+    sessionWaitTimeout: '等待超时，未停止目标 Run。',
+    sessionApprovalUnsupported: '此 Node 不支持待审批状态观察。',
+
+    userContextUnavailable: '此 Node 会话没有有效的 marctl 用户授权。',
+    sessionContextRequired: '当前上下文没有会话，请显式指定会话 ID。',
+    serverUrlInvalid: 'MAR_CTL_SERVER_URL 无效。',
+    serverUrlTransport: 'MAR_CTL_SERVER_URL 必须使用 HTTPS 或回环 HTTP。',
+    serverUrlOrigin: 'MAR_CTL_SERVER_URL 必须是不含凭据或查询参数的 Origin。',
+    fetchUnavailable: '当前 Node.js 运行时没有 Fetch。',
+    serverInvalidNodes: 'Server 返回的节点列表无效。',
+    serverInvalidManifest: 'Server 返回的节点清单无效。',
+    terminalCommandInvalid: '终端命令无效。',
+    terminalSequenceInvalid: '终端序列无效。',
+    terminalTicketInvalid: '终端票据无效。',
+    terminalIdInvalid: '终端标识无效。',
+    nodeIdInvalid: '节点标识无效。',
+    nodeNameAmbiguous: '多个可访问节点同名，请使用节点 ID。',
+    nodeNotFound: '没有与该 ID 或名称匹配的可访问节点。',
+    terminalSizeInvalid: '终端尺寸无效。',
+    serverInvalidTerminalId: 'Server 返回的终端标识无效。',
+    serverInvalidTicket: 'Server 返回的终端票据无效。',
+    serverInvalidJson: 'Server 返回的 JSON 无效。',
+    serverTimeout: 'marctl Server 未能在控制面请求超时前响应。',
+    serverUnreachable: '无法连接 marctl Server。',
+    serverRejected: 'marctl Server 拒绝了请求。',
+    terminalConnectionStart: '无法启动终端连接。',
+    terminalConnectionOpen: '无法打开终端连接。',
+    terminalAttachTimeout: '终端未能在连接建立超时前完成附着。',
+    terminalAttachConnection: '终端附着期间连接失败。',
+    terminalAttachLost: '终端附着期间连接断开。',
+    terminalRemoteError: '远程终端返回错误。',
+    terminalClosedBeforeAttach: '远程终端在附着前关闭。',
+    terminalFrameInvalid: '终端帧无效。',
+    terminalInvalidJson: '终端返回了无效 JSON。',
+    terminalBinaryFrame: '终端返回了无效二进制帧。',
+    terminalConnectionFailed: '终端连接失败。',
+    terminalConnectionLost: '终端连接断开。',
+    terminalUnexpectedFrame: '远程终端返回了意外帧。',
+    terminalInputFailed: '无法发送终端输入。',
+    terminalResizeFailed: '无法发送终端尺寸。',
+    terminalInteractiveRequired: '需要交互式终端。',
+    terminalInteractiveInit: '无法初始化交互式终端。',
+    terminalCloseFailed: '无法关闭远程终端。',
+    terminalSessionFailed: '终端会话失败。',
+    terminalDirectUnsafeFallback: 'OPEN 后无法安全取消直连终端，已跳过 relay 回退。',
+    invalidArguments: '命令参数无效。',
+    sessionDeliveryRequired: 'send 必须且只能选择 --steer 或 --queue，即使目标空闲也需指定。',
+    sshOptionsUnsupported: '不支持 SSH 选项，请使用 marssh <节点>。',
+    scpOptionsUnsupported: 'Node Terminal 传输不支持此 SCP 选项。',
+    terminalBinaryUnavailable: '二进制复制需要支持 pipe 终端的 Server 与 Node。',
+    commandFailed: '命令执行失败。'
+  })
+});

package/dist/marctl/src/scp-channel.mjs

@@ -0,0 +1,99 @@
+import { MarctlError } from './errors.mjs';
+import { CHUNK, WINDOW } from './scp-protocol.mjs';
+
+const MAX_BUFFERED_BYTES = WINDOW * (CHUNK + 4) + 64;
+
+export class ByteChannel {
+  #buffer = Buffer.alloc(0);
+  #waiting = [];
+  #sending = new Map();
+  #ended;
+  #failure;
+  #controller;
+
+  constructor(send, controller) {
+    this.#controller = controller;
+    const signal = controller.signal;
+    this.send = (bytes) => {
+      if (this.#failure) throw this.#failure;
+      if (this.#ended !== undefined) throw new MarctlError('Copy stream ended unexpectedly.');
+      return new Promise((resolve, reject) => {
+        this.#sending.set(reject, resolve);
+        const settle = (complete, value) => {
+          this.#sending.delete(reject);
+          complete(value);
+        };
+        try {
+          Promise.resolve(send(bytes)).then(
+            (value) => settle(resolve, value),
+            (error) => settle(reject, error)
+          );
+        } catch (error) {
+          settle(reject, error);
+        }
+      });
+    };
+    if (signal) {
+      if (signal.aborted) this.fail(signal.reason);
+      else
+        signal.addEventListener('abort', () => this.fail(signal.reason), {
+          once: true
+        });
+    }
+  }
+
+  feed(bytes) {
+    if (this.#failure) return;
+    this.#buffer = Buffer.concat([this.#buffer, bytes]);
+    if (this.#buffer.length > MAX_BUFFERED_BYTES)
+      return this.fail(new MarctlError('Copy output exceeded the bounded window.'));
+    this.#wake();
+  }
+
+  finish(code) {
+    this.#ended = code;
+    if (code !== 0) return this.fail(new MarctlError('Remote copy command failed.'));
+    // A successful exit confirms the worker consumed its final protocol input.
+    for (const resolve of this.#sending.values()) resolve();
+    this.#sending.clear();
+    this.#wake();
+  }
+
+  connectionEnded(error) {
+    if (this.#ended === undefined) this.fail(error);
+  }
+
+  fail(error) {
+    if (this.#failure !== undefined) return;
+    this.#failure = error;
+    for (const reject of this.#sending.keys()) reject(this.#failure);
+    this.#sending.clear();
+    this.#wake();
+    // Any endpoint failure must wake reads and writes across the entire copy.
+    this.#controller.abort(error);
+  }
+
+  #wake() {
+    for (const resolve of this.#waiting.splice(0)) resolve();
+  }
+
+  async read(length) {
+    if (this.#failure) throw this.#failure;
+    while (this.#buffer.length < length) {
+      if (this.#failure) throw this.#failure;
+      if (this.#ended !== undefined) throw new MarctlError('Copy stream ended unexpectedly.');
+      await new Promise((resolve) => this.#waiting.push(resolve));
+    }
+    const bytes = this.#buffer.subarray(0, length);
+    this.#buffer = this.#buffer.subarray(length);
+    return bytes;
+  }
+
+  async done() {
+    if (this.#failure) throw this.#failure;
+    while (this.#ended === undefined && this.#failure === undefined)
+      await new Promise((resolve) => this.#waiting.push(resolve));
+    if (this.#failure) throw this.#failure;
+    if (this.#ended !== 0) throw new MarctlError('Remote copy command failed.');
+  }
+}