@myagentroam/marctl 0.11.0 → 0.11.1

package/package.json

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

package/src/i18n/en-US.mjs

@@ -52,6 +52,9 @@ Usage:
   {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} schedule list [--cursor <cursor>] [--limit <1..100>] [--json]
   {program} schedule get [<session-id>] [--json]
   {program} schedule create [<session-id>] --cron <cron>
@@ -78,13 +81,15 @@ Usage:
   {program} goal set <session-id>
     (-m <text> | --message-file <file|->) [--json]
   {program} wait <session-id>
-    --run <run-id> --timeout <30s|5m> [--json]
+    --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 may omit the ID.
+  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 always require an explicit Session ID.
+  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.
@@ -92,6 +97,7 @@ Input:
   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.
@@ -106,6 +112,8 @@ Reading JSON:
   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.
@@ -117,7 +125,8 @@ Delivery and waiting:
     Node decides from actual state; reserve it for updates
     affecting current work.
   --queue schedules a subsequent turn; an active Goal can delay it
-    until the Goal exits.
+    until the Goal exits. 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
@@ -125,6 +134,9 @@ Delivery and waiting:
   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.
@@ -265,6 +277,7 @@ or Server connection is required.`
     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.',

package/src/i18n/zh-CN.mjs

@@ -51,6 +51,9 @@ ${configurationHelp}
   {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} schedule list [--cursor <cursor>] [--limit <1..100>] [--json]
   {program} schedule get [<session-id>] [--json]
   {program} schedule create [<session-id>] --cron <cron>
@@ -77,12 +80,14 @@ ${configurationHelp}
   {program} goal set <session-id>
     (-m <text> | --message-file <file|->) [--json]
   {program} wait <session-id>
-    --run <run-id> --timeout <30s|5m> [--json]
+    --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 和 schedule get/create/update 可省略 ID，
-  使用当前会话；没有当前会话时请显式指定 ID。
-  send/goal/stop/wait 始终要求显式会话 ID。
+  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 读取。
@@ -90,6 +95,7 @@ ${configurationHelp}
   最多 5 张，单张 5 MiB、合计 10 MiB；goal set 只接受文本。
   config 至少指定 model 或 effort；未指定字段和权限不变。
   --effort "" 使用 Runner 默认值，不重启当前执行。
+  prompt 读取、设置或清除持久指令，从后续执行生效。
 
 标题与定时任务：
   rename 复用现有标题更新，不限制 parent 树、不重启执行。
@@ -103,6 +109,8 @@ ${configurationHelp}
   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。
@@ -113,6 +121,7 @@ ${configurationHelp}
   --steer 优先补充新信息，可能切换当前执行；
     Node 按实际状态裁决，仅用于影响当前工作的必要更新。
   --queue 排入后续轮次；有活动 Goal 时可能等待 Goal 退出才处理。
+    新输入自动恢复暂停的 FIFO，不打断活动执行；取消收敛后才恢复。
   示例：
     marctl sessions send <session-id> --steer \\
       -m "Additional context: focus on the resume path." --json
@@ -120,6 +129,9 @@ ${configurationHelp}
   需按 queueItemId/clientMessageId 与可见历史核对。
   wait 通过 Watch 等待指定 Run；超时不会停止任务，
   超时错误可附 progress，表示最后观察到的有界快照。
+  --until approval 在需要审批决定时也提前返回。
+  approval decide 显式批准或拒绝单个请求，沿用实际用户授权；
+    决定被接受不代表任务完成。
   Run 成功不等于业务完成。Worker 完成不自动唤醒 Coordinator。
   投递结果未知时先查状态/历史，不盲目重发。
 
@@ -250,6 +262,7 @@ ${configurationHelp}`,
     sessionWaitUnknown: '无法确认指定 Run，请查看会话状态和历史。',
     sessionWaitCancelled: '已取消等待，未停止目标 Run。',
     sessionWaitTimeout: '等待超时，未停止目标 Run。',
