ticlawk 0.1.16-dev.9 → 0.1.16

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

@@ -7,7 +7,8 @@
  * 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>`
+ * CLI can speak `#<group>` / `dm:<conversation-id>` / `dm:@<user>` /
+ * `#<group>:<short-msg-id>`
  * while backend keeps a flat conversation_id contract.
  */
 
@@ -34,7 +35,7 @@ export function invalidateServerInfoCache(actingAgentId = null) {
 }
 
 /**
- * Parse a target string into { conversationId, threadRootMsgId } using a
+ * Parse a target string into { conversationId, replyToMessageId } using a
  * cached server-info lookup. Returns null fields if the target cannot be
  * resolved; callers should treat that as a 404.
  *
@@ -43,29 +44,29 @@ export function invalidateServerInfoCache(actingAgentId = null) {
  *   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
+ *   <foo>:<short-msg-id>  -> replies 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' };
+  if (!target) return { conversationId: null, replyToMessageId: null, error: 'target is required' };
 
-  // Strip optional thread suffix.
+  // Strip optional message-reply suffix.
   let base = target;
-  let threadShort = null;
+  let replyToMessageId = null;
   const colonIdx = target.indexOf(':', target.startsWith('dm:') ? 3 : 1);
   if (colonIdx > 0 && colonIdx < target.length - 1) {
-    threadShort = target.slice(colonIdx + 1);
+    replyToMessageId = target.slice(colonIdx + 1);
     base = target.slice(0, colonIdx);
   }
 
   if (/^[0-9a-f-]{36}$/i.test(base)) {
-    return { conversationId: base, threadRootMsgId: threadShort, error: null };
+    return { conversationId: base, replyToMessageId, error: null };
   }
   if (base.startsWith('dm:') && /^[0-9a-f-]{36}$/i.test(base.slice(3))) {
-    return { conversationId: base.slice(3), threadRootMsgId: threadShort, error: null };
+    return { conversationId: base.slice(3), replyToMessageId, error: null };
   }
   if (base.startsWith('#') && /^[0-9a-f-]{36}$/i.test(base.slice(1))) {
-    return { conversationId: base.slice(1), threadRootMsgId: threadShort, error: null };
+    return { conversationId: base.slice(1), replyToMessageId, error: null };
   }
 
   const info = await getCachedServerInfo(actingAgentId);
@@ -76,19 +77,30 @@ export async function resolveTarget(actingAgentId, target) {
     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 (match) return { conversationId: match.id, replyToMessageId, error: null };
+    return { conversationId: null, replyToMessageId: 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}` };
+    if (match) return { conversationId: match.id, replyToMessageId, error: null };
+
+    if (info?.agent?.is_cos) {
+      const workstreams = await api.listWorkstreams({ actingAgentId });
+      const workstreamMatch = workstreams.find((c) =>
+        String(c.name || c.display_name || '').toLowerCase() === name
+      );
+      if (workstreamMatch) {
+        return { conversationId: workstreamMatch.id, replyToMessageId, error: null };
+      }
+    }
+
+    return { conversationId: null, replyToMessageId: null, error: `unknown group target: ${target}` };
   }
 
-  return { conversationId: null, threadRootMsgId: null, error: `invalid target syntax: ${target}` };
+  return { conversationId: null, replyToMessageId: null, error: `invalid target syntax: ${target}` };
 }
 
 function getActingAgentId(req, body = {}) {
@@ -109,6 +121,15 @@ function getRuntimeHostId(req, body = {}) {
   return null;
 }
 
+function getCurrentConversationId(req, body = {}) {
+  const fromHeader = req.headers['x-ticlawk-current-conversation-id'];
+  if (typeof fromHeader === 'string' && fromHeader.trim()) return fromHeader.trim();
+  if (typeof body?.current_conversation_id === 'string' && body.current_conversation_id.trim()) {
+    return body.current_conversation_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)' };
@@ -123,6 +144,16 @@ function validateActingAgent(actingAgentId, ctx) {
   return { ok: true };
 }
 
+function validateAgentResponsePhase(metadata) {
+  const phase = metadata?.agent_response_phase;
+  if (phase == null) return { ok: true, phase: null };
+  const normalized = String(phase).trim().toLowerCase();
+  if (normalized === 'progress' || normalized === 'final') {
+    return { ok: true, phase: normalized };
+  }
+  return { ok: false, error: 'metadata.agent_response_phase must be progress or final' };
+}
+
 export async function handleMessageSend(req, body, ctx) {
   const actingAgentId = getActingAgentId(req, body);
   const v = validateActingAgent(actingAgentId, ctx);
@@ -132,22 +163,45 @@ export async function handleMessageSend(req, body, ctx) {
   if (!text) return { status: 400, body: { error: 'text is required' } };
 
   let conversationId = body?.conversation_id || null;
-  let threadRootMsgId = null;
+  let targetReplyToMessageId = 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;
+    targetReplyToMessageId = resolved.replyToMessageId;
   }
   if (!conversationId) {
     return { status: 400, body: { error: 'target or conversation_id is required' } };
   }
 
+  const currentConversationId = getCurrentConversationId(req, body);
+  if (currentConversationId && currentConversationId !== conversationId && !body?.allow_cross_target) {
+    debugLog('agent-cli', 'send.blocked-cross-target', {
+      actingAgentId,
+      currentConversationId,
+      conversationId,
+      target: body?.target || null,
+    });
+    return {
+      status: 409,
+      body: {
+        error: 'refusing to send to a different conversation from the current runtime turn',
+        current_conversation_id: currentConversationId,
+        target_conversation_id: conversationId,
+        hint: 'Use --allow-cross-target only for an intentional cross-conversation send.',
+      },
+    };
+  }
+
   const mediaAssetIds = Array.isArray(body?.media_asset_ids)
     ? body.media_asset_ids.map((v) => String(v).trim()).filter(Boolean)
     : [];
+  const metadata = body?.metadata;
+  const phaseRes = validateAgentResponsePhase(metadata);
+  if (!phaseRes.ok) return { status: 400, body: { error: phaseRes.error } };
+  if (metadata && phaseRes.phase) metadata.agent_response_phase = phaseRes.phase;
 
   try {
     const data = await api.sendAgentMessage({
@@ -155,15 +209,17 @@ export async function handleMessageSend(req, body, ctx) {
       conversationId,
       text,
       seenUpToSeq: body?.seen_up_to_seq,
-      replyToMessageId: body?.reply_to_message_id || threadRootMsgId || null,
+      replyToMessageId: body?.reply_to_message_id || targetReplyToMessageId || null,
       runtimeHostId: getRuntimeHostId(req, body),
       mediaAssetIds,
+      metadata,
     });
     debugLog('agent-cli', 'send.ok', {
       actingAgentId,
       conversationId,
       messageId: data?.id,
       seq: data?.seq,
+      agentResponsePhase: phaseRes.phase,
       bodyChars: text.length,
     });
     return { status: 200, body: { ok: true, data } };
@@ -229,6 +285,7 @@ export async function handleTaskCreate(req, body, ctx) {
       conversationId,
       text,
       title: body?.title ?? null,
+      assignAgentId: body?.assign_agent_id || body?.assignee_agent_id || null,
     });
     debugLog('agent-cli', 'task.create', {
       actingAgentId,
@@ -716,6 +773,366 @@ export async function handleGroupMembersRemove(req, body, ctx) {
   }
 }
 
+export async function handleWorkstreamCreate(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.createWorkstream({
+      actingAgentId,
+      name,
+      description: body?.description || null,
+      charter: body?.charter ?? null,
+      memberAgentIds: Array.isArray(body?.member_agent_ids) ? body.member_agent_ids : [],
+    });
+    invalidateServerInfoCache(actingAgentId);
+    debugLog('agent-cli', 'workstream.create', {
+      actingAgentId, conversationId: data?.conversation?.id,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'workstream create failed' } };
+  }
+}
+
+export async function handleWorkstreamDelete(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' } };
+  try {
+    const data = await api.deleteWorkstream({ actingAgentId, conversationId });
+    invalidateServerInfoCache(actingAgentId);
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'workstream delete failed' } };
+  }
+}
+
+export async function handleWorkstreamList(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.listWorkstreams({ actingAgentId });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'workstream list failed' } };
+  }
+}
+
+export async function handleAgentList(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.listAgentSlots({ actingAgentId });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'agent list failed' } };
+  }
+}
+
+export async function handleAgentCreate(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();
+  const runtime = String(body?.runtime || '').trim();
+  if (!name) return { status: 400, body: { error: 'name is required' } };
+  if (!runtime) return { status: 400, body: { error: 'runtime is required' } };
+  try {
+    const data = await api.createAgentSlot({
+      actingAgentId,
+      name,
+      runtime,
+      description: body?.description || null,
+      displayName: body?.display_name || null,
+      model: body?.model || null,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'agent create failed' } };
+  }
+}
+
+export async function handleAgentDelete(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 agentId = String(body?.agent_id || '').trim();
+  if (!agentId) return { status: 400, body: { error: 'agent_id is required' } };
+  try {
+    const data = await api.archiveAgentSlot({ actingAgentId, agentId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'agent delete failed' } };
+  }
+}
+
+export async function handleServiceCreate(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' } };
+  if (!body?.endpoint_config || typeof body.endpoint_config !== 'object') {
+    return { status: 400, body: { error: 'endpoint_config is required' } };
+  }
+  try {
+    const data = await api.createService({
+      actingAgentId, name,
+      description: body?.description || null,
+      contractSchema: body?.contract_schema ?? null,
+      endpointConfig: body.endpoint_config,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'service create failed' } };
+  }
+}
+
+export async function handleServiceUpdate(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 serviceId = String(body?.service_id || '').trim();
+  if (!serviceId) return { status: 400, body: { error: 'service_id is required' } };
+  const patch = {};
+  if ('description' in (body || {})) patch.description = body.description;
+  if ('contract_schema' in (body || {})) patch.contract_schema = body.contract_schema;
+  if ('endpoint_config' in (body || {})) patch.endpoint_config = body.endpoint_config;
+  if ('status' in (body || {})) patch.status = body.status;
+  try {
+    const data = await api.updateService({ actingAgentId, serviceId, ...patch });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'service update failed' } };
+  }
+}
+
+export async function handleServiceDelete(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 serviceId = String(body?.service_id || '').trim();
+  if (!serviceId) return { status: 400, body: { error: 'service_id is required' } };
+  try {
+    const data = await api.deleteService({ actingAgentId, serviceId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'service delete failed' } };
+  }
+}
+
+export async function handleServiceList(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.listServices({ actingAgentId });
+    return { status: 200, body: { data } };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'service list failed' } };
+  }
+}
+
+export async function handleServiceInfo(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 name = String(query?.name || '').trim();
+  if (!name) return { status: 400, body: { error: 'name is required' } };
+  try {
+    const data = await api.getServiceInfo({ actingAgentId, name });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'service info failed' } };
+  }
+}
+
+export async function handleServiceCall(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.callService({
+      actingAgentId, name,
+      input: body?.input ?? null,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'service call failed' } };
+  }
+}
+
+export async function handleBriefingGet(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 briefingId = String(query?.id || '').trim();
+  if (!briefingId) return { status: 400, body: { error: 'id is required' } };
+  try {
+    const data = await api.getBriefing({ actingAgentId, briefingId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'briefing get failed' } };
+  }
+}
+
+export async function handleBriefingPublish(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 bodyText = typeof body?.body_text === 'string' && body.body_text.trim() ? body.body_text.trim() : null;
+  const attachmentAssetId = typeof body?.attachment_asset_id === 'string' && body.attachment_asset_id.trim()
+    ? body.attachment_asset_id.trim()
+    : null;
+  const responseMode = typeof body?.response_mode === 'string' && body.response_mode.trim()
+    ? body.response_mode.trim().toLowerCase()
+    : 'info';
+  if (!bodyText) {
+    return { status: 400, body: { error: 'body_text is required' } };
+  }
+  if (bodyText && bodyText.length > 140) {
+    return { status: 400, body: { error: 'body_text must be ≤140 chars' } };
+  }
+  if (!['info', 'approval'].includes(responseMode)) {
+    return { status: 400, body: { error: 'response_mode must be info or approval' } };
+  }
+  const currentConversationId = getCurrentConversationId(req, body);
+  try {
+    const data = await api.publishBriefing({
+      actingAgentId,
+      bodyText,
+      attachmentAssetId,
+      currentConversationId,
+      responseMode,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'briefing publish failed' } };
+  }
+}
+
+export async function handleCredentialRequest(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' } };
+  let workstreamId = body?.workstream_id || null;
+  if (!workstreamId && body?.target) {
+    const resolved = await resolveTarget(actingAgentId, String(body.target));
+    if (resolved.error) return { status: 404, body: { error: resolved.error } };
+    workstreamId = resolved.conversationId;
+  }
+  try {
+    const data = await api.requestCredential({
+      actingAgentId,
+      name,
+      description: body?.description || null,
+      workstreamId,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'credential request failed' } };
+  }
+}
+
+export async function handleWorkstreamDashboardSet(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 payload = { actingAgentId, conversationId };
+  if ('data_json' in (body || {})) payload.dataJson = body.data_json;
+  if ('html_template' in (body || {})) payload.htmlTemplate = body.html_template;
+  try {
+    const data = await api.setWorkstreamDashboard(payload);
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'dashboard set failed' } };
+  }
+}
+
+export async function handleWorkstreamDashboardGet(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.getWorkstreamDashboard({ actingAgentId, conversationId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'dashboard get failed' } };
+  }
+}
+
+export async function handleWorkstreamCharterGet(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.getWorkstreamCharter({ actingAgentId, conversationId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'charter get failed' } };
+  }
+}
+
+export async function handleWorkstreamCharterSet(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 charter = typeof body?.charter === 'string' ? body.charter : null;
+  try {
+    const data = await api.setWorkstreamCharter({ actingAgentId, conversationId, charter });
+    debugLog('agent-cli', 'workstream.charter.set', {
+      actingAgentId, conversationId, len: charter?.length ?? 0,
+    });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'charter set failed' } };
+  }
+}
+
 export async function handleServerInfo(req, query, ctx) {
   const actingAgentId = getActingAgentId(req, query);
   const v = validateActingAgent(actingAgentId, ctx);

package/src/core/agent-home.mjs

@@ -7,9 +7,10 @@
  * lives in cwd, agent reads it via `cat MEMORY.md`.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { AF_HOME } from './config.mjs';
+import { buildAgentHandbookFiles, LEGACY_HANDBOOK_FILE_NAMES } from '../runtimes/_shared/agent-handbook.mjs';
 
 export const AF_AGENTS_DIR = join(AF_HOME, 'agents');
 
@@ -37,9 +38,88 @@ export function ensureAgentHome(agentId, { displayName } = {}) {
   if (!existsSync(memoryPath)) {
     writeFileSync(memoryPath, buildInitialMemoryMd({ displayName, home }), 'utf8');
   }
+  writeManagedHandbookFiles(home);
+  ensureSkillSymlinks(home);
   return home;
 }
 
+function writeManagedHandbookFiles(home) {
+  removeLegacyManagedHandbookFiles(home);
+  for (const { name, content } of buildAgentHandbookFiles()) {
+    const path = join(home, name);
+    try {
+      let stat = null;
+      try { stat = lstatSync(path); } catch { /* not present */ }
+      if (stat && !stat.isFile()) continue;
+      const next = `${content.trim()}\n`;
+      if (stat) {
+        const current = readFileSync(path, 'utf8');
+        if (current === next) continue;
+      }
+      writeFileSync(path, next, { encoding: 'utf8', mode: 0o600 });
+    } catch (err) {
+      console.warn(`[agent-home] failed to write ${path}: ${err?.message || err}`);
+    }
+  }
+}
+
+function removeLegacyManagedHandbookFiles(home) {
+  for (const name of LEGACY_HANDBOOK_FILE_NAMES) {
+    const path = join(home, name);
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isFile()) continue;
+      unlinkSync(path);
+    } catch (err) {
+      if (err?.code === 'ENOENT') continue;
+      console.warn(`[agent-home] failed to remove legacy handbook ${path}: ${err?.message || err}`);
+    }
+  }
+}
+
+/**
+ * Cross-runtime skill discovery: every runtime (Claude Code, Codex,
+ * opencode, pi, openclaw) auto-discovers SKILL.md under at least one of
+ * .claude/skills/, .codex/skills/, .opencode/skills/, .pi/skills/, or
+ * .agents/skills/. We pin everything to a single source-of-truth
+ * directory (.agents/skills/) and symlink the rest so a skill written
+ * once is visible to every runtime without sync machinery.
+ *
+ * .pi and .opencode skip the symlink — both natively scan
+ * .agents/skills/ in addition to their own folder.
+ *
+ * No migration / no recovery: if the target path already exists as a
+ * real dir or wrong-target symlink, we leave it alone. The user (or a
+ * future agent) resolves it manually. See cos_impl.md §一.不为错误兜底.
+ */
+function ensureSkillSymlinks(home) {
+  const realRoot = join(home, '.agents', 'skills');
+  mkdirSync(realRoot, { recursive: true });
+
+  const links = [
+    { dir: join(home, '.claude'), name: 'skills', target: '../.agents/skills' },
+    { dir: join(home, '.codex'), name: 'skills', target: '../.agents/skills' },
+    // openclaw expects skills/ at the home root
+    { dir: home, name: 'skills', target: '.agents/skills' },
+  ];
+
+  for (const { dir, name, target } of links) {
+    mkdirSync(dir, { recursive: true });
+    const linkPath = join(dir, name);
+    let stat = null;
+    try { stat = lstatSync(linkPath); } catch { /* not present */ }
+    if (stat) continue; // path already exists — do not touch
+    try {
+      symlinkSync(target, linkPath, 'dir');
+    } catch (err) {
+      // Best-effort: an EEXIST race or platform that disallows symlinks
+      // gets logged but doesn't fail spawn. Skills just won't be visible
+      // for that runtime via this folder.
+      console.warn(`[agent-home] failed to symlink ${linkPath} -> ${target}: ${err?.message || err}`);
+    }
+  }
+}
+
 function buildInitialMemoryMd({ displayName, home }) {
   const lines = [
     `# ${displayName || 'Agent'}`,

package/src/core/argv.mjs

@@ -29,7 +29,17 @@ export function parseOptionArgs(argv = []) {
       const value = inlineValue !== undefined
         ? inlineValue
         : argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : true;
-      args[rawKey] = value;
+      // Repeated flags collect into an array so `--attach a --attach b`
+      // surfaces as ['a','b'] to callers that expect repeatable input
+      // (--attach on message send, --member on group create, etc).
+      // First occurrence stays scalar so single-value callers don't
+      // have to learn array-or-string.
+      if (Object.prototype.hasOwnProperty.call(args, rawKey)) {
+        const existing = args[rawKey];
+        args[rawKey] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+      } else {
+        args[rawKey] = value;
+      }
       continue;
     }
     args._.push(arg);