@myagentroam/marctl 0.10.8 → 0.10.10

package/package.json

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

package/src/i18n/en-US.mjs

@@ -48,10 +48,19 @@ Usage:
   {program} current [--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>
+  {program} show [<session-id>] [--json]
+  {program} config [<session-id>]
+    [--model <id>] [--effort <value>] [--json]
+  {program} rename [<session-id>] --title <name> [--json]
+  {program} schedule list [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} schedule get [<session-id>] [--json]
+  {program} schedule create [<session-id>] --cron <cron>
+    (-m <text> | --message-file <file|->) [--json]
+  {program} schedule update [<session-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>
@@ -72,6 +81,10 @@ Usage:
     --run <run-id> --timeout <30s|5m> [--json]
 
 Input:
+  show/config/history/graph/rename 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.
   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.
@@ -80,11 +93,29 @@ Input:
   Config requires model or effort; other fields and permissions are unchanged.
   Use --effort "" for the Runner default. Active execution is not restarted.
 
+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; scheduled callers are read-only.
+  Read the current revision before updating; a version conflict is not retried.
+
+Reading JSON:
+  show: session.activity, session.model, session.effort,
+    session.customTitle / session.runnerTitle, runs[] (id/status),
+    queue.items[], goal.status (goal may be null).
+  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.
-  When useful, --steer adds gentle context to an in-progress task.
-  --queue places input in a subsequent turn.
+  --steer prioritizes new context and may switch the current execution.
+    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.
   Example:
     marctl sessions send <session-id> --steer \\
       -m "Additional context: focus on the resume path." --json
@@ -233,6 +264,7 @@ or Server connection is required.`
     sessionWaitTimeout: 'Waiting timed out; the target Run was not stopped.',
 
     userContextUnavailable: 'This Node session has no valid marctl user authorization.',
+    sessionContextRequired: 'No current Session is available; specify a Session ID explicitly.',
     serverUrlInvalid: 'MAR_CTL_SERVER_URL is invalid.',
     serverUrlTransport: 'MAR_CTL_SERVER_URL must use HTTPS or loopback HTTP.',
     serverUrlOrigin: 'MAR_CTL_SERVER_URL must be an origin without credentials or query data.',

package/src/i18n/zh-CN.mjs

@@ -47,10 +47,19 @@ ${configurationHelp}
   {program} current [--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>
+  {program} show [<session-id>] [--json]
+  {program} config [<session-id>]
+    [--model <id>] [--effort <value>] [--json]
+  {program} rename [<session-id>] --title <name> [--json]
+  {program} schedule list [--cursor <cursor>] [--limit <1..100>] [--json]
+  {program} schedule get [<session-id>] [--json]
+  {program} schedule create [<session-id>] --cron <cron>
+    (-m <text> | --message-file <file|->) [--json]
+  {program} schedule update [<session-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>
@@ -71,6 +80,9 @@ ${configurationHelp}
     --run <run-id> --timeout <30s|5m> [--json]
 
 输入：
+  show/config/history/graph/rename 和 schedule get/create/update 可省略 ID，
+  使用当前会话；没有当前会话时请显式指定 ID。
+  send/goal/stop/wait 始终要求显式会话 ID。
   Runner：mar-agent、codex、claude-code、opencode，操作以实际能力为准。
   -m / --message 直接传文本，与 --message-file 互斥；
   文件用 UTF-8，- 从 stdin 读取。
@@ -79,11 +91,26 @@ ${configurationHelp}
   config 至少指定 model 或 effort；未指定字段和权限不变。
   --effort "" 使用 Runner 默认值，不重启当前执行。
 
+标题与定时任务：
+  rename 复用现有标题更新，不限制 parent 树、不重启执行。
+  schedule list 读取本地 Workspace 任务，get/create/update 与 MCP 共用任务数据。
+  任务正文最多 20,000 字符；update 至少指定 cron 或正文。
+  修改其他用户的任务会生成 PENDING 提议；定时来源只读。
+  更新前读取当前 revision；版本冲突不会自动重试。
+
+读取 JSON：
+  show：session.activity、session.model、session.effort、
+    session.customTitle / session.runnerTitle、runs[]（id/status）、
+    queue.items[]、goal.status（goal 可为空）。
+  history：segments[].items[] 中按 kind === "assistant_message"
+    筛选，读取 payload.text。
+
 投递与等待：
   start/send 返回 clientMessageId。
   send 必须二选一：--steer 或 --queue，空闲时也需指定。
-  --steer 在必要时为正在进行的任务补充温和的新信息。
-  --queue 将输入排入后续轮次。
+  --steer 优先补充新信息，可能切换当前执行；
+    Node 按实际状态裁决，仅用于影响当前工作的必要更新。
+  --queue 排入后续轮次；有活动 Goal 时可能等待 Goal 退出才处理。
   示例：
     marctl sessions send <session-id> --steer \\
       -m "Additional context: focus on the resume path." --json
@@ -222,6 +249,7 @@ ${configurationHelp}`,
     sessionWaitTimeout: '等待超时，未停止目标 Run。',
 
     userContextUnavailable: '此 Node 会话没有有效的 marctl 用户授权。',
+    sessionContextRequired: '当前上下文没有会话，请显式指定会话 ID。',
     serverUrlInvalid: 'MAR_CTL_SERVER_URL 无效。',
     serverUrlTransport: 'MAR_CTL_SERVER_URL 必须使用 HTTPS 或回环 HTTP。',
     serverUrlOrigin: 'MAR_CTL_SERVER_URL 必须是不含凭据或查询参数的 Origin。',

package/src/sessions.mjs

@@ -5,6 +5,16 @@ import { MarctlError } from './config.mjs';
 import { createTranslator } from './i18n/index.mjs';
 
 const terminal = new Set(['SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED']);
+const currentSessionActions = new Set([
+  'show',
+  'config',
+  'history',
+  'graph',
+  'rename',
+  'schedule.get',
+  'schedule.create',
+  'schedule.update'
+]);
 const commands = {
   current: [],
   list: ['cursor', 'limit', 'query', 'parent'],
@@ -22,6 +32,11 @@ const commands = {
     'client-message-id'
   ],
   config: ['model', 'effort'],
+  rename: ['title'],
+  'schedule.list': ['cursor', 'limit'],
+  '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'],
   'goal.get': [],
@@ -31,6 +46,7 @@ const commands = {
 };
 const fieldNames = {
   parent: 'parentSessionId',
+  'expected-revision': 'expectedRevision',
   'message-file': 'messageFile',
   'client-message-id': 'clientMessageId',
   run: 'runId',
@@ -51,13 +67,17 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     return { command: 'sessions', help: true };
   const input = [...argv];
   let action = input.shift();
-  if (action === 'goal') action += '.' + input.shift();
+  if (action === 'goal' || action === 'schedule') action += '.' + input.shift();
   if (!Object.hasOwn(commands, action)) throw invalid();
   const args = { command: 'sessions', action };
-  if (!['current', 'list', 'start'].includes(action)) {
-    const sessionId = input.shift();
-    if (!sessionId || sessionId.startsWith('-') || sessionId.length > 512) throw invalid();
-    args.sessionId = sessionId;
+  if (!['current', 'list', 'start', 'schedule.list'].includes(action)) {
+    if ((input[0] === undefined || input[0].startsWith('-')) && !currentSessionActions.has(action))
+      throw invalid();
+    if (input[0] !== undefined && !input[0].startsWith('-')) {
+      const sessionId = input.shift();
+      if (!sessionId || sessionId.length > 512) throw invalid();
+      args.sessionId = sessionId;
+    }
   }
   while (input.length > 0) {
     const rawFlag = input.shift();
@@ -86,8 +106,13 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     if (name === 'image') {
       (args.images ??= []).push(value);
       if (args.images.length > 5) throw invalid();
-    } else if (name === 'limit') {
-      if (!/^[1-9][0-9]*$/u.test(value) || Number(value) > 100) throw invalid();
+    } else if (name === 'limit' || name === 'expected-revision') {
+      if (
+        !/^[1-9][0-9]*$/u.test(value) ||
+        !Number.isSafeInteger(Number(value)) ||
+        (name === 'limit' && Number(value) > 100)
+      )
+        throw invalid();
       args[key] = Number(value);
     } else if (name === 'timeout') {
       const match = /^([1-9][0-9]*)(ms|s|m)$/u.exec(value);
@@ -100,7 +125,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'].includes(action) &&
+    ['start', 'send', 'goal.set', 'schedule.create'].includes(action) &&
     args.messageFile === undefined &&
     args.message === undefined &&
     !args.images?.length
@@ -113,17 +138,37 @@ export function parseSessionArgs(argv, translate = createTranslator()) {
     throw invalid();
   if (action === 'wait' && (args.runId === undefined || args.timeoutMs === undefined))
     throw invalid();
+  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))
     throw invalid();
   if (args.effort !== undefined && args.effort.length > 120) throw invalid();
   if (action === 'config' && args.model === undefined && args.effort === undefined) throw invalid();
+  if (action === 'rename') {
+    if (args.title === undefined || args.title.trim().length === 0) throw invalid();
+  }
+  if (action === 'schedule.create' && args.cron === undefined) throw invalid();
+  if (args.cron !== undefined && (args.cron.trim().length === 0 || args.cron.length > 512))
+    throw invalid();
+  if (
+    action === 'schedule.update' &&
+    (args.expectedRevision === undefined ||
+      (args.cron === undefined && args.message === undefined && args.messageFile === 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;
 }
 
 export async function runSessionCommand({ args, client, env, stdin, WebSocketClass, translate }) {
+  const targeted = !['current', 'list', 'start', 'schedule.list'].includes(args.action);
+  const sessionId =
+    args.sessionId ?? (currentSessionActions.has(args.action) ? env.MAR_CTL_SESSION_ID : undefined);
+  if (targeted && !sessionId)
+    throw new MarctlError(translate('errors.sessionContextRequired'), {
+      code: 'MARCTL_SESSION_CONTEXT_REQUIRED'
+    });
   if (args.action === 'wait') {
     const controller = new AbortController();
     const cancel = () => controller.abort();
@@ -132,7 +177,7 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
     try {
       return await waitForSessionRun({
         client,
-        sessionId: args.sessionId,
+        sessionId,
         runId: args.runId,
         timeoutMs: args.timeoutMs,
         WebSocketClass,
@@ -155,9 +200,12 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
     'cursor',
     'limit',
     'query',
-    'runId'
+    'runId',
+    'cron',
+    'expectedRevision'
   ])
     if (args[name] !== undefined) body[name] = args[name];
+  if (targeted) body.sessionId = sessionId;
   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;
@@ -167,7 +215,7 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
     body.content = await messageContent(
       args,
       stdin,
-      args.action === 'goal.set' ? 20000 : 100000,
+      args.action === 'goal.set' || args.action.startsWith('schedule.') ? 20000 : 100000,
       translate
     );
   if (args.images !== undefined) {
@@ -189,7 +237,17 @@ export async function runSessionCommand({ args, client, env, stdin, WebSocketCla
   } catch (error) {
     if (body.clientMessageId !== undefined) error.clientMessageId = body.clientMessageId;
     if (
-      ['start', 'send', 'config', 'stop', 'goal.set', 'goal.clear'].includes(args.action) &&
+      [
+        'start',
+        'send',
+        'config',
+        'rename',
+        'schedule.create',
+        'schedule.update',
+        'stop',
+        'goal.set',
+        'goal.clear'
+      ].includes(args.action) &&
       ['MARCTL_REQUEST_TIMEOUT', 'MARCTL_SERVER_UNREACHABLE', 'MARCTL_RESPONSE_INVALID'].includes(
         error.code
       )