@controlflow-ai/daemon 0.1.2 → 0.1.4

package/src/cli.ts

@@ -1,32 +1,71 @@
 #!/usr/bin/env bun
 import { readFileSync, statSync } from 'node:fs';
-import { parseArgs, flag, numberFlag } from './args.js';
+import { basename, extname } from 'node:path';
+import { parseArgs, flag, flagValues, numberFlag } from './args.js';
+import { LockClient, type HeldDraftResolutionResult } from './client.js';
 import { DaemonClient } from './daemon-client.js';
-import { defaultDaemonUrl } from './config.js';
+import { defaultDaemonUrl, defaultServerUrl, defaultDbPath, defaultServerToken } from './config.js';
+import { MessageStore } from './db.js';
 import { formatMessages } from './format.js';
+import { runMessagingCommand } from './messaging-cli.js';
 import { sanitizeProviderIds } from './provider-identity.js';
+import type { HeldMessageDraft, MessageDelivery, RoomReminder, RoomReminderStatus, RoomSavedMessage, RoomTask, RoomTaskStatus, SkillBinding, SkillBindingScope, SkillDefinition, SkillSource, WorkflowRun, WorkflowRunRecord, WorkflowRunStatus } from './types.js';
+import { runWorkflowFile, type WorkflowAgentExecutionInput, type WorkflowAgentExecutionResult } from './workflow-runtime.js';
 
 function usage(): string {
   return `pal cli (agent CLI)
 
 Usage:
-  bun run src/cli.ts send --room general --from alice [--to codex] [--channel <channel-id>] <message>
+  bun run src/cli.ts send --room general --from alice [--mention codex ...] [--literal-mentions|--infer-mentions] [--channel <channel-id>] <message>
+  bun run src/cli.ts send --chat-id <room-id> --from alice [--mention codex ...] [--base-message-id <id> --hold-if-stale] [--attach <path> ...] <message>
+  bun run src/cli.ts send --chat-id <room-id> --from alice --stdin < message.md
   bun run src/cli.ts topics create --room general <name>
+  bun run src/cli.ts rooms handoff --from-room <room-id> --from <agent> --purpose <goal> [--source-message <id>] [--name <room>] [--team agent:mode ...] [--stdin]
   bun run src/cli.ts rooms invite --room general --agent codex [--mode mentions|all|periodic|muted|off]
+  bun run src/cli.ts rooms restart-agent --room general --agent codex [--json]
   bun run src/cli.ts debate start --chat general --a palbeta --b clawed [--turns 6] <topic>
   bun run src/cli.ts rooms list [--json]
   bun run src/cli.ts rooms members --room <room-id-or-name> [--json]
+  bun run src/cli.ts tasks list --chat-id <room-id> [--status all|todo|in_progress|in_review|done|closed] [--json]
+  bun run src/cli.ts tasks create --chat-id <room-id> [--from <agent-or-user>] <title> [title...]
+  bun run src/cli.ts tasks claim --chat-id <room-id> --tasks 1,2 [--assignee <agent>]
+  bun run src/cli.ts tasks unclaim --chat-id <room-id> --task 1
+  bun run src/cli.ts tasks status --chat-id <room-id> --task 1 --status in_review
+  bun run src/cli.ts reminders schedule --msg-id <message-id> --title <title> (--delay-seconds <seconds>|--fire-at <iso-time>) [--repeat daily|weekly|every:2h] [--json]
+  bun run src/cli.ts reminders list [--status scheduled|fired|canceled|all] [--created-by <agent>] [--chat-id <room-id>] [--json]
+  bun run src/cli.ts reminders cancel <reminder-id> [--json]
+  bun run src/cli.ts saved save --msg-id <message-id> [--from <agent-or-user>] [--note <note>] [--json]
+  bun run src/cli.ts saved list [--chat-id <room-id>] [--saved-by <agent-or-user>] [--json]
+  bun run src/cli.ts saved remove <saved-message-id> [--json]
+  bun run src/cli.ts drafts list [--agent <agent>] [--chat-id <room-id>] [--json]
+  bun run src/cli.ts drafts revise <draft-id> <message> [--json]
+  bun run src/cli.ts drafts stay-silent <draft-id> [--json]
+  bun run src/cli.ts drafts send-anyway <draft-id> [--json]
+  bun run src/cli.ts skills list [--source system|user|project] [--include-disabled] [--json]
+  bun run src/cli.ts skills create --key <key> --name <name> [--owner-user <id>] [--stdin|--instruction <text>] [--json]
+  bun run src/cli.ts skills edit --key <key> [--name <name>] [--status active|disabled] [--stdin|--instruction <text>] [--json]
+  bun run src/cli.ts skills bind --scope project|room|agent --scope-id <id> --skill <key> [--priority <n>] [--disabled] [--json]
+  bun run src/cli.ts skills unbind --scope project|room|agent --scope-id <id> --skill <key> [--json]
+  bun run src/cli.ts skills enabled [--project-id <id>] [--room-id <id>] [--agent <key>] [--json]
+  bun run src/cli.ts workflow run <file> [--goal <goal>] [--from <agent>] [--mock-agent-executor|--real-agent-executor --executor-agent <agent> --executor-room <room>] [--db <path>] [--json]
+  bun run src/cli.ts workflow list [--status running|completed|failed|all] [--db <path>] [--json]
+  bun run src/cli.ts workflow show <run-id> [--db <path>] [--json]
   bun run src/cli.ts messages list [--room general] [--topic 1] [--after 0] [--limit 50] [--q text] [--json]
   bun run src/cli.ts messages show <message-id> [--json]
   bun run src/cli.ts runs [--json]
   bun run src/cli.ts run-action <run-id> kill|restart
   bun run src/cli.ts chats [--json]
   bun run src/cli.ts health
+  bun run src/cli.ts messaging health [--json]
+  bun run src/cli.ts messaging status [--verbose] [--json]
+  bun run src/cli.ts messaging verify-lark-ingress [--app-id <id>] [--timeout-ms 60000] [--interval-ms 1000] [--json]
+  bun run src/cli.ts messaging probe-delivery [--agent lock] [--room <room>] [--timeout-ms 120000] [--json]
   bun run src/cli.ts http file <path> [--mime <type>] [--title <title>] [--ttl <seconds>]
 
 Environment:
   LOCK_DAEMON_URL=${defaultDaemonUrl()}
   LOCK_DAEMON_TOKEN=<token>
+  PAL_SERVER=${defaultServerUrl()}
 `;
 }
 
