@myagentroam/marctl 0.10.5 → 0.10.7

package/package.json

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

package/src/cli.mjs

@@ -106,11 +106,18 @@ export async function main(
           ? {}
           : { upstreamRequestId: error.upstreamRequestId }),
         ...(error.details === undefined ? {} : { details: error.details }),
+        ...(error.sessionId === undefined ? {} : { sessionId: error.sessionId }),
+        ...(error.runId === undefined ? {} : { runId: error.runId }),
+        ...(error.stage === undefined ? {} : { stage: error.stage }),
+        ...(error.upstreamCode === undefined ? {} : { upstreamCode: error.upstreamCode }),
         ...(error.clientMessageId === undefined ? {} : { clientMessageId: error.clientMessageId })
       };
       if (args?.json === true || (args === undefined && argv.includes('--json')))
         writeLine(stdout, JSON.stringify({ error: failure }));
-      else writeLine(stderr, program + ': ' + failure.message + ' [' + failure.code + ']');
+      else {
+        writeLine(stderr, program + ': ' + failure.message + ' [' + failure.code + ']');
+        if (failure.details !== undefined) writeLine(stderr, failure.details);
+      }
       return sessionExitCode(error);
     }
     writeLine(

package/src/i18n/en-US.mjs

@@ -46,19 +46,22 @@ Notes:
 
 Usage:
   {program} current [--json]
-  {program} list [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} list [--query <title>] [--parent <session-id>]
+    [--cursor <cursor>] [--limit <1..100>] [--json]
   {program} show <session-id> [--json]
+  {program} config <session-id> [--model <id>] [--effort <value>] [--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>] [--title <name>]
+    [--model <id>] [--effort <value>] [--title <name>]
     [--client-message-id <id>] [--json]
 
   {program} send <session-id>
     [-m <text> | --message-file <file|->] [--image <path> ...]
-    [--delivery send|queue|replace-current]
+    (--steer | --queue)
     [--client-message-id <id>] [--json]
 
   {program} stop <session-id> [--run <run-id>] [--json]
@@ -74,10 +77,18 @@ Input:
   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.
 
 Delivery and waiting:
   Start/send return a clientMessageId.
-  Send defaults to non-interrupting delivery. Queued runId may identify another
+  Send requires exactly one of --steer or --queue, even when idle.
+  When useful, --steer adds gentle context to an in-progress task.
+  --queue places input in a subsequent turn.
+  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;
   Run success is not proof of task success.
@@ -88,6 +99,11 @@ 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
@@ -261,6 +277,7 @@ or Server connection is required.`
     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/src/i18n/zh-CN.mjs

@@ -45,19 +45,22 @@ ${configurationHelp}
 
 用法：
   {program} current [--json]
-  {program} list [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} list [--query <title>] [--parent <session-id>]
+    [--cursor <cursor>] [--limit <1..100>] [--json]
   {program} show <session-id> [--json]
+  {program} config <session-id> [--model <id>] [--effort <value>] [--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>] [--title <name>]
+    [--model <id>] [--effort <value>] [--title <name>]
     [--client-message-id <id>] [--json]
 
   {program} send <session-id>
     [-m <text> | --message-file <file|->] [--image <path> ...]
-    [--delivery send|queue|replace-current]
+    (--steer | --queue)
     [--client-message-id <id>] [--json]
 
   {program} stop <session-id> [--run <run-id>] [--json]
@@ -73,10 +76,18 @@ ${configurationHelp}
   文件用 UTF-8，- 从 stdin 读取。
   start/send 可重复 --image 传 PNG/JPEG/GIF/WebP 图片，也可只发送图片。
   最多 5 张，单张 5 MiB、合计 10 MiB；goal set 只接受文本。
+  config 至少指定 model 或 effort；未指定字段和权限不变。
+  --effort "" 使用 Runner 默认值，不重启当前执行。
 
 投递与等待：
   start/send 返回 clientMessageId。
-  send 默认不打断；排队回执的 runId 可能属于其他活动输入，
+  send 必须二选一：--steer 或 --queue，空闲时也需指定。
+  --steer 在必要时为正在进行的任务补充温和的新信息。
+  --queue 将输入排入后续轮次。
+  示例：
+    marctl sessions send <session-id> --steer \\
+      -m "Additional context: focus on the resume path." --json
+  排队回执的 runId 可能属于其他活动输入，
   需按 queueItemId/clientMessageId 与可见历史核对。
   wait 通过 Watch 等待指定 Run；超时不会停止任务，
   Run 成功不等于业务完成。Worker 完成不自动唤醒 Coordinator。
@@ -85,6 +96,11 @@ ${configurationHelp}
 凭据与范围：
   凭据自签发起 24 小时到期，不自动续签。
   MAR 绑定当前 Node/Workspace，不提供覆盖范围的参数。
+  列表及 ID 定位只查 Node 已知会话，不扫描 Runner。
+  --query 按展示标题筛选；ID 不存在时可提示近似候选，不自动重试。
+  start 自动记录可用的当前会话为 parent，不提供 parent 覆盖参数。
+  --parent 查直接子会话；graph 查包含根的后代，默认最多 100 个节点，
+  截断时明确标记；创建关系不表示任务依赖。
 
 Worker：
   按任务需要创建会话，例如 --title "fixer#42 Handle empty totals" 或
@@ -247,6 +263,7 @@ ${configurationHelp}`,
     terminalSessionFailed: '终端会话失败。',
     terminalDirectUnsafeFallback: 'OPEN 后无法安全取消直连终端，已跳过 relay 回退。',
     invalidArguments: '命令参数无效。',
+    sessionDeliveryRequired: 'send 必须且只能选择 --steer 或 --queue，即使目标空闲也需指定。',
     sshOptionsUnsupported: '不支持 SSH 选项，请使用 marssh <节点>。',
     scpOptionsUnsupported: 'Node Terminal 传输不支持此 SCP 选项。',
     terminalBinaryUnavailable: '二进制复制需要支持 pipe 终端的 Server 与 Node。',

package/src/sessions.mjs

@@ -7,11 +7,22 @@ import { createTranslator } from './i18n/index.mjs';
 const terminal = new Set(['SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED']);
 const commands = {
   current: [],
-  list: ['cursor', 'limit'],
+  list: ['cursor', 'limit', 'query', 'parent'],
+  graph: ['limit'],
   show: [],
   history: ['cursor', 'limit'],
-  start: ['runner', 'model', 'title', 'message', 'message-file', 'image', 'client-message-id'],
-  send: ['message', 'message-file', 'image', 'delivery', 'client-message-id'],
+  start: [
+    'runner',
+    'model',
+    'effort',
+    'title',
+    'message',
+    'message-file',
+    'image',
+    'client-message-id'
+  ],
+  config: ['model', 'effort'],
+  send: ['message', 'message-file', 'image', 'steer', 'queue', 'client-message-id'],
   stop: ['run'],
   'goal.get': [],
   'goal.set': ['message', 'message-file'],
@@ -19,6 +30,7 @@ const commands = {
   wait: ['run', 'timeout']
 };
 const fieldNames = {
+  parent: 'parentSessionId',
   'message-file': 'messageFile',
   'client-message-id': 'clientMessageId',
   run: 'runId',
@@ -27,8 +39,8 @@ const fieldNames = {
 };
 
 export function parseSessionArgs(argv, translate = createTranslator()) {
-  const invalid = () =>
-    new MarctlError(translate('errors.invalidArguments'), { code: 'MARCTL_SESSION_INPUT_INVALID' });
+  const invalid = (key = 'errors.invalidArguments') =>
+    new MarctlError(translate(key), { code: 'MARCTL_SESSION_INPUT_INVALID' });
   if (
     argv.length === 0 ||
     argv.some(
@@ -54,12 +66,22 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
       args.json = true;
       continue;
     }
+    if (action === 'send' && (flag === '--steer' || flag === '--queue')) {
+      const key = flag.slice(2);
+      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)))
       throw invalid();
     const value = input.shift();
-    if (value === undefined || value === '' || (name !== 'message' && value.startsWith('--')))
+    if (
+      value === undefined ||
+      (value === '' && name !== 'effort') ||
+      (name !== 'message' && value.startsWith('--'))
+    )
       throw invalid();
     if (name === 'image') {
       (args.images ??= []).push(value);
@@ -74,6 +96,8 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
       args[key] = ms;
     } else args[key] = value;
   }
+  if (action === 'send' && (args.steer === true) === (args.queue === true))
+    throw invalid('errors.sessionDeliveryRequired');
   if (args.message !== undefined && args.messageFile !== undefined) throw invalid();
   if (
     ['start', 'send', 'goal.set'].includes(action) &&
@@ -89,9 +113,13 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     throw invalid();
   if (action === 'wait' && (args.runId === undefined || args.timeoutMs === undefined))
     throw invalid();
-  if (args.delivery !== undefined && !['send', 'queue', 'replace-current'].includes(args.delivery))
-    throw invalid();
   if (args.title !== undefined && args.title.length > 160) throw invalid();
+  if (args.model !== undefined && (args.model.trim().length === 0 || args.model.length > 120))
+    throw invalid();
+  if (args.effort !== undefined && args.effort.length > 120) throw invalid();
+  if (action === 'config' && args.model === undefined && args.effort === undefined) throw invalid();
+  if (args.query !== undefined && args.query.length > 160) throw invalid();
+  if (args.parentSessionId !== undefined && args.parentSessionId.length > 512) throw invalid();
   return args;
 }
 
@@ -117,9 +145,22 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
     }
   }
   const body = { action: args.action };
