@myagentroam/marctl 0.11.4 → 0.11.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/marctl",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "description": "MyAgentRoam command-line interface for authorized Node access.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli.mjs

@@ -75,7 +75,7 @@ export async function main(
       }
       return 0;
     }
-    if (args.command === 'sessions') {
+    if (args.command === 'agents') {
       const execute = (signal) =>
         runSessionCommand({
           args,
@@ -122,7 +122,7 @@ export async function main(
       })
     );
   } catch (error) {
-    if (argv[0] === 'sessions') {
+    if (argv[0] === 'agents') {
       const failure = {
         code: error.code ?? 'MARCTL_COMMAND_FAILED',
         message: error instanceof MarctlError ? error.message : translate('errors.commandFailed'),
@@ -176,7 +176,7 @@ export function executableArgs(executable, args) {
 }
 
 export function parseArgs(argv, translate = createTranslator()) {
-  if (argv[0] === 'sessions') return parseSessionArgs(argv.slice(1), translate);
+  if (argv[0] === 'agents') return parseSessionArgs(argv.slice(1), translate);
   let command;
   let nodeId;
   const remoteArgs = [];
@@ -208,7 +208,7 @@ export function parseArgs(argv, translate = createTranslator()) {
         argument !== 'nodes' &&
         argument !== 'ssh' &&
         argument !== 'scp' &&
-        argument !== 'sessions' &&
+        argument !== 'agents' &&
         argument !== 'version'
       )
         throw unsupportedSshOption(argument, translate);

package/src/client.mjs

@@ -49,11 +49,13 @@ export class MarctlClient {
     });
   }
 
-  async sessionCommand(body) {
+  async sessionCommand(body, { timeoutMs, signal } = {}) {
     const result = await this.#requestJson('/api/marctl/sessions', {
       method: 'POST',
       body,
-      preserveError: true
+      preserveError: true,
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      ...(signal === undefined ? {} : { signal })
     });
     if (!isRecord(result))
       throw new MarctlError(this.#translate('errors.serverInvalidJson'), {
@@ -171,19 +173,33 @@ export class MarctlClient {
     return this.#request(pathname, { ...options, json: true });
   }
 
-  async #request(pathname, { method = 'GET', body, json = false, preserveError = false } = {}) {
+  async #request(
+    pathname,
+    {
+      method = 'GET',
+      body,
+      json = false,
+      preserveError = false,
+      timeoutMs = this.#requestTimeoutMs,
+      signal
+    } = {}
+  ) {
     const headers = {
       Accept: 'application/json',
       Authorization: `Bearer ${this.#key}`
     };
     const controller = new AbortController();
-    const request = { method, headers, signal: controller.signal };
+    const request = {
+      method,
+      headers,
+      signal: signal ? AbortSignal.any([controller.signal, signal]) : controller.signal
+    };
     if (body !== undefined) {
       headers['Content-Type'] = 'application/json';
       request.body = JSON.stringify(body);
     }
 
-    const timer = setTimeout(() => controller.abort(), this.#requestTimeoutMs);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const response = await this.#fetch(new URL(pathname, `${this.#serverUrl}/`), request);
       if (!response?.ok) {
@@ -227,6 +243,10 @@ export class MarctlClient {
         );
       }
     } catch (error) {
+      if (signal?.aborted)
+        throw new MarctlError(this.#translate('errors.sessionWaitCancelled'), {
+          code: 'MARCTL_WAIT_CANCELLED'
+        });
       if (error instanceof MarctlError) throw error;
       throw new MarctlError(
         this.#translate(

package/src/i18n/en-US.mjs

@@ -11,7 +11,7 @@ Usage:
   marctl help [command]
 
 Commands:
-  sessions Inspect and coordinate Sessions in the current Workspace.
+  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.
@@ -42,130 +42,73 @@ Notes:
   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({
-    sessions: `{program} — Coordinate Sessions in the current MAR Workspace
+    agents: `{program} — Coordinate Agents in the current MAR Workspace
 
 Usage:
-  {program} current [--json]
-  {program} list [--query <title>] [--parent <session-id>]
+  {program} start [-m <text> | --message-file <file|->] [--image <path> ...]
+    [--runner <runner>] [--parent <id>] [--model <id>] [--effort <value>]
+    [--title <name>] [--goal <objective> | --clear-goal]
+    [--client-message-id <id>] [--json]
+  {program} send <id> [-m <text> | --message-file <file|->]
+    [--image <path> ...]
+    [--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> --execution <execution-id> [--json]
+  {program} list [--scope children|descendants|workspace|profile]
+    [--agent <id>]
+    [--runner <runner>] [--query <title>] [--parent <id>]
     [--cursor <cursor>] [--limit <1..100>] [--json]
-  {program} show [<session-id>] [--json]
-  {program} config [<session-id>]
-    [--model <id>] [--effort <value>] [--json]
-  {program} rename [<session-id>] --title <name> [--json]
-  {program} prompt get|clear [<session-id>] [--json]
-  {program} prompt set [<session-id>]
-    (-m <text> | --message-file <file|->) [--json]
+  {program} view [<id>] [--history] [--cursor <cursor>]
+    [--limit <1..100>] [--json]
+
+Management:
+  {program} config [<id>] [--model <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 [<session-id>] [--json]
-  {program} schedule create [<session-id>] --cron <cron>
+  {program} schedule get [<id>] [--json]
+  {program} schedule create [<id>] --cron <cron>
     (-m <text> | --message-file <file|->) [--json]
-  {program} schedule update [<session-id>]
-    --expected-revision <revision>
+  {program} schedule update [<id>] --expected-revision <revision>
     [--cron <cron>] [-m <text> | --message-file <file|->] [--json]
-  {program} graph [<session-id>] [--limit <1..100>] [--json]
-  {program} history [<session-id>]
-    [--cursor <cursor>] [--limit <1..100>] [--json]
-
-  {program} start --runner <runner>
-    [-m <text> | --message-file <file|->] [--image <path> ...]
-    [--model <id>] [--effort <value>] [--title <name>]
-    [--client-message-id <id>] [--json]
-
-  {program} send <session-id>
-    [-m <text> | --message-file <file|->] [--image <path> ...]
-    (--steer | --queue)
-    [--client-message-id <id>] [--json]
-
-  {program} stop <session-id> [--run <run-id>] [--json]
-  {program} goal get|clear <session-id> [--json]
-  {program} goal set <session-id>
-    (-m <text> | --message-file <file|->) [--json]
-  {program} wait <session-id>
-    --run <run-id> --timeout <30s|5m> [--until approval] [--json]
-  {program} approval decide <session-id> --run <run-id>
-    --approval <approval-id> --decision <approve|reject> [--json]
-
-Input:
-  show/config/history/graph/rename and prompt may omit the ID.
-  schedule get/create/update follow the same rule.
-  They use the current Session; without one, specify an ID explicitly.
-  send/goal/stop/wait/approval always require an explicit Session ID.
-  Runners: mar-agent, codex, claude-code, opencode; actual capabilities apply.
-  -m / --message supplies text; it is mutually exclusive with --message-file.
-  Files use UTF-8; - reads stdin. Repeat --image for PNG/JPEG/GIF/WebP files.
-  Start/send allow image-only input: up to 5 images, 5 MiB each, 10 MiB total.
-  Goal set accepts text only.
-  Config requires model or effort; other fields and permissions are unchanged.
-  Use --effort "" for the Runner default. Active execution is not restarted.
-  Prompt reads, sets or clears persistent instructions for future executions.
-
-Titles and scheduled tasks:
-  rename uses the existing title update; no parent-tree restriction.
-  It does not restart execution. schedule list reads local Workspace tasks.
-  schedule get/create/update share MCP task data.
-  Schedule text is limited to 20,000 characters; update requires cron or text.
-  Other-owner edits create PENDING proposals.
-  Read the current revision before updating; a version conflict is not retried.
-
-Reading JSON:
-  list: id/title/runner/status/runId and one latestActivity per Session.
-  show: session.status, session.title, session.runId,
-    session.model, session.effort, session.queuedCount,
-    session.latestMessage, session.recentTools (up to three summaries).
-    session.pendingApprovals shows current requests; pendingApprovalsTruncated
-    marks an incomplete summary. Full evidence remains in history.
-  Status is RUNNING/IDLE/SLEEPING; tools keep their original states.
-  history: segments[].items[]; select kind === "assistant_message",
-    read payload.text.
-
-Delivery and waiting:
-  Start/send return a clientMessageId.
-  Send requires exactly one of --steer or --queue, even when idle.
-  Prefer --steer for timely coordination: blockers, decisions, corrections,
-    and results the recipient is waiting for. It uses native delivery when
-    available, but may switch the current execution.
-    Node decides from actual state.
-  Use --queue only for deliberately deferred follow-up work.
-    It does not interrupt active execution; during normal active work it
-    waits for that execution and earlier queued work. An active Goal can delay
-    it until the Goal exits.
-    Use --steer instead when the update is needed during current work.
-    New input resumes a paused FIFO without interrupting
-    active execution; cancellation settles before resuming.
-  Example:
-    marctl sessions send <session-id> --steer \\
-      -m "Additional context: focus on the resume path." --json
-  A queued runId may identify another
-  active input: correlate queueItemId/clientMessageId with visible history.
-  Wait observes the specified Run through Watch. Timeout does not stop it;
-  timeout errors may include progress, the last observed bounded snapshot.
-  --until approval also returns when the Run needs an approval decision.
-  Approval decide explicitly approves or rejects one request, subject to
-    existing user authorization. Accepted decisions do not prove completion.
-  Run success is not proof of task success.
-  Completion never wakes a Coordinator.
-  On an unknown delivery outcome, inspect state/history; do not blindly resend.
-
-Credentials and scope:
-  Credentials expire 24 hours after issue without automatic renewal.
-  Scope is bound by MAR to the current Node/Workspace;
-  there are no scope override options.
-  List and ID lookup use Node-known Sessions without scanning Runners.
-  --query filters display titles; missing IDs may suggest nearby IDs, not retry.
-  Start records the current Session as parent; no parent override.
-  --parent lists direct children; graph includes the root and descendants.
-  Graph defaults to 100 nodes and reports truncation, not task dependencies.
-
-Workers:
-  Create workers as needed, e.g. --title "fixer#42 Handle empty totals" or
-  --title "reviewer#42 Review empty totals". Titles are not routing identities;
-  record returned Session IDs. Put task/role instructions in the first message.
-  Sessions share files and the Git index; no automatic worktree or worker pool.
-
-Exit codes:
-  1 failure, 2 input, 3 authorization, 4 unsupported, 5 timeout,
-  6 unknown outcome, 130 cancelled wait.
-  --json prints one result/error object.`,
+  {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>] | history [<id>]
+
+Input and results:
+  Start defaults to the current Session Runner; a terminal without a current
+  Session must specify --runner or --parent. Profile lists configured models,
+  not guaranteed account availability. Start returns without waiting.
+  Send appends by default; --steer replaces 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 clears the target Session Goal.
+  Wait defaults to direct-child completion and 30s; 0ms is a snapshot.
+  Positive timeouts below 10s become 10s; maximum is 5m. Waiting does not stop.
+  Images may be supplied without text: at most 5, 5 MiB each, 10 MiB total.
+  -m and --message-file are exclusive; files use UTF-8 and - reads stdin.
+  List exposes current identity and bounded pages; nextCursor marks more.
+  Configuration and prompt changes apply to future executions.
+  Prefer --steer for timely coordination and for
+  results the recipient is waiting for; Node may switch the current execution.
+  Use --queue only for deliberately deferred follow-up work;
+  it waits for that execution and earlier queued work. Use --steer instead when
+  a result cannot wait until the current Goal exits.
+
+  show --json includes session.status, session.model, session.effort,
+  session.title, session.runId, session.recentTools, session.queuedCount and
+  session.latestMessage. list reports latestActivity; wait may include progress.
+  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:

package/src/i18n/zh-CN.mjs

@@ -10,7 +10,7 @@ export default Object.freeze({
   marctl help [子命令]
 
 子命令：
-  sessions 查看和协调当前工作区中的会话。
+  agents   查看和协调当前工作区中的会话。
   nodes    列出有权限的节点及连接状态。
   ssh      打开节点终端或执行远程命令。
   scp      在当前机器与节点之间、节点之间复制普通文件。
@@ -41,122 +41,68 @@ ${configurationHelp}
   快捷命令仅显示对应操作的帮助。用 marctl help <子命令> 查看详细说明。
   远程访问使用授权的 Node Terminal 传输，不是系统 SSH 或 SCP 协议。`,
   commandHelp: Object.freeze({
-    sessions: `{program} — 协调当前 MAR 工作区中的会话
+    agents: `{program} — 协调当前 MAR 工作区中的 Agent
 
 用法：
-  {program} current [--json]
-  {program} list [--query <title>] [--parent <session-id>]
+  {program} start [-m <text> | --message-file <file|->] [--image <path> ...]
+    [--runner <runner>] [--parent <id>] [--model <id>] [--effort <value>]
+    [--title <name>] [--goal <objective> | --clear-goal]
+    [--client-message-id <id>] [--json]
+  {program} send <id> [-m <text> | --message-file <file|->]
+    [--image <path> ...]
+    [--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> --execution <execution-id> [--json]
+  {program} list [--scope children|descendants|workspace|profile]
+    [--agent <id>]
+    [--runner <runner>] [--query <title>] [--parent <id>]
     [--cursor <cursor>] [--limit <1..100>] [--json]
-  {program} show [<session-id>] [--json]
-  {program} config [<session-id>]
-    [--model <id>] [--effort <value>] [--json]
-  {program} rename [<session-id>] --title <name> [--json]
-  {program} prompt get|clear [<session-id>] [--json]
-  {program} prompt set [<session-id>]
-    (-m <text> | --message-file <file|->) [--json]
+  {program} view [<id>] [--history] [--cursor <cursor>]
+    [--limit <1..100>] [--json]
+
+管理：
+  {program} config [<id>] [--model <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 [<session-id>] [--json]
-  {program} schedule create [<session-id>] --cron <cron>
+  {program} schedule get [<id>] [--json]
+  {program} schedule create [<id>] --cron <cron>
     (-m <text> | --message-file <file|->) [--json]
-  {program} schedule update [<session-id>]
-    --expected-revision <revision>
+  {program} schedule update [<id>] --expected-revision <revision>
     [--cron <cron>] [-m <text> | --message-file <file|->] [--json]
-  {program} graph [<session-id>] [--limit <1..100>] [--json]
-  {program} history [<session-id>]
-    [--cursor <cursor>] [--limit <1..100>] [--json]
-
-  {program} start --runner <runner>
-    [-m <text> | --message-file <file|->] [--image <path> ...]
-    [--model <id>] [--effort <value>] [--title <name>]
-    [--client-message-id <id>] [--json]
-
-  {program} send <session-id>
-    [-m <text> | --message-file <file|->] [--image <path> ...]
-    (--steer | --queue)
-    [--client-message-id <id>] [--json]
-
-  {program} stop <session-id> [--run <run-id>] [--json]
-  {program} goal get|clear <session-id> [--json]
-  {program} goal set <session-id>
-    (-m <text> | --message-file <file|->) [--json]
-  {program} wait <session-id>
-    --run <run-id> --timeout <30s|5m> [--until approval] [--json]
-  {program} approval decide <session-id> --run <run-id>
-    --approval <approval-id> --decision <approve|reject> [--json]
-
-输入：
-  show/config/history/graph/rename、prompt 和 schedule get/create/update
-  可省略 ID，使用当前会话；没有当前会话时请显式指定 ID。
-  send/goal/stop/wait/approval 始终要求显式会话 ID。
-  Runner：mar-agent、codex、claude-code、opencode，操作以实际能力为准。
-  -m / --message 直接传文本，与 --message-file 互斥；
-  文件用 UTF-8，- 从 stdin 读取。
-  start/send 可重复 --image 传 PNG/JPEG/GIF/WebP 图片，也可只发送图片。
-  最多 5 张，单张 5 MiB、合计 10 MiB；goal set 只接受文本。
-  config 至少指定 model 或 effort；未指定字段和权限不变。
-  --effort "" 使用 Runner 默认值，不重启当前执行。
-  prompt 读取、设置或清除持久指令，从后续执行生效。
-
-标题与定时任务：
-  rename 复用现有标题更新，不限制 parent 树、不重启执行。
-  schedule list 读取本地 Workspace 任务，get/create/update 与 MCP 共用任务数据。
-  任务正文最多 20,000 字符；update 至少指定 cron 或正文。
-  修改其他用户的任务会生成 PENDING 提议。
-  更新前读取当前 revision；版本冲突不会自动重试。
-
-读取 JSON：
-  list：id/title/runner/status/runId，以及一条 latestActivity。
-  show：session.status、session.title、session.runId，
-    session.model、session.effort、session.queuedCount，
-    session.latestMessage、session.recentTools（最多三条摘要）。
-    session.pendingApprovals 展示当前审批；pendingApprovalsTruncated 标记
-    摘要未完整列出，完整证据仍查 history。
-  状态为 RUNNING/IDLE/SLEEPING；工具保留原有生命周期。
-  history：segments[].items[] 中按 kind === "assistant_message"
-    筛选，读取 payload.text。
-
-投递与等待：
-  start/send 返回 clientMessageId。
-  send 必须二选一：--steer 或 --queue，空闲时也需指定。
-  及时协作优先使用 --steer：阻塞、决策请求、纠偏
-    和对方正在等待的结果。可用时优先原生投递，
-    否则可能切换当前执行；Node 按实际状态裁决。
-  仅明确要延后执行的后续工作使用 --queue。
-    它不打断活动执行；正常运行时等待当前执行和前面的队列项；
-    有活动 Goal 时可能等待 Goal 退出才处理。
-    当前工作需要及时获知的信息应使用 --steer。
-    新输入自动恢复暂停的 FIFO，不打断活动执行；取消收敛后才恢复。
-  示例：
-    marctl sessions send <session-id> --steer \\
-      -m "Additional context: focus on the resume path." --json
-  排队回执的 runId 可能属于其他活动输入，
-  需按 queueItemId/clientMessageId 与可见历史核对。
-  wait 通过 Watch 等待指定 Run；超时不会停止任务，
-  超时错误可附 progress，表示最后观察到的有界快照。
-  --until approval 在需要审批决定时也提前返回。
-  approval decide 显式批准或拒绝单个请求，沿用实际用户授权；
-    决定被接受不代表任务完成。
-  Run 成功不等于业务完成。Worker 完成不自动唤醒 Coordinator。
-  投递结果未知时先查状态/历史，不盲目重发。
-
-凭据与范围：
-  凭据自签发起 24 小时到期，不自动续签。
-  MAR 绑定当前 Node/Workspace，不提供覆盖范围的参数。
-  列表及 ID 定位只查 Node 已知会话，不扫描 Runner。
-  --query 按展示标题筛选；ID 不存在时可提示近似候选，不自动重试。
-  start 自动记录可用的当前会话为 parent，不提供 parent 覆盖参数。
-  --parent 查直接子会话；graph 查包含根的后代，默认最多 100 个节点，
-  截断时明确标记；创建关系不表示任务依赖。
-
-Worker：
-  按任务需要创建会话，例如 --title "fixer#42 Handle empty totals" 或
-  --title "reviewer#42 Review empty totals"；标题不是寻址身份，
-  保存返回的会话 ID。角色和任务要求放入首条普通消息。
-  会话共享文件与 Git 索引，不自动隔离工作目录或维护池。
-
-退出码：
-  1 失败，2 参数，3 授权，4 不支持，5 超时，6 结果未知，130 取消等待。
-  --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>] | history [<id>]
+
+输入与结果：
+  start 默认当前会话的 Runner；没有当前会话的终端须指定 --runner 或
+  --parent。profile 显示已配置模型，不代表账号实时可用。start 不等待。
+  send 默认追加；--steer 替换，--queue 排队。--goal 设置或替换目标，
+  --clear-goal 清除目标；send 可仅更新目标，省略则不修改。
+  stop 清除目标会话的 Goal。wait 默认等待直接子会话终态 30 秒，
+  0ms 为快照；正数小于 10 秒按 10 秒等待，最多 5 分钟。等待不会停止任务。
+  可只传图片：最多 5 张，单张 5 MiB、总计 10 MiB。-m 与 --message-file
+  互斥；文件使用 UTF-8，- 从 stdin 读取。list 返回当前身份和分页结果，
+  nextCursor 表示还有后续页面。配置和持久提示从后续执行生效。
+  及时协作优先使用 --steer，包括对方正在等待的结果；Node 可能切换当前执行。
+  仅明确要延后执行的后续工作使用 --queue，它会等待当前执行和前面的队列项；
+  无法等待 Goal 退出的结果应使用 --steer。
+
+  show --json 包含 session.status、session.model、session.effort、
+  session.title、session.runId、session.recentTools、session.queuedCount 和
+  session.latestMessage。list 返回 latestActivity；wait 可能包含 progress；
+  状态为 RUNNING/IDLE/SLEEPING。历史中 segments[].items[] 的
+  kind === "assistant_message" 包含 payload.text。
+
+退出码：1 失败，2 参数，3 授权，4 不支持，5 超时，6 结果未知，
+  130 取消等待。--json 输出单个结果或错误对象。`,
     nodes: `{program} — 列出有权限的节点
 
 用法：

package/src/session-args.mjs

@@ -4,9 +4,10 @@ import { sessionTarget } from './session-target.mjs';
 
 const commands = {
   current: [],
-  list: ['cursor', 'limit', 'query', 'parent'],
+  list: ['cursor', 'limit', 'query', 'parent', 'scope', 'agent', 'runner'],
   graph: ['limit'],
   show: [],
+  view: ['cursor', 'limit', 'history'],
   history: ['cursor', 'limit'],
   start: [
     'runner',
@@ -16,7 +17,10 @@ const commands = {
     'message',
     'message-file',
     'image',
-    'client-message-id'
+    'client-message-id',
+    'parent',
+    'goal',
+    'clear-goal'
   ],
   config: ['model', 'effort'],
   rename: ['title'],
@@ -28,12 +32,23 @@ const commands = {
   'schedule.get': [],
   'schedule.create': ['cron', 'message', 'message-file'],
   'schedule.update': ['cron', 'message', 'message-file', 'expected-revision'],
-  send: ['message', 'message-file', 'image', 'steer', 'queue', 'client-message-id'],
-  stop: ['run'],
+  send: [
+    'message',
+    'message-file',
+    'image',
+    'steer',
+    'queue',
+    'client-message-id',
+    'goal',
+    'clear-goal',
+    'approval',
+    'decision'
+  ],
+  stop: ['execution'],
   'goal.get': [],
   'goal.set': ['message', 'message-file'],
   'goal.clear': [],
-  wait: ['run', 'timeout', 'until']
+  wait: ['timeout', 'wait-for', 'mode', 'agent', 'run', 'until']
 };
 const fieldNames = {
   parent: 'parentSessionId',
@@ -43,6 +58,9 @@ const fieldNames = {
   run: 'runId',
   approval: 'approvalId',
   timeout: 'timeoutMs',
+  execution: 'executionId',
+  'wait-for': 'waitFor',
+  'clear-goal': 'clearGoal',
   image: 'images'
 };
 
@@ -65,12 +83,12 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
         (value === '--help' || value === '-h') && !['-m', '--message'].includes(argv[index - 1])
     )
   )
-    return { command: 'sessions', help: true };
+    return { command: 'agents', help: true };
   const input = [...argv];
   let action = input.shift();
   if (['goal', 'schedule', 'prompt', 'approval'].includes(action)) action += '.' + input.shift();
   if (!Object.hasOwn(commands, action)) throw invalid();
-  const args = { command: 'sessions', action };
+  const args = { command: 'agents', action };
   if (sessionTarget[action] !== 'workspace') {
     if (
       (input[0] === undefined || input[0].startsWith('-')) &&
@@ -96,9 +114,21 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
       args[key] = true;
       continue;
     }
+    if (
+      (flag === '--clear-goal' && ['start', 'send'].includes(action)) ||
+      (flag === '--history' && action === 'view')
+    ) {
+      const key = flag === '--history' ? 'history' : 'clearGoal';
+      if (Object.hasOwn(args, key)) throw invalid();
+      args[key] = true;
+      continue;
+    }
     const name = flag.startsWith('--') ? flag.slice(2) : '';
     const key = fieldNames[name] ?? name;
-    if (!commands[action].includes(name) || (name !== 'image' && Object.hasOwn(args, key)))
+    if (
+      !commands[action].includes(name) ||
+      (name !== 'image' && !(name === 'agent' && action === 'wait') && Object.hasOwn(args, key))
+    )
       throw invalid();
     const value = input.shift();
     if (
@@ -107,7 +137,10 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
       (name !== 'message' && value.startsWith('--'))
     )
       throw invalid();
-    if (name === 'image') {
+    if (name === 'agent' && action === 'wait') {
+      (args.agentIds ??= []).push(value);
+      if (args.agentIds.length > 8) throw invalid();
+    } else if (name === 'image') {
       (args.images ??= []).push(value);
       if (args.images.length > 5) throw invalid();
     } else if (name === 'limit' || name === 'expected-revision') {
@@ -119,31 +152,69 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
         throw invalid();
       args[key] = Number(value);
     } else if (name === 'timeout') {
-      const match = /^([1-9][0-9]*)(ms|s|m)$/u.exec(value);
+      const match = /^(0|[1-9][0-9]*)(ms|s|m)$/u.exec(value);
       const ms = match === null ? 0 : Number(match[1]) * { ms: 1, s: 1000, m: 60000 }[match[2]];
-      if (!Number.isSafeInteger(ms) || ms < 1 || ms > 3600000) throw invalid();
+      if (match === null || !Number.isSafeInteger(ms) || ms > 300000) throw invalid();
       args[key] = ms;
     } else args[key] = value;
   }
-  if (action === 'send' && (args.steer === true) === (args.queue === true))
+  if (action === 'send' && args.steer === true && args.queue === true)
     throw invalid('errors.sessionDeliveryRequired');
+  if (
+    action === 'send' &&
+    ((args.approvalId === undefined) !== (args.decision === undefined) ||
+      (args.decision !== undefined && !['approve', 'reject'].includes(args.decision)))
+  )
+    throw invalid();
+  if (args.goal !== undefined && (args.clearGoal || !args.goal.trim() || args.goal.length > 20000))
+    throw invalid();
   if (args.message !== undefined && args.messageFile !== undefined) throw invalid();
   if (
     ['start', 'send', 'goal.set', 'schedule.create', 'prompt.set'].includes(action) &&
     args.messageFile === undefined &&
     args.message === undefined &&
-    !args.images?.length
+    !args.images?.length &&
+    !(
+      action === 'send' &&
+      (args.goal !== undefined || args.clearGoal || args.approvalId !== undefined)
+    )
   )
     throw invalid();
   if (
     action === 'start' &&
+    args.runner !== undefined &&
     !['mar-agent', 'codex', 'claude-code', 'opencode'].includes(args.runner)
   )
     throw invalid();
-  if (action === 'wait' && (args.runId === undefined || args.timeoutMs === undefined))
+  if (action === 'stop' && !args.executionId) throw invalid();
+  if (action === 'wait' && args.sessionId && args.agentIds?.length) throw invalid();
+  if (
+    args.until !== undefined &&
+    (args.until !== 'approval' ||
+      !args.sessionId ||
+      !args.runId ||
+      !args.timeoutMs ||
+      args.agentIds?.length)
+  )
+    throw invalid();
+  if (
+    action === 'wait' &&
+    args.runId !== undefined &&
+    (!args.sessionId ||
+      args.timeoutMs === 0 ||
+      args.agentIds?.length ||
+      args.mode !== undefined ||
+      args.waitFor !== undefined)
+  )
+    throw invalid();
+  if (args.waitFor !== undefined && !['message', 'completion'].includes(args.waitFor))
+    throw invalid();
+  if (args.mode !== undefined && !['any', 'all'].includes(args.mode)) throw invalid();
+  if (
+    args.scope !== undefined &&
+    !['children', 'descendants', 'workspace', 'profile'].includes(args.scope)
+  )
     throw invalid();
-  if (args.until !== undefined && args.until !== 'approval')
-    throw invalid(undefined, '--until: expected approval.');
   if (
     action === 'approval.decide' &&
     (!args.runId || !args.approvalId || !['approve', 'reject'].includes(args.decision))

package/src/session-prepare.mjs

@@ -1,6 +1,54 @@
 import { randomUUID } from 'node:crypto';
 import { messageContent, imageAttachments } from './session-input.mjs';
 
+const networkActions = new Set(['start', 'send', 'wait', 'stop', 'list', 'view']);
+
+/** Adapt CLI syntax to the same Node Agent Network command used by native tools. */
+export async function prepareAgentNetworkRequest({ args, stdin, translate, sessionId }) {
+  const input = {};
+  for (const name of [
+    'runner',
+    'model',
+    'effort',
+    'title',
+    'cursor',
+    'limit',
+    'query',
+    'parentSessionId',
+    'scope',
+    'waitFor',
+    'mode',
+    'executionId'
+  ])
+    if (args[name] !== undefined) input[name] = args[name];
+  if (args.action === 'list' && input.parentSessionId !== undefined) {
+    input.parent = input.parentSessionId;
+    delete input.parentSessionId;
+  }
+  if (args.action === 'list' && args.agent !== undefined) input.agentId = args.agent;
+  if (['send', 'stop', 'view', 'wait'].includes(args.action) && sessionId)
+    input.agentId = sessionId;
+  if (args.action === 'wait' && args.agentIds?.length) input.agentIds = args.agentIds;
+  if (args.action === 'wait' && args.timeoutMs !== undefined) input.waitMs = args.timeoutMs;
+  if (args.action === 'view' && args.history) input.includeHistory = true;
+  if (args.message !== undefined || args.messageFile !== undefined)
+    input.content = await messageContent(args, stdin, 100000, translate);
+  if (args.images?.length) input.attachments = await imageAttachments(args.images, translate);
+  if (args.goal !== undefined) input.goal = { objective: args.goal.trim() };
+  if (args.clearGoal) input.goal = { clear: true };
+  if (args.action === 'send' && args.approvalId !== undefined)
+    input.approval = { approvalId: args.approvalId, decision: args.decision };
+  if (args.action === 'start' || args.action === 'send')
+    input.clientMessageId = args.clientMessageId ?? randomUUID();
+  if (args.action === 'send')
+    input.deliveryIntent = args.steer ? 'REPLACE_CURRENT' : args.queue ? 'QUEUE' : 'SEND';
+  return { action: 'network', command: { operation: args.action, input } };
+}
+
+export function isAgentNetworkAction(action) {
+  return networkActions.has(action);
+}
+
 export async function prepareSessionRequest({ args, env, stdin, translate, sessionId, targeted }) {
   const body = { action: args.action };
   for (const name of [

package/src/session-target.mjs

@@ -5,6 +5,7 @@ export const sessionTarget = Object.freeze({
   start: 'workspace',
   'schedule.list': 'workspace',
   show: 'current',
+  view: 'current',
   config: 'current',
   history: 'current',
   graph: 'current',
@@ -17,7 +18,7 @@ export const sessionTarget = Object.freeze({
   'schedule.update': 'current',
   send: 'explicit',
   stop: 'explicit',
-  wait: 'explicit',
+  wait: 'optional',
   'approval.decide': 'explicit',
   'goal.get': 'explicit',
   'goal.set': 'explicit',

package/src/sessions.mjs

@@ -1,6 +1,10 @@
 import { MarctlError } from './errors.mjs';
 import { sessionTarget } from './session-target.mjs';
-import { prepareSessionRequest } from './session-prepare.mjs';
+import {
+  isAgentNetworkAction,
+  prepareAgentNetworkRequest,
+  prepareSessionRequest
+} from './session-prepare.mjs';
 import { waitForSessionRun } from './session-wait.mjs';
 
 export async function runSessionCommand({
@@ -17,33 +21,41 @@ export async function runSessionCommand({
   const sessionId =
     args.sessionId ??
     (sessionTarget[args.action] === 'current' ? env.MAR_CTL_SESSION_ID : undefined);
-  if (targeted && !sessionId)
+  if (targeted && !sessionId && sessionTarget[args.action] !== 'optional')
     throw new MarctlError(translate('errors.sessionContextRequired'), {
       code: 'MARCTL_SESSION_CONTEXT_REQUIRED'
     });
-  if (args.action === 'wait') {
+  if (args.action === 'wait' && args.runId !== undefined)
     return waitForSessionRun({
       client,
       sessionId,
       runId: args.runId,
-      timeoutMs: args.timeoutMs,
+      timeoutMs: args.timeoutMs ?? 30000,
       until: args.until,
       WebSocketClass,
       translate,
       signal
     });
-  }
-  const body = await prepareSessionRequest({ args, env, stdin, translate, sessionId, targeted });
+  const network = isAgentNetworkAction(args.action);
+  const body = network
+    ? await prepareAgentNetworkRequest({ args, stdin, translate, sessionId })
+    : await prepareSessionRequest({ args, env, stdin, translate, sessionId, targeted });
+  const clientMessageId = network ? body.command.input.clientMessageId : body.clientMessageId;
   try {
-    const result = await client.sessionCommand(body);
+    const requestedWait = args.timeoutMs ?? 30000;
+    const effectiveWait = requestedWait === 0 ? 0 : Math.max(10000, requestedWait);
+    const result = await client.sessionCommand(
+      body,
+      args.action === 'wait' ? { timeoutMs: effectiveWait + 10000, signal } : undefined
+    );
     return {
       ...result,
       ...(typeof result?.session?.id === 'string' ? { sessionId: result.session.id } : {}),
       ...(typeof result?.run?.id === 'string' ? { runId: result.run.id } : {}),
-      ...(body.clientMessageId === undefined ? {} : { clientMessageId: body.clientMessageId })
+      ...(clientMessageId === undefined ? {} : { clientMessageId })
     };
   } catch (error) {
-    if (body.clientMessageId !== undefined) error.clientMessageId = body.clientMessageId;
+    if (clientMessageId !== undefined) error.clientMessageId = clientMessageId;
     if (
       [
         'start',