@@ -46,21 +85,427 @@ function printJson(value: unknown): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
+const MIME_BY_EXTENSION = new Map([
+  ['.csv', 'text/csv'],
+  ['.gif', 'image/gif'],
+  ['.htm', 'text/html'],
+  ['.html', 'text/html'],
+  ['.jpeg', 'image/jpeg'],
+  ['.jpg', 'image/jpeg'],
+  ['.json', 'application/json'],
+  ['.md', 'text/markdown'],
+  ['.pdf', 'application/pdf'],
+  ['.png', 'image/png'],
+  ['.txt', 'text/plain'],
+  ['.webp', 'image/webp'],
+  ['.zip', 'application/zip'],
+]);
+
+function mimeForPath(path: string, explicit?: string): string {
+  const override = explicit?.trim();
+  if (override) return override;
+  return MIME_BY_EXTENSION.get(extname(path).toLowerCase()) ?? 'application/octet-stream';
+}
+
+function attachmentKindForMime(mimeType: string): 'image' | 'file' {
+  return mimeType.toLowerCase().startsWith('image/') ? 'image' : 'file';
+}
+
+function loadSendAttachments(paths: string[], explicitMime?: string): Array<{ kind: 'image' | 'file'; mime_type: string; filename: string; content_base64: string }> | undefined {
+  if (paths.length === 0) return undefined;
+  return paths.map((path) => {
+    const stat = statSync(path);
+    if (!stat.isFile()) throw new Error(`--attach path is not a file: ${path}`);
+    const mimeType = mimeForPath(path, explicitMime);
+    return {
+      kind: attachmentKindForMime(mimeType),
+      mime_type: mimeType,
+      filename: basename(path),
+      content_base64: Buffer.from(readFileSync(path)).toString('base64'),
+    };
+  });
+}
+
 function looksLikeId(value: string): boolean {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
 
+function roomNameFromPurpose(purpose: string): string {
+  const slug = purpose
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+  return `handoff-${slug || Date.now().toString(36)}`;
+}
+
+function parseTeamFlags(values: string[]): Array<{ agent: string; mode?: 'all' | 'periodic' | 'mentions' | 'muted' | 'off' }> | undefined {
+  if (!values.length) return undefined;
+  return values.map((value) => {
+    const [agent, mode] = value.split(':');
+    if (!agent?.trim()) throw new Error('--team requires agent or agent:mode');
+    if (mode && !['all', 'periodic', 'mentions', 'muted', 'off'].includes(mode)) {
+      throw new Error('--team mode must be all, periodic, mentions, muted, or off');
+    }
+    return { agent: agent.trim(), mode: mode as 'all' | 'periodic' | 'mentions' | 'muted' | 'off' | undefined };
+  });
+}
+
 function buildDebateOpening(input: { topic: string; firstAgent: string; secondAgent: string; turns: number; chat: string }): string {
   return [
     'Start an agent-to-agent debate in this room.',
     `Debate topic: ${input.topic}`,
     `Participants: @${input.firstAgent} and @${input.secondAgent}.`,
     `Turn budget: ${input.turns} total agent turns.`,
-    `You are @${input.firstAgent}. Make the first argument, then send the next turn to @${input.secondAgent} with: bun run src/cli.ts send --chat ${input.chat} --from ${input.firstAgent} --to ${input.secondAgent} <message>`,
-    `Every later turn should address the other agent with --to so their daemon runtime is triggered. Stop naturally when the turn budget is reached.`,
+    `You are @${input.firstAgent}. Make the first argument, then send the next turn to @${input.secondAgent} with: bun run src/cli.ts send --chat ${input.chat} --from ${input.firstAgent} --mention ${input.secondAgent} <message>`,
+    `Every later turn should mention the other agent with --mention so their daemon runtime is triggered. Stop naturally when the turn budget is reached.`,
   ].join('\n');
 }
 
+function taskRoomRef(args: ReturnType<typeof parseArgs>): string {
+  const room = flag(args.flags, 'chat-id')
+    ?? flag(args.flags, 'room-id')
+    ?? flag(args.flags, 'room')
+    ?? flag(args.flags, 'chat');
+  if (!room) throw new Error('tasks command requires --chat-id <room-id> or --room <room>');
+  return room;
+}
+
+function taskActor(args: ReturnType<typeof parseArgs>, kind: 'creator' | 'assignee'): string {
+  const value = kind === 'assignee'
+    ? flag(args.flags, 'assignee') ?? flag(args.flags, 'agent') ?? flag(args.flags, 'from') ?? flag(args.flags, 'sender')
+    : flag(args.flags, 'created-by') ?? flag(args.flags, 'from') ?? flag(args.flags, 'sender') ?? flag(args.flags, 'agent');
+  return value?.trim() || process.env.PAL_AGENT || process.env.USER || 'human';
+}
+
+function taskNumbers(args: ReturnType<typeof parseArgs>): number[] {
+  const rawValues = [
+    flag(args.flags, 'tasks'),
+    flag(args.flags, 'task'),
+    flag(args.flags, 'task-number'),
+    ...args.values.slice(1),
+  ].filter((value): value is string => Boolean(value));
+  const numbers = rawValues
+    .flatMap((value) => value.split(','))
+    .map((value) => Number(value.trim()))
+    .filter((value) => Number.isInteger(value) && value > 0);
+  if (!numbers.length) throw new Error('tasks command requires --task <number> or --tasks <numbers>');
+  return Array.from(new Set(numbers));
+}
+
+function formatTasks(tasks: RoomTask[]): string {
+  return tasks.map((task) => [
+    `#${task.task_number}`,
+    `[${task.status}]`,
+    sanitizeProviderIds(task.title),
+    task.assignee ? `@${sanitizeProviderIds(task.assignee)}` : '',
+  ].filter(Boolean).join(' ')).join('\n');
+}
+
+function reminderActor(args: ReturnType<typeof parseArgs>): string {
+  return flag(args.flags, 'created-by')
+    ?? flag(args.flags, 'from')
+    ?? flag(args.flags, 'sender')
+    ?? flag(args.flags, 'agent')
+    ?? process.env.PAL_AGENT
+    ?? process.env.USER
+    ?? 'human';
+}
+
+function formatReminders(reminders: RoomReminder[]): string {
+  return reminders.map((reminder) => [
+    reminder.id,
+    `[${reminder.status}]`,
+    sanitizeProviderIds(reminder.title),
+    `room=${sanitizeProviderIds(reminder.room_name || reminder.room_id)}`,
+    `fire=${reminder.fire_at}`,
+    reminder.repeat ? `repeat=${sanitizeProviderIds(reminder.repeat)}` : '',
+    reminder.created_by ? `from=${sanitizeProviderIds(reminder.created_by)}` : '',
+  ].filter(Boolean).join(' ')).join('\n');
+}
+
+function savedActor(args: ReturnType<typeof parseArgs>): string {
+  return flag(args.flags, 'saved-by')
+    ?? flag(args.flags, 'from')
+    ?? flag(args.flags, 'sender')
+    ?? flag(args.flags, 'agent')
+    ?? process.env.PAL_AGENT
+    ?? process.env.USER
+    ?? 'human';
+}
+
+function formatSavedMessages(savedMessages: RoomSavedMessage[]): string {
+  return savedMessages.map((savedMessage) => [
+    savedMessage.id,
+    `msg #${savedMessage.message_id}`,
+    sanitizeProviderIds(savedMessage.message_content),
+    `room=${sanitizeProviderIds(savedMessage.room_name || savedMessage.room_id)}`,
+    `by=${sanitizeProviderIds(savedMessage.saved_by)}`,
+    savedMessage.note ? `note=${sanitizeProviderIds(savedMessage.note)}` : '',
+  ].filter(Boolean).join(' ')).join('\n');
+}
+
+function draftActor(args: ReturnType<typeof parseArgs>): string {
+  return flag(args.flags, 'agent')
+    ?? flag(args.flags, 'from')
+    ?? flag(args.flags, 'sender')
+    ?? process.env.PAL_AGENT
+    ?? '';
+}
+
+function formatHeldDrafts(drafts: HeldMessageDraft[]): string {
+  return drafts.map((draft) => [
+    draft.id,
+    `[${draft.status}]`,
+    `room=${sanitizeProviderIds(draft.chat_name || draft.chat_id)}`,
+    `base=#${draft.base_message_id}`,
+    `intervening=${draft.intervening_message_count}`,
+    sanitizeProviderIds(draft.content).replace(/\s+/g, ' ').trim().slice(0, 180),
+  ].filter(Boolean).join(' ')).join('\n');
+}
+
+function formatWorkflowRuns(runs: WorkflowRun[]): string {
+  return runs.map((run) => [
+    run.id,
+    `[${run.status}]`,
+    sanitizeProviderIds(run.goal ?? run.file_path),
+    `nodes-final=${run.final_output ? 'yes' : 'no'}`,
+    `updated=${run.updated_at}`,
+  ].join(' ')).join('\n');
+}
+
+function formatSkills(skills: SkillDefinition[]): string {
+  if (!skills.length) return 'No skills.';
+  return skills.map((skill) => [
+    skill.key,
+    `[${skill.status}]`,
+    `source=${skill.source}`,
+    skill.owner_user_id ? `owner=${sanitizeProviderIds(skill.owner_user_id)}` : '',
+    skill.project_id ? `project=${sanitizeProviderIds(skill.project_id)}` : '',
+    sanitizeProviderIds(skill.name),
+    skill.repository_path ? `path=${sanitizeProviderIds(skill.repository_path)}` : '',
+  ].filter(Boolean).join(' ')).join('\n');
+}
+
+function formatSkillBindings(bindings: SkillBinding[]): string {
+  if (!bindings.length) return 'No skill bindings.';
+  return bindings.map((binding) => [
+    `${binding.scope}:${sanitizeProviderIds(binding.scope_id)}`,
+    binding.skill_key,
+    binding.enabled ? 'enabled' : 'disabled',
+    `priority=${binding.priority}`,
+  ].join(' ')).join('\n');
+}
+
+function parseSkillScopeFlag(value: string | undefined): SkillBindingScope {
+  if (value !== 'project' && value !== 'room' && value !== 'agent') throw new Error('skill scope must be project, room, or agent');
+  return value;
+}
+
+function parseSkillSourceFlag(value: string | undefined): SkillSource | undefined {
+  if (!value) return undefined;
+  if (value !== 'system' && value !== 'user' && value !== 'project') throw new Error('skill source must be system, user, or project');
+  return value;
+}
+
+function formatWorkflowRunRecord(record: WorkflowRunRecord): string {
+  const lines = [
+    `${record.run.id} [${record.run.status}] ${sanitizeProviderIds(record.run.goal ?? record.run.file_path)}`,
+  ];
+  for (const node of record.nodes) {
+    const role = node.role ? ` role=${sanitizeProviderIds(node.role)}` : '';
+    const parent = node.parent_id ? ` parent=${node.parent_id}` : '';
+    const evidence = node.evidence ? ' evidence=yes' : '';
+    lines.push(`- ${node.kind} [${node.status}] ${sanitizeProviderIds(node.title)}${role}${parent}${evidence}`);
+  }
+  if (record.run.final_output) {
+    lines.push(`final=${sanitizeProviderIds(JSON.stringify(record.run.final_output))}`);
+  }
+  if (record.run.error) {
+    lines.push(`error=${sanitizeProviderIds(record.run.error)}`);
+  }
+  return lines.join('\n');
+}
+
+function mockWorkflowAgentExecutor(input: WorkflowAgentExecutionInput): WorkflowAgentExecutionResult {
+  return {
+    output: {
+      role: input.role,
+      summary: `Mock ${input.role} completed: ${input.instruction}`,
+      recommendation: input.role === 'evaluator' ? 'ship with verification' : 'produce a concise plan',
+    },
+    evidence: {
+      executor: 'mock',
+      node_id: input.nodeId,
+      capabilities: input.capabilities ?? [],
+    },
+  };
+}
+
+function isTerminalDeliveryStatus(status: MessageDelivery['status']): boolean {
+  return status === 'acked' || status === 'failed' || status === 'canceled';
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function realWorkflowAgentExecutor(input: {
+  serverUrl?: string;
+  daemonUrl?: string;
+  agent?: string;
+  room?: string;
+  sender?: string;
+  timeoutMs?: number;
+  intervalMs?: number;
+}): (node: WorkflowAgentExecutionInput) => Promise<WorkflowAgentExecutionResult> {
+  const client = new LockClient(input.serverUrl);
+  const timeoutMs = input.timeoutMs ?? 120_000;
+  const intervalMs = input.intervalMs ?? 1_000;
+  return async (node) => {
+    const token = crypto.randomUUID();
+    const agent = input.agent?.trim() || node.role;
+    const room = input.room?.trim() || `workflow-runtime-${agent}`;
+    const content = [
+      `PAL workflow real runtime node ${token}.`,
+      `Role: ${node.role}`,
+      `Title: ${node.title}`,
+      `Instruction: ${node.instruction}`,
+      `Output contract: ${JSON.stringify(node.outputContract ?? {})}`,
+      `Reply with a concise result and include workflow-ok ${token}.`,
+    ].join('\n');
+    if (!defaultServerToken()) {
+      const daemon = new DaemonClient(input.daemonUrl);
+      const roomRef = looksLikeId(room) ? { chat_id: room } : { chat: room };
+      const sent = await daemon.sendMessageResult({
+        ...roomRef,
+        sender: input.sender?.trim() || 'pal-workflow',
+        recipient: agent,
+        content,
+        mentions: [agent],
+        idempotency_key: `pal.workflow.node:${node.runId}:${node.nodeId}:${token}`,
+      });
+      if (!sent.message) throw new Error('REAL_WORKFLOW_LOCAL_SEND_FAILED');
+      let replies = [] as Awaited<ReturnType<DaemonClient['getMessages']>>;
+      const startedAt = Date.now();
+      while (Date.now() - startedAt < timeoutMs) {
+        const params = new URLSearchParams({ q: token, limit: '20' });
+        if (looksLikeId(room)) params.set('chat_id', room);
+        else params.set('chat', room);
+        replies = (await daemon.getMessages(params)).filter((message) => message.id !== sent.message!.id);
+        if (replies.length > 0) break;
+        await sleep(Math.min(intervalMs, Math.max(1, timeoutMs - (Date.now() - startedAt))));
+      }
+      if (replies.length === 0) throw new Error('REAL_WORKFLOW_LOCAL_REPLY_TIMEOUT');
+      const firstReply = replies[0]!;
+      return {
+        output: {
+          role: node.role,
+          agent,
+          room,
+          summary: firstReply.content,
+          ...(node.role === 'evaluator' ? { recommendation: 'ship with verification' } : {}),
+          delivery_status: sent.deliveries?.length ? 'created' : 'unknown',
+          reply_count: replies.length,
+          reply: firstReply.content,
+        },
+        evidence: {
+          executor: 'pal-local-message',
+          token,
+          message_id: sent.message.id,
+          delivery_ids: sent.deliveries?.map((delivery) => delivery.id) ?? [],
+          notify: sent.notify ?? null,
+          reply_message_ids: replies.map((reply) => reply.id),
+        },
+      };
+    }
+    const created = await client.probeDelivery({
+      agent,
+      room,
+      sender: input.sender?.trim() || 'pal-workflow',
+      content,
+      idempotencyKey: `pal.workflow.node:${node.runId}:${node.nodeId}:${token}`,
+    });
+    const deliveryIds = created.deliveries.map((delivery) => delivery.id);
+    let deliveries = created.deliveries;
+    const startedAt = Date.now();
+    while (deliveryIds.length > 0 && Date.now() - startedAt < timeoutMs) {
+      deliveries = await Promise.all(deliveryIds.map((id) => client.getDelivery(id)));
+      if (deliveries.every((delivery) => isTerminalDeliveryStatus(delivery.status))) break;
+      await sleep(Math.min(intervalMs, Math.max(1, timeoutMs - (Date.now() - startedAt))));
+    }
+    if (deliveryIds.length === 0) throw new Error('REAL_WORKFLOW_EXECUTOR_NO_DELIVERY');
+    const pending = deliveries.find((delivery) => !isTerminalDeliveryStatus(delivery.status));
+    if (pending) throw new Error(`REAL_WORKFLOW_EXECUTOR_TIMEOUT: delivery ${pending.id} status=${pending.status}`);
+    const failed = deliveries.find((delivery) => delivery.status !== 'acked');
+    if (failed) throw new Error(`REAL_WORKFLOW_EXECUTOR_DELIVERY_FAILED: delivery ${failed.id} status=${failed.status}`);
+
+    const params = new URLSearchParams({ chat: created.probe.room, q: token, limit: '20' });
+    const replies = (await client.getMessages(params)).filter((message) => message.id !== created.message.id);
+    const firstReply = replies[0] ?? null;
+    return {
+      output: {
+        role: node.role,
+        agent,
+        room: created.probe.room,
+        summary: firstReply?.content ?? `Delivery acked by ${agent}`,
+        ...(node.role === 'evaluator' ? { recommendation: 'ship with verification' } : {}),
+        delivery_status: 'acked',
+        reply_count: replies.length,
+        reply: firstReply?.content ?? null,
+      },
+      evidence: {
+        executor: 'pal-delivery',
+        token,
+        message_id: created.message.id,
+        delivery_ids: deliveryIds,
+        run_ids: deliveries.map((delivery) => delivery.run_id).filter(Boolean),
+        reply_message_ids: replies.map((reply) => reply.id),
+      },
+    };
+  };
+}
+
+function printHeldDraftResolution(result: HeldDraftResolutionResult, json: boolean): void {
+  if (json) {
+    printJson(result);
+    return;
+  }
+  if (result.message) {
+    console.log(formatMessages([result.message]));
+    return;
+  }
+  console.log(formatHeldDrafts([result.draft]));
+}
+
+function mentionFlags(flags: ReturnType<typeof parseArgs>['flags']): string[] {
+  const values = [
+    ...flagValues(flags, 'mention'),
+    ...flagValues(flags, 'mentions').flatMap((value) => value.split(',')),
+    ...flagValues(flags, 'to'),
+    ...flagValues(flags, 'recipient'),
+  ];
+  const seen = new Set<string>();
+  const mentions: string[] = [];
+  for (const value of values) {
+    const trimmed = value.trim().replace(/^@/, '');
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    mentions.push(trimmed);
+  }
+  return mentions;
+}
+
+function mentionLintMode(flags: ReturnType<typeof parseArgs>['flags']): 'strict' | 'literal' | 'infer' {
+  if (flags['infer-mentions']) return 'infer';
+  if (flags['literal-mentions'] || flags['no-mention-lint']) return 'literal';
+  return 'strict';
+}
+
+function mentionDisplayForCli(mention: string): string {
+  return mention === '__pal_all_agents__' ? 'all' : mention;
+}
+
 async function main(): Promise<void> {
   const args = parseArgs();
   const daemonClient = new DaemonClient(flag(args.flags, 'daemon'));
@@ -75,6 +520,12 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (args.command === 'messaging') {
+    const serverClient = new LockClient(flag(args.flags, 'server'));
+    await runMessagingCommand(serverClient, args, usage);
+    return;
+  }
+
   if (args.command === 'chats') {
     const chats = await daemonClient.listChats();
     if (args.flags.json) {
@@ -100,6 +551,31 @@ async function main(): Promise<void> {
       }
       return;
     }
+    if (sub === 'handoff') {
+      const sourceRoomId = flag(args.flags, 'from-room') ?? flag(args.flags, 'source-room') ?? flag(args.flags, 'chat-id') ?? flag(args.flags, 'room-id');
+      const actor = flag(args.flags, 'from') ?? flag(args.flags, 'agent') ?? process.env.PAL_AGENT;
+      const purpose = flag(args.flags, 'purpose') ?? flag(args.flags, 'goal') ?? args.values.slice(1).join(' ');
+      if (!sourceRoomId) throw new Error('rooms handoff requires --from-room <room-id>');
+      if (!actor) throw new Error('rooms handoff requires --from <agent>');
+      if (!purpose?.trim()) throw new Error('rooms handoff requires --purpose <goal>');
+      const handoffContent = args.flags.stdin ? await readStdin() : flag(args.flags, 'context') ?? '';
+      const result = await daemonClient.createHandoffRoom({
+        source_room_id: sourceRoomId,
+        source_message_id: numberFlag(args.flags, 'source-message') ?? numberFlag(args.flags, 'source-message-id'),
+        actor,
+        purpose,
+        name: flag(args.flags, 'name') ?? roomNameFromPurpose(purpose),
+        team: parseTeamFlags(flagValues(args.flags, 'team')),
+        handoff_content: handoffContent,
+      });
+      if (args.flags.json) {
+        printJson(result);
+      } else {
+        console.log(`#${result.room.name} (${result.room.id}) created by @${sanitizeProviderIds(actor)}`);
+        if (result.message) console.log(`handoff message #${result.message.id}`);
+      }
+      return;
+    }
     if (sub === 'invite') {
       const roomRef = flag(args.flags, 'room') ?? args.values[1];
       const agent = flag(args.flags, 'agent') ?? args.values[2];
@@ -125,9 +601,193 @@ async function main(): Promise<void> {
       }
       return;
     }
+    if (sub === 'restart-agent') {
+      const roomRef = flag(args.flags, 'room') ?? flag(args.flags, 'chat-id') ?? args.values[1];
+      const agent = flag(args.flags, 'agent') ?? args.values[2];
+      if (!roomRef) throw new Error('rooms restart-agent requires --room <room-id-or-name>');
+      if (!agent) throw new Error('rooms restart-agent requires --agent <agent-key>');
+      const run = await daemonClient.restartRoomAgent(roomRef, agent);
+      if (args.flags.json) {
+        printJson(run);
+      } else {
+        console.log(`restart requested for @${sanitizeProviderIds(agent)} in ${roomRef}: run=${run.id} status=${run.status}`);
+      }
+      return;
+    }
     throw new Error(`unknown rooms subcommand: ${sub}`);
   }
 
+  if (args.command === 'tasks') {
+    const sub = args.values[0] ?? 'list';
+    const roomRef = taskRoomRef(args);
+    if (sub === 'list') {
+      const tasks = await daemonClient.listRoomTasks(
+        roomRef,
+        (flag(args.flags, 'status') ?? 'all') as RoomTaskStatus | 'all',
+        numberFlag(args.flags, 'limit', 50),
+      );
+      if (args.flags.json) printJson(tasks);
+      else console.log(formatTasks(tasks));
+      return;
+    }
+    if (sub === 'create') {
+      const titles = args.values.slice(1).map((value) => value.trim()).filter(Boolean);
+      const titleFlag = flag(args.flags, 'title');
+      if (titleFlag) titles.unshift(titleFlag);
+      if (!titles.length) throw new Error('tasks create requires at least one title');
+      const tasks = await daemonClient.createRoomTasks(roomRef, {
+        created_by: taskActor(args, 'creator'),
+        tasks: titles.map((title) => ({ title })),
+      });
+      if (args.flags.json) printJson(tasks);
+      else console.log(formatTasks(tasks));
+      return;
+    }
+    if (sub === 'claim') {
+      const assignee = taskActor(args, 'assignee');
+      const tasks: RoomTask[] = [];
+      for (const taskNumber of taskNumbers(args)) {
+        tasks.push(await daemonClient.claimRoomTask(roomRef, taskNumber, { assignee }));
+      }
+      if (args.flags.json) printJson(tasks);
+      else console.log(formatTasks(tasks));
+      return;
+    }
+    if (sub === 'unclaim') {
+      const [taskNumber] = taskNumbers(args);
+      const task = await daemonClient.unclaimRoomTask(roomRef, taskNumber!);
+      if (args.flags.json) printJson(task);
+      else console.log(formatTasks([task]));
+      return;
+    }
+    if (sub === 'status') {
+      const [taskNumber] = taskNumbers(args);
+      const status = flag(args.flags, 'status') as RoomTaskStatus | undefined;
+      if (!status) throw new Error('tasks status requires --status <status>');
+      const task = await daemonClient.updateRoomTaskStatus(roomRef, taskNumber!, status);
+      if (args.flags.json) printJson(task);
+      else console.log(formatTasks([task]));
+      return;
+    }
+    throw new Error(`unknown tasks subcommand: ${sub}`);
+  }
+
+  if (args.command === 'reminders') {
+    const sub = args.values[0] ?? 'list';
+    if (sub === 'schedule') {
+      const messageIdFlag = numberFlag(args.flags, 'msg-id') ?? numberFlag(args.flags, 'message-id');
+      const msgId = messageIdFlag ?? Number(args.values[1]);
+      if (!Number.isInteger(msgId) || msgId < 1) throw new Error('reminders schedule requires --msg-id <message-id>');
+      const title = flag(args.flags, 'title') ?? positionalContent(args.values.slice(messageIdFlag === undefined ? 2 : 1));
+      if (!title) throw new Error('reminders schedule requires --title <title>');
+      const fireAt = flag(args.flags, 'fire-at');
+      const delaySeconds = numberFlag(args.flags, 'delay-seconds');
+      if (!fireAt && delaySeconds === undefined) throw new Error('reminders schedule requires --delay-seconds <seconds> or --fire-at <iso-time>');
+      const reminder = await daemonClient.scheduleReminder({
+        msg_id: msgId,
+        title,
+        created_by: reminderActor(args),
+        fire_at: fireAt,
+        delay_seconds: delaySeconds,
+        repeat: flag(args.flags, 'repeat'),
+      });
+      if (args.flags.json) printJson(reminder);
+      else console.log(formatReminders([reminder]));
+      return;
+    }
+    if (sub === 'list') {
+      const reminders = await daemonClient.listReminders({
+        status: (flag(args.flags, 'status') ?? 'scheduled') as RoomReminderStatus | 'all',
+        created_by: flag(args.flags, 'created-by'),
+        room_id: flag(args.flags, 'chat-id') ?? flag(args.flags, 'room-id'),
+        limit: numberFlag(args.flags, 'limit', 50),
+      });
+      if (args.flags.json) printJson(reminders);
+      else console.log(formatReminders(reminders));
+      return;
+    }
+    if (sub === 'cancel') {
+      const reminderId = args.values[1] ?? flag(args.flags, 'id');
+      if (!reminderId) throw new Error('reminders cancel requires <reminder-id>');
+      const reminder = await daemonClient.cancelReminder(reminderId);
+      if (args.flags.json) printJson(reminder);
+      else console.log(formatReminders([reminder]));
+      return;
+    }
+    throw new Error(`unknown reminders subcommand: ${sub}`);
+  }
+
+  if (args.command === 'saved') {
+    const sub = args.values[0] ?? 'list';
+    if (sub === 'save') {
+      const messageIdFlag = numberFlag(args.flags, 'msg-id') ?? numberFlag(args.flags, 'message-id');
+      const msgId = messageIdFlag ?? Number(args.values[1]);
+      if (!Number.isInteger(msgId) || msgId < 1) throw new Error('saved save requires --msg-id <message-id>');
+      const savedMessage = await daemonClient.saveMessage({
+        msg_id: msgId,
+        saved_by: savedActor(args),
+        note: flag(args.flags, 'note') ?? null,
+      });
+      if (args.flags.json) printJson(savedMessage);
+      else console.log(formatSavedMessages([savedMessage]));
+      return;
+    }
+    if (sub === 'list') {
+      const savedMessages = await daemonClient.listSavedMessages({
+        saved_by: flag(args.flags, 'saved-by'),
+        room_id: flag(args.flags, 'chat-id') ?? flag(args.flags, 'room-id'),
+        limit: numberFlag(args.flags, 'limit', 50),
+      });
+      if (args.flags.json) printJson(savedMessages);
+      else console.log(formatSavedMessages(savedMessages));
+      return;
+    }
+    if (sub === 'remove' || sub === 'delete') {
+      const savedMessageId = args.values[1] ?? flag(args.flags, 'id');
+      if (!savedMessageId) throw new Error('saved remove requires <saved-message-id>');
+      const savedMessage = await daemonClient.removeSavedMessage(savedMessageId);
+      if (args.flags.json) printJson(savedMessage);
+      else console.log(formatSavedMessages([savedMessage]));
+      return;
+    }
+    throw new Error(`unknown saved subcommand: ${sub}`);
+  }
+
+  if (args.command === 'drafts' || args.command === 'held-drafts') {
+    const sub = args.values[0] ?? 'list';
+    if (sub === 'list') {
+      const drafts = await daemonClient.listHeldDrafts({
+        agent: draftActor(args),
+        room_id: flag(args.flags, 'chat-id') ?? flag(args.flags, 'room-id'),
+        status: (flag(args.flags, 'status') ?? 'held') as never,
+        limit: numberFlag(args.flags, 'limit', 50),
+      });
+      if (args.flags.json) printJson(drafts);
+      else console.log(formatHeldDrafts(drafts));
+      return;
+    }
+
+    const draftId = args.values[1] ?? flag(args.flags, 'id');
+    if (!draftId) throw new Error(`drafts ${sub} requires <draft-id>`);
+    if (sub === 'revise') {
+      const inlineContent = flag(args.flags, 'content') ?? positionalContent(args.values.slice(2));
+      const stdinContent = !inlineContent && !process.stdin.isTTY ? (await readStdin()).trim() : '';
+      const content = inlineContent || stdinContent;
+      if (!content) throw new Error('drafts revise requires a revised message');
+      printHeldDraftResolution(await daemonClient.reviseHeldDraft(draftId, content), Boolean(args.flags.json));
+      return;
+    }
+    if (sub === 'stay-silent' || sub === 'abandon') {
+      printHeldDraftResolution(await daemonClient.staySilentHeldDraft(draftId), Boolean(args.flags.json));
+      return;
+    }
+    if (sub === 'send-anyway') {
+      printHeldDraftResolution(await daemonClient.sendHeldDraftAnyway(draftId), Boolean(args.flags.json));
+      return;
+    }
+    throw new Error(`unknown drafts subcommand: ${sub}`);
+  }
+
   if (args.command === 'runs') {
     const runs = await daemonClient.listRuns();
     if (args.flags.json) {
@@ -166,8 +826,8 @@ async function main(): Promise<void> {
     const message = await daemonClient.sendMessage({
       chat,
       sender: 'debate',
-      recipient: firstAgent,
       content: buildDebateOpening({ topic, firstAgent, secondAgent, turns, chat }),
+      mentions: [firstAgent],
     });
 
     if (args.flags.json) {
@@ -212,31 +872,230 @@ async function main(): Promise<void> {
 
   if (args.command === 'send') {
     const file = flag(args.flags, 'file');
+    const attachments = loadSendAttachments(flagValues(args.flags, 'attach'), flag(args.flags, 'attach-mime') ?? flag(args.flags, 'mime'));
+    const useStdin = Boolean(args.flags.stdin);
     const inlineContent = positionalContent(args.values);
-    const fileContent = !inlineContent && file ? readFileSync(file, 'utf8').trim() : '';
-    const stdinContent = !inlineContent && !fileContent && !process.stdin.isTTY ? (await readStdin()).trim() : '';
+    if (useStdin && inlineContent) throw new Error('send --stdin cannot be combined with a positional message');
+    if (useStdin && file) throw new Error('send --stdin cannot be combined with --file');
+    const fileContent = !inlineContent && !useStdin && file ? readFileSync(file, 'utf8') : '';
+    const stdinContent = !inlineContent && !fileContent && (useStdin || !process.stdin.isTTY) ? await readStdin() : '';
     const content = inlineContent || fileContent || stdinContent;
     const sender = flag(args.flags, 'from') ?? flag(args.flags, 'sender') ?? process.env.USER ?? 'human';
-    if (!content) throw new Error('message content is required');
+    const baseMessageId = numberFlag(args.flags, 'base-message-id') ?? numberFlag(args.flags, 'freshness-base-message-id');
+    const holdIfStale = Boolean(args.flags['hold-if-stale']);
+    const sendAnywayIfStale = Boolean(args.flags['send-anyway-if-stale']);
+    if (!content.trim() && !attachments?.length) throw new Error('message content or --attach is required');
+    if (holdIfStale && sendAnywayIfStale) throw new Error('choose only one of --hold-if-stale or --send-anyway-if-stale');
+    if ((holdIfStale || sendAnywayIfStale) && baseMessageId === undefined) throw new Error('--base-message-id is required with stale-message handling');
+    const freshness = baseMessageId === undefined
+      ? undefined
+      : { base_message_id: baseMessageId, on_stale: sendAnywayIfStale ? 'send_anyway' as const : 'hold' as const };
 
-    const message = await daemonClient.sendMessage({
+    const result = await daemonClient.sendMessageResult({
       chat: flag(args.flags, 'room') ?? flag(args.flags, 'chat') ?? 'general',
       room: flag(args.flags, 'room'),
+      chat_id: flag(args.flags, 'chat-id') ?? flag(args.flags, 'room-id'),
+      room_id: flag(args.flags, 'room-id'),
       parent_id: numberFlag(args.flags, 'parent'),
       channel_id: flag(args.flags, 'channel') ?? flag(args.flags, 'channel-id') ?? null,
       sender,
-      recipient: flag(args.flags, 'to') ?? flag(args.flags, 'recipient'),
       content,
+      freshness,
+      mentions: mentionFlags(args.flags),
+      mention_lint: mentionLintMode(args.flags),
+      attachments,
     });
 
-    if (args.flags.json) {
-      printJson(message);
+    if (result.mention_lint?.missing_mentions?.length) {
+      if (args.flags.json) {
+        printJson(result);
+      } else {
+        const missing = result.mention_lint.missing_mentions.map(mentionDisplayForCli);
+        console.error(result.mention_lint.message);
+        console.error(`Re-run with ${missing.map((mention) => `--mention ${mention}`).join(' ')}, or pass --literal-mentions if this is only quoted text.`);
+        const available = result.mention_lint.available_mentions?.length ? result.mention_lint.available_mentions.join(', ') : '(none)';
+        console.error(`Available agent mention keys for this room: ${available}`);
+      }
+      process.exitCode = 1;
+    } else if (result.invalid_mentions?.length) {
+      if (args.flags.json) {
+        printJson(result);
+      } else {
+        const available = result.available_mentions?.length ? result.available_mentions.join(', ') : '(none)';
+        console.error(`Invalid mention key(s): ${result.invalid_mentions.join(', ')}`);
+        console.error(`Available mention keys for this room: ${available}`);
+      }
+      process.exitCode = 1;
+    } else if (args.flags.json) {
+      printJson(result);
+    } else if (result.message) {
+      console.log(formatMessages([result.message]));
+    } else if (result.draft) {
+      console.log(`Held draft ${result.draft.id} for #${result.draft.chat_name}.`);
+      console.log(`Room changed after message ${result.draft.base_message_id}; ${result.intervening_messages?.length ?? result.draft.intervening_message_count} intervening message(s) were returned.`);
+      for (const message of result.intervening_messages ?? []) {
+        console.log(`- #${message.id} @${sanitizeProviderIds(message.sender)}: ${sanitizeProviderIds(message.content).replace(/\s+/g, ' ').trim().slice(0, 160)}`);
+      }
     } else {
-      console.log(formatMessages([message]));
+      console.log('Message send completed without a visible message.');
     }
     return;
   }
 
+  if (args.command === 'skills') {
+    const sub = args.values[0] ?? 'list';
+    const store = new MessageStore(flag(args.flags, 'db') ?? defaultDbPath());
+    try {
+      if (sub === 'list') {
+        const skills = store.listSkillDefinitions({
+          source: parseSkillSourceFlag(flag(args.flags, 'source')),
+          includeDisabled: Boolean(args.flags['include-disabled']),
+          ownerUserId: flag(args.flags, 'owner-user') ?? undefined,
+          projectId: flag(args.flags, 'project-id') ?? undefined,
+        });
+        const bindings = store.listSkillBindings({
+          scope: flag(args.flags, 'scope') ? parseSkillScopeFlag(flag(args.flags, 'scope')) : undefined,
+          scopeId: flag(args.flags, 'scope-id') ?? undefined,
+        });
+        const warning = 'PAL-managed skills are injected by PAL. Native runtime-discovered global skills may still be loaded by Codex/OpenCode and may not be fully blockable from PAL.';
+        if (args.flags.json) printJson({ skills, bindings, native_runtime_warning: warning });
+        else {
+          console.log(warning);
+          console.log(formatSkills(skills));
+          if (bindings.length) {
+            console.log('');
+            console.log(formatSkillBindings(bindings));
+          }
+        }
+        return;
+      }
+      if (sub === 'create') {
+        const instruction = args.flags.stdin ? await readStdin() : flag(args.flags, 'instruction') ?? positionalContent(args.values.slice(1));
+        const skill = store.createSkillDefinition({
+          key: flag(args.flags, 'key') ?? '',
+          name: flag(args.flags, 'name') ?? '',
+          description: flag(args.flags, 'description') ?? '',
+          instructionContent: instruction,
+          source: parseSkillSourceFlag(flag(args.flags, 'source')) ?? 'user',
+          ownerUserId: flag(args.flags, 'owner-user') ?? flag(args.flags, 'owner-user-id') ?? 'owner',
+          projectId: flag(args.flags, 'project-id') ?? null,
+          repositoryPath: flag(args.flags, 'repository-path') ?? null,
+        });
+        if (args.flags.json) printJson(skill);
+        else console.log(formatSkills([skill]));
+        return;
+      }
+      if (sub === 'edit') {
+        const key = flag(args.flags, 'key') ?? args.values[1];
+        if (!key) throw new Error('skills edit requires --key <key>');
+        const instruction = args.flags.stdin ? await readStdin() : flag(args.flags, 'instruction');
+        const status = flag(args.flags, 'status');
+        if (status && status !== 'active' && status !== 'disabled') throw new Error('skill status must be active or disabled');
+        const skill = store.updateSkillDefinition(key, {
+          name: flag(args.flags, 'name'),
+          description: flag(args.flags, 'description'),
+          instructionContent: instruction,
+          status: status as SkillDefinition['status'] | undefined,
+          repositoryPath: flag(args.flags, 'repository-path') ?? undefined,
+        });
+        if (args.flags.json) printJson(skill);
+        else console.log(formatSkills([skill]));
+        return;
+      }
+      if (sub === 'bind') {
+        const binding = store.upsertSkillBinding({
+          scope: parseSkillScopeFlag(flag(args.flags, 'scope')),
+          scopeId: flag(args.flags, 'scope-id') ?? '',
+          skillKey: flag(args.flags, 'skill') ?? flag(args.flags, 'skill-key') ?? '',
+          enabled: !args.flags.disabled,
+          priority: numberFlag(args.flags, 'priority'),
+        });
+        if (args.flags.json) printJson(binding);
+        else console.log(formatSkillBindings([binding]));
+        return;
+      }
+      if (sub === 'unbind') {
+        const deleted = store.deleteSkillBinding({
+          scope: parseSkillScopeFlag(flag(args.flags, 'scope')),
+          scopeId: flag(args.flags, 'scope-id') ?? '',
+          skillKey: flag(args.flags, 'skill') ?? flag(args.flags, 'skill-key') ?? '',
+        });
+        if (args.flags.json) printJson({ deleted });
+        else console.log(deleted ? 'Skill binding removed.' : 'No matching skill binding.');
+        return;
+      }
+      if (sub === 'enabled') {
+        const skills = store.listEnabledSkills({
+          projectId: flag(args.flags, 'project-id') ?? null,
+          roomId: flag(args.flags, 'room-id') ?? flag(args.flags, 'chat-id') ?? null,
+          agent: flag(args.flags, 'agent') ?? null,
+        });
+        if (args.flags.json) printJson(skills);
+        else console.log(formatSkills(skills));
+        return;
+      }
+      throw new Error(`unknown skills subcommand: ${sub}`);
+    } finally {
+      store.close();
+    }
+  }
+
+  if (args.command === 'workflow' || args.command === 'workflows') {
+    const sub = args.values[0] ?? 'list';
+    const store = new MessageStore(flag(args.flags, 'db') ?? defaultDbPath());
+    try {
+      if (sub === 'run') {
+        const filePath = args.values[1] ?? flag(args.flags, 'file');
+        if (!filePath) throw new Error('workflow run requires <file>');
+        if (args.flags['mock-agent-executor'] && args.flags['real-agent-executor']) {
+          throw new Error('choose only one of --mock-agent-executor or --real-agent-executor');
+        }
+        const record = await runWorkflowFile(store, {
+          filePath,
+          goal: flag(args.flags, 'goal') ?? null,
+          createdBy: flag(args.flags, 'from') ?? flag(args.flags, 'created-by') ?? process.env.PAL_AGENT ?? process.env.USER ?? null,
+          executor: args.flags['mock-agent-executor']
+            ? mockWorkflowAgentExecutor
+            : args.flags['real-agent-executor']
+              ? realWorkflowAgentExecutor({
+                  serverUrl: flag(args.flags, 'server'),
+                  daemonUrl: flag(args.flags, 'daemon'),
+                  agent: flag(args.flags, 'executor-agent') ?? flag(args.flags, 'agent'),
+                  room: flag(args.flags, 'executor-room') ?? flag(args.flags, 'room') ?? flag(args.flags, 'chat'),
+                  sender: flag(args.flags, 'executor-sender') ?? flag(args.flags, 'from'),
+                  timeoutMs: numberFlag(args.flags, 'timeout-ms', 120_000),
+                  intervalMs: numberFlag(args.flags, 'interval-ms', 1_000),
+                })
+              : undefined,
+        });
+        if (args.flags.json) printJson(record);
+        else console.log(formatWorkflowRunRecord(record));
+        return;
+      }
+      if (sub === 'list') {
+        const runs = store.listWorkflowRuns({
+          status: (flag(args.flags, 'status') ?? 'all') as WorkflowRunStatus | 'all',
+          limit: numberFlag(args.flags, 'limit', 50),
+        });
+        if (args.flags.json) printJson(runs);
+        else console.log(formatWorkflowRuns(runs));
+        return;
+      }
+      if (sub === 'show') {
+        const runId = args.values[1] ?? flag(args.flags, 'run-id') ?? flag(args.flags, 'id');
+        if (!runId) throw new Error('workflow show requires <run-id>');
+        const record = store.getWorkflowRunRecord(runId);
+        if (!record) throw new Error(`workflow run ${runId} was not found`);
+        if (args.flags.json) printJson(record);
+        else console.log(formatWorkflowRunRecord(record));
+        return;
+      }
+      throw new Error(`unknown workflow subcommand: ${sub}`);
+    } finally {
+      store.close();
+    }
+  }
+
   if (args.command === 'messages') {
     const sub = args.values[0];
     if (sub === 'show') {