@myagentroam/marctl 0.11.9 → 0.11.11

package/package.json

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

package/src/i18n/en-US.mjs

@@ -45,22 +45,20 @@ Notes:
     agents: `{program} — Coordinate Agents in the current MAR Workspace
 
 Usage:
-  {program} start [-m <text> | --message-file <file|->] [--image <path> ...]
+  {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|->]
-    [--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} stop <id> [--json]
   {program} list [--scope tree|active] [--query <title>]
     [--limit <1..100>] [--json]
-  {program} view [<id>] [--history] [--cursor <cursor>]
-    [--limit <1..100>] [--json]
+  {program} view [<id>] [--json]
 
 Management:
   {program} config [<id>] [--model-id <id>] [--effort <value>] [--json]
@@ -78,34 +76,41 @@ Management:
   {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>]
+  {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 clears the target Session 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 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.
+  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 100, maximum 100; no cursor or pagination.
+  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.
-  Use --queue only for deliberately deferred input: it is consumed after
+  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, runner
-  and status; wait may include progress.
+  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.
 
@@ -222,8 +227,6 @@ or Server connection is required.`
       '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.',
-    sessionImageInvalid:
-      'Images must be readable PNG, JPEG, GIF or WebP files: at most 5 images, 5 MiB each and 10 MiB total.',
     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.',

package/src/i18n/zh-CN.mjs