-  for (const name of ['sessionId', 'runner', 'model', 'title', 'cursor', 'limit', 'runId'])
+  for (const name of [
+    'sessionId',
+    'parentSessionId',
+    'runner',
+    'model',
+    'effort',
+    'title',
+    'cursor',
+    'limit',
+    'query',
+    'runId'
+  ])
     if (args[name] !== undefined) body[name] = args[name];
   if (args.action === 'current' && env.MAR_CTL_SESSION_ID) body.sessionId = env.MAR_CTL_SESSION_ID;
+  if (args.action === 'start' && env.MAR_CTL_SESSION_ID)
+    body.parentSessionId = env.MAR_CTL_SESSION_ID;
   if (args.messageFile !== undefined || args.message !== undefined)
     body.content = await messageContent(
       args,
@@ -134,9 +175,7 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
   if (args.action === 'start' || args.action === 'send')
     body.clientMessageId = args.clientMessageId ?? randomUUID();
   if (args.action === 'send')
-    body.deliveryIntent = { send: 'SEND', queue: 'QUEUE', 'replace-current': 'REPLACE_CURRENT' }[
-      args.delivery ?? 'send'
-    ];
+    body.deliveryIntent = args.steer === true ? 'REPLACE_CURRENT' : 'QUEUE';
   try {
     const result = await client.sessionCommand(body);
     return {
@@ -148,7 +187,7 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
   } catch (error) {
     if (body.clientMessageId !== undefined) error.clientMessageId = body.clientMessageId;
     if (
-      ['start', 'send', 'stop', 'goal.set', 'goal.clear'].includes(args.action) &&
+      ['start', 'send', 'config', 'stop', 'goal.set', 'goal.clear'].includes(args.action) &&
       ['MARCTL_REQUEST_TIMEOUT', 'MARCTL_SERVER_UNREACHABLE', 'MARCTL_RESPONSE_INVALID'].includes(
         error.code
       )
@@ -244,7 +283,7 @@ export async function waitForSessionRun({
   translate = createTranslator(),
   signal
 }) {
-  const socket = client.openWorkbenchWebSocket(WebSocketClass ?? (await import('ws')).default);
+  let socket;
   const watchId = randomUUID();
   let connectionId;
   let renewal;
@@ -256,13 +295,34 @@ export async function waitForSessionRun({
     accept = resolve;
     rejectResult = fail;
   });
-  const reject = (error) => {
+  const reject = (error, stage) => {
     if (settled) return;
     settled = true;
+    Object.assign(error, { sessionId, runId, stage });
     rejectResult(error);
   };
-  const fail = (code, key, options = {}) =>
-    reject(new MarctlError(translate(key), { ...options, code }));
+  const fail = (code, key, { stage, upstreamCode, ...options } = {}) => {
+    const error = new MarctlError(translate(key), { ...options, code });
+    if (upstreamCode !== undefined) error.upstreamCode = upstreamCode;
+    reject(error, stage);
+  };
+  const unknown = (stage, detail, source) =>
+    fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown', {
+      stage,
+      upstreamCode:
+        typeof source?.code === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,127}$/u.test(source.code)
+          ? source.code
+          : undefined,
+      requestId: typeof source?.requestId === 'string' ? source.requestId.slice(0, 160) : undefined,
+      upstreamRequestId:
+        typeof source?.upstreamRequestId === 'string'
+          ? source.upstreamRequestId.slice(0, 160)
+          : undefined,
+      details: [detail, source?.message, source?.details]
+        .filter((value) => typeof value === 'string')
+        .join(' ')
+        .slice(0, 4000)
+    });
   const command = (mode) =>
     client.sessionCommand({
       action: 'watch',
@@ -275,7 +335,7 @@ export async function waitForSessionRun({
     clearTimeout(renewal);
     const remaining = expiresAt - Date.now();
     if (!Number.isFinite(remaining) || remaining <= 0) {
-      fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+      unknown('lease', 'The Watch lease is missing or expired.');
       return;
     }
     renewal = setTimeout(
@@ -285,8 +345,13 @@ export async function waitForSessionRun({
             if (!settled) scheduleRenewal(ack?.expiresAt);
           })
           .catch((error) => {
-            if ([401, 403].includes(error.statusCode)) reject(error);
-            else fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+            if ([401, 403].includes(error.statusCode)) reject(error, 'renew');
+            else
+              unknown(
+                'renew',
+                'The Watch lease could not be renewed.',
+                error instanceof MarctlError ? error : undefined
+              );
           });
       },
       Math.max(50, Math.floor(remaining / 2))
@@ -315,22 +380,22 @@ export async function waitForSessionRun({
     ) {
       connectionId = message.workbenchConnectionId;
       subscribed = true;
-      command('initial').catch(reject);
+      command('initial').catch((error) => reject(error, 'subscribe'));
     }
     if (message.watchId !== watchId) return;
     if (message.type === 'watch.failed') {
-      fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+      unknown('watch', 'The Session Watch failed.', message);
       return;
     }
     if (message.type === 'watch.session.snapshot') {
       const runs = message.payload?.runs;
       if (!Array.isArray(runs)) {
-        fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+        unknown('snapshot', 'The Watch snapshot did not contain a Run list.');
         return;
       }
-      const run = runs.find((value) => value.id === runId && value.sessionId === sessionId);
+      const run = runs.find((value) => value?.id === runId && value.sessionId === sessionId);
       if (run === undefined) {
-        fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+        unknown('snapshot', 'The requested Run was absent from the Watch snapshot.');
         return;
       }
       check(run);
@@ -339,24 +404,43 @@ export async function waitForSessionRun({
   };
   const onClose = (code, reason) => {
     if (code === 1008 && String(reason) === 'UNAUTHENTICATED')
-      fail('UNAUTHENTICATED', 'errors.userContextUnavailable', { statusCode: 401 });
-    else fail('MARCTL_WAIT_UNKNOWN', 'errors.sessionWaitUnknown');
+      fail('UNAUTHENTICATED', 'errors.userContextUnavailable', {
+        statusCode: 401,
+        stage: 'connection'
+      });
+    else
+      unknown(
+        'connection',
+        Number.isInteger(code)
+          ? `The Watch connection closed (code ${code}).`
+          : 'The Watch connection closed.'
+      );
   };
+  const onError = (error) =>
+    unknown('connection', 'The Watch connection failed.', { code: error?.code });
   const onOpen = () => {
     try {
       socket.send(JSON.stringify({ type: 'resume' }));
-    } catch {
-      onClose();
+    } catch (error) {
+      onError(error);
     }
   };
-  const onAbort = () => fail('MARCTL_WAIT_CANCELLED', 'errors.sessionWaitCancelled');
+  const onAbort = () =>
+    fail('MARCTL_WAIT_CANCELLED', 'errors.sessionWaitCancelled', { stage: 'cancel' });
+  try {
+    socket = client.openWorkbenchWebSocket(WebSocketClass ?? (await import('ws')).default);
+  } catch (error) {
+    if (error instanceof MarctlError) reject(error, 'connection');
+    else unknown('connection', 'The Watch connection could not be opened.');
+    return await result;
+  }
   const timer = setTimeout(
-    () => fail('MARCTL_WAIT_TIMEOUT', 'errors.sessionWaitTimeout'),
+    () => fail('MARCTL_WAIT_TIMEOUT', 'errors.sessionWaitTimeout', { stage: 'timeout' }),
     timeoutMs
   );
   socket.on('open', onOpen);
   socket.on('message', onMessage);
-  socket.on('error', onClose);
+  socket.on('error', onError);
   socket.on('close', onClose);
   signal?.addEventListener('abort', onAbort, { once: true });
   if (signal?.aborted) onAbort();