@myagentroam/marctl 0.11.8 → 0.11.10

package/package.json

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

package/src/i18n/en-US.mjs

@@ -45,22 +45,19 @@ 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} list [--scope children|descendants|workspace|profile]
-    [--agent <id>]
-    [--runner <runner>] [--query <title>] [--parent <id>]
-    [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} list [--scope tree|active] [--query <title>]
+    [--limit <1..100>] [--json]
   {program} view [<id>] [--history] [--cursor <cursor>]
     [--limit <1..100>] [--json]
 
@@ -84,26 +81,33 @@ Management:
 
 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.
+  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.
   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.
+  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.
   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 reports latestActivity; wait may include progress.
+  session.latestMessage. List entries have id, parentSessionId, title, runner
+  and status; wait may include progress.
   Status is RUNNING/IDLE/SLEEPING. In history, segments[].items[] with
   kind === "assistant_message" expose payload.text.
 
@@ -220,8 +224,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,19 @@ ${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} list [--scope children|descendants|workspace|profile]
-    [--agent <id>]
-    [--runner <runner>] [--query <title>] [--parent <id>]
-    [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} list [--scope tree|active] [--query <title>]
+    [--limit <1..100>] [--json]
   {program} view [<id>] [--history] [--cursor <cursor>]
     [--limit <1..100>] [--json]
 
@@ -83,21 +80,28 @@ ${configurationHelp}
 
 输入与结果：
   start 默认当前会话的 Runner；没有当前会话的终端须指定 --runner 或
-  --parent。profile 显示已配置模型，不代表账号实时可用。start 不等待。
+  --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 返回当前身份和分页结果，
-  nextCursor 表示还有后续页面。配置和持久提示从后续执行生效。
+  -m 与 --message-file 互斥；文件使用 UTF-8，- 从 stdin 读取。
+  list 默认查询所在会话树，包含空闲会话；
+  没有当前会话时默认 active，显式 tree 须有会话上下文。active 包含当前
+  Workspace 中运行及睡眠的会话。返回 currentAgentId（无会话时为 null）、
+  扁平 sessions 和 truncated。limit 默认及上限均为 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 返回 latestActivity；wait 可能包含 progress；
+  session.latestMessage。list 每项仅含 id、parentSessionId、title、runner 和
+  status；wait 可能包含 progress；
   状态为 RUNNING/IDLE/SLEEPING。历史中 segments[].items[] 的
   kind === "assistant_message" 包含 payload.text。
 
@@ -207,8 +211,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

@@ -4,7 +4,7 @@ import { sessionTarget } from './session-target.mjs';
 
 const commands = {
   current: [],
-  list: ['cursor', 'limit', 'query', 'parent', 'scope', 'agent', 'runner'],
+  list: ['scope', 'query', 'limit'],
   graph: ['limit'],
   show: [],
   view: ['cursor', 'limit', 'history'],
@@ -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',
@@ -61,8 +59,7 @@ const fieldNames = {
   timeout: 'timeoutMs',
   execution: 'executionId',
   'wait-for': 'waitFor',
-  'clear-goal': 'clearGoal',
-  image: 'images'
+  'clear-goal': 'clearGoal'
 };
 
 export function parseSessionArgs(argv, translate = createTranslator()) {
@@ -128,7 +125,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 +138,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 +168,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)
@@ -211,11 +204,7 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
   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.scope !== undefined && !['tree', 'active'].includes(args.scope)) throw invalid();
   if (
     action === 'approval.decide' &&
     (!args.runId || !args.approvalId || !['approve', 'reject'].includes(args.decision))

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']);
 
@@ -21,11 +21,6 @@ export async function prepareAgentNetworkRequest({ args, stdin, translate, sessi
     '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;
@@ -33,7 +28,6 @@ export async function prepareAgentNetworkRequest({ args, stdin, translate, sessi
   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)
@@ -87,10 +81,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')