ticlawk 0.1.16-dev.9 → 0.1.17-dev.1

package/src/cli/agent-commands.mjs

@@ -8,11 +8,13 @@
  * the ticlawk backend.
  *
  * Commands:
- *   ticlawk message send --target <t> [--seen-up-to-seq N] [--reply-to <msg>]
+ *   ticlawk message send --target <t> [--phase progress|final] [--seen-up-to-seq N] [--reply-to <msg>]
  *   ticlawk message read --target <t> [--around <msg>] [--limit N]
+ *   ticlawk task create --target <t> [--title <t>] [--assign-agent <id>]
  *   ticlawk task claim --message-id <id> [--lease-seconds N]
  *   ticlawk task update --task-id <id> --status <s>
- *   ticlawk task list [--target <t>]
+ *   ticlawk task list [--target <t>]   # group admins see the full task board
+ *   ticlawk charter get/set --target <t>
  *   ticlawk group members --target <t>
  *   ticlawk server info [--refresh]
  *
@@ -41,6 +43,9 @@ function requireAgentEnv() {
     agentId,
     hostId: String(process.env.TICLAWK_RUNTIME_HOST_ID || '').trim() || null,
     sessionId: String(process.env.TICLAWK_RUNTIME_SESSION_ID || '').trim() || null,
+    currentConversationId: String(process.env.TICLAWK_RUNTIME_CONVERSATION_ID || '').trim() || null,
+    currentMessageId: String(process.env.TICLAWK_RUNTIME_MESSAGE_ID || '').trim() || null,
+    currentTarget: String(process.env.TICLAWK_RUNTIME_TARGET || '').trim() || null,
   };
 }
 
@@ -51,6 +56,11 @@ function commonHeaders(env) {
   };
   if (env.hostId) headers['X-Ticlawk-Runtime-Host-Id'] = env.hostId;
   if (env.sessionId) headers['X-Ticlawk-Runtime-Session-Id'] = env.sessionId;
+  if (env.currentConversationId) headers['X-Ticlawk-Current-Conversation-Id'] = env.currentConversationId;
+  if (env.currentMessageId) headers['X-Ticlawk-Current-Message-Id'] = env.currentMessageId;
+  if (env.currentTarget && /^[\x00-\x7F]*$/.test(env.currentTarget)) {
+    headers['X-Ticlawk-Current-Target'] = env.currentTarget;
+  }
   return headers;
 }
 
@@ -104,6 +114,14 @@ function getNumberArg(args, name) {
   return Number.isFinite(n) ? n : null;
 }
 
+function getMessagePhaseArg(args) {
+  const raw = getArg(args, 'phase');
+  if (raw == null) return null;
+  const phase = raw.trim().toLowerCase();
+  if (phase === 'progress' || phase === 'final') return phase;
+  return { error: '--phase must be progress or final' };
+}
+
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -160,13 +178,28 @@ export async function runMessageSendCommand(args) {
     mediaAssetIds.push(upload.assetId);
   }
 
+  // Optional metadata flags. --kind classifies the message; --phase
+  // marks whether this is an intermediate progress update or the final
+  // visible response for the current turn.
+  const kind = getArg(args, 'kind');
+  const phase = getMessagePhaseArg(args);
+  if (phase && typeof phase === 'object') {
+    console.error(phase.error);
+    return 2;
+  }
+  const metadata = {};
+  if (kind) metadata.kind = kind;
+  if (phase) metadata.agent_response_phase = phase;
+
   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'),
+    allow_cross_target: Boolean(args['allow-cross-target']),
     media_asset_ids: mediaAssetIds.length > 0 ? mediaAssetIds : undefined,