+    sessionApprovalUnsupported: '此 Node 不支持待审批状态观察。',
 
     userContextUnavailable: '此 Node 会话没有有效的 marctl 用户授权。',
     sessionContextRequired: '当前上下文没有会话，请显式指定会话 ID。',

package/src/sessions.mjs

@@ -11,6 +11,9 @@ const currentSessionActions = new Set([
   'history',
   'graph',
   'rename',
+  'prompt.get',
+  'prompt.set',
+  'prompt.clear',
   'schedule.get',
   'schedule.create',
   'schedule.update'
@@ -33,6 +36,10 @@ const commands = {
   ],
   config: ['model', 'effort'],
   rename: ['title'],
+  'prompt.get': [],
+  'prompt.set': ['message', 'message-file'],
+  'prompt.clear': [],
+  'approval.decide': ['run', 'approval', 'decision'],
   'schedule.list': ['cursor', 'limit'],
   'schedule.get': [],
   'schedule.create': ['cron', 'message', 'message-file'],
@@ -42,7 +49,7 @@ const commands = {
   'goal.get': [],
   'goal.set': ['message', 'message-file'],
   'goal.clear': [],
-  wait: ['run', 'timeout']
+  wait: ['run', 'timeout', 'until']
 };
 const fieldNames = {
   parent: 'parentSessionId',
@@ -50,13 +57,23 @@ const fieldNames = {
   'message-file': 'messageFile',
   'client-message-id': 'clientMessageId',
   run: 'runId',
+  approval: 'approvalId',
   timeout: 'timeoutMs',
   image: 'images'
 };
 
 export function parseSessionArgs(argv, translate = createTranslator()) {
-  const invalid = (key = 'errors.invalidArguments') =>
-    new MarctlError(translate(key), { code: 'MARCTL_SESSION_INPUT_INVALID' });
+  const invalid = (key = 'errors.invalidArguments', details) =>
+    new MarctlError(translate(key), {
+      code: 'MARCTL_SESSION_INPUT_INVALID',
+      details:
+        details ??
+        (argv[0] === 'prompt'
+          ? 'Use prompt get|clear [session-id], or prompt set [session-id] with exactly one of -m/--message or --message-file.'
+          : argv[0] === 'approval'
+            ? 'Use approval decide <session-id> --run <run-id> --approval <approval-id> --decision approve|reject.'
+            : undefined)
+    });
   if (
     argv.length === 0 ||
     argv.some(
@@ -67,7 +84,7 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     return { command: 'sessions', help: true };
   const input = [...argv];
   let action = input.shift();
-  if (action === 'goal' || action === 'schedule') 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 };
   if (!['current', 'list', 'start', 'schedule.list'].includes(action)) {
@@ -125,7 +142,7 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     throw invalid('errors.sessionDeliveryRequired');
   if (args.message !== undefined && args.messageFile !== undefined) throw invalid();
   if (
-    ['start', 'send', 'goal.set', 'schedule.create'].includes(action) &&
+    ['start', 'send', 'goal.set', 'schedule.create', 'prompt.set'].includes(action) &&
     args.messageFile === undefined &&
     args.message === undefined &&
     !args.images?.length
@@ -138,6 +155,16 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     throw invalid();
   if (action === 'wait' && (args.runId === undefined || args.timeoutMs === undefined))
     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))
+  )
+    throw invalid(
+      undefined,
+      'Approval decisions require --run, --approval and --decision approve|reject.'
+    );
   if (action === 'rename' && args.title !== undefined) args.title = args.title.trim();
   if (args.title !== undefined && args.title.length > 160) throw invalid();
   if (args.model !== undefined && (args.model.trim().length === 0 || args.model.length > 120))
@@ -180,6 +207,7 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
         sessionId,
         runId: args.runId,
         timeoutMs: args.timeoutMs,
+        until: args.until,
         WebSocketClass,
         translate,
         signal: controller.signal
@@ -201,6 +229,7 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
     'limit',
     'query',
     'runId',
+    'approvalId',
     'cron',
     'expectedRevision'
   ])
@@ -215,9 +244,16 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
     body.content = await messageContent(
       args,
       stdin,
-      args.action === 'goal.set' || args.action.startsWith('schedule.') ? 20000 : 100000,
-      translate
+      args.action === 'goal.set' ||
+        args.action.startsWith('schedule.') ||
+        args.action === 'prompt.set'
+        ? 20000
+        : 100000,
+      translate,
+      args.action === 'prompt.set'
     );
+  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 ??= '';
@@ -242,6 +278,9 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
         'send',
         'config',
         'rename',
+        'prompt.set',
+        'prompt.clear',
+        'approval.decide',
         'schedule.create',
         'schedule.update',
         'stop',
@@ -259,7 +298,13 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
   }
 }
 
