ticlawk 0.1.15 → 0.1.16-dev.2

package/src/core/agent-cli-handlers.mjs

@@ -0,0 +1,704 @@
+/**
+ * Daemon-side handlers for the agent CLI surface.
+ *
+ * The CLI subcommands (`ticlawk message send`, `ticlawk task claim`, ...)
+ * post to the local daemon at 127.0.0.1:8741. The daemon validates the
+ * caller's TICLAWK_RUNTIME_AGENT_ID against the active binding store
+ * and forwards to the ticlawk backend using the connector API key.
+ *
+ * Targets are parsed in the daemon (not on the wire to backend) so the
+ * CLI can speak `#<group>` / `dm:@<user>` / `#<group>:<short-msg-id>`
+ * while backend keeps a flat conversation_id contract.
+ */
+
+import { debugError, debugLog } from './logger.mjs';
+import * as api from '../adapters/ticlawk/api.mjs';
+
+const SERVER_INFO_CACHE_MS = 30 * 1000;
+const serverInfoCacheByAgent = new Map(); // agentId -> { ts, info }
+
+async function getCachedServerInfo(actingAgentId) {
+  const now = Date.now();
+  const cached = serverInfoCacheByAgent.get(actingAgentId);
+  if (cached && now - cached.ts < SERVER_INFO_CACHE_MS) {
+    return cached.info;
+  }
+  const info = await api.getAgentServerInfo({ actingAgentId });
+  serverInfoCacheByAgent.set(actingAgentId, { ts: now, info });
+  return info;
+}
+
+export function invalidateServerInfoCache(actingAgentId = null) {
+  if (actingAgentId) serverInfoCacheByAgent.delete(actingAgentId);
+  else serverInfoCacheByAgent.clear();
+}
+
+/**
+ * Parse a target string into { conversationId, threadRootMsgId } using a
+ * cached server-info lookup. Returns null fields if the target cannot be
+ * resolved; callers should treat that as a 404.
+ *
+ * Target syntax:
+ *   dm:<uuid>             -> conversation_id = <uuid>
+ *   dm:@<handle>          -> find DM conversation whose other member is <handle>
+ *   #<uuid>               -> conversation_id = <uuid>
+ *   #<group-name>         -> find group conversation by name
+ *   <foo>:<short-msg-id>  -> thread under <foo>, root = first message whose
+ *                            id startsWith <short-msg-id>
+ */
+export async function resolveTarget(actingAgentId, target) {
+  if (!target) return { conversationId: null, threadRootMsgId: null, error: 'target is required' };
+
+  // Strip optional thread suffix.
+  let base = target;
+  let threadShort = null;
+  const colonIdx = target.indexOf(':', target.startsWith('dm:') ? 3 : 1);
+  if (colonIdx > 0 && colonIdx < target.length - 1) {
+    threadShort = target.slice(colonIdx + 1);
+    base = target.slice(0, colonIdx);
+  }
+
+  if (/^[0-9a-f-]{36}$/i.test(base)) {
+    return { conversationId: base, threadRootMsgId: threadShort, error: null };
+  }
+  if (base.startsWith('dm:') && /^[0-9a-f-]{36}$/i.test(base.slice(3))) {
+    return { conversationId: base.slice(3), threadRootMsgId: threadShort, error: null };
+  }
+  if (base.startsWith('#') && /^[0-9a-f-]{36}$/i.test(base.slice(1))) {
+    return { conversationId: base.slice(1), threadRootMsgId: threadShort, error: null };
+  }
+
+  const info = await getCachedServerInfo(actingAgentId);
+  const convs = Array.isArray(info?.conversations) ? info.conversations : [];
+
+  if (base.startsWith('dm:@')) {
+    const handle = base.slice(4).toLowerCase();
+    const match = convs.find((c) =>
+      c.type === 'dm' && (String(c.display_name || c.name || '').toLowerCase() === handle)
+    );
+    if (match) return { conversationId: match.id, threadRootMsgId: threadShort, error: null };
+    return { conversationId: null, threadRootMsgId: null, error: `unknown dm target: ${target}` };
+  }
+  if (base.startsWith('#')) {
+    const name = base.slice(1).toLowerCase();
+    const match = convs.find((c) =>
+      c.type === 'group' && (String(c.name || c.display_name || '').toLowerCase() === name)
+    );
+    if (match) return { conversationId: match.id, threadRootMsgId: threadShort, error: null };
+    return { conversationId: null, threadRootMsgId: null, error: `unknown group target: ${target}` };
+  }
+
+  return { conversationId: null, threadRootMsgId: null, error: `invalid target syntax: ${target}` };
+}
+
+function getActingAgentId(req, body = {}) {
+  const fromHeader = req.headers['x-ticlawk-acting-agent-id'];
+  if (typeof fromHeader === 'string' && fromHeader.trim()) return fromHeader.trim();
+  if (typeof body?.acting_as_agent_id === 'string' && body.acting_as_agent_id.trim()) {
+    return body.acting_as_agent_id.trim();
+  }
+  return null;
+}
+
+function getRuntimeHostId(req, body = {}) {
+  const fromHeader = req.headers['x-ticlawk-runtime-host-id'];
+  if (typeof fromHeader === 'string' && fromHeader.trim()) return fromHeader.trim();
+  if (typeof body?.runtime_host_id === 'string' && body.runtime_host_id.trim()) {
+    return body.runtime_host_id.trim();
+  }
+  return null;
+}
+
+function validateActingAgent(actingAgentId, ctx) {
+  if (!actingAgentId) {
+    return { ok: false, status: 400, error: 'TICLAWK_RUNTIME_AGENT_ID required (passed via X-Ticlawk-Acting-Agent-Id or body.acting_as_agent_id)' };
+  }
+  if (typeof ctx.listBindings === 'function') {
+    const local = ctx.listBindings({ adapter: 'ticlawk' }) || [];
+    const match = local.find((b) => b?.id === actingAgentId);
+    if (!match) {
+      return { ok: false, status: 401, error: `agent ${actingAgentId} is not bound on this host` };
+    }
+  }
+  return { ok: true };
+}
+
+export async function handleMessageSend(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+
+  const text = String(body?.text || '').trim();
+  if (!text) return { status: 400, body: { error: 'text is required' } };
+
+  let conversationId = body?.conversation_id || null;
+  let threadRootMsgId = null;
+  if (!conversationId && body?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(body.target));
+    if (resolved.error) {
+      return { status: 404, body: { error: resolved.error } };
+    }
+    conversationId = resolved.conversationId;
+    threadRootMsgId = resolved.threadRootMsgId;
+  }
+  if (!conversationId) {
+    return { status: 400, body: { error: 'target or conversation_id is required' } };
+  }
+
+  try {
+    const data = await api.sendAgentMessage({
+      actingAgentId,
+      conversationId,
+      text,
+      seenUpToSeq: body?.seen_up_to_seq,
+      replyToMessageId: body?.reply_to_message_id || threadRootMsgId || null,
+      runtimeHostId: getRuntimeHostId(req, body),
+    });
+    debugLog('agent-cli', 'send.ok', {
+      actingAgentId,
+      conversationId,
+      messageId: data?.id,
+      seq: data?.seq,
+      bodyChars: text.length,
+    });
+    return { status: 200, body: { ok: true, data } };
+  } catch (err) {
+    debugError('agent-cli', 'send.failed', {
+      actingAgentId,
+      conversationId,
+      error: err?.message || String(err),
+      status: err?.status || null,
+    });
+    return { status: err?.status || 500, body: { error: err?.message || 'send failed', payload: err?.payload || null } };
+  }
+}
+
+export async function handleMessageRead(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+
+  let conversationId = query?.conversation_id || null;
+  if (!conversationId && query?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(query.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    conversationId = resolved.conversationId;
+  }
+  if (!conversationId) return { status: 400, body: { error: 'target or conversation_id is required' } };
+
+  try {
+    const data = await api.readAgentMessages({
+      actingAgentId,
+      conversationId,
+      aroundMessageId: query?.around_message_id || null,
+      beforeSeq: query?.before_seq != null ? Number(query.before_seq) : null,
+      limit: query?.limit != null ? Number(query.limit) : null,
+    });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'read failed' } };
+  }
+}
+
+export async function handleTaskCreate(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+
+  const text = String(body?.text || '').trim();
+  if (!text) return { status: 400, body: { error: 'text is required' } };
+
+  let conversationId = body?.conversation_id || null;
+  if (!conversationId && body?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(body.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    conversationId = resolved.conversationId;
+  }
+  if (!conversationId) {
+    return { status: 400, body: { error: 'target or conversation_id is required' } };
+  }
+
+  try {
+    const data = await api.createAgentTask({
+      actingAgentId,
+      conversationId,
+      text,
+      title: body?.title ?? null,
+    });
+    debugLog('agent-cli', 'task.create', {
+      actingAgentId,
+      conversationId,
+      messageId: data?.message?.id,
+      taskNumber: data?.task?.number,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    debugError('agent-cli', 'task.create.failed', {
+      actingAgentId,
+      conversationId,
+      error: err?.message || String(err),
+    });
+    return { status: err?.status || 500, body: { error: err?.message || 'task create failed' } };
+  }
+}
+
+export async function handleTaskClaim(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const sourceMessageId = body?.source_message_id || body?.message_id || null;
+  const number = body?.number != null ? Number(body.number) : null;
+
+  // Number-based claim needs the conversation_id to disambiguate. Allow
+  // the caller to pass either conversation_id directly or a target.
+  let conversationId = body?.conversation_id || null;
+  if (number != null && !conversationId && body?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(body.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    conversationId = resolved.conversationId;
+  }
+
+  if (!sourceMessageId && number == null) {
+    return { status: 400, body: { error: '--message-id or --number is required' } };
+  }
+  if (number != null && !conversationId) {
+    return { status: 400, body: { error: '--target or --conversation-id is required when claiming by number' } };
+  }
+
+  try {
+    const data = await api.claimAgentTask({
+      actingAgentId,
+      sourceMessageId,
+      conversationId,
+      number,
+      leaseSeconds: body?.lease_seconds,
+    });
+    debugLog('agent-cli', 'task.claim', {
+      actingAgentId,
+      sourceMessageId: sourceMessageId || null,
+      number: number ?? null,
+      conversationId: conversationId || null,
+      claimed: data?.claimed,
+      taskNumber: data?.task?.number || null,
+    });
+    return { status: data?.claimed === false ? 409 : 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'claim failed' } };
+  }
+}
+
+export async function handleTaskUnclaim(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.task_id) return { status: 400, body: { error: 'task_id is required' } };
+  try {
+    const data = await api.unclaimAgentTask({
+      actingAgentId,
+      taskId: body.task_id,
+    });
+    debugLog('agent-cli', 'task.unclaim', {
+      actingAgentId,
+      taskId: body.task_id,
+      ok: data?.ok,
+    });
+    return { status: data?.ok ? 200 : 409, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'unclaim failed' } };
+  }
+}
+
+export async function handleTaskUpdate(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.task_id) return { status: 400, body: { error: 'task_id is required' } };
+  try {
+    const data = await api.updateAgentTask({
+      actingAgentId,
+      taskId: body.task_id,
+      status: body.status || null,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'update failed' } };
+  }
+}
+
+export async function handleTaskList(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  let conversationId = query?.conversation_id || null;
+  if (!conversationId && query?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(query.target));
+    if (!resolved.error) conversationId = resolved.conversationId;
+  }
+  try {
+    const data = await api.listAgentTasks({ actingAgentId, conversationId });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'list failed' } };
+  }
+}
+
+export async function handleGroupMembers(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  let conversationId = query?.conversation_id || null;
+  if (!conversationId && query?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(query.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    conversationId = resolved.conversationId;
+  }
+  if (!conversationId) return { status: 400, body: { error: 'target or conversation_id is required' } };
+  try {
+    const res = await api.getConversationMembers({ actingAgentId, conversationId });
+    return { status: 200, body: res };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'members lookup failed' } };
+  }
+}
+
+export async function handleMessageReact(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const messageId = body?.message_id;
+  const emoji = body?.emoji;
+  const remove = !!body?.remove;
+  if (!messageId) return { status: 400, body: { error: 'message_id is required' } };
+  if (!emoji) return { status: 400, body: { error: 'emoji is required' } };
+  try {
+    const data = await api.reactToMessage({
+      actingAgentId, messageId, emoji, remove,
+    });
+    debugLog('agent-cli', remove ? 'message.unreact' : 'message.react', {
+      actingAgentId, messageId, emoji,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'react failed' } };
+  }
+}
+
+export async function handleReminderSchedule(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.title) return { status: 400, body: { error: 'title is required' } };
+  if (!body?.fire_at) return { status: 400, body: { error: 'fire_at (ISO timestamp) is required' } };
+
+  let anchorConversationId = body?.anchor_conversation_id || null;
+  if (!anchorConversationId && body?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(body.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    anchorConversationId = resolved.conversationId;
+  }
+  if (!anchorConversationId) {
+    return { status: 400, body: { error: '--target or --anchor-conversation-id required' } };
+  }
+
+  try {
+    const data = await api.scheduleAgentReminder({
+      actingAgentId,
+      title: body.title,
+      fireAt: body.fire_at,
+      anchorConversationId,
+      anchorMessageId: body?.anchor_message_id || null,
+    });
+    debugLog('agent-cli', 'reminder.schedule', {
+      actingAgentId,
+      reminderId: data?.data?.id,
+      fireAt: body.fire_at,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'schedule failed' } };
+  }
+}
+
+export async function handleReminderList(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  try {
+    const data = await api.listAgentReminders({
+      actingAgentId,
+      status: query?.status || null,
+    });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'list failed' } };
+  }
+}
+
+export async function handleReminderSnooze(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.reminder_id) return { status: 400, body: { error: 'reminder_id is required' } };
+  if (!body?.fire_at) return { status: 400, body: { error: 'fire_at is required' } };
+  try {
+    const data = await api.snoozeAgentReminder({
+      actingAgentId,
+      reminderId: body.reminder_id,
+      fireAt: body.fire_at,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'snooze failed' } };
+  }
+}
+
+export async function handleReminderUpdate(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.reminder_id) return { status: 400, body: { error: 'reminder_id is required' } };
+  try {
+    const data = await api.updateAgentReminder({
+      actingAgentId,
+      reminderId: body.reminder_id,
+      title: body?.title || null,
+      fireAt: body?.fire_at || null,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'update failed' } };
+  }
+}
+
+export async function handleReminderCancel(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.reminder_id) return { status: 400, body: { error: 'reminder_id is required' } };
+  try {
+    const data = await api.cancelAgentReminder({
+      actingAgentId,
+      reminderId: body.reminder_id,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'cancel failed' } };
+  }
+}
+
+export async function handleReminderLog(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!query?.reminder_id) return { status: 400, body: { error: 'reminder_id is required' } };
+  try {
+    const data = await api.getAgentReminderLog({
+      actingAgentId,
+      reminderId: query.reminder_id,
+    });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'log failed' } };
+  }
+}
+
+export async function handleMessageCheck(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  let conversationId = query?.conversation_id || null;
+  if (!conversationId && query?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(query.target));
+    if (!resolved.error) conversationId = resolved.conversationId;
+  }
+  try {
+    const data = await api.checkAgentMessages({ actingAgentId, conversationId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'check failed' } };
+  }
+}
+
+export async function handleMessageSearch(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!query?.q) return { status: 400, body: { error: 'q is required' } };
+  let conversationId = query?.conversation_id || null;
+  if (!conversationId && query?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(query.target));
+    if (!resolved.error) conversationId = resolved.conversationId;
+  }
+  try {
+    const data = await api.searchAgentMessages({
+      actingAgentId,
+      query: query.q,
+      conversationId,
+      limit: query?.limit != null ? Number(query.limit) : null,
+    });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'search failed' } };
+  }
+}
+
+export async function handleProfileShow(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const idOrHandle = query?.id || query?.handle || actingAgentId;
+  try {
+    const data = await api.getAgentProfile({ actingAgentId, idOrHandle });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'profile show failed' } };
+  }
+}
+
+export async function handleProfileUpdate(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  try {
+    const data = await api.patchAgentProfile({
+      actingAgentId,
+      displayName: body?.display_name ?? null,
+      description: body?.description ?? null,
+      avatarUrl: body?.avatar_url ?? null,
+    });
+    debugLog('agent-cli', 'profile.update', { actingAgentId, keys: Object.keys(body || {}) });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'profile update failed' } };
+  }
+}
+
+export async function handleAttachmentUpload(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  if (!body?.data_base64) return { status: 400, body: { error: 'data_base64 is required' } };
+  try {
+    const data = await api.uploadAgentAttachment({
+      actingAgentId,
+      filename: body?.filename || 'attachment.bin',
+      contentType: body?.content_type || 'application/octet-stream',
+      dataBase64: body.data_base64,
+    });
+    debugLog('agent-cli', 'attachment.upload', {
+      actingAgentId,
+      asset_id: data?.asset?.asset_id,
+      bytes: data?.asset?.size_bytes,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'attachment upload failed' } };
+  }
+}
+
+export async function handleAttachmentView(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const assetId = query?.asset_id;
+  if (!assetId) return { status: 400, body: { error: 'asset_id is required' } };
+  try {
+    const data = await api.viewAgentAttachment({ actingAgentId, assetId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'attachment view failed' } };
+  }
+}
+
+export async function handleGroupCreate(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const name = String(body?.name || '').trim();
+  if (!name) return { status: 400, body: { error: 'name is required' } };
+  try {
+    const data = await api.createAgentGroup({
+      actingAgentId,
+      name,
+      description: body?.description || null,
+      memberAgentIds: Array.isArray(body?.member_agent_ids) ? body.member_agent_ids : [],
+    });
+    invalidateServerInfoCache(actingAgentId);
+    debugLog('agent-cli', 'group.create', {
+      actingAgentId,
+      conversationId: data?.conversation?.id,
+      members: data?.member_agent_ids,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'group create failed' } };
+  }
+}
+
+export async function handleGroupMembersAdd(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  let conversationId = body?.conversation_id || null;
+  if (!conversationId && body?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(body.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    conversationId = resolved.conversationId;
+  }
+  if (!conversationId) return { status: 400, body: { error: 'target or conversation_id is required' } };
+  const agentIds = Array.isArray(body?.agent_ids) ? body.agent_ids : [];
+  if (agentIds.length === 0) return { status: 400, body: { error: 'agent_ids must be non-empty' } };
+  try {
+    const data = await api.addAgentGroupMembers({
+      actingAgentId, conversationId, agentIds,
+    });
+    invalidateServerInfoCache(actingAgentId);
+    debugLog('agent-cli', 'group.members.add', {
+      actingAgentId, conversationId, agentIds,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'add failed' } };
+  }
+}
+
+export async function handleGroupMembersRemove(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  let conversationId = body?.conversation_id || null;
+  if (!conversationId && body?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(body.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    conversationId = resolved.conversationId;
+  }
+  if (!conversationId) return { status: 400, body: { error: 'target or conversation_id is required' } };
+  const agentId = body?.agent_id;
+  if (!agentId) return { status: 400, body: { error: 'agent_id is required' } };
+  try {
+    const data = await api.removeAgentGroupMember({
+      actingAgentId, conversationId, agentId,
+    });
+    invalidateServerInfoCache(actingAgentId);
+    debugLog('agent-cli', 'group.members.remove', {
+      actingAgentId, conversationId, agentId,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'remove failed' } };
+  }
+}
+
+export async function handleServerInfo(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  // Bust cache when CLI explicitly asks
+  if (query?.refresh === '1') invalidateServerInfoCache(actingAgentId);
+  try {
+    const info = await getCachedServerInfo(actingAgentId);
+    return { status: 200, body: info };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'server-info failed' } };
+  }
+}