+    metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
   };
   const res = await daemonRequest({
     method: 'POST',
@@ -217,7 +250,7 @@ export async function runTaskCreateCommand(args) {
   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("  ticlawk task create --target \"#frontend\" --title \"fix login\" --assign-agent <agent-id> <<'EOF'");
     console.error('  Detailed description goes here.');
     console.error('  EOF');
     return 2;
@@ -231,6 +264,7 @@ export async function runTaskCreateCommand(args) {
       conversation_id: conversationId,
       text: text.replace(/\n+$/, ''),
       title: getArg(args, 'title'),
+      assign_agent_id: getArg(args, 'assign-agent') || getArg(args, 'assignee-agent'),
     },
   });
   printJson(res.body);
@@ -310,6 +344,137 @@ export async function runTaskUpdateCommand(args) {
   return exitFromStatus(res.statusCode);
 }
 
+const GOAL_OUTCOMES = [
+  'gap', 'no_gap', 'wait',
+  'task_completed', 'needs_approval', 'blocked',
+  'accepted', 'rejected',
+];
+
+export async function runGoalReportCommand(args) {
+  const env = requireAgentEnv();
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  const transitionId = getArg(args, 'transition') || getArg(args, 'transition-id');
+  const outcome = getArg(args, 'outcome');
+  if (!conversationId) {
+    console.error('--conversation is required');
+    return 2;
+  }
+  if (!transitionId) {
+    console.error('--transition is required');
+    return 2;
+  }
+  if (!outcome || !GOAL_OUTCOMES.includes(outcome)) {
+    console.error(`--outcome must be one of: ${GOAL_OUTCOMES.join(', ')}`);
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/goal/report',
+    headers: commonHeaders(env),
+    body: {
+      conversation_id: conversationId,
+      transition_id: transitionId,
+      outcome,
+      detail: getArg(args, 'detail'),
+      current_task_id: getArg(args, 'current-task') || getArg(args, 'task-id'),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runGoalChangedCommand(args) {
+  const env = requireAgentEnv();
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  if (!conversationId) {
+    console.error('--conversation is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/goal/changed',
+    headers: commonHeaders(env),
+    body: { conversation_id: conversationId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runApprovalRequestCommand(args) {
+  const env = requireAgentEnv();
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  const title = getArg(args, 'title');
+  if (!conversationId) {
+    console.error('--conversation is required');
+    return 2;
+  }
+  if (!title) {
+    console.error('--title is required');
+    return 2;
+  }
+  const ttlRaw = getArg(args, 'ttl-seconds');
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/approval/request',
+    headers: commonHeaders(env),
+    body: {
+      conversation_id: conversationId,
+      title,
+      detail: getArg(args, 'detail'),
+      ttl_seconds: ttlRaw != null ? Number(ttlRaw) : undefined,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runApprovalResolveCommand(args) {
+  const env = requireAgentEnv();
+  const requestId = getArg(args, 'request') || getArg(args, 'request-id');
+  let decision = getArg(args, 'decision');
+  if (args.grant) decision = 'granted';
+  if (args.reject) decision = 'rejected';
+  if (!requestId) {
+    console.error('--request is required');
+    return 2;
+  }
+  if (decision !== 'granted' && decision !== 'rejected') {
+    console.error('--decision must be granted or rejected (or use --grant / --reject)');
+    return 2;
+  }
+  const confidenceRaw = getArg(args, 'confidence');
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/approval/resolve',
+    headers: commonHeaders(env),
+    body: {
+      request_id: requestId,
+      decision,
+      original_text: getArg(args, 'original-text'),
+      confidence: confidenceRaw != null ? Number(confidenceRaw) : undefined,
+      source_message_id: getArg(args, 'source-message-id'),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runApprovalListCommand(args) {
+  const env = requireAgentEnv();
+  const params = new URLSearchParams();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation') || getArg(args, 'conversation-id') || env.currentConversationId;
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/approval/list?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
 export async function runMessageReactCommand(args) {
   const env = requireAgentEnv();
   const messageId = getArg(args, 'message-id');
@@ -654,6 +819,11 @@ function inferContentType(filePath) {
     case '.jpg': case '.jpeg': return 'image/jpeg';
     case '.gif': return 'image/gif';
     case '.webp': return 'image/webp';
+    case '.mp4': return 'video/mp4';
+    case '.mov': return 'video/quicktime';
+    case '.m4v': return 'video/x-m4v';
+    case '.webm': return 'video/webm';
+    case '.html': case '.htm': return 'text/html';
     case '.pdf': return 'application/pdf';
     case '.txt': return 'text/plain';
     case '.md': return 'text/markdown';
@@ -800,6 +970,410 @@ export async function runGroupMembersCommand(args) {
   return exitFromStatus(res.statusCode);
 }
 
+export async function runWorkstreamCreateCommand(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] : [];
+  // Optional charter from stdin when --charter is supplied with no value
+  let charter = null;
+  if (args.charter === true) {
+    charter = await readStdin();
+  } else if (typeof args.charter === 'string') {
+    charter = args.charter;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/workstream/create',
+    headers: commonHeaders(env),
+    body: {
+      name,
+      description,
+      charter,
+      member_agent_ids: memberAgentIds.map((s) => String(s).trim()).filter(Boolean),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamDeleteCommand(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 res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/workstream/delete',
+    headers: commonHeaders(env),
+    body: { target, conversation_id: conversationId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamListCommand(args) {
+  const env = requireAgentEnv();
+  const res = await daemonRequest({
+    method: 'GET',
+    path: '/agent/workstream/list',
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runAgentListCommand(args) {
+  const env = requireAgentEnv();
+  const res = await daemonRequest({
+    method: 'GET',
+    path: '/agent/agent/list',
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runAgentCreateCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  const runtime = getArg(args, 'runtime');
+  if (!name) { console.error('--name is required'); return 2; }
+  if (!runtime) { console.error('--runtime is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/agent/create',
+    headers: commonHeaders(env),
+    body: {
+      name,
+      runtime,
+      description: getArg(args, 'description'),
+      display_name: getArg(args, 'display-name'),
+      model: getArg(args, 'model'),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runAgentDeleteCommand(args) {
+  const env = requireAgentEnv();
+  const agentId = getArg(args, 'agent-id');
+  if (!agentId) { console.error('--agent-id is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/agent/delete',
+    headers: commonHeaders(env),
+    body: { agent_id: agentId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+function readJsonFromFileOrInline(value) {
+  if (!value) return null;
+  // Accept either a path to a .json file or a raw JSON string.
+  try {
+    return JSON.parse(value);
+  } catch {}
+  try {
+    const fs = require('node:fs');
+    const txt = fs.readFileSync(value, 'utf8');
+    return JSON.parse(txt);
+  } catch (err) {
+    throw new Error(`could not parse JSON from ${value}: ${err?.message || err}`);
+  }
+}
+
+export async function runServiceCreateCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required'); return 2; }
+  const description = getArg(args, 'description');
+  let contractSchema = null;
+  let endpointConfig = null;
+  try {
+    const contractRaw = getArg(args, 'contract');
+    if (contractRaw) contractSchema = readJsonFromFileOrInline(contractRaw);
+    const endpointRaw = getArg(args, 'endpoint');
+    if (endpointRaw) endpointConfig = readJsonFromFileOrInline(endpointRaw);
+  } catch (err) {
+    console.error(err.message);
+    return 2;
+  }
+  if (!endpointConfig) { console.error('--endpoint <path-or-json> is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/create',
+    headers: commonHeaders(env),
+    body: { name, description, contract_schema: contractSchema, endpoint_config: endpointConfig },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceUpdateCommand(args) {
+  const env = requireAgentEnv();
+  const serviceId = getArg(args, 'service-id');
+  if (!serviceId) { console.error('--service-id is required'); return 2; }
+  const body = { service_id: serviceId };
+  if (getArg(args, 'description')) body.description = getArg(args, 'description');
+  if (getArg(args, 'contract')) body.contract_schema = readJsonFromFileOrInline(getArg(args, 'contract'));
+  if (getArg(args, 'endpoint')) body.endpoint_config = readJsonFromFileOrInline(getArg(args, 'endpoint'));
+  if (getArg(args, 'status')) body.status = getArg(args, 'status');
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/update',
+    headers: commonHeaders(env), body,
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceDeleteCommand(args) {
+  const env = requireAgentEnv();
+  const serviceId = getArg(args, 'service-id');
+  if (!serviceId) { console.error('--service-id is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/delete',
+    headers: commonHeaders(env),
+    body: { service_id: serviceId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceListCommand(args) {
+  const env = requireAgentEnv();
+  const res = await daemonRequest({
+    method: 'GET', path: '/agent/service/list',
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceInfoCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required'); return 2; }
+  const params = new URLSearchParams();
+  params.set('name', name);
+  const res = await daemonRequest({
+    method: 'GET', path: `/agent/service/info?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceCallCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required'); return 2; }
+  const inputText = await readStdin();
+  let input = null;
+  if (inputText && inputText.trim().length > 0) {
+    try {
+      input = JSON.parse(inputText);
+    } catch (err) {
+      console.error('stdin must be JSON for service call input');
+      return 2;
+    }
+  }
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/call',
+    headers: commonHeaders(env),
+    body: { name, input },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runBriefingGetCommand(args) {
+  const env = requireAgentEnv();
+  const id = args._[2] || getArg(args, 'id');
+  if (!id) { console.error('briefing id required (positional or --id)'); return 2; }
+  const params = new URLSearchParams();
+  params.set('id', id);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/briefing/get?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runBriefingPublishCommand(args) {
+  const env = requireAgentEnv();
+  const textArg = getArg(args, 'text');
+  const attachPath = getArg(args, 'attach');
+  const mode = String(getArg(args, 'mode') || 'info').trim().toLowerCase();
+  if (!textArg) {
+    console.error('--text "<short>" is required');
+    return 2;
+  }
+  if (textArg.length > 140) {
+    console.error('--text must be ≤140 chars');
+    return 2;
+  }
+  if (!['info', 'approval'].includes(mode)) {
+    console.error('--mode must be info or approval');
+    return 2;
+  }
+  let attachmentAssetId = null;
+  if (attachPath) {
+    const contentType = inferContentType(String(attachPath));
+    if (!contentType.startsWith('image/') && !contentType.startsWith('video/') && contentType !== 'text/html') {
+      console.error('--attach must be an image, video, or HTML file');
+      return 2;
+    }
+    const upload = await uploadFileViaDaemon(env, String(attachPath));
+    if (!upload.ok) {
+      console.error(`attachment upload failed for ${attachPath}: ${upload.error}`);
+      return 1;
+    }
+    attachmentAssetId = upload.assetId;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/briefing/publish',
+    headers: commonHeaders(env),
+    body: {
+      body_text: textArg,
+      attachment_asset_id: attachmentAssetId,
+      current_conversation_id: env.currentConversationId,
+      response_mode: mode,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runCredentialRequestCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required (e.g. GEMINI_API_KEY)'); return 2; }
+  const description = getArg(args, 'description');
+  const groupTarget = getArg(args, 'group') || getArg(args, 'workstream');
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/credential/request',
+    headers: commonHeaders(env),
+    body: {
+      name,
+      description,
+      target: groupTarget,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runDashboardSetCommand(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;
+  }
+  // Body is read from stdin as JSON: { data_json?, html_template? }
+  const stdinText = await readStdin();
+  let payload = {};
+  if (stdinText && stdinText.trim().length > 0) {
+    try {
+      payload = JSON.parse(stdinText);
+    } catch (err) {
+      console.error('stdin must be JSON: { data_json?, html_template? }');
+      return 2;
+    }
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/dashboard/set',
+    headers: commonHeaders(env),
+    body: {
+      target,
+      conversation_id: conversationId,
+      ...(('data_json' in payload) ? { data_json: payload.data_json } : {}),
+      ...(('html_template' in payload) ? { html_template: payload.html_template } : {}),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runDashboardGetCommand(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/dashboard/get?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamCharterGetCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id') || env.currentConversationId;
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required outside a delivered conversation');
+    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/workstream/charter/get?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamCharterSetCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id') || env.currentConversationId;
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required outside a delivered conversation');
+    return 2;
+  }
+  // Body from stdin (heredoc / pipe). Empty input clears the charter.
+  const charter = await readStdin();
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/workstream/charter/set',
+    headers: commonHeaders(env),
+    body: {
+      target,
+      conversation_id: conversationId,
+      charter: charter ?? '',
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
 export async function runServerInfoCommand(args) {
   const env = requireAgentEnv();
   const params = new URLSearchParams();
@@ -815,12 +1389,18 @@ export async function runServerInfoCommand(args) {
 
 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>] [--attach <file> ...]
+  ticlawk message send --target "<target>" [--phase progress|final] [--seen-up-to-seq N] [--reply-to <msg-id>] [--allow-cross-target] [--attach <file> ...] [--kind <kind>]
     Body is read from stdin (use <<'EOF' ... EOF for multiline).
+    During a delivered turn, sending to a different conversation is blocked
+      unless --allow-cross-target is passed deliberately.
+    --phase progress|final tags whether this is an intermediate update or
+      the final visible response after the current work/goal check is done.
+    --kind <kind> tags this message via metadata.kind.
     Targets:
-      dm:@<user>         private message
-      #<group>           group conversation
-      #<group>:<msgid>   thread under a top-level message in that group
+      dm:<conversation-id>  private message by conversation id
+      dm:@<user>            private message by user/agent handle
+      #<group>              group conversation by name or id
+      #<group>:<msgid>      replies under a top-level message in that group
     --attach <file> uploads a local file and attaches it to the message
       (repeatable; max 10 attachments per message).
   ticlawk message read --target "<target>" [--around <msg-id>] [--before-seq N] [--limit N]
@@ -832,7 +1412,11 @@ export const AGENT_COMMAND_HELP = {
     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>
+  profile: `ticlawk profile <list|current|use|show|update>
+  ticlawk profile list
+  ticlawk profile current
+  ticlawk profile use ticlawk:<user-id>
+
   ticlawk profile show [@handle | --id <agent-id>]
   ticlawk profile update [--display-name X] [--description Y] [--avatar-file path]
 `,
@@ -853,23 +1437,136 @@ export const AGENT_COMMAND_HELP = {
   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 create --target "<target>" [--title <t>] [--assign-agent <agent-id>]
+    Body is read from stdin. Creates a brand-new group task. Group admins
+    may assign it immediately to an agent member with --assign-agent.
   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>]
+    Only a group admin can set status=done. Other agents should set
+    in_review and let the group's admin finalize. A group admin can also
+    reopen another agent's in_review task to in_progress for redo.
+  ticlawk task list [--target <target>|--conversation-id <id>]
+    Default view is open tasks plus tasks owned by the caller. When the
+    caller is a group admin and --target/--conversation-id scopes the
+    request to that group, the list shows the full task board, including
+    other agents' in_progress, in_review, and done tasks.
+`,
+  workstream: `ticlawk workstream <create|delete|list|charter>
+    Compatibility alias for group admin commands. Prefer \`ticlawk group ...\`
+    for groups and \`ticlawk charter ...\` for conversation charters.
+`,
+  goal: `ticlawk goal <report|changed>
+    Goal-lane (FSM) control. Normally invoked from a goal-step turn, not by hand.
+  ticlawk goal report --transition <id> --outcome <outcome> [--conversation <id>] [--detail <text>] [--current-task <task-id>]
+    Report the outcome of the current FSM step and advance the state machine.
+    --conversation defaults to the current goal-turn conversation.
+    Outcomes by step:
+      gap_analysis: gap | no_gap | wait
+      execute:      task_completed | needs_approval | blocked
+      review:       accepted | rejected
+  ticlawk goal changed [--conversation <id>]
+    Signal that the conversation's goal changed; wakes the FSM into gap analysis.
+`,
+  approval: `ticlawk approval <request|resolve|list>
+    Canonical goal-loop approval flow. The goal lane parks on an approval and is
+    resumed by exactly one idempotent decision (button token OR chat resolver).
+  ticlawk approval request --title "<text>" [--conversation <id>] [--detail <text>] [--ttl-seconds <n>]
+    Park a pending owner approval on the goal_session (after EXECUTE reports
+    needs_approval). Returns request_id plus a one-time button action token.
+    --conversation defaults to the current goal-turn conversation.
+  ticlawk approval list [--conversation <id> | --target "<target>"]
+    List pending approval requests in the conversation. Use this from the chat
+    lane to find which request an owner's natural-language approval refers to.
+    --conversation defaults to the current conversation.
+  ticlawk approval resolve --request <id> (--grant | --reject | --decision granted|rejected) [--original-text <text>] [--confidence <0-1>] [--source-message-id <id>]
+    Resolve a pending approval from a natural-language chat decision (source=chat).
+    Idempotent: a second resolve (or a button tap) on the same request is a no-op.
+`,
+  charter: `ticlawk charter <get|set> [--target "<target>" | --conversation-id <id>]
+  ticlawk charter get [--target "<target>" | --conversation-id <id>]
+    Print the conversation charter. DM/group members can read.
+  ticlawk charter set [--target "<target>" | --conversation-id <id>]   # body via stdin
+    Replace the conversation charter. DM member agents can write their DM
+    charter; group writes require group admin/owner. Empty stdin clears it.
+    During a delivered turn, omitting target/conversation-id uses the
+    current conversation.
+`,
+  service: `ticlawk service <create|update|delete|list|info|call>
+  service create --name X --endpoint <path-or-json> [--description Y] [--contract <path-or-json>]
+    Any agent. Register a callable service. --endpoint takes either a
+    .json file path or a JSON string; same for --contract.
+    endpoint_config shape: { url, method?, headers? }.
+  service update --service-id <id> [--description Y] [--contract <json>] [--endpoint <json>] [--status <active|down|archived>]
+    Any agent.
+  service delete --service-id <id>
+    Any agent. Soft-archives.
+  service list
+    Any agent. Returns active services (no endpoint_config).
+  service info --name X
+    Any agent. Returns contract_schema + description.
+  service call --name X    # input from stdin (JSON)
+    Any agent. Backend proxies to endpoint_config.url. No retry.
+`,
+  briefing: `ticlawk briefing <publish|get>
+  briefing publish --text "..." [--mode info|approval] [--attach <image|video|html path>]
+    Publish a briefing to the owner's Briefings. Allowed from DMs, or
+    from groups where this agent is admin/owner.
+    --text  short plain text (≤140 chars)
+    --mode  owner response mode: info shows ack; approval shows approve
+    --attach optional image, video, or HTML file when visual context matters
+    Briefings are independent of chat — they do NOT appear in any DM
+    message stream. Use this verb (not \`message send\`) for any status
+    surface the owner consumes in Briefings.
+  briefing get <id>
+    Fetch a briefing including text and attachment metadata. Use this when a
+    quote (metadata.quote.kind=briefing) points at a briefing whose
+    full body you want to read.
+`,
+  credential: `ticlawk credential request --name <ENV_VAR> [--description Y] [--group "#<group>"]
+    Any agent. Pre-allocate a credential slot. Response includes a deep
+    link the user opens in the mobile app (Settings → Credentials)
+    to fill the value. Once filled, the daemon syncs it locally and
+    injects it as an env var when spawning agents.
+`,
+  dashboard: `ticlawk dashboard <set|get> (--target "<target>" | --conversation-id <id>)
+  dashboard set (--target "<target>" | --conversation-id <id>)   # body via stdin (JSON)
+    Allowed from DMs, or from groups where this agent is admin/owner.
+    stdin = { "data_json": ..., "html_template": "..." }.
+    Either field may be omitted (leaves unchanged) or null (clears).
+  dashboard get (--target "<target>" | --conversation-id <id>)
+    Conversation members can read.
+`,
+  agent: `ticlawk agent <list|create|delete>
+  agent list
+    Any agent. List all non-archived agents owned by the user, including
+    descriptions, runtime/status, and group memberships.
+  agent create --name X --runtime <claude_code|codex|opencode|openclaw|pi> [--description Y] [--display-name N] [--model M]
+    Any agent. Pre-allocate an agent slot (status='unpaired'). User
+    later pairs a runtime to fill it.
+  agent delete --agent-id <id>
+    Owner-only. Agent-facing deletion is disabled.
 `,
-  group: `ticlawk group <create|members>
+  group: `ticlawk group <create|list|delete|charter|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
+    Agent self-creates a new group. The agent is added as admin; 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>
+    member agents join as regular members and must belong to the same user
+    (RLS enforces).
+  ticlawk group list
+    List group conversations the caller belongs to, including agent members,
+    descriptions, charters, and dashboard presence.
+  ticlawk group delete --target "#<group>"
+    Group-admin only. Hard-delete the group (messages, members, deliveries).
+  ticlawk group charter get (--target "#<group>" | --conversation-id <id>)
+    Compatibility alias for \`ticlawk charter get\` on groups.
+  ticlawk group charter set (--target "#<group>" | --conversation-id <id>)   # body via stdin
+    Compatibility alias for \`ticlawk charter set\` on groups. Group-admin only.
+  ticlawk group members (--target "<target>" | --conversation-id <id>)
+  ticlawk group members (--target "<target>" | --conversation-id <id>) --add <agent-id> [--add <agent-id> ...]
+  ticlawk group members (--target "<target>" | --conversation-id <id>) --remove <agent-id>
+    Listing requires membership; add/remove requires group admin.
 `,
   server: `ticlawk server info [--refresh]
 `,