ticlawk 0.1.15 → 0.1.16-dev.2

package/src/cli/agent-commands.mjs

@@ -0,0 +1,829 @@
+/**
+ * Agent-facing CLI subcommands.
+ *
+ * These run inside a runtime (Codex / Claude Code / etc.) and post to
+ * the local daemon at TICLAWK_RUNTIME_DAEMON_URL (default
+ * http://127.0.0.1:8741). The daemon validates the caller's
+ * TICLAWK_RUNTIME_AGENT_ID against active bindings before forwarding to
+ * the ticlawk backend.
+ *
+ * Commands:
+ *   ticlawk message send --target <t> [--seen-up-to-seq N] [--reply-to <msg>]
+ *   ticlawk message read --target <t> [--around <msg>] [--limit N]
+ *   ticlawk task claim --message-id <id> [--lease-seconds N]
+ *   ticlawk task update --task-id <id> --status <s>
+ *   ticlawk task list [--target <t>]
+ *   ticlawk group members --target <t>
+ *   ticlawk server info [--refresh]
+ *
+ * `ticlawk message send` reads the message body from stdin so heredocs
+ * work cleanly (matching the Slock convention).
+ */
+
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+
+function getDaemonUrl() {
+  return process.env.TICLAWK_RUNTIME_DAEMON_URL || 'http://127.0.0.1:8741';
+}
+
+function requireAgentEnv() {
+  const agentId = String(process.env.TICLAWK_RUNTIME_AGENT_ID || '').trim();
+  if (!agentId) {
+    console.error('TICLAWK_RUNTIME_AGENT_ID is required (must be set by the daemon when spawning the runtime).');
+    console.error('If you are seeing this outside an agent runtime, this command is not for you.');
+    process.exit(2);
+  }
+  return {
+    agentId,
+    hostId: String(process.env.TICLAWK_RUNTIME_HOST_ID || '').trim() || null,
+    sessionId: String(process.env.TICLAWK_RUNTIME_SESSION_ID || '').trim() || null,
+  };
+}
+
+function commonHeaders(env) {
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-Ticlawk-Acting-Agent-Id': env.agentId,
+  };
+  if (env.hostId) headers['X-Ticlawk-Runtime-Host-Id'] = env.hostId;
+  if (env.sessionId) headers['X-Ticlawk-Runtime-Session-Id'] = env.sessionId;
+  return headers;
+}
+
+function daemonRequest({ method, path, headers, body }) {
+  const url = new URL(path, getDaemonUrl());
+  const isHttps = url.protocol === 'https:';
+  const requestFn = isHttps ? httpsRequest : httpRequest;
+  const payload = body == null ? null : (typeof body === 'string' ? body : JSON.stringify(body));
+  return new Promise((resolve, reject) => {
+    const req = requestFn({
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: `${url.pathname}${url.search}`,
+      method,
+      headers: {
+        ...headers,
+        ...(payload != null ? { 'Content-Length': Buffer.byteLength(payload) } : {}),
+      },
+    }, (res) => {
+      let text = '';
+      res.on('data', (chunk) => { text += chunk; });
+      res.on('end', () => {
+        let parsed = null;
+        if (text) {
+          try { parsed = JSON.parse(text); } catch { parsed = null; }
+        }
+        resolve({ statusCode: res.statusCode || 0, body: parsed, raw: text });
+      });
+    });
+    req.on('error', reject);
+    if (payload != null) req.write(payload);
+    req.end();
+  });
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  let buf = '';
+  for await (const chunk of process.stdin) buf += chunk;
+  return buf;
+}
+
+function getArg(args, name) {
+  return args[name] != null ? String(args[name]) : null;
+}
+
+function getNumberArg(args, name) {
+  const v = args[name];
+  if (v == null) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function exitFromStatus(statusCode, errorBody) {
+  if (statusCode >= 200 && statusCode < 300) return 0;
+  if (statusCode === 409) {
+    if (errorBody) printJson(errorBody);
+    return 1;
+  }
+  if (errorBody) printJson(errorBody);
+  return 1;
+}
+
+export async function runMessageSendCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  const text = await readStdin();
+  if (!text || !text.trim()) {
+    console.error('message body is required on stdin');
+    console.error('Example:');
+    console.error("  echo \"hello\" | ticlawk message send --target dm:@alice");
+    console.error("  ticlawk message send --target \"#frontend\" <<'EOF'");
+    console.error('  ...message...');
+    console.error('  EOF');
+    return 2;
+  }
+  const body = {
+    target,
+    conversation_id: conversationId,
+    text: text.replace(/\n+$/, ''),
+    seen_up_to_seq: getNumberArg(args, 'seen-up-to-seq'),
+    reply_to_message_id: getArg(args, 'reply-to'),
+  };
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/message/send',
+    headers: commonHeaders(env),
+    body,
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode, null);
+}
+
+export async function runMessageReadCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  const params = new URLSearchParams();
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const around = getArg(args, 'around');
+  if (around) params.set('around_message_id', around);
+  const beforeSeq = getArg(args, 'before-seq');
+  if (beforeSeq) params.set('before_seq', beforeSeq);
+  const limit = getArg(args, 'limit');
+  if (limit) params.set('limit', limit);
+
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/message/read?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runTaskCreateCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  const text = await readStdin();
+  if (!text || !text.trim()) {
+    console.error('task body is required on stdin');
+    console.error('Example:');
+    console.error("  ticlawk task create --target \"#frontend\" --title \"fix login\" <<'EOF'");
+    console.error('  Detailed description goes here.');
+    console.error('  EOF');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/task/create',
+    headers: commonHeaders(env),
+    body: {
+      target,
+      conversation_id: conversationId,
+      text: text.replace(/\n+$/, ''),
+      title: getArg(args, 'title'),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runTaskClaimCommand(args) {
+  const env = requireAgentEnv();
+  const messageId = getArg(args, 'message-id');
+  const number = getNumberArg(args, 'number');
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!messageId && number == null) {
+    console.error('--message-id or --number is required');
+    return 2;
+  }
+  if (number != null && !target && !conversationId) {
+    console.error('--target or --conversation-id is required when claiming by --number');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/task/claim',
+    headers: commonHeaders(env),
+    body: {
+      source_message_id: messageId,
+      number,
+      target,
+      conversation_id: conversationId,
+      lease_seconds: getNumberArg(args, 'lease-seconds'),
+    },
+  });
+  printJson(res.body);
+  if (res.statusCode === 409) {
+    console.error(`task already claimed by another agent`);
+    return 1;
+  }
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runTaskUnclaimCommand(args) {
+  const env = requireAgentEnv();
+  const taskId = getArg(args, 'task-id');
+  if (!taskId) {
+    console.error('--task-id is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/task/unclaim',
+    headers: commonHeaders(env),
+    body: { task_id: taskId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runTaskUpdateCommand(args) {
+  const env = requireAgentEnv();
+  const taskId = getArg(args, 'task-id');
+  const status = getArg(args, 'status');
+  if (!taskId || !status) {
+    console.error('--task-id and --status are required');
+    return 2;
+  }
+  if (!['todo', 'in_progress', 'in_review', 'done', 'canceled'].includes(status)) {
+    console.error(`--status must be one of: todo, in_progress, in_review, done, canceled`);
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/task/update',
+    headers: commonHeaders(env),
+    body: { task_id: taskId, status },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runMessageReactCommand(args) {
+  const env = requireAgentEnv();
+  const messageId = getArg(args, 'message-id');
+  const emoji = getArg(args, 'emoji');
+  const remove = !!args.remove;
+  if (!messageId) {
+    console.error('--message-id is required');
+    return 2;
+  }
+  if (!emoji) {
+    console.error('--emoji is required');
+    return 2;
+  }
+  if (emoji.length > 16 || /\s/.test(emoji)) {
+    console.error('--emoji must be a single emoji, ≤16 chars, no whitespace');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/message/react',
+    headers: commonHeaders(env),
+    body: { message_id: messageId, emoji, remove },
+  });
+  printJson(res.body);
+  if (res.statusCode >= 200 && res.statusCode < 300) {
+    const verb = remove ? 'removed from' : 'added to';
+    console.error(`Reaction ${emoji} ${verb} message ${messageId.slice(0, 8)}.`);
+  }
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runTaskListCommand(args) {
+  const env = requireAgentEnv();
+  const params = new URLSearchParams();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/task/list?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+// ── Reminders ──
+
+function resolveFireAt(args) {
+  const explicit = getArg(args, 'fire-at');
+  if (explicit) return explicit;
+  const inSeconds = getNumberArg(args, 'in-seconds');
+  if (inSeconds != null) {
+    return new Date(Date.now() + inSeconds * 1000).toISOString();
+  }
+  const inMinutes = getNumberArg(args, 'in-minutes');
+  if (inMinutes != null) {
+    return new Date(Date.now() + inMinutes * 60 * 1000).toISOString();
+  }
+  return null;
+}
+
+export async function runReminderScheduleCommand(args) {
+  const env = requireAgentEnv();
+  const title = getArg(args, 'title');
+  if (!title) {
+    console.error('--title is required');
+    return 2;
+  }
+  const fireAt = resolveFireAt(args);
+  if (!fireAt) {
+    console.error('one of --fire-at <ISO>, --in-seconds N, --in-minutes N is required');
+    return 2;
+  }
+  const target = getArg(args, 'target');
+  const anchorConversationId = getArg(args, 'anchor-conversation-id');
+  const anchorMessageId = getArg(args, 'anchor-message-id');
+  if (!target && !anchorConversationId) {
+    console.error('--target or --anchor-conversation-id is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/reminder/schedule',
+    headers: commonHeaders(env),
+    body: {
+      title,
+      fire_at: fireAt,
+      target,
+      anchor_conversation_id: anchorConversationId,
+      anchor_message_id: anchorMessageId,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runReminderListCommand(args) {
+  const env = requireAgentEnv();
+  const params = new URLSearchParams();
+  const status = getArg(args, 'status');
+  if (status) params.set('status', status);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/reminder/list?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runReminderSnoozeCommand(args) {
+  const env = requireAgentEnv();
+  const reminderId = getArg(args, 'reminder-id') || args._?.[2];
+  const fireAt = resolveFireAt(args);
+  if (!reminderId) {
+    console.error('--reminder-id (or positional) is required');
+    return 2;
+  }
+  if (!fireAt) {
+    console.error('one of --fire-at <ISO>, --in-seconds N, --in-minutes N is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/reminder/snooze',
+    headers: commonHeaders(env),
+    body: { reminder_id: reminderId, fire_at: fireAt },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runReminderUpdateCommand(args) {
+  const env = requireAgentEnv();
+  const reminderId = getArg(args, 'reminder-id') || args._?.[2];
+  const title = getArg(args, 'title');
+  const fireAt = resolveFireAt(args);
+  if (!reminderId) {
+    console.error('--reminder-id (or positional) is required');
+    return 2;
+  }
+  if (!title && !fireAt) {
+    console.error('at least one of --title or --fire-at / --in-seconds / --in-minutes is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/reminder/update',
+    headers: commonHeaders(env),
+    body: { reminder_id: reminderId, title, fire_at: fireAt },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runReminderCancelCommand(args) {
+  const env = requireAgentEnv();
+  const reminderId = getArg(args, 'reminder-id') || args._?.[2];
+  if (!reminderId) {
+    console.error('--reminder-id (or positional) is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/reminder/cancel',
+    headers: commonHeaders(env),
+    body: { reminder_id: reminderId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runReminderLogCommand(args) {
+  const env = requireAgentEnv();
+  const reminderId = getArg(args, 'reminder-id') || args._?.[2];
+  if (!reminderId) {
+    console.error('--reminder-id (or positional) is required');
+    return 2;
+  }
+  const params = new URLSearchParams();
+  params.set('reminder_id', reminderId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/reminder/log?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runMessageCheckCommand(args) {
+  const env = requireAgentEnv();
+  const params = new URLSearchParams();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/message/check?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runMessageSearchCommand(args) {
+  const env = requireAgentEnv();
+  const query = getArg(args, 'query') || getArg(args, 'q');
+  if (!query) {
+    console.error('--query (or --q) is required');
+    return 2;
+  }
+  const params = new URLSearchParams();
+  params.set('q', query);
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  const limit = getArg(args, 'limit');
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  if (limit) params.set('limit', limit);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/message/search?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runProfileShowCommand(args) {
+  const env = requireAgentEnv();
+  const positional = args._?.[2];   // ticlawk profile show @handle
+  const explicit = getArg(args, 'id') || getArg(args, 'handle');
+  let target = explicit || positional || env.agentId;
+  if (typeof target === 'string' && target.startsWith('@')) target = target.slice(1);
+  const params = new URLSearchParams();
+  if (target) params.set('id', target);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/profile/show?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runProfileUpdateCommand(args) {
+  const env = requireAgentEnv();
+  const displayName = getArg(args, 'display-name');
+  const description = getArg(args, 'description');
+  const avatarFile = getArg(args, 'avatar-file');
+  if (displayName == null && description == null && avatarFile == null) {
+    console.error('at least one of --display-name, --description, --avatar-file is required');
+    return 2;
+  }
+  let avatarUrl = null;
+  if (avatarFile) {
+    // Re-use the attachment upload path then set the public_url as the avatar.
+    const upload = await uploadFileViaDaemon(env, avatarFile);
+    if (!upload.ok) {
+      console.error(`avatar upload failed: ${upload.error}`);
+      return 1;
+    }
+    avatarUrl = upload.publicUrl;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/profile/update',
+    headers: commonHeaders(env),
+    body: {
+      display_name: displayName,
+      description,
+      avatar_url: avatarUrl,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+async function uploadFileViaDaemon(env, filePath) {
+  let stat;
+  try { stat = statSync(filePath); } catch (err) {
+    return { ok: false, error: `cannot stat ${filePath}: ${err.message}` };
+  }
+  if (!stat.isFile()) return { ok: false, error: `${filePath} is not a regular file` };
+  const data = readFileSync(filePath);
+  const contentType = inferContentType(filePath);
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/attachment/upload',
+    headers: commonHeaders(env),
+    body: {
+      filename: basename(filePath),
+      content_type: contentType,
+      data_base64: data.toString('base64'),
+    },
+  });
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    return { ok: false, error: res.body?.error || `HTTP ${res.statusCode}` };
+  }
+  return { ok: true, assetId: res.body?.asset?.asset_id, publicUrl: res.body?.public_url };
+}
+
+function inferContentType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  switch (ext) {
+    case '.png': return 'image/png';
+    case '.jpg': case '.jpeg': return 'image/jpeg';
+    case '.gif': return 'image/gif';
+    case '.webp': return 'image/webp';
+    case '.pdf': return 'application/pdf';
+    case '.txt': return 'text/plain';
+    case '.md': return 'text/markdown';
+    case '.json': return 'application/json';
+    default: return 'application/octet-stream';
+  }
+}
+
+export async function runAttachmentUploadCommand(args) {
+  const env = requireAgentEnv();
+  const file = args._?.[2];
+  if (!file) {
+    console.error('usage: ticlawk attachment upload <file>');
+    return 2;
+  }
+  const upload = await uploadFileViaDaemon(env, file);
+  printJson(upload);
+  return upload.ok ? 0 : 1;
+}
+
+export async function runAttachmentViewCommand(args) {
+  const env = requireAgentEnv();
+  const assetId = args._?.[2];
+  if (!assetId) {
+    console.error('usage: ticlawk attachment view <asset_id> [--out <path>]');
+    return 2;
+  }
+  const params = new URLSearchParams();
+  params.set('asset_id', assetId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/attachment/view?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  const out = getArg(args, 'out');
+  if (out && res.body?.public_url) {
+    // Download via fetch and write to disk.
+    const fetched = await fetch(res.body.public_url);
+    if (fetched.ok) {
+      const buf = Buffer.from(await fetched.arrayBuffer());
+      writeFileSync(out, buf);
+      console.error(`wrote ${buf.length} bytes to ${out}`);
+    } else {
+      console.error(`download failed: HTTP ${fetched.status}`);
+      return 1;
+    }
+  }
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runGroupCreateCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) {
+    console.error('--name is required');
+    return 2;
+  }
+  const description = getArg(args, 'description');
+  const memberArgs = args.member;
+  const memberAgentIds = Array.isArray(memberArgs)
+    ? memberArgs
+    : memberArgs
+      ? [memberArgs]
+      : [];
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/group/create',
+    headers: commonHeaders(env),
+    body: {
+      name,
+      description,
+      member_agent_ids: memberAgentIds.map((s) => String(s).trim()).filter(Boolean),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runGroupMembersAddCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  const memberArgs = args.add;
+  const agentIds = Array.isArray(memberArgs)
+    ? memberArgs
+    : memberArgs
+      ? [memberArgs]
+      : [];
+  if (agentIds.length === 0) {
+    console.error('--add <agent-id> required (may repeat)');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/group/members/add',
+    headers: commonHeaders(env),
+    body: {
+      target,
+      conversation_id: conversationId,
+      agent_ids: agentIds.map((s) => String(s).trim()).filter(Boolean),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runGroupMembersRemoveCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  const removeArg = getArg(args, 'remove');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  if (!removeArg) {
+    console.error('--remove <agent-id> required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/group/members/remove',
+    headers: commonHeaders(env),
+    body: {
+      target,
+      conversation_id: conversationId,
+      agent_id: removeArg,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runGroupMembersCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  const params = new URLSearchParams();
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/group/members?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServerInfoCommand(args) {
+  const env = requireAgentEnv();
+  const params = new URLSearchParams();
+  if (args.refresh) params.set('refresh', '1');
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/server/info?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export const AGENT_COMMAND_HELP = {
+  message: `ticlawk message <send|read|check|search|react>
+  ticlawk message send --target "<target>" [--seen-up-to-seq N] [--reply-to <msg-id>]
+    Body is read from stdin (use <<'EOF' ... EOF for multiline).
+    Targets:
+      dm:@<user>         private message
+      #<group>           group conversation
+      #<group>:<msgid>   thread under a top-level message in that group
+  ticlawk message read --target "<target>" [--around <msg-id>] [--before-seq N] [--limit N]
+  ticlawk message check [--target "<target>"]
+    Non-blocking poll for new/unprocessed messages.
+  ticlawk message search --query <q> [--target "<target>"] [--limit N]
+    Text search (ilike) across messages visible to you.
+  ticlawk message react --message-id <id> --emoji <e> [--remove]
+    Use sparingly: prefer acknowledgement/follow-up signals like 👀. Do not
+    auto-react to every merge, deploy, or task completion with celebratory emoji.
+`,
+  profile: `ticlawk profile <show|update>
+  ticlawk profile show [@handle | --id <agent-id>]
+  ticlawk profile update [--display-name X] [--description Y] [--avatar-file path]
+`,
+  attachment: `ticlawk attachment <upload|view>
+  ticlawk attachment upload <file>
+  ticlawk attachment view <asset-id> [--out <path>]
+`,
+  reminder: `ticlawk reminder <schedule|list|snooze|update|cancel|log>
+  ticlawk reminder schedule --title <t> (--fire-at <iso> | --in-seconds N | --in-minutes N) (--target "<target>" | --anchor-conversation-id <id>) [--anchor-message-id <id>]
+  ticlawk reminder list [--status active|fired|canceled]
+  ticlawk reminder snooze <reminder-id> (--fire-at <iso> | --in-seconds N | --in-minutes N)
+  ticlawk reminder update <reminder-id> [--title <t>] [--fire-at <iso>]
+  ticlawk reminder cancel <reminder-id>
+  ticlawk reminder log <reminder-id>
+
+  Use reminders for follow-up that depends on future state you cannot resolve
+  now. A reminder fires by posting a system message into the anchor
+  conversation and waking the owner agent via an explicit delivery.
+`,
+  task: `ticlawk task <create|claim|unclaim|update|list>
+  ticlawk task create --target "<target>" [--title <t>]
+    Body is read from stdin. Creates a brand-new message published as a todo
+    task. To own it, follow up with \`ticlawk task claim --message-id <id>\`.
+  ticlawk task claim --message-id <id> [--lease-seconds N]
+  ticlawk task claim --number <N> --target "<target>" [--lease-seconds N]
+  ticlawk task unclaim --task-id <id>
+  ticlawk task update --task-id <id> --status <todo|in_progress|in_review|done|canceled>
+  ticlawk task list [--target <target>]
+`,
+  group: `ticlawk group <create|members>
+  ticlawk group create --name <n> [--description <d>] [--member <agent-id> ...]
+    Agent self-creates a new group. The agent is added as a member; the
+    conversation owner is set to the user that owns this agent. Other
+    member agents must belong to the same user (RLS enforces).
+  ticlawk group members --target "<target>"
+  ticlawk group members --target "<target>" --add <agent-id> [--add <agent-id> ...]
+  ticlawk group members --target "<target>" --remove <agent-id>
+`,
+  server: `ticlawk server info [--refresh]
+`,
+};