@@ -44,22 +44,20 @@ ${configurationHelp}
     agents: `{program} — 协调当前 MAR 工作区中的 Agent
 
 用法：
-  {program} start [-m <text> | --message-file <file|->] [--image <path> ...]
+  {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|->]
-    [--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} stop <id> [--json]
   {program} list [--scope tree|active] [--query <title>]
     [--limit <1..100>] [--json]
-  {program} view [<id>] [--history] [--cursor <cursor>]
-    [--limit <1..100>] [--json]
+  {program} view [<id>] [--json]
 
 管理：
   {program} config [<id>] [--model-id <id>] [--effort <value>] [--json]
@@ -77,29 +75,34 @@ ${configurationHelp}
   {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>]
+  {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 为快照；正数小于 10 秒按 10 秒等待，最多 5 分钟。等待不会停止任务。
-  可只传图片：最多 5 张，单张 5 MiB、总计 10 MiB。-m 与 --message-file
-  互斥；文件使用 UTF-8，- 从 stdin 读取。list 默认查询所在会话树，包含空闲会话；
+  stop 停止目标当前执行并清除 Goal。wait 默认等待直接子会话终态 30 秒，
+  0ms 为快照；正数按传入时长等待，最多 5 分钟。等待不会停止任务。
+  -m 与 --message-file 互斥；文件使用 UTF-8，- 从 stdin 读取。
+  list 默认查询所在会话树，包含空闲会话；
   没有当前会话时默认 active，显式 tree 须有会话上下文。active 包含当前
   Workspace 中运行及睡眠的会话。返回 currentAgentId（无会话时为 null）、
-  扁平 sessions 和 truncated。limit 默认及上限均为 100，无 cursor 或分页。
+  扁平 sessions 和 truncated。limit 默认 10、上限 100，无 cursor 或分页。
+  活跃会话优先，其后按最近活动时间倒序。
   配置和持久提示从后续执行生效。
   即时沟通或纠偏优先使用 --steer。
-  仅明确要延后处理的输入使用 --queue：当前工作及前面的队列项结束后才消费，
+  建议仅将 --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、runner 和
-  status；wait 可能包含 progress；
+  session.latestMessage。list 每项仅含 id、parentSessionId、title 和 status；
+  wait 可能包含 progress；view 不公开 Run 或 Execution ID。
   状态为 RUNNING/IDLE/SLEEPING。历史中 segments[].items[] 的
   kind === "assistant_message" 包含 payload.text。
 
@@ -209,8 +212,6 @@ ${configurationHelp}`,
   errors: Object.freeze({
     sessionOutcomeUnknown: '投递结果未知，请先查看会话状态和历史，不要盲目重试。',
     sessionMessageInvalid: '消息不能为空或超过长度限制；输入文件必须是可读取的 UTF-8 文本。',
-    sessionImageInvalid:
-      '图片必须是可读取的 PNG、JPEG、GIF 或 WebP 文件：最多 5 张，单张 5 MiB，合计 10 MiB。',
     sessionWaitUnknown: '无法确认指定 Run，请查看会话状态和历史。',
     sessionWaitCancelled: '已取消等待，未停止目标 Run。',
     sessionWaitTimeout: '等待超时，未停止目标 Run。',

package/src/session-args.mjs

@@ -7,7 +7,7 @@ const commands = {
   list: ['scope', 'query', 'limit'],
   graph: ['limit'],
   show: [],
-  view: ['cursor', 'limit', 'history'],
+  view: [],
   history: ['cursor', 'limit'],
   start: [
     'runner',
@@ -16,7 +16,6 @@ const commands = {
     'title',
     'message',
     'message-file',
-    'image',
     'client-message-id',
     'parent',
     'goal',
@@ -35,7 +34,6 @@ const commands = {
   send: [
     'message',
     'message-file',
-    'image',
     'steer',
     'queue',
     'client-message-id',
@@ -44,7 +42,7 @@ const commands = {
     'approval',
     'decision'
   ],
-  stop: ['execution'],
+  stop: [],
   'goal.get': [],
   'goal.set': ['message', 'message-file'],
   'goal.clear': [],
@@ -59,10 +57,8 @@ const fieldNames = {
   run: 'runId',
   approval: 'approvalId',
   timeout: 'timeoutMs',
-  execution: 'executionId',
   'wait-for': 'waitFor',
-  'clear-goal': 'clearGoal',
-  image: 'images'
+  'clear-goal': 'clearGoal'
 };
 
 export function parseSessionArgs(argv, translate = createTranslator()) {
@@ -115,11 +111,8 @@ 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 (flag === '--clear-goal' && ['start', 'send'].includes(action)) {
+      const key = 'clearGoal';
       if (Object.hasOwn(args, key)) throw invalid();
       args[key] = true;
       continue;
@@ -128,7 +121,7 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     const key = fieldNames[name] ?? name;
     if (
       !commands[action].includes(name) ||
-      (name !== 'image' && !(name === 'agent' && action === 'wait') && Object.hasOwn(args, key))
+      (!(name === 'agent' && action === 'wait') && Object.hasOwn(args, key))
     )
       throw invalid();
     const value = input.shift();
@@ -141,9 +134,6 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     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') {
       if (
         !/^[1-9][0-9]*$/u.test(value) ||
@@ -174,7 +164,6 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     ['start', 'send', 'goal.set', 'schedule.create', 'prompt.set'].includes(action) &&
     args.messageFile === undefined &&
     args.message === undefined &&
-    !args.images?.length &&
     !(
       action === 'send' &&
       (args.goal !== undefined || args.clearGoal || args.approvalId !== undefined)
@@ -187,7 +176,6 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     !['mar-agent', 'codex', 'claude-code', 'opencode'].includes(args.runner)
   )
     throw invalid();
-  if (action === 'stop' && !args.executionId) throw invalid();
   if (action === 'wait' && args.sessionId && args.agentIds?.length) throw invalid();
   if (
     args.until !== undefined &&

package/src/session-input.mjs

@@ -1,5 +1,4 @@
 import { open } from 'node:fs/promises';
-import { basename } from 'node:path';
 import { MarctlError } from './errors.mjs';
 
 export async function messageContent(
@@ -42,47 +41,3 @@ export async function messageContent(
     await file?.close();
   }
 }
-
-export async function imageAttachments(paths, translate) {
-  const attachments = [];
-  let total = 0;
-  for (const path of paths) {
-    let file;
-    try {
-      file = await open(path, 'r');
-      const info = await file.stat();
-      if (!info.isFile() || info.size === 0 || info.size > 5 * 1024 * 1024)
-        throw new Error('IMAGE_INVALID');
-      const parts = [];
-      let size = 0;
-      for await (const part of file.createReadStream({ autoClose: false })) {
-        size += part.length;
-        total += part.length;
-        if (size > 5 * 1024 * 1024 || total > 10 * 1024 * 1024) throw new Error('IMAGE_TOO_LARGE');
-        parts.push(part);
-      }
-      const data = Buffer.concat(parts);
-      const mime = imageMime(data);
-      if (mime === undefined) throw new Error('IMAGE_INVALID');
-      attachments.push({ name: basename(path), mime, dataBase64: data.toString('base64') });
-    } catch {
-      throw new MarctlError(translate('errors.sessionImageInvalid'), {
-        code: 'MARCTL_SESSION_INPUT_INVALID'
-      });
-    } finally {
-      await file?.close();
-    }
-  }
-  return attachments;
-}
-
-function imageMime(data) {
-  if (data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) return 'image/png';
-  if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg';
-  if (['GIF87a', 'GIF89a'].includes(data.subarray(0, 6).toString('ascii'))) return 'image/gif';
-  if (
-    data.subarray(0, 4).toString('ascii') === 'RIFF' &&
-    data.subarray(8, 12).toString('ascii') === 'WEBP'
-  )
-    return 'image/webp';
-}

package/src/session-prepare.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { messageContent, imageAttachments } from './session-input.mjs';
+import { messageContent } from './session-input.mjs';
 
 const networkActions = new Set(['start', 'send', 'wait', 'stop', 'list', 'view']);
 
@@ -17,18 +17,15 @@ export async function prepareAgentNetworkRequest({ args, stdin, translate, sessi
     'parentSessionId',
     'scope',
     'waitFor',
-    'mode',
-    'executionId'
+    'mode'
   ])
     if (args[name] !== undefined) input[name] = args[name];
   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)
@@ -82,10 +79,6 @@ export async function prepareSessionRequest({ args, env, stdin, translate, sessi
     );
   if (args.action === 'approval.decide')
     body.decision = args.decision === 'approve' ? 'APPROVED' : 'REJECTED';
-  if (args.images !== undefined) {
-    body.attachments = await imageAttachments(args.images, translate);
-    body.content ??= '';
-  }
   if (args.action === 'start' || args.action === 'send')
     body.clientMessageId = args.clientMessageId ?? randomUUID();
   if (args.action === 'send')