-async function messageContent({ message, messageFile: path }, stdin, limit, translate) {
+async function messageContent(
+  { message, messageFile: path },
+  stdin,
+  limit,
+  translate,
+  diagnostic = false
+) {
   let file;
   try {
     let content = message;
@@ -280,9 +325,14 @@ async function messageContent({ message, messageFile: path }, stdin, limit, tran
     }
     if (content.trim().length === 0 || content.length > limit) throw new Error('MESSAGE_INVALID');
     return content;
-  } catch {
+  } catch (error) {
     throw new MarctlError(translate('errors.sessionMessageInvalid'), {
-      code: 'MARCTL_SESSION_INPUT_INVALID'
+      code: 'MARCTL_SESSION_INPUT_INVALID',
+      ...(diagnostic
+        ? {
+            details: `${path === undefined ? 'message' : path === '-' ? 'stdin' : 'message-file'}: provide non-blank UTF-8 text of at most ${limit} characters.${typeof error.code === 'string' && /^[A-Z_]+$/u.test(error.code) ? ' File error: ' + error.code + '.' : ''}`
+          }
+        : {})
     });
   } finally {
     await file?.close();
@@ -339,6 +389,7 @@ export async function waitForSessionRun({
   sessionId,
   runId,
   timeoutMs,
+  until,
   WebSocketClass,
   translate = createTranslator(),
   signal
@@ -425,6 +476,27 @@ export async function waitForSessionRun({
       accept({ run });
     }
   };
+  const checkApproval = () => {
+    if (settled || until !== 'approval' || progress === undefined) return;
+    if (!Array.isArray(progress.pendingApprovals)) {
+      fail('NODE_OPERATION_UNSUPPORTED', 'errors.sessionApprovalUnsupported', {
+        stage: 'approval'
+      });
+      return;
+    }
+    const pendingApprovals = progress.pendingApprovals.filter(
+      (approval) => approval.runId === runId
+    );
+    if (pendingApprovals.length === 0) return;
+    settled = true;
+    accept({
+      sessionId,
+      runId,
+      stopReason: 'APPROVAL_REQUIRED',
+      pendingApprovals,
+      ...(progress.pendingApprovalsTruncated ? { pendingApprovalsTruncated: true } : {})
+    });
+  };
   const onMessage = (raw) => {
     if (settled) return;
     let message;
@@ -463,6 +535,12 @@ export async function waitForSessionRun({
       if (message.payload?.session?.id === sessionId && message.payload?.progress?.runId === runId)
         progress = message.payload.progress;
       check(run);
+      if (!settled && until === 'approval' && progress === undefined) {
+        fail('NODE_OPERATION_UNSUPPORTED', 'errors.sessionApprovalUnsupported', {
+          stage: 'approval'
+        });
+      }
+      checkApproval();
     } else if (message.type === 'watch.session.event') {
       const payload = message.event?.payload;
       if (
@@ -471,6 +549,7 @@ export async function waitForSessionRun({
       )
         progress = payload.progress;
       check(payload?.run);
+      checkApproval();
     }
     if (!settled && message.expiresAt !== undefined) scheduleRenewal(message.expiresAt);
   };