@magclaw/cli-core 0.1.34 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magclaw/cli-core",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Shared local MagClaw CLI implementation used by daemon and computer packages.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -61,6 +61,79 @@ function now() {
   return new Date().toISOString();
 }
 
+function claudeStreamEvents(raw) {
+  if (!raw || typeof raw !== 'object') return [];
+  const event = raw;
+  const output = [];
+  if (event.type === 'system' && event.subtype === 'init') {
+    output.push({
+      type: 'system',
+      sessionId: event.session_id || event.sessionId || '',
+      model: event.model || '',
+      cwd: event.cwd || '',
+    });
+    return output;
+  }
+  const content = Array.isArray(event.message?.content) ? event.message.content : [];
+  if (event.type === 'assistant') {
+    for (const block of content) {
+      if (block?.type === 'text' && typeof block.text === 'string' && block.text) {
+        output.push({ type: 'text', delta: block.text });
+      } else if (block?.type === 'thinking' && typeof block.thinking === 'string' && block.thinking) {
+        output.push({ type: 'thinking', delta: block.thinking });
+      } else if (block?.type === 'tool_use' && block.id && block.name) {
+        output.push({ type: 'tool_use', id: block.id, name: block.name, input: block.input });
+      }
+    }
+    return output;
+  }
+  if (event.type === 'user') {
+    for (const block of content) {
+      if (block?.type === 'tool_result' && block.tool_use_id) {
+        output.push({
+          type: 'tool_result',
+          id: block.tool_use_id,
+          output: typeof block.content === 'string' ? block.content : JSON.stringify(block.content),
+          isError: block.is_error === true,
+        });
+      }
+    }
+    return output;
+  }
+  if (event.type === 'result') {
+    if (event.usage) {
+      output.push({
+        type: 'usage',
+        inputTokens: event.usage.input_tokens,
+        outputTokens: event.usage.output_tokens,
+        costUsd: event.total_cost_usd,
+      });
+    }
+    output.push({ type: 'done', sessionId: event.session_id || event.sessionId || '' });
+  }
+  return output;
+}
+
+function claudeToolActivityDetail(event) {
+  if (!event || typeof event !== 'object') return 'Claude Code activity';
+  if (event.type === 'tool_use') return `Claude Code using ${event.name || 'tool'}`;
+  if (event.type === 'tool_result') return event.isError ? 'Claude Code tool returned an error' : 'Claude Code tool completed';
+  if (event.type === 'thinking') return 'Claude Code thinking';
+  if (event.type === 'usage') return `Claude Code usage input=${event.inputTokens || 0} output=${event.outputTokens || 0}`;
+  return 'Claude Code activity';
+}
+
+function codexStderrRuntimeError(text = '') {
+  const detail = String(text || '').trim();
+  if (!detail) return '';
+  const lower = detail.toLowerCase();
+  if (lower.includes('responses_websocket') && lower.includes('error')) return detail.slice(0, 2000);
+  if (lower.includes('failed to connect to websocket') && lower.includes('/v1/responses')) return detail.slice(0, 2000);
+  if (lower.includes('authentication') && lower.includes('openai')) return detail.slice(0, 2000);
+  if (lower.includes('not logged in') || lower.includes('login is required')) return detail.slice(0, 2000);
+  return '';
+}
+
 function packageInfoFromSpec(packageSpec = '') {
   const match = String(packageSpec || '').trim().match(/^(@magclaw\/(?:daemon|computer))(?:@(.+))?$/);
   return {
@@ -1721,6 +1794,60 @@ function contextSnippet(value, limit = 240) {
   return text.length >= limit ? `${text.slice(0, Math.max(0, limit - 3)).trim()}...` : text;
 }
 
+function contextImageMimeFromName(value = '') {
+  const name = String(value || '').toLowerCase().split(/[?#]/)[0];
+  if (name.endsWith('.png')) return 'image/png';
+  if (name.endsWith('.jpg') || name.endsWith('.jpeg')) return 'image/jpeg';
+  if (name.endsWith('.webp')) return 'image/webp';
+  if (name.endsWith('.gif')) return 'image/gif';
+  if (name.endsWith('.svg')) return 'image/svg+xml';
+  return '';
+}
+
+function contextDataImageUrl(value = '') {
+  const text = String(value || '').trim();
+  return /^data:image\//i.test(text) ? text : '';
+}
+
+function contextImageType(reference = {}) {
+  const explicit = String(reference.type || reference.mime || reference.mimeType || '').toLowerCase();
+  if (explicit.startsWith('image/')) return explicit;
+  const data = contextDataImageUrl(reference.dataUrl || reference.url || reference.downloadUrl);
+  if (data) return data.match(/^data:([^;,]+)[;,]/i)?.[1]?.toLowerCase() || 'image';
+  return contextImageMimeFromName(reference.name || reference.filename || reference.url || reference.downloadUrl || reference.path || reference.description);
+}
+
+function isContextImageReference(reference = {}) {
+  return contextImageType(reference).startsWith('image/');
+}
+
+function remoteImageUrl(value = '', serverUrl = '', fallbackPath = '') {
+  const raw = String(value || '').trim();
+  if (contextDataImageUrl(raw)) return raw;
+  const base = String(serverUrl || DEFAULT_SERVER_URL).replace(/\/+$/, '');
+  const candidate = raw || String(fallbackPath || '').trim();
+  if (!candidate) return '';
+  if (candidate.startsWith('/')) {
+    try {
+      return new URL(candidate, base).toString();
+    } catch {
+      return '';
+    }
+  }
+  if (/^https?:\/\//i.test(candidate)) {
+    try {
+      const parsed = new URL(candidate);
+      if (['0.0.0.0', '127.0.0.1', 'localhost', '::1'].includes(parsed.hostname) && base) {
+        return new URL(`${parsed.pathname}${parsed.search}${parsed.hash}`, base).toString();
+      }
+      return parsed.toString();
+    } catch {
+      return '';
+    }
+  }
+  return '';
+}
+
 function contextActorName(pack, id) {
   const value = String(id || '').trim();
   if (!value) return 'unknown';
@@ -1767,6 +1894,50 @@ function renderContextTasks(pack) {
   }).join('\n');
 }
 
+function renderContextAttachments(pack) {
+  const attachments = contextArray(pack?.attachments);
+  if (!attachments.length) return '- (none)';
+  return attachments.map((item) => {
+    const details = [
+      item.id ? `id=${item.id}` : '',
+      item.messageId ? `from msg=${item.messageId}` : '',
+      item.source ? `source=${item.source}` : '',
+      item.path ? `path=${item.path}` : '',
+      item.url ? `url=${item.url}` : '',
+      item.id ? `tool=read_attachment(attachmentId="${item.id}")` : '',
+    ].filter(Boolean).join(', ');
+    return `- ${item.name || item.filename || item.id || 'attachment'} ${item.type || item.mime || 'file'} ${Number(item.bytes || item.sizeBytes || 0)} bytes${details ? ` (${details})` : ''}`;
+  }).join('\n');
+}
+
+function renderContextTargetAgentAvatar(pack) {
+  const avatar = pack?.targetAgent?.avatar;
+  if (!avatar || avatar.kind === 'none') return '';
+  const description = avatar.description ? ` (${avatar.description})` : '';
+  if (avatar.visualInput !== false && isContextImageReference(avatar)) {
+    return `- Your profile avatar: image supplied as visual input${description}. Use it when the user asks what your avatar shows.`;
+  }
+  return `- Your profile avatar: ${avatar.description || 'configured'}, but no visual input is available.`;
+}
+
+function contextParticipantAvatarVisualInputs(pack, targetAgentId = '') {
+  return compactContextParticipants(pack, targetAgentId).selected.filter((item) => (
+    item.id !== targetAgentId
+    && item.type === 'agent'
+    && item.avatar
+    && item.avatar.kind !== 'none'
+    && item.avatar.visualInput !== false
+    && isContextImageReference(item.avatar)
+  ));
+}
+
+function renderContextParticipantAvatarInputs(pack, targetAgentId = '') {
+  const visible = contextParticipantAvatarVisualInputs(pack, targetAgentId);
+  if (!visible.length) return '';
+  const names = visible.map((item) => `@${item.name || item.id}`).join(', ');
+  return `- Participant avatar visual inputs: ${names}. Use these when comparing an uploaded image to another Agent avatar; call read_agent_avatar if the relevant Agent is omitted.`;
+}
+
 function renderContextEventMembers(pack, event = {}) {
   const ids = [
     ...contextArray(event.memberIds),
@@ -1889,6 +2060,8 @@ function renderRemoteAgentContextPack(pack, targetAgentId = '') {
     `- Space: ${pack.space?.type || 'space'} (${pack.space?.visibility || 'public'}${pack.space?.defaultChannel ? ', default workspace channel' : ''})`,
     pack.space?.description ? `- Channel description: ${contextSnippet(pack.space.description, 180)}` : '',
     `- Participants shown: ${participants.selected.map((item) => renderContextParticipant(item, targetAgentId)).join(', ') || '(none)'}`,
+    renderContextTargetAgentAvatar(pack),
+    renderContextParticipantAvatarInputs(pack, targetAgentId),
     participants.omitted ? `- Participants omitted: ${participants.omitted}. Use list_agents/read_agent_profile or search_agent_memory when a broader roster or specialties matter.` : '',
     pack.space?.type === 'channel' && !pack.space?.defaultChannel ? renderContextSuggestedMembers(pack) : '',
     '',
@@ -1917,9 +2090,12 @@ function renderRemoteAgentContextPack(pack, targetAgentId = '') {
     'Relevant tasks:',
     renderContextTasks(pack),
     '',
+    'Visible attachment metadata and original-file tools:',
+    renderContextAttachments(pack),
+    '',
     renderContextPeerMemory(pack),
     '',
-    'Progressive context tools: list_agents, read_agent_profile, read_history, search_messages, search_agent_memory, read_agent_memory, read_agent_file, and list_tasks are available through MagClaw MCP.',
+    'Progressive context tools: list_agents, read_agent_profile, read_agent_avatar, read_history, search_messages, list_attachments, read_attachment, search_agent_memory, read_agent_memory, read_agent_file, and list_tasks are available through MagClaw MCP.',
     'For "who can we bring in" or agent suitability questions, use the server member list above first; call list_agents without a target for the server-wide agent roster, because target filters to the current channel.',
     'For agent capability or specialty questions, use peer memory first; if memory is empty or weak, search_messages/read_history for earlier user role assignments before saying the fact is unknown.',
     'Use this compact snapshot first. Call the tools only when the answer depends on omitted participants, deeper history, memory, or task details.',
@@ -2020,11 +2196,14 @@ function canonicalMagClawToolName(name) {
     'send_message',
     'read_history',
     'search_messages',
+    'list_attachments',
+    'read_attachment',
     'search_agent_memory',
     'read_agent_memory',
     'read_agent_file',
     'list_agents',
     'read_agent_profile',
+    'read_agent_avatar',
     'write_memory',
     'list_tasks',
     'create_tasks',
@@ -2508,11 +2687,14 @@ function daemonSkillTools() {
     'send_message',
     'read_history',
     'search_messages',
+    'list_attachments',
+    'read_attachment',
     'search_agent_memory',
     'read_agent_memory',
     'read_agent_file',
     'list_agents',
     'read_agent_profile',
+    'read_agent_avatar',
     'write_memory',
     'list_tasks',
     'create_tasks',
@@ -2808,9 +2990,12 @@ class CodexAgentSession {
     this.completedToolCallIds = new Set();
     this.activeTurnToolSignatures = new Set();
     this.activeTurnUsedSendMessage = false;
+    this.activeTurnSawResponseDelta = false;
+    this.activeTurnDeltaItemIds = new Set();
     this.codexMessageQueue = Promise.resolve();
     this.streamActivityTimer = null;
     this.pendingStreamActivity = null;
+    this.lastRuntimeError = '';
     this.trajectoryCoalesceMs = envInteger(this.env, 'MAGCLAW_DAEMON_TRAJECTORY_COALESCE_MS', DEFAULT_TRAJECTORY_COALESCE_MS, { min: 0, max: 5_000 });
   }
 
@@ -2960,6 +3145,38 @@ class CodexAgentSession {
     if (payload) this.send(payload);
   }
 
+  async reportRuntimeError(errorText, rawText = '') {
+    const error = String(errorText || rawText || 'Codex runtime error.').trim().slice(0, 2000);
+    if (!error) return;
+    if (this.status === 'error' && this.lastRuntimeError === error) return;
+    this.lastRuntimeError = error;
+    const activity = {
+      source: 'codex-stderr',
+      error,
+      text: String(rawText || error).trim().slice(0, 2000),
+      at: now(),
+    };
+    this.send({
+      type: 'agent:error',
+      commandId: this.activeDeliveryId || undefined,
+      deliveryId: this.activeDeliveryId || null,
+      agentId: this.agent.id,
+      error,
+    });
+    if (this.activeDeliveryId) {
+      await this.markDelivery(this.activeDeliveryId, 'failed', {
+        agentId: this.agent.id,
+        sessionKey: this.sessionKey || null,
+        messageId: this.lastSourceMessage?.id || null,
+        workItemId: this.lastSourceMessage?.workItemId || null,
+        error,
+      }).catch((markError) => {
+        logWarning('daemon', `Failed to mark delivery ${this.activeDeliveryId} failed after Codex runtime error: ${markError.message}`);
+      });
+    }
+    this.sendStatus('error', activity);
+  }
+
   async requestMagClawTool(pathname, { method = 'GET', query = {}, body = null } = {}) {
     const url = new URL(`${this.serverUrl.replace(/\/+$/, '')}${pathname}`);
     for (const [key, value] of Object.entries(query || {})) {
@@ -2998,6 +3215,92 @@ class CodexAgentSession {
     }
   }
 
+  async readAttachmentImageInput(reference = {}) {
+    const attachmentId = String(reference.id || reference.attachmentId || reference.attachment_id || '').trim();
+    if (!attachmentId) return null;
+    try {
+      const data = await this.requestMagClawTool('/api/agent-tools/attachments/read', {
+        query: {
+          agentId: this.agent.id,
+          attachmentId,
+          maxBytes: 8 * 1024 * 1024,
+        },
+      });
+      const dataUrl = contextDataImageUrl(data?.dataUrl);
+      if (!dataUrl || data?.file?.truncated) return null;
+      return {
+        key: `attachment:${attachmentId}`,
+        input: { type: 'image', url: dataUrl },
+      };
+    } catch (error) {
+      logWarning('attachments', `Could not read image attachment ${attachmentId} for agent ${this.agent.id}: ${error.message}`);
+      return null;
+    }
+  }
+
+  async imageInputFromContextReference(reference = {}, { preferReadAttachment = false } = {}) {
+    if (!isContextImageReference(reference)) return null;
+    if (preferReadAttachment) {
+      const resolved = await this.readAttachmentImageInput(reference);
+      if (resolved) return resolved;
+    }
+    const dataUrl = contextDataImageUrl(reference.dataUrl || reference.url || reference.downloadUrl);
+    if (dataUrl) {
+      return {
+        key: `url:${dataUrl}`,
+        input: { type: 'image', url: dataUrl },
+      };
+    }
+    const url = remoteImageUrl(reference.url || reference.downloadUrl || '', this.serverUrl, reference.description);
+    if (url) {
+      return {
+        key: `url:${url}`,
+        input: { type: 'image', url },
+      };
+    }
+    const filePath = String(reference.path || '').trim();
+    if (filePath && existsSync(filePath)) {
+      return {
+        key: `path:${filePath}`,
+        input: { type: 'localImage', path: filePath },
+      };
+    }
+    return null;
+  }
+
+  async imageInputsForDelivery(message = {}) {
+    const inputs = [];
+    const seen = new Set();
+    const pack = message?.contextPack || {};
+    const attachments = contextArray(pack.attachments);
+    for (const attachment of attachments) {
+      const resolved = await this.imageInputFromContextReference(attachment, { preferReadAttachment: true });
+      if (!resolved || seen.has(resolved.key)) continue;
+      seen.add(resolved.key);
+      inputs.push(resolved.input);
+    }
+    const avatar = pack?.targetAgent?.avatar || null;
+    if (avatar?.visualInput !== false) {
+      const resolved = await this.imageInputFromContextReference(avatar);
+      if (resolved && !seen.has(resolved.key)) {
+        seen.add(resolved.key);
+        inputs.push(resolved.input);
+      }
+    }
+    const targetAgentId = String(pack?.targetAgentId || pack?.targetAgent?.id || this.agent.id || '');
+    for (const participant of contextArray(pack.participants)) {
+      if (participant?.type !== 'agent') continue;
+      if (targetAgentId && String(participant.id || '') === targetAgentId) continue;
+      const participantAvatar = participant.avatar || null;
+      if (!participantAvatar || participantAvatar.visualInput === false || !isContextImageReference(participantAvatar)) continue;
+      const resolved = await this.imageInputFromContextReference(participantAvatar);
+      if (!resolved || seen.has(resolved.key)) continue;
+      seen.add(resolved.key);
+      inputs.push(resolved.input);
+    }
+    return inputs;
+  }
+
   async executeMagClawTool(name, rawArgs = {}) {
     const args = { ...rawArgs, agentId: rawArgs.agentId || this.agent.id };
     switch (name) {
@@ -3035,6 +3338,25 @@ class CodexAgentSession {
             limit: args.limit,
           },
         });
+      case 'list_attachments':
+        return this.requestMagClawTool('/api/agent-tools/attachments', {
+          query: {
+            agentId: args.agentId,
+            target: args.target || args.channel,
+            workItemId: args.workItemId || args.work_item_id,
+            messageId: args.messageId || args.message_id,
+            limit: args.limit,
+          },
+        });
+      case 'read_attachment':
+        return this.requestMagClawTool('/api/agent-tools/attachments/read', {
+          query: {
+            agentId: args.agentId,
+            attachmentId: args.attachmentId || args.attachment_id || args.id,
+            maxBytes: args.maxBytes || args.max_bytes,
+            format: args.format,
+          },
+        });
       case 'search_agent_memory':
         return this.requestMagClawTool('/api/agent-tools/memory/search', {
           query: {
@@ -3076,6 +3398,14 @@ class CodexAgentSession {
             targetAgentId: args.targetAgentId || args.targetAgent,
           },
         });
+      case 'read_agent_avatar':
+        return this.requestMagClawTool('/api/agent-tools/agents/avatar/read', {
+          query: {
+            agentId: args.agentId,
+            targetAgentId: args.targetAgentId || args.targetAgent,
+            maxBytes: args.maxBytes || args.max_bytes,
+          },
+        });
       case 'write_memory':
         {
           const local = await writeDaemonLocalMemory(this.agentDir(), this.agent, args);
@@ -3161,6 +3491,18 @@ class CodexAgentSession {
     }
   }
 
+  appendCompletedAgentText(text = '', { hadDelta = false } = {}) {
+    const value = String(text || '');
+    if (!value) return;
+    if (hadDelta) {
+      if (this.responseBuffer.endsWith(value) || this.responseBuffer.includes(value)) return;
+      if (value.startsWith(this.responseBuffer)) this.responseBuffer = value;
+      else this.responseBuffer += value;
+      return;
+    }
+    if (!this.responseBuffer.includes(value)) this.responseBuffer += value;
+  }
+
   async executeCodexToolItem(item = {}, requestId = null, params = {}) {
     const callId = codexToolCallId(item) || String(params.callId || params.call_id || '');
     const name = canonicalMagClawToolName(codexToolName(item));
@@ -3257,10 +3599,18 @@ class CodexAgentSession {
     this.child.stderr.on('data', (chunk) => {
       const text = chunk.toString().trim();
       if (!text) return;
+      const runtimeError = codexStderrRuntimeError(text);
+      if (runtimeError) {
+        this.reportRuntimeError(runtimeError, text).catch((error) => {
+          logWarning('daemon', `Failed to report Codex runtime error for ${this.agent.id}: ${error.message}`);
+        });
+        return;
+      }
       this.send({
         type: 'agent:activity',
         agentId: this.agent.id,
         status: this.status || 'working',
+        deliveryId: this.activeDeliveryId || null,
         activity: { source: 'codex-stderr', text: text.slice(0, 2000), at: now() },
       });
     });
@@ -3301,19 +3651,23 @@ class CodexAgentSession {
       this.pendingPrompts.push({ prompt, message, workItem, deliveryId });
       return;
     }
-    this.startTurn(prompt, message, workItem, deliveryId);
+    await this.startTurn(prompt, message, workItem, deliveryId);
   }
 
-  startTurn(prompt, message = {}, workItem = null, deliveryId = '') {
+  async startTurn(prompt, message = {}, workItem = null, deliveryId = '') {
     if (!this.threadId) return false;
     this.activeDeliveryId = deliveryId || '';
     this.activeTurnToolSignatures = new Set();
     this.activeTurnUsedSendMessage = false;
+    this.activeTurnSawResponseDelta = false;
+    this.activeTurnDeltaItemIds = new Set();
+    this.lastRuntimeError = '';
     const model = this.agent.model || undefined;
     const effort = this.agent.reasoningEffort || undefined;
+    const imageInputs = await this.imageInputsForDelivery(message);
     const params = {
       threadId: this.threadId,
-      input: [{ type: 'text', text: prompt }],
+      input: [{ type: 'text', text: prompt }, ...imageInputs],
       approvalPolicy: codexApprovalPolicy(this.env),
       ...(model ? { model } : {}),
       ...(effort ? { effort } : {}),
@@ -3382,7 +3736,7 @@ class CodexAgentSession {
         this.send({ type: 'agent:session', agentId: this.agent.id, status: 'idle', sessionId: this.threadId, sessionKey: this.sessionKey || null });
         this.sendStatus('idle', { source: '@magclaw/daemon', detail: 'Codex session ready', at: now() });
         const queued = this.pendingPrompts.splice(0);
-        for (const item of queued) this.startTurn(item.prompt, item.message, item.workItem, item.deliveryId);
+        for (const item of queued) await this.startTurn(item.prompt, item.message, item.workItem, item.deliveryId);
       } else if (pending?.method === 'turn/start' || pending?.method === 'turn/steer') {
         this.activeTurnId = message.result?.turn?.id || message.result?.turnId || this.activeTurnId;
       }
@@ -3418,6 +3772,9 @@ class CodexAgentSession {
     }
     if (method === 'item/agentMessage/delta' || method === 'response/output_text/delta') {
       this.responseBuffer += String(params.delta || params.text || '');
+      const itemId = String(params.itemId || params.item_id || params.item?.id || '');
+      if (itemId) this.activeTurnDeltaItemIds.add(itemId);
+      this.activeTurnSawResponseDelta = true;
       this.queueCodexStreamActivity();
       return;
     }
@@ -3425,7 +3782,10 @@ class CodexAgentSession {
       const item = params.item || {};
       if (await this.executeCodexToolItem(item, null, params)) return;
       const text = item?.text || item?.message || params.text || '';
-      if (text) this.responseBuffer += String(text);
+      const itemId = String(item?.id || item?.itemId || item?.item_id || '');
+      this.appendCompletedAgentText(text, {
+        hadDelta: Boolean((itemId && this.activeTurnDeltaItemIds.has(itemId)) || this.activeTurnSawResponseDelta),
+      });
       return;
     }
     if (method === 'turn/completed' || method === 'turn/failed') {
@@ -3457,6 +3817,8 @@ class CodexAgentSession {
       this.responseBuffer = '';
       this.activeTurnId = '';
       this.activeTurnUsedSendMessage = false;
+      this.activeTurnSawResponseDelta = false;
+      this.activeTurnDeltaItemIds.clear();
       this.sendStatus(method === 'turn/completed' ? 'idle' : 'error', {
         source: '@magclaw/daemon',
         detail: method === 'turn/completed' ? 'Turn completed' : 'Turn failed',
@@ -3495,6 +3857,11 @@ class ClaudeAgentSession {
     this.status = 'offline';
     this.started = false;
     this.activeDeliveryId = '';
+    this.responseBuffer = '';
+    this.lastSourceMessage = null;
+    this.pendingMessageDelta = null;
+    this.messageDeltaTimer = null;
+    this.trajectoryCoalesceMs = envInteger(this.env, 'MAGCLAW_DAEMON_TRAJECTORY_COALESCE_MS', DEFAULT_TRAJECTORY_COALESCE_MS, { min: 0, max: 5_000 });
   }
 
   agentDir() {
@@ -3558,6 +3925,87 @@ class ClaudeAgentSession {
     });
   }
 
+  queueMessageDelta(delta = '') {
+    const body = this.responseBuffer.trim();
+    if (!body) return;
+    this.pendingMessageDelta = {
+      type: 'agent:message_delta',
+      agentId: this.agent.id,
+      deliveryId: this.activeDeliveryId || null,
+      payload: {
+        body,
+        delta: String(delta || ''),
+        message: this.lastSourceMessage || null,
+        sourceMessage: this.lastSourceMessage || null,
+        spaceType: this.lastSourceMessage?.spaceType || 'channel',
+        spaceId: this.lastSourceMessage?.spaceId || 'chan_all',
+        parentMessageId: this.lastSourceMessage?.parentMessageId || null,
+        idempotencyKey: this.activeDeliveryId || null,
+      },
+    };
+    if (this.trajectoryCoalesceMs <= 0) {
+      this.flushMessageDelta();
+      return;
+    }
+    if (this.messageDeltaTimer) return;
+    this.messageDeltaTimer = setTimeout(() => {
+      this.messageDeltaTimer = null;
+      this.flushMessageDelta();
+    }, this.trajectoryCoalesceMs);
+    this.messageDeltaTimer.unref?.();
+  }
+
+  flushMessageDelta() {
+    if (this.messageDeltaTimer) {
+      clearTimeout(this.messageDeltaTimer);
+      this.messageDeltaTimer = null;
+    }
+    const payload = this.pendingMessageDelta;
+    this.pendingMessageDelta = null;
+    if (payload) this.send(payload);
+  }
+
+  handleClaudeStreamEvent(event) {
+    if (event.type === 'system') {
+      if (event.sessionId) {
+        this.send({
+          type: 'agent:session',
+          agentId: this.agent.id,
+          status: this.status,
+          sessionId: event.sessionId,
+          sessionKey: null,
+        });
+      }
+      return;
+    }
+    if (event.type === 'text') {
+      this.responseBuffer += String(event.delta || '');
+      this.queueMessageDelta(event.delta || '');
+      this.send({
+        type: 'agent:activity',
+        agentId: this.agent.id,
+        status: 'working',
+        deliveryId: this.activeDeliveryId || null,
+        activity: { source: 'claude-code-stream', chars: this.responseBuffer.length, at: now() },
+      });
+      return;
+    }
+    if (event.type === 'thinking' || event.type === 'tool_use' || event.type === 'tool_result' || event.type === 'usage') {
+      this.send({
+        type: 'agent:activity',
+        agentId: this.agent.id,
+        status: event.type === 'thinking' ? 'thinking' : 'working',
+        deliveryId: this.activeDeliveryId || null,
+        activity: {
+          source: 'claude-code-stream',
+          phase: event.type,
+          detail: claudeToolActivityDetail(event),
+          at: now(),
+        },
+      });
+    }
+  }
+
   async start() {
     if (this.started) return;
     await this.prepare();
@@ -3568,11 +4016,12 @@ class ClaudeAgentSession {
   async deliver(message = {}, workItem = null, deliveryId = '') {
     await this.start();
     this.activeDeliveryId = deliveryId || '';
+    this.responseBuffer = '';
+    this.lastSourceMessage = message || null;
     const prompt = deliveryPrompt(this.agent, message, workItem);
     const claudeCommand = this.env.CLAUDE_PATH || 'claude';
-    const args = ['--print'];
+    const args = ['-p', prompt, '--output-format', 'stream-json', '--verbose'];
     if (this.agent.model) args.push('--model', String(this.agent.model));
-    args.push(prompt);
     const timeoutMs = Number(this.env.MAGCLAW_DAEMON_RUNTIME_TIMEOUT_MS || 10 * 60 * 1000);
     if (this.activeDeliveryId) {
       await this.markDelivery(this.activeDeliveryId, 'started', {
@@ -3583,31 +4032,33 @@ class ClaudeAgentSession {
     }
     this.sendStatus('thinking', { source: 'claude-code', detail: 'Claude Code turn started', at: now() });
     await new Promise((resolve) => {
-      let stdout = '';
       let stderr = '';
+      let stdoutBuffer = '';
       let settled = false;
+      const finalMessageFrame = (body) => ({
+        type: 'agent:message',
+        agentId: this.agent.id,
+        deliveryId: this.activeDeliveryId || null,
+        payload: {
+          body,
+          message,
+          sourceMessage: message,
+          spaceType: message.spaceType || 'channel',
+          spaceId: message.spaceId || 'chan_all',
+          parentMessageId: message.parentMessageId || null,
+          idempotencyKey: this.activeDeliveryId || null,
+        },
+      });
       const finish = (status, detail) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
+        this.flushMessageDelta();
         this.child = null;
+        const body = this.responseBuffer.trim();
         if (status === 'idle') {
-          const body = stdout.trim();
           if (body) {
-            const frame = {
-              type: 'agent:message',
-              agentId: this.agent.id,
-              deliveryId: this.activeDeliveryId || null,
-              payload: {
-                body,
-                message,
-                sourceMessage: message,
-                spaceType: message.spaceType || 'channel',
-                spaceId: message.spaceId || 'chan_all',
-                parentMessageId: message.parentMessageId || null,
-                idempotencyKey: this.activeDeliveryId || null,
-              },
-            };
+            const frame = finalMessageFrame(body);
             this.send(frame);
             this.markDelivery(this.activeDeliveryId, 'completed', { resultFrame: frame }).catch(() => {});
           }
@@ -3615,8 +4066,10 @@ class ClaudeAgentSession {
           this.sendStatus('idle', { source: 'claude-code', detail: detail || 'Claude Code turn completed', at: now() });
         } else {
           const error = detail || stderr.trim() || 'Claude Code failed.';
+          const frame = body ? finalMessageFrame(body) : null;
+          if (frame) this.send(frame);
           this.send({ type: 'agent:error', commandId: this.activeDeliveryId || undefined, deliveryId: this.activeDeliveryId || null, agentId: this.agent.id, error });
-          this.markDelivery(this.activeDeliveryId, 'failed', { error }).catch(() => {});
+          this.markDelivery(this.activeDeliveryId, 'failed', { error, ...(frame ? { resultFrame: frame } : {}) }).catch(() => {});
           this.sendStatus('error', { source: 'claude-code', error, at: now() });
         }
         this.activeDeliveryId = '';
@@ -3639,19 +4092,40 @@ class ClaudeAgentSession {
         finish('error', 'Claude Code session timed out.');
       }, timeoutMs);
       this.child.stdout.on('data', (chunk) => {
-        stdout += chunk.toString();
-        this.send({
-          type: 'agent:activity',
-          agentId: this.agent.id,
-          status: 'working',
-          activity: { source: 'claude-code', chars: stdout.length, at: now() },
-        });
+        stdoutBuffer += chunk.toString();
+        const lines = stdoutBuffer.split(/\r?\n/);
+        stdoutBuffer = lines.pop() || '';
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const raw = JSON.parse(line);
+            for (const event of claudeStreamEvents(raw)) this.handleClaudeStreamEvent(event);
+          } catch (error) {
+            stderr += `${line}\n`;
+            this.send({
+              type: 'agent:activity',
+              agentId: this.agent.id,
+              status: 'working',
+              deliveryId: this.activeDeliveryId || null,
+              activity: { source: 'claude-code-stream', error: `Invalid stream JSON: ${error.message}`, at: now() },
+            });
+          }
+        }
       });
       this.child.stderr.on('data', (chunk) => {
         stderr += chunk.toString();
       });
       this.child.on('error', (error) => finish('error', error.message));
       this.child.on('close', (code, signal) => {
+        if (stdoutBuffer.trim()) {
+          try {
+            const raw = JSON.parse(stdoutBuffer.trim());
+            for (const event of claudeStreamEvents(raw)) this.handleClaudeStreamEvent(event);
+          } catch (error) {
+            stderr += `${stdoutBuffer}\n`;
+          }
+          stdoutBuffer = '';
+        }
         if (code === 0) finish('idle');
         else finish('error', stderr.trim() || `Claude Code exited with code ${code ?? 'unknown'}${signal ? ` (${signal})` : ''}.`);
       });
@@ -3660,6 +4134,7 @@ class ClaudeAgentSession {
 
   stop() {
     this.status = 'stopping';
+    this.flushMessageDelta();
     if (this.child) this.child.kill('SIGTERM');
     this.started = false;
   }
@@ -4600,7 +5075,11 @@ class MagClawDaemon {
       }
       const sessionContext = {
         sessionKey: message.payload?.sessionKey || message.sessionKey || '',
-        workspaceId: message.workspaceId || message.payload?.workspaceId || '',
+        workspaceId: message.payload?.message?.workspaceId
+          || message.payload?.workItem?.workspaceId
+          || message.payload?.workspaceId
+          || message.workspaceId
+          || '',
         message: message.payload?.message || {},
       };
       const sessionKey = sessionContext.sessionKey || daemonConversationLaneKey({

package/src/mcp-bridge.js

@@ -246,6 +246,36 @@ const tools = [
       targetAgent: { type: 'string' },
     }),
   },
+  {
+    name: 'read_agent_avatar',
+    description: 'Read a MagClaw agent avatar image for visual comparison with uploaded attachments.',
+    inputSchema: schema({
+      targetAgentId: { type: 'string' },
+      targetAgent: { type: 'string' },
+      maxBytes: { type: 'number' },
+    }),
+  },
+  {
+    name: 'list_attachments',
+    description: 'List MagClaw attachment metadata visible to this agent.',
+    inputSchema: schema({
+      target: { type: 'string' },
+      channel: { type: 'string' },
+      workItemId: { type: 'string' },
+      messageId: { type: 'string' },
+      limit: { type: 'number' },
+    }),
+  },
+  {
+    name: 'read_attachment',
+    description: 'Read an uploaded MagClaw attachment original file. Image attachments are returned as MCP image content when possible.',
+    inputSchema: schema({
+      attachmentId: { type: 'string' },
+      id: { type: 'string' },
+      maxBytes: { type: 'number' },
+      format: { type: 'string' },
+    }),
+  },
   {
     name: 'write_memory',
     description: 'Record a concise durable memory for this agent.',
@@ -358,8 +388,20 @@ function sendError(id, code, message, data = null) {
   process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message, data } })}\n`);
 }
 
-function textResult(text) {
-  return { content: [{ type: 'text', text: String(text || '') }] };
+function imageResultContent(value = {}) {
+  const type = String(value?.avatar?.type || value?.file?.type || value?.attachment?.type || '').toLowerCase();
+  if (!type.startsWith('image/')) return null;
+  if (value?.file?.truncated || value?.avatar?.truncated) return null;
+  const data = String(value?.contentBase64 || '').trim();
+  if (!data) return null;
+  return { type: 'image', data, mimeType: type };
+}
+
+function contentResult(value) {
+  const content = [{ type: 'text', text: jsonText(value) }];
+  const image = imageResultContent(value);
+  if (image) content.push(image);
+  return { content };
 }
 
 function jsonText(value) {
@@ -511,6 +553,33 @@ async function callTool(name, rawArgs = {}) {
           targetAgentId: args.targetAgentId || args.targetAgent,
         },
       });
+    case 'read_agent_avatar':
+      return request('/api/agent-tools/agents/avatar/read', {
+        query: {
+          agentId: args.agentId,
+          targetAgentId: args.targetAgentId || args.targetAgent,
+          maxBytes: args.maxBytes || args.max_bytes,
+        },
+      });
+    case 'list_attachments':
+      return request('/api/agent-tools/attachments', {
+        query: {
+          agentId: args.agentId,
+          target: args.target || args.channel,
+          workItemId: args.workItemId || args.work_item_id,
+          messageId: args.messageId || args.message_id,
+          limit: args.limit,
+        },
+      });
+    case 'read_attachment':
+      return request('/api/agent-tools/attachments/read', {
+        query: {
+          agentId: args.agentId,
+          attachmentId: args.attachmentId || args.attachment_id || args.id,
+          maxBytes: args.maxBytes || args.max_bytes,
+          format: args.format,
+        },
+      });
     case 'list_tasks':
       return request('/api/agent-tools/tasks', {
         query: {
@@ -587,7 +656,7 @@ async function handle(message) {
     }
     if (message.method === 'tools/call') {
       const result = await callTool(message.params?.name, message.params?.arguments || {});
-      send(id, textResult(jsonText(result)));
+      send(id, contentResult(result));
       return;
     }
     if (message.method === 'notifications/initialized' || message.method === 'initialized') return;