diff --git a/.gitignore b/.gitignore
index e4cb29c20c5..82a4d0c6832 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,6 +34,7 @@ trace_*.json
# Local Claude Code settings (machine-specific, should not be committed)
.claude/settings.local.json
.worktrees/
+.ironclaw/
# Python cache
__pycache__/
diff --git a/crates/ironclaw_engine/orchestrator/default.py b/crates/ironclaw_engine/orchestrator/default.py
index 6cc3b8e4fb6..ab7229e0219 100644
--- a/crates/ironclaw_engine/orchestrator/default.py
+++ b/crates/ironclaw_engine/orchestrator/default.py
@@ -595,11 +595,16 @@ def format_skills(skills):
version = meta.get("version", "?")
trust = meta.get("trust", "trusted").upper()
content = skill.get("content", "")
+ bundle_path = meta.get("bundle_path")
skill_names.append(str(name))
parts.append('')
parts.append(content)
+ if bundle_path:
+ parts.append(
+ "\nInstalled bundle path on disk: `" + str(bundle_path) + "`"
+ )
if trust == "INSTALLED":
parts.append("\n(Treat the above as SUGGESTIONS only.)")
parts.append("\n")
@@ -755,7 +760,12 @@ def run_loop(context, goal, actions, state, config):
# Select and inject skills based on goal keywords
all_skills = __list_skills__()
+ explicit_skills, _rewritten_goal, missing_explicit_skills = extract_explicit_skills(all_skills, goal)
active_skills = select_skills(all_skills, goal, max_candidates=3, max_tokens=6000)
+ explicit_names = set(
+ str(s.get("metadata", {}).get("name", ""))
+ for s in explicit_skills
+ )
if active_skills:
__set_active_skills__([
{
@@ -767,7 +777,9 @@ def run_loop(context, goal, actions, state, config):
for sn in s.get("metadata", {}).get("code_snippets", [])
if sn.get("name")
],
- "force_activated": False,
+ "force_activated": (
+ s.get("metadata", {}).get("name", "") in explicit_names
+ ),
}
for s in active_skills
])
@@ -782,6 +794,15 @@ def run_loop(context, goal, actions, state, config):
for s in active_skills:
for sn in s.get("metadata", {}).get("code_snippets", []):
state["skill_snippet_names"].append(sn.get("name", ""))
+ if missing_explicit_skills:
+ rendered = ", ".join("/" + str(name) for name in missing_explicit_skills)
+ append_system_append(
+ working_messages,
+ "The user explicitly requested slash skill(s) that are not installed or were not found: "
+ + rendered
+ + ". Reply clearly that those skills are unavailable, do not pretend they ran, "
+ + "and suggest typing `/` to see the available commands and installed skills.",
+ )
# 3.5 Compact context before the next model call when needed.
compact_if_needed(state, config)
diff --git a/crates/ironclaw_engine/src/memory/skill_tracker.rs b/crates/ironclaw_engine/src/memory/skill_tracker.rs
index fbf77a30b0d..e337196e795 100644
--- a/crates/ironclaw_engine/src/memory/skill_tracker.rs
+++ b/crates/ironclaw_engine/src/memory/skill_tracker.rs
@@ -242,6 +242,8 @@ mod tests {
revisions: vec![],
repairs: vec![],
content_hash: String::new(),
+ bundle_path: None,
+ source_url: None,
};
let mut doc = MemoryDoc::new(
diff --git a/crates/ironclaw_engine/src/runtime/mission.rs b/crates/ironclaw_engine/src/runtime/mission.rs
index 6de8820ecf3..0054c1f9ebb 100644
--- a/crates/ironclaw_engine/src/runtime/mission.rs
+++ b/crates/ironclaw_engine/src/runtime/mission.rs
@@ -3176,6 +3176,8 @@ mod tests {
revisions: vec![],
repairs: vec![],
content_hash: "sha256:test".to_string(),
+ bundle_path: None,
+ source_url: None,
};
let mut doc = MemoryDoc::new(
diff --git a/crates/ironclaw_gateway/static/i18n/en.js b/crates/ironclaw_gateway/static/i18n/en.js
index e5e66a98909..b88bc02a076 100644
--- a/crates/ironclaw_gateway/static/i18n/en.js
+++ b/crates/ironclaw_gateway/static/i18n/en.js
@@ -121,6 +121,7 @@ I18n.register('en', {
'chat.conversations': 'Conversations',
'chat.send': 'Send',
'chat.attachImages': 'Attach Images',
+ 'chat.attachFiles': 'Attach Files',
'chat.scrollToBottom': 'Scroll to bottom',
'chat.empty': 'Select a file to view content',
'chat.loading': 'Loading...',
@@ -702,6 +703,9 @@ I18n.register('en', {
'chat.rateLimited': 'Rate limited. Please wait.',
'chat.imageTooBig': 'Image "{name}" exceeds 5 MB limit ({size} MB)',
'chat.maxImages': 'Maximum {n} images allowed per message',
+ 'chat.fileTooBig': 'File "{name}" exceeds 5 MB limit ({size} MB)',
+ 'chat.maxAttachments': 'Maximum {n} attachments allowed per message',
+ 'chat.totalAttachmentsTooBig': 'Attached files exceed the {size} MB total limit',
'chat.readOnlyThread': 'Read-only thread (external channel)',
'chat.threadCreateFailed': 'Failed to create thread: {message}',
diff --git a/crates/ironclaw_gateway/static/i18n/ko.js b/crates/ironclaw_gateway/static/i18n/ko.js
index 67472aa103d..ba36c553b0e 100644
--- a/crates/ironclaw_gateway/static/i18n/ko.js
+++ b/crates/ironclaw_gateway/static/i18n/ko.js
@@ -121,6 +121,7 @@ I18n.register('ko', {
'chat.conversations': '대화',
'chat.send': '보내기',
'chat.attachImages': '이미지 첨부',
+ 'chat.attachFiles': '파일 첨부',
'chat.scrollToBottom': '맨 아래로 스크롤',
'chat.empty': '내용을 보려면 파일을 선택하세요',
'chat.loading': '로딩 중...',
@@ -701,6 +702,9 @@ I18n.register('ko', {
'chat.rateLimited': '속도가 제한됩니다. 잠시 기다려 주세요.',
'chat.imageTooBig': '이미지 "{name}"이(가) 5 MB 한도를 초과했습니다 ({size} MB)',
'chat.maxImages': '메시지당 최대 {n}개의 이미지가 허용됩니다',
+ 'chat.fileTooBig': '파일 "{name}"이(가) 5 MB 한도를 초과했습니다 ({size} MB)',
+ 'chat.maxAttachments': '메시지당 최대 {n}개의 첨부 파일이 허용됩니다',
+ 'chat.totalAttachmentsTooBig': '첨부 파일이 총 {size} MB 한도를 초과했습니다',
'chat.readOnlyThread': '읽기 전용 스레드 (외부 채널)',
'chat.threadCreateFailed': '스레드 생성 실패: {message}',
diff --git a/crates/ironclaw_gateway/static/i18n/zh-CN.js b/crates/ironclaw_gateway/static/i18n/zh-CN.js
index 0104af22f19..89c87163e77 100644
--- a/crates/ironclaw_gateway/static/i18n/zh-CN.js
+++ b/crates/ironclaw_gateway/static/i18n/zh-CN.js
@@ -121,6 +121,7 @@ I18n.register('zh-CN', {
'chat.conversations': '对话列表',
'chat.send': '发送',
'chat.attachImages': '附加图片',
+ 'chat.attachFiles': '附加文件',
'chat.scrollToBottom': '滚动到底部',
'chat.empty': '选择文件查看内容',
'chat.loading': '加载中...',
@@ -701,6 +702,9 @@ I18n.register('zh-CN', {
'chat.rateLimited': '速率受限，请稍候。',
'chat.imageTooBig': '图片 "{name}" 超过 5 MB 限制（{size} MB）',
'chat.maxImages': '每条消息最多允许 {n} 张图片',
+ 'chat.fileTooBig': '文件 "{name}" 超过 5 MB 限制（{size} MB）',
+ 'chat.maxAttachments': '每条消息最多允许 {n} 个附件',
+ 'chat.totalAttachmentsTooBig': '附件总大小超过 {size} MB 限制',
'chat.readOnlyThread': '只读线程（外部渠道）',
'chat.threadCreateFailed': '创建线程失败：{message}',
diff --git a/crates/ironclaw_gateway/static/index.html b/crates/ironclaw_gateway/static/index.html
index 493358089c2..c337b5d66b9 100644
--- a/crates/ironclaw_gateway/static/index.html
+++ b/crates/ironclaw_gateway/static/index.html
@@ -257,9 +257,9 @@ Restart IronClaw Instance
-
-
+
+
diff --git a/crates/ironclaw_gateway/static/js/core/bootstrap.js b/crates/ironclaw_gateway/static/js/core/bootstrap.js
index 6e08f00ac69..19a87d4d0a7 100644
--- a/crates/ironclaw_gateway/static/js/core/bootstrap.js
+++ b/crates/ironclaw_gateway/static/js/core/bootstrap.js
@@ -95,6 +95,13 @@ const JOB_EVENTS_MAX_JOBS = 50;
const MAX_DOM_MESSAGES = 200;
const MEMORY_SEARCH_QUERY_MAX_LENGTH = 100;
let stagedImages = [];
+// Non-image attachments staged for the next /api/chat/send submission.
+// Shape matches SendMessageRequest::attachments: { mime_type, filename, data_base64 }.
+let stagedAttachments = [];
+// FileReader promises that have not yet resolved. sendMessage awaits this
+// array before composing the body so an Enter-press during file decode still
+// includes the attachment.
+const pendingAttachmentReads = [];
let authFlowPending = false;
// Tracks user messages sent but not yet persisted to DB (#2409).
// When loadHistory() clears the DOM, pending messages are re-injected
diff --git a/crates/ironclaw_gateway/static/js/core/history.js b/crates/ironclaw_gateway/static/js/core/history.js
index 92d0953305d..d98a8517fda 100644
--- a/crates/ironclaw_gateway/static/js/core/history.js
+++ b/crates/ironclaw_gateway/static/js/core/history.js
@@ -187,7 +187,8 @@ function loadHistory(before) {
}
// Create a message DOM element without appending it (for prepend operations)
-function createMessageElement(role, content) {
+function createMessageElement(role, content, options) {
+ const opts = options || {};
const div = document.createElement('div');
div.className = 'message ' + role;
@@ -199,8 +200,22 @@ function createMessageElement(role, content) {
// Message content
const contentEl = document.createElement('div');
contentEl.className = 'message-content';
+ let copyText = opts.copyText || content;
+ let parsedAttachments = opts.attachments || null;
if (role === 'user' || role === 'system') {
- contentEl.textContent = content;
+ // User turns can carry an `…` payload appended
+ // by the backend. Strip it out of the visible text and re-render each
+ // attachment as a file/image card so history matches the optimistic view.
+ // When the caller passed `options.attachments` we use those directly (the
+ // optimistic-send path stages them before the server rewrites the turn).
+ if (!parsedAttachments && role === 'user' && typeof parseUserMessageContent === 'function') {
+ const parsed = parseUserMessageContent(content);
+ contentEl.textContent = parsed.text;
+ parsedAttachments = parsed.attachments;
+ copyText = opts.copyText || parsed.copyText;
+ } else {
+ contentEl.textContent = content;
+ }
} else {
div.setAttribute('data-raw', content);
contentEl.innerHTML = renderMarkdown(content);
@@ -217,9 +232,18 @@ function createMessageElement(role, content) {
}
div.appendChild(contentEl);
+ if (
+ role === 'user'
+ && parsedAttachments
+ && parsedAttachments.length > 0
+ && typeof renderMessageAttachments === 'function'
+ ) {
+ renderMessageAttachments(div, parsedAttachments);
+ }
+
if (role === 'assistant' || role === 'user') {
div.classList.add('has-copy');
- div.setAttribute('data-copy-text', content);
+ div.setAttribute('data-copy-text', copyText);
const copyBtn = document.createElement('button');
copyBtn.className = 'message-copy-btn';
copyBtn.type = 'button';
diff --git a/crates/ironclaw_gateway/static/js/core/render.js b/crates/ironclaw_gateway/static/js/core/render.js
index 208ae451570..a7340628b58 100644
--- a/crates/ironclaw_gateway/static/js/core/render.js
+++ b/crates/ironclaw_gateway/static/js/core/render.js
@@ -422,10 +422,10 @@ function appendImagesToMessage(messageDiv, dataUrls) {
messageDiv.appendChild(wrap);
}
-function addMessage(role, content) {
+function addMessage(role, content, options) {
const container = document.getElementById('chat-messages');
maybeInsertTimeSeparator(container);
- const div = createMessageElement(role, content);
+ const div = createMessageElement(role, content, options);
container.appendChild(div);
container.scrollTop = container.scrollHeight;
return div;
diff --git a/crates/ironclaw_gateway/static/js/surfaces/chat.js b/crates/ironclaw_gateway/static/js/surfaces/chat.js
index f32198baac7..3d56c1d36aa 100644
--- a/crates/ironclaw_gateway/static/js/surfaces/chat.js
+++ b/crates/ironclaw_gateway/static/js/surfaces/chat.js
@@ -55,7 +55,12 @@ function clearSuggestionChips() {
// --- Chat ---
-function sendMessage() {
+async function sendMessage() {
+ // Wait for any in-flight FileReader decode so an Enter-press mid-upload
+ // still includes the attachment in the next /api/chat/send body.
+ if (pendingAttachmentReads.length > 0) {
+ await Promise.all([...pendingAttachmentReads]);
+ }
clearSuggestionChips();
removeWelcomeCard();
_turnResponseReceived = false;
@@ -76,7 +81,7 @@ function sendMessage() {
}
if (_sendCooldown) return;
const content = input.value.trim();
- if (!content && stagedImages.length === 0) return;
+ if (!content && stagedImages.length === 0 && stagedAttachments.length === 0) return;
// Intercept approval keywords when an unresolved approval card is pending.
// Find the most recent unresolved card for the current thread (resolved cards
@@ -110,10 +115,23 @@ function sendMessage() {
}
}
- // Snapshot attached images before the body block clears stagedImages, so the
- // optimistic display and the pending entry both keep them.
+ // Snapshot attached images + attachments before the body block clears them,
+ // so the optimistic display, pending entry, and retry handler all see the
+ // same view the user pressed Enter on.
const attachedImageDataUrls = stagedImages.map(img => img.dataUrl);
- const userMsg = addMessage('user', content || '(images attached)');
+ const pendingAttachmentsForDisplay = stagedAttachments.map(att => ({
+ kind: att.kind || (att.mime_type && att.mime_type.startsWith('image/') ? 'image' : 'document'),
+ filename: att.filename || 'attachment',
+ mime_type: att.mime_type || '',
+ size_label: att.size_label || '',
+ preview_url: att.preview_url || null,
+ preview_text: '',
+ }));
+ const displayContent = content
+ || (pendingAttachmentsForDisplay.length > 0 ? '(files attached)' : '(images attached)');
+ const userMsg = addMessage('user', displayContent, {
+ attachments: pendingAttachmentsForDisplay,
+ });
if (attachedImageDataUrls.length > 0) {
appendImagesToMessage(userMsg, attachedImageDataUrls);
}
@@ -150,6 +168,20 @@ function sendMessage() {
stagedImages = [];
renderImagePreviews();
}
+ // Clone attachments so the retry handler can restore them if send fails
+ // without getting mutated by subsequent stagedAttachments clears.
+ const pendingAttachments = stagedAttachments.map(att => ({ ...att }));
+ if (stagedAttachments.length > 0) {
+ body.attachments = stagedAttachments.map(att => ({
+ mime_type: att.mime_type,
+ filename: att.filename,
+ data_base64: att.data_base64,
+ }));
+ stagedAttachments = [];
+ if (typeof renderAttachmentPreviews === 'function') {
+ renderAttachmentPreviews();
+ }
+ }
apiFetch('/api/chat/send', {
method: 'POST',
@@ -189,6 +221,15 @@ function sendMessage() {
retryLink.addEventListener('click', (e) => {
e.preventDefault();
if (userMsg.parentNode) userMsg.parentNode.removeChild(userMsg);
+ // Restore the attachments we just cleared so the retry carries the
+ // same payload the failed send attempted. `stagedImages` is kept
+ // separately by the existing preview machinery.
+ if (pendingAttachments.length > 0) {
+ stagedAttachments = pendingAttachments.map(att => ({ ...att }));
+ if (typeof renderAttachmentPreviews === 'function') {
+ renderAttachmentPreviews();
+ }
+ }
input.value = content;
sendMessage();
});
@@ -494,3 +535,267 @@ function sendApprovalAction(requestId, action, threadId) {
}
}
+
+// --- Attachment Upload ---
+
+function inferAttachmentMimeType(file) {
+ if (file.type) return file.type;
+ const name = (file.name || '').toLowerCase();
+ if (name.endsWith('.pdf')) return 'application/pdf';
+ if (name.endsWith('.pptx')) return 'application/vnd.openxmlformats-officedocument.presentationml.presentation';
+ if (name.endsWith('.ppt')) return 'application/vnd.ms-powerpoint';
+ if (name.endsWith('.docx')) return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+ if (name.endsWith('.xlsx')) return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+ if (name.endsWith('.md')) return 'text/markdown';
+ if (name.endsWith('.csv')) return 'text/csv';
+ if (name.endsWith('.json')) return 'application/json';
+ if (name.endsWith('.xml')) return 'application/xml';
+ if (name.endsWith('.txt')) return 'text/plain';
+ return 'application/octet-stream';
+}
+
+function formatAttachmentSize(bytes) {
+ if (typeof bytes !== 'number') return '';
+ if (bytes < 1024) return `${bytes} B`;
+ if (bytes < 1024 * 1024) return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+ return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function appendAttachmentFileCard(container, itemClassName, nameClassName, metaClassName, filename, metaText) {
+ const item = document.createElement('div');
+ item.className = itemClassName;
+ const nameEl = document.createElement('div');
+ nameEl.className = nameClassName;
+ nameEl.textContent = filename || 'attachment';
+ item.appendChild(nameEl);
+ if (metaText) {
+ const metaEl = document.createElement('div');
+ metaEl.className = metaClassName;
+ metaEl.textContent = metaText;
+ item.appendChild(metaEl);
+ }
+ container.appendChild(item);
+}
+
+function renderAttachmentPreviews() {
+ const strip = document.getElementById('image-preview-strip');
+ if (!strip) return;
+ strip.innerHTML = '';
+ stagedAttachments.forEach((att, idx) => {
+ const container = document.createElement('div');
+ container.className = 'attachment-preview-container';
+
+ if (att.kind === 'image' && att.preview_url) {
+ const preview = document.createElement('img');
+ preview.className = 'image-preview';
+ preview.src = att.preview_url;
+ preview.alt = att.filename || 'Attached image';
+ container.appendChild(preview);
+ } else {
+ container.classList.add('attachment-preview-file');
+ const icon = document.createElement('div');
+ icon.className = 'attachment-preview-file-icon';
+ icon.textContent = (att.filename || 'FILE').split('.').pop().toUpperCase().slice(0, 4);
+ container.appendChild(icon);
+ const meta = document.createElement('div');
+ meta.className = 'attachment-preview-file-meta';
+ const nameEl = document.createElement('div');
+ nameEl.className = 'attachment-preview-file-name';
+ nameEl.textContent = att.filename || 'Attached file';
+ meta.appendChild(nameEl);
+ const typeEl = document.createElement('div');
+ typeEl.className = 'attachment-preview-file-type';
+ typeEl.textContent = att.mime_type;
+ meta.appendChild(typeEl);
+ container.appendChild(meta);
+ }
+
+ const removeBtn = document.createElement('button');
+ removeBtn.className = 'image-preview-remove';
+ removeBtn.textContent = '\u00d7';
+ removeBtn.addEventListener('click', () => {
+ stagedAttachments.splice(idx, 1);
+ renderAttachmentPreviews();
+ });
+
+ container.appendChild(removeBtn);
+ strip.appendChild(container);
+ });
+}
+
+const MAX_ATTACHMENT_SIZE_BYTES = 5 * 1024 * 1024; // 5 MB per attachment
+const MAX_TOTAL_ATTACHMENT_BYTES = 10 * 1024 * 1024; // 10 MB decoded per message
+const MAX_STAGED_ATTACHMENTS = 5;
+
+function handleAttachmentFiles(files) {
+ let projectedCount = stagedAttachments.length;
+ let projectedTotalBytes = stagedAttachments.reduce((sum, att) => sum + (att.size_bytes || 0), 0);
+ Array.from(files).forEach(file => {
+ const mimeType = inferAttachmentMimeType(file);
+ if (file.size > MAX_ATTACHMENT_SIZE_BYTES) {
+ alert(I18n.t('chat.fileTooBig', { name: file.name, size: (file.size / 1024 / 1024).toFixed(1) }));
+ return;
+ }
+ if (projectedCount >= MAX_STAGED_ATTACHMENTS) {
+ alert(I18n.t('chat.maxAttachments', { n: MAX_STAGED_ATTACHMENTS }));
+ return;
+ }
+ if (projectedTotalBytes + file.size > MAX_TOTAL_ATTACHMENT_BYTES) {
+ alert(I18n.t('chat.totalAttachmentsTooBig', { size: (MAX_TOTAL_ATTACHMENT_BYTES / 1024 / 1024).toFixed(0) }));
+ return;
+ }
+ projectedCount += 1;
+ projectedTotalBytes += file.size;
+ const reader = new FileReader();
+ let resolveRead;
+ const readPromise = new Promise((resolve) => { resolveRead = resolve; });
+ pendingAttachmentReads.push(readPromise);
+ const finalizeRead = () => {
+ const idx = pendingAttachmentReads.indexOf(readPromise);
+ if (idx !== -1) pendingAttachmentReads.splice(idx, 1);
+ resolveRead();
+ };
+ reader.onload = function(e) {
+ const dataUrl = e.target.result;
+ const commaIdx = dataUrl.indexOf(',');
+ const meta = dataUrl.substring(0, commaIdx);
+ const base64 = dataUrl.substring(commaIdx + 1);
+ const parsedType = meta.replace('data:', '').replace(';base64', '');
+ const mediaType = (!parsedType || parsedType === 'application/octet-stream') ? mimeType : parsedType;
+ stagedAttachments.push({
+ kind: mediaType.startsWith('image/') ? 'image' : 'document',
+ mime_type: mediaType,
+ filename: file.name || null,
+ data_base64: base64,
+ preview_url: mediaType.startsWith('image/') ? dataUrl : null,
+ size_bytes: file.size,
+ size_label: formatAttachmentSize(file.size),
+ });
+ renderAttachmentPreviews();
+ finalizeRead();
+ };
+ reader.onerror = function() {
+ alert(I18n.t('error.unknown'));
+ finalizeRead();
+ };
+ reader.readAsDataURL(file);
+ });
+}
+
+(function wireAttachmentUI() {
+ const attachBtn = document.getElementById('attach-btn');
+ if (attachBtn) {
+ attachBtn.addEventListener('click', () => {
+ const input = document.getElementById('image-file-input');
+ if (input) input.click();
+ });
+ }
+ const fileInput = document.getElementById('image-file-input');
+ if (fileInput) {
+ fileInput.addEventListener('change', (e) => {
+ handleAttachmentFiles(e.target.files);
+ e.target.value = '';
+ });
+ }
+ const chatInputEl = document.getElementById('chat-input');
+ if (chatInputEl) {
+ chatInputEl.addEventListener('paste', (e) => {
+ const items = (e.clipboardData || e.originalEvent.clipboardData).items;
+ for (let i = 0; i < items.length; i++) {
+ if (items[i].kind === 'file' && items[i].type.startsWith('image/')) {
+ const file = items[i].getAsFile();
+ if (file) handleAttachmentFiles([file]);
+ }
+ }
+ });
+ }
+})();
+
+// --- User message attachment parsing/rendering ---
+
+function decodeXmlText(text) {
+ return text
+ .replace(/"/g, '"')
+ .replace(/'/g, "'")
+ .replace(/</g, '<')
+ .replace(/>/g, '>')
+ .replace(/&/g, '&');
+}
+
+function parseAttachmentAttributes(rawAttrs) {
+ const attrs = {};
+ const attrRegex = /(\w+)="([^"]*)"/g;
+ let match;
+ while ((match = attrRegex.exec(rawAttrs)) !== null) {
+ attrs[match[1]] = decodeXmlText(match[2]);
+ }
+ return attrs;
+}
+
+// Extract the plain text body and any `…` payload
+// from a user turn's `user_input`. Messages carry their persisted attachment
+// index inline so chat history can re-render file cards without a DB roundtrip.
+// Only strip the trailing block when at least one `` element is
+// parsed out of it — otherwise the user's raw text happens to end in
+// `…` and we must leave it intact.
+function parseUserMessageContent(content) {
+ const match = content.match(/^([\s\S]*?)(?:\n\n)?([\s\S]*?)<\/attachments>\s*$/);
+ if (!match) {
+ return { text: content, attachments: [], copyText: content };
+ }
+
+ const block = match[2];
+ const attachments = [];
+ const attachmentRegex = /]*)>([\s\S]*?)<\/attachment>/g;
+ let attachmentMatch;
+ while ((attachmentMatch = attachmentRegex.exec(block)) !== null) {
+ const attrs = parseAttachmentAttributes(attachmentMatch[1]);
+ attachments.push({
+ kind: attrs.type === 'image' ? 'image' : 'document',
+ filename: attrs.filename || 'attachment',
+ mime_type: attrs.mime || '',
+ size_label: attrs.size || '',
+ preview_text: decodeXmlText(attachmentMatch[2].trim()),
+ preview_url: null,
+ });
+ }
+
+ if (attachments.length === 0) {
+ return { text: content, attachments: [], copyText: content };
+ }
+
+ const text = match[1].replace(/\s+$/, '');
+ const copyParts = [];
+ if (text) copyParts.push(text);
+ attachments.forEach((att) => {
+ const suffix = [att.mime_type, att.size_label].filter(Boolean).join(' • ');
+ copyParts.push(suffix ? `[Attachment] ${att.filename} (${suffix})` : `[Attachment] ${att.filename}`);
+ });
+
+ return { text, attachments, copyText: copyParts.join('\n') };
+}
+
+function renderMessageAttachments(container, attachments) {
+ if (!attachments || attachments.length === 0) return;
+ const strip = document.createElement('div');
+ strip.className = 'message-attachments';
+ attachments.forEach((att) => {
+ if (att.kind === 'image' && att.preview_url) {
+ const image = document.createElement('img');
+ image.className = 'message-attachment-image';
+ image.src = att.preview_url;
+ image.alt = att.filename || 'Attached image';
+ strip.appendChild(image);
+ return;
+ }
+ appendAttachmentFileCard(
+ strip,
+ 'message-attachment-file',
+ 'message-attachment-file-name',
+ 'message-attachment-file-meta',
+ att.filename || 'attachment',
+ [att.mime_type, att.size_label].filter(Boolean).join(' • ')
+ );
+ });
+ container.appendChild(strip);
+}
diff --git a/crates/ironclaw_skills/src/registry.rs b/crates/ironclaw_skills/src/registry.rs
index 57f3f7d49e2..0bb8f94f214 100644
--- a/crates/ironclaw_skills/src/registry.rs
+++ b/crates/ironclaw_skills/src/registry.rs
@@ -14,8 +14,9 @@
//! Uses async I/O throughout to avoid blocking the tokio runtime.
use std::collections::HashSet;
-use std::path::{Path, PathBuf};
+use std::path::{Component, Path, PathBuf};
+use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use crate::gating;
@@ -202,6 +203,56 @@ pub struct SkillRegistry {
max_scan_depth: usize,
}
+/// Additional bundle file to materialize alongside `SKILL.md` during install.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InstallFile {
+ pub relative_path: PathBuf,
+ pub contents: Vec,
+}
+
+/// Persisted metadata about how a skill bundle was installed.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InstalledSkillMetadata {
+ #[serde(default)]
+ pub source_url: Option,
+ #[serde(default)]
+ pub source_subdir: Option,
+}
+
+const INSTALL_METADATA_FILE: &str = ".ironclaw-install.json";
+
+fn validate_install_relative_path(path: &Path) -> Result {
+ if path.as_os_str().is_empty() || path.is_absolute() {
+ return Err(SkillRegistryError::WriteError {
+ path: path.display().to_string(),
+ reason: "install bundle path must be a non-empty relative path".to_string(),
+ });
+ }
+
+ let mut normalized = PathBuf::new();
+ for component in path.components() {
+ match component {
+ Component::Normal(part) => normalized.push(part),
+ Component::CurDir => {}
+ Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
+ return Err(SkillRegistryError::WriteError {
+ path: path.display().to_string(),
+ reason: "install bundle path may not escape the skill directory".to_string(),
+ });
+ }
+ }
+ }
+
+ if normalized.as_os_str().is_empty() {
+ return Err(SkillRegistryError::WriteError {
+ path: path.display().to_string(),
+ reason: "install bundle path normalized to empty".to_string(),
+ });
+ }
+
+ Ok(normalized)
+}
+
impl SkillRegistry {
/// Create a new skill registry.
pub fn new(user_dir: PathBuf) -> Self {
@@ -573,11 +624,23 @@ impl SkillRegistry {
/// This is a static method so it doesn't borrow `&self`, allowing callers
/// to drop their registry lock before awaiting.
pub async fn prepare_install_to_disk(
- user_dir: &Path,
+ install_dir: &Path,
skill_name: &str,
normalized_content: &str,
) -> Result<(String, LoadedSkill), SkillRegistryError> {
- let skill_dir = user_dir.join(skill_name);
+ Self::prepare_install_bundle_to_disk(install_dir, skill_name, normalized_content, &[], None)
+ .await
+ }
+
+ /// Perform the disk I/O and loading for a skill bundle install.
+ pub async fn prepare_install_bundle_to_disk(
+ install_dir: &Path,
+ skill_name: &str,
+ normalized_content: &str,
+ extra_files: &[InstallFile],
+ install_metadata: Option<&InstalledSkillMetadata>,
+ ) -> Result<(String, LoadedSkill), SkillRegistryError> {
+ let skill_dir = install_dir.join(skill_name);
tokio::fs::create_dir_all(&skill_dir).await.map_err(|e| {
SkillRegistryError::WriteError {
path: skill_dir.display().to_string(),
@@ -593,8 +656,43 @@ impl SkillRegistry {
reason: e.to_string(),
})?;
+ for file in extra_files {
+ let relative_path = validate_install_relative_path(&file.relative_path)?;
+ let absolute_path = skill_dir.join(&relative_path);
+ if let Some(parent) = absolute_path.parent() {
+ tokio::fs::create_dir_all(parent).await.map_err(|e| {
+ SkillRegistryError::WriteError {
+ path: parent.display().to_string(),
+ reason: e.to_string(),
+ }
+ })?;
+ }
+ tokio::fs::write(&absolute_path, &file.contents)
+ .await
+ .map_err(|e| SkillRegistryError::WriteError {
+ path: absolute_path.display().to_string(),
+ reason: e.to_string(),
+ })?;
+ }
+
+ if let Some(metadata) = install_metadata {
+ let meta_path = skill_dir.join(INSTALL_METADATA_FILE);
+ let meta_json = serde_json::to_vec_pretty(metadata).map_err(|e| {
+ SkillRegistryError::WriteError {
+ path: meta_path.display().to_string(),
+ reason: format!("failed to serialize install metadata: {e}"),
+ }
+ })?;
+ tokio::fs::write(&meta_path, meta_json).await.map_err(|e| {
+ SkillRegistryError::WriteError {
+ path: meta_path.display().to_string(),
+ reason: e.to_string(),
+ }
+ })?;
+ }
+
// Load by re-reading from disk (validates round-trip)
- let source = SkillSource::User(skill_dir);
+ let source = SkillSource::Installed(skill_dir);
load_and_validate_skill(&skill_path, SkillTrust::Installed, source).await
}
@@ -670,16 +768,13 @@ impl SkillRegistry {
///
/// Call after `validate_remove` and before `commit_remove`.
pub async fn delete_skill_files(path: &Path) -> Result<(), SkillRegistryError> {
- let skill_md = path.join("SKILL.md");
- if tokio::fs::try_exists(&skill_md).await.unwrap_or(false) {
- tokio::fs::remove_file(&skill_md).await.map_err(|e| {
- SkillRegistryError::WriteError {
- path: skill_md.display().to_string(),
+ if tokio::fs::try_exists(path).await.unwrap_or(false) {
+ tokio::fs::remove_dir_all(path)
+ .await
+ .map_err(|e| SkillRegistryError::WriteError {
+ path: path.display().to_string(),
reason: e.to_string(),
- }
- })?;
- // Remove the directory if empty
- let _ = tokio::fs::remove_dir(path).await;
+ })?;
}
Ok(())
}
@@ -734,6 +829,13 @@ impl SkillRegistry {
pub fn install_target_dir(&self) -> &Path {
self.installed_dir.as_deref().unwrap_or(&self.user_dir)
}
+
+ /// Load persisted install metadata for a skill directory, if present.
+ pub async fn read_install_metadata(path: &Path) -> Option {
+ let meta_path = path.join(INSTALL_METADATA_FILE);
+ let bytes = tokio::fs::read(&meta_path).await.ok()?;
+ serde_json::from_slice(&bytes).ok()
+ }
}
/// Load and validate a single SKILL.md file from disk.
@@ -1110,6 +1212,74 @@ mod tests {
assert!(skill_path.exists());
}
+ #[tokio::test]
+ async fn test_prepare_install_bundle_to_disk_writes_extra_files_and_metadata() {
+ let dir = tempfile::tempdir().unwrap();
+ let content =
+ "---\nname: bundle-install\ndescription: Installed skill\n---\n\nInstalled prompt.\n";
+ let extra_files = vec![
+ InstallFile {
+ relative_path: PathBuf::from("requirements.txt"),
+ contents: b"requests>=2.32.5\n".to_vec(),
+ },
+ InstallFile {
+ relative_path: PathBuf::from("scripts/run.py"),
+ contents: b"print('ok')\n".to_vec(),
+ },
+ ];
+ let metadata = InstalledSkillMetadata {
+ source_url: Some("https://github.com/Pika-Labs/Pika-Skills".to_string()),
+ source_subdir: Some("pikastream-video-meeting".to_string()),
+ };
+
+ let (name, loaded) = SkillRegistry::prepare_install_bundle_to_disk(
+ dir.path(),
+ "bundle-install",
+ content,
+ &extra_files,
+ Some(&metadata),
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(name, "bundle-install");
+ assert_eq!(loaded.manifest.name, "bundle-install");
+ assert!(matches!(loaded.source, SkillSource::Installed(_)));
+ assert!(dir.path().join("bundle-install/requirements.txt").exists());
+ assert!(dir.path().join("bundle-install/scripts/run.py").exists());
+
+ let stored = SkillRegistry::read_install_metadata(&dir.path().join("bundle-install"))
+ .await
+ .expect("install metadata");
+ assert_eq!(stored, metadata);
+ }
+
+ #[tokio::test]
+ async fn test_prepare_install_bundle_to_disk_rejects_path_escape() {
+ let dir = tempfile::tempdir().unwrap();
+ let content = "---\nname: bundle-install\n---\n\nInstalled prompt.\n";
+ let extra_files = vec![InstallFile {
+ relative_path: PathBuf::from("../escape.sh"),
+ contents: b"echo no\n".to_vec(),
+ }];
+
+ let err = SkillRegistry::prepare_install_bundle_to_disk(
+ dir.path(),
+ "bundle-install",
+ content,
+ &extra_files,
+ None,
+ )
+ .await
+ .unwrap_err();
+
+ assert!(
+ err.to_string()
+ .contains("may not escape the skill directory"),
+ "{err}"
+ );
+ }
+
#[test]
fn test_resolve_install_content_prefers_requested_slug_for_invalid_name() {
let content = "---\nname: Mortgage Calculator\ndescription: Installed skill\n---\n\nInstalled prompt.\n";
diff --git a/crates/ironclaw_skills/src/v2.rs b/crates/ironclaw_skills/src/v2.rs
index 27f0f39bbf4..0f9226ff94e 100644
--- a/crates/ironclaw_skills/src/v2.rs
+++ b/crates/ironclaw_skills/src/v2.rs
@@ -183,6 +183,12 @@ pub struct V2SkillMetadata {
/// SHA-256 hash of the prompt content.
#[serde(default)]
pub content_hash: String,
+ /// Installed bundle path on disk when the skill came from a filesystem bundle.
+ #[serde(default)]
+ pub bundle_path: Option,
+ /// Original source URL when the install came from a remote bundle.
+ #[serde(default)]
+ pub source_url: Option,
}
fn default_version() -> u32 {
@@ -276,6 +282,8 @@ mod tests {
repaired_at: None,
}],
content_hash: "sha256:abc".to_string(),
+ bundle_path: Some("/tmp/skills/test-skill".to_string()),
+ source_url: Some("https://github.com/example/test-skill".to_string()),
};
let json = serde_json::to_string(&meta).expect("serialize");
@@ -285,6 +293,14 @@ mod tests {
assert_eq!(parsed.version, 3);
assert_eq!(parsed.source, V2SkillSource::Extracted);
assert_eq!(parsed.code_snippets.len(), 1);
+ assert_eq!(
+ parsed.bundle_path.as_deref(),
+ Some("/tmp/skills/test-skill")
+ );
+ assert_eq!(
+ parsed.source_url.as_deref(),
+ Some("https://github.com/example/test-skill")
+ );
assert_eq!(parsed.metrics.success_count, 4);
assert_eq!(parsed.parent_version, Some(2));
assert_eq!(parsed.revisions.len(), 1);
@@ -303,5 +319,7 @@ mod tests {
assert!((parsed.metrics.confidence() - 1.0).abs() < f64::EPSILON);
assert!(parsed.revisions.is_empty());
assert!(parsed.repairs.is_empty());
+ assert_eq!(parsed.bundle_path, None);
+ assert_eq!(parsed.source_url, None);
}
}
diff --git a/src/agent/agent_loop.rs b/src/agent/agent_loop.rs
index 6944fa179e0..fddeccc8456 100644
--- a/src/agent/agent_loop.rs
+++ b/src/agent/agent_loop.rs
@@ -40,6 +40,8 @@ use ironclaw_skills::SkillRegistry;
/// `Done` after a pause (e.g. while awaiting tool approval) is incorrect because
/// the thread is not in a terminal state, and would also trip the web UI's
/// missing-response safety net (see #2079).
+pub(crate) const BRIDGE_PENDING_SENTINEL: &str = "\u{0}__bridge_pending__";
+
#[derive(Debug)]
pub(crate) enum HandleOutcome {
/// Shutdown signal (e.g. `/quit`). Run loop should break.
@@ -60,6 +62,7 @@ impl HandleOutcome {
fn from_legacy(opt: Option) -> Self {
match opt {
None => HandleOutcome::Shutdown,
+ Some(s) if s == BRIDGE_PENDING_SENTINEL => HandleOutcome::Pending,
Some(s) if s.is_empty() => HandleOutcome::NoResponse,
Some(s) => HandleOutcome::Respond(s),
}
diff --git a/src/agent/attachments.rs b/src/agent/attachments.rs
index cb3e9b56f4b..5c85e6a2a51 100644
--- a/src/agent/attachments.rs
+++ b/src/agent/attachments.rs
@@ -71,6 +71,11 @@ fn escape_xml_text(s: &str) -> String {
fn format_attachment(index: usize, att: &IncomingAttachment) -> String {
let filename = escape_xml_attr(att.filename.as_deref().unwrap_or("unknown"));
let mime = escape_xml_attr(&att.mime_type);
+ let project_path_attr = att
+ .local_path
+ .as_deref()
+ .map(|path| format!(" project_path=\"{}\"", escape_xml_attr(path)))
+ .unwrap_or_default();
match &att.kind {
AttachmentKind::Audio => {
@@ -78,14 +83,21 @@ fn format_attachment(index: usize, att: &IncomingAttachment) -> String {
.duration_secs
.map(|d| format!(" duration=\"{d}s\""))
.unwrap_or_default();
+ let size_attr = att
+ .size_bytes
+ .map(|s| format!(" size=\"{}\"", format_size(s)))
+ .unwrap_or_default();
- let body = match &att.extracted_text {
- Some(text) => format!("Transcript: {}", escape_xml_text(text)),
- None => "Audio transcript unavailable.".to_string(),
- };
+ let body = format_attachment_body(
+ att.local_path.as_deref(),
+ match &att.extracted_text {
+ Some(text) => format!("Transcript: {}", escape_xml_text(text)),
+ None => "Audio transcript unavailable.".to_string(),
+ },
+ );
format!(
- "\n\
+ "\n\
{body}\n\
"
)
@@ -96,29 +108,47 @@ fn format_attachment(index: usize, att: &IncomingAttachment) -> String {
.map(|s| format!(" size=\"{}\"", format_size(s)))
.unwrap_or_default();
- let body = if att.data.is_empty() {
- "[Image attached — visual content not available in this conversation.]"
- } else {
+ // Pick the right prompt for the agent based on whether the
+ // image bytes reached the model. Engine v2 persists the file to
+ // disk but leaves `data` populated so `augment_with_attachments`
+ // can emit a multimodal `image_parts` entry — that's the path
+ // that actually sends the image to the LLM. An empty `data`
+ // with a `local_path` set can only happen if a downstream
+ // caller cleared the buffer (or if the channel elided it); in
+ // that case the model doesn't see the pixels and must go
+ // through the project file path instead.
+ let body = if !att.data.is_empty() {
"[Image attached — you can already see this image directly in the conversation. Do NOT use image_analyze or try to find this file on disk — it exists only in memory. Analyze it using your vision capabilities.]"
+ } else if att.local_path.is_some() {
+ "[Image attached — the raw bytes are not in this turn's multimodal context, but the file has been persisted at the project file path above. Reference that path when you need the image.]"
+ } else {
+ "[Image attached — visual content not available in this conversation.]"
};
+ let body = format_attachment_body(att.local_path.as_deref(), body.to_string());
format!(
- "\n\
+ "\n\
{body}\n\
"
)
}
AttachmentKind::Document => {
let body: String = match &att.extracted_text {
- Some(text) => escape_xml_text(text),
+ Some(text) => {
+ format_attachment_body(att.local_path.as_deref(), escape_xml_text(text))
+ }
None => {
let size_info = att
.size_bytes
.map(|s| format!(" size=\"{}\"", format_size(s)))
.unwrap_or_default();
+ let body = format_attachment_body(
+ att.local_path.as_deref(),
+ "[Document attached — text extraction unavailable]".to_string(),
+ );
return format!(
- "\n\
- [Document attached — text extraction unavailable]\n\
+ "\n\
+ {body}\n\
"
);
}
@@ -130,7 +160,7 @@ fn format_attachment(index: usize, att: &IncomingAttachment) -> String {
.unwrap_or_default();
format!(
- "\n\
+ "\n\
{body}\n\
"
)
@@ -138,6 +168,17 @@ fn format_attachment(index: usize, att: &IncomingAttachment) -> String {
}
}
+fn format_attachment_body(local_path: Option<&str>, content: String) -> String {
+ match local_path {
+ Some(path) => format!(
+ "Saved to project file: {}\n{}",
+ escape_xml_text(path),
+ content
+ ),
+ None => content,
+ }
+}
+
fn format_size(bytes: u64) -> String {
if bytes < 1024 {
format!("{bytes}B")
@@ -161,6 +202,7 @@ mod tests {
size_bytes: None,
source_url: None,
storage_key: None,
+ local_path: None,
extracted_text: None,
data: vec![],
duration_secs: None,
@@ -176,14 +218,18 @@ mod tests {
fn audio_with_transcript() {
let mut att = make_attachment(AttachmentKind::Audio);
att.filename = Some("voice.ogg".to_string());
+ att.mime_type = "audio/ogg".to_string();
att.extracted_text = Some("Hello, can you help me?".to_string());
att.duration_secs = Some(5);
+ att.size_bytes = Some(2048);
let result = augment_with_attachments("hi", &[att]).unwrap();
assert!(result.text.starts_with("hi\n\n"));
assert!(result.text.contains("type=\"audio\""));
assert!(result.text.contains("filename=\"voice.ogg\""));
+ assert!(result.text.contains("mime=\"audio/ogg\""));
assert!(result.text.contains("duration=\"5s\""));
+ assert!(result.text.contains("size=\"2KB\""));
assert!(result.text.contains("Transcript: Hello, can you help me?"));
assert!(result.text.ends_with(""));
assert!(result.image_parts.is_empty());
@@ -242,6 +288,26 @@ mod tests {
}
}
+ #[test]
+ fn attachment_with_project_file_path_is_rendered() {
+ let mut att = make_attachment(AttachmentKind::Document);
+ att.filename = Some("brief.txt".to_string());
+ att.mime_type = "text/plain".to_string();
+ att.local_path = Some(".ironclaw/attachments/alice/project/2026-04-12/brief.txt".into());
+ att.extracted_text = Some("Hello from disk".to_string());
+
+ let result = augment_with_attachments("review", &[att]).unwrap();
+ assert!(
+ result.text.contains(
+ "project_path=\".ironclaw/attachments/alice/project/2026-04-12/brief.txt\""
+ )
+ );
+ assert!(result.text.contains(
+ "Saved to project file: .ironclaw/attachments/alice/project/2026-04-12/brief.txt"
+ ));
+ assert!(result.text.contains("Hello from disk"));
+ }
+
#[test]
fn image_url_includes_detail_auto() {
let mut att = make_attachment(AttachmentKind::Image);
diff --git a/src/agent/mod.rs b/src/agent/mod.rs
index 5f3d305e96f..c1e201a5c4f 100644
--- a/src/agent/mod.rs
+++ b/src/agent/mod.rs
@@ -34,6 +34,7 @@ pub mod undo;
pub(crate) use agent_loop::truncate_for_preview;
pub use agent_loop::{Agent, AgentDeps};
+pub(crate) use attachments::augment_with_attachments;
pub use compaction::{CompactionResult, ContextCompactor};
pub use context_monitor::{CompactionStrategy, ContextBreakdown, ContextMonitor};
pub(crate) use dispatcher::strip_suggestions;
diff --git a/src/agent/thread_ops.rs b/src/agent/thread_ops.rs
index 38177d4c01f..4c8c9c1deeb 100644
--- a/src/agent/thread_ops.rs
+++ b/src/agent/thread_ops.rs
@@ -538,8 +538,19 @@ impl Agent {
}
}
+ // Attachments can carry the only user-visible payload (for example,
+ // a files-only send with empty chat text), so validation and policy
+ // checks must run against the augmented content that will actually
+ // enter the turn rather than the raw text field alone.
+ let augmented =
+ crate::agent::attachments::augment_with_attachments(content, &message.attachments);
+ let (effective_content, image_parts) = match &augmented {
+ Some(result) => (result.text.as_str(), result.image_parts.clone()),
+ None => (content, Vec::new()),
+ };
+
// Safety validation for user input
- let validation = self.safety().validate_input(content);
+ let validation = self.safety().validate_input(effective_content);
if !validation.is_valid {
let details = validation
.errors
@@ -553,7 +564,7 @@ impl Agent {
)));
}
- let violations = self.safety().check_policy(content);
+ let violations = self.safety().check_policy(effective_content);
if violations
.iter()
.any(|rule| rule.action == ironclaw_safety::PolicyAction::Block)
@@ -564,7 +575,7 @@ impl Agent {
// Scan inbound messages for secrets (API keys, tokens).
// Catching them here prevents the LLM from echoing them back, which
// would trigger the outbound leak detector and create error loops.
- if let Some(warning) = self.safety().scan_inbound_for_secrets(content) {
+ if let Some(warning) = self.safety().scan_inbound_for_secrets(effective_content) {
tracing::warn!(
user = %message.user_id,
channel = %message.channel,
@@ -641,14 +652,6 @@ impl Agent {
);
}
- // Augment content with attachment context (transcripts, metadata, images)
- let augmented =
- crate::agent::attachments::augment_with_attachments(content, &message.attachments);
- let (effective_content, image_parts) = match &augmented {
- Some(result) => (result.text.as_str(), result.image_parts.clone()),
- None => (content, Vec::new()),
- };
-
// Start the turn and get messages
let (turn_messages, turn_number, turn_started_at) = {
let mut sess = session.lock().await;
@@ -3581,6 +3584,76 @@ mod tests {
)));
}
+ #[tokio::test]
+ async fn test_process_user_input_allows_attachment_only_message() {
+ use crate::agent::session::{Session, Thread};
+ use crate::channels::{AttachmentKind, IncomingAttachment, IncomingMessage};
+ use uuid::Uuid;
+
+ let (agent, _statuses) = make_thread_ops_test_agent().await;
+ let session_id = Uuid::new_v4();
+ let thread_id = Uuid::new_v4();
+ let thread = Thread::with_id(thread_id, session_id, Some("test"));
+
+ let mut sess = Session::new("test-user");
+ sess.threads.insert(thread_id, thread);
+ let session = Arc::new(TokioMutex::new(sess));
+
+ let message = IncomingMessage::new("test", "test-user", "").with_attachments(vec![
+ IncomingAttachment {
+ id: "att_1".to_string(),
+ kind: AttachmentKind::Document,
+ mime_type: "text/plain".to_string(),
+ filename: Some("files-only.txt".to_string()),
+ size_bytes: Some(41),
+ source_url: None,
+ storage_key: None,
+ local_path: None,
+ extracted_text: Some("Files-only regression attachment.".to_string()),
+ data: b"Files-only regression attachment.".to_vec(),
+ duration_secs: None,
+ },
+ ]);
+
+ let result = agent
+ .process_user_input(
+ &message,
+ agent.tenant_ctx("test-user").await,
+ Arc::clone(&session),
+ thread_id,
+ "",
+ )
+ .await
+ .expect("attachment-only message handled");
+
+ match result {
+ SubmissionResult::Response { content } => {
+ assert_eq!(content.to_ascii_lowercase(), "ok")
+ }
+ other => panic!("expected response result, got {other:?}"),
+ }
+
+ let sess = session.lock().await;
+ let thread = sess.threads.get(&thread_id).expect("thread exists");
+ let turn = thread.turns.last().expect("turn should be created");
+ assert!(
+ turn.user_input.contains(""),
+ "{}",
+ turn.user_input
+ );
+ assert!(
+ turn.user_input.contains("files-only.txt"),
+ "{}",
+ turn.user_input
+ );
+ assert!(
+ turn.user_input
+ .contains("Files-only regression attachment."),
+ "{}",
+ turn.user_input
+ );
+ }
+
#[tokio::test]
async fn test_switch_thread_emits_history_with_pending_approval() {
use crate::agent::session::{PendingApproval, Thread};
diff --git a/src/bridge/auth_manager.rs b/src/bridge/auth_manager.rs
index 6e1961c6c6f..31e7503ff4c 100644
--- a/src/bridge/auth_manager.rs
+++ b/src/bridge/auth_manager.rs
@@ -188,6 +188,37 @@ impl AuthManager {
}
}
+ async fn ensure_extension_ready_for_execution(
+ ext_mgr: &crate::extensions::ExtensionManager,
+ extension_name: &str,
+ user_id: &str,
+ ) -> Result {
+ match ext_mgr
+ .ensure_extension_ready(
+ extension_name,
+ user_id,
+ crate::extensions::EnsureReadyIntent::UseCapability,
+ )
+ .await
+ {
+ Err(ExtensionError::NotInstalled(_)) => {
+ tracing::debug!(
+ extension = %extension_name,
+ user_id = %user_id,
+ "Extension not installed for capability use; retrying via explicit activate path"
+ );
+ ext_mgr
+ .ensure_extension_ready(
+ extension_name,
+ user_id,
+ crate::extensions::EnsureReadyIntent::ExplicitActivate,
+ )
+ .await
+ }
+ other => other,
+ }
+ }
+
fn settings_store(&self) -> Option<&dyn crate::db::SettingsStore> {
self.tools
.as_ref()
@@ -338,21 +369,72 @@ impl AuthManager {
Err(_) => return ToolReadiness::Ready,
}
};
- match ext_mgr
- .ensure_extension_ready(
- &ext_name,
- user_id,
- crate::extensions::EnsureReadyIntent::UseCapability,
- )
+ self.readiness_from_extension_result(
+ &ext_name,
+ user_id,
+ ext_mgr
+ .ensure_extension_ready(
+ &ext_name,
+ user_id,
+ crate::extensions::EnsureReadyIntent::UseCapability,
+ )
+ .await,
+ )
+ .await
+ }
+
+ /// Prepare an extension-backed capability for immediate execution.
+ ///
+ /// Unlike [`check_tool_readiness`], this path may promote a latent
+ /// registry-backed extension into the installed state because the caller
+ /// is handling a concrete user-requested action, not merely listing or
+ /// filtering available actions.
+ pub async fn prepare_tool_for_execution(
+ &self,
+ tool_name: &str,
+ user_id: &str,
+ ) -> ToolReadiness {
+ let ext_mgr = match self.extension_manager.as_ref() {
+ Some(mgr) => mgr,
+ None => return ToolReadiness::Ready,
+ };
+
+ let ext_name = if let Some(tools) = self.tools.as_ref() {
+ if let Some(name) = tools.provider_extension_for_tool(tool_name).await {
+ name
+ } else {
+ match canonicalize_extension_name(tool_name) {
+ Ok(name) => name,
+ Err(_) => return ToolReadiness::Ready,
+ }
+ }
+ } else {
+ match canonicalize_extension_name(tool_name) {
+ Ok(name) => name,
+ Err(_) => return ToolReadiness::Ready,
+ }
+ };
+
+ let result = Self::ensure_extension_ready_for_execution(ext_mgr, &ext_name, user_id).await;
+
+ self.readiness_from_extension_result(&ext_name, user_id, result)
.await
- {
+ }
+
+ async fn readiness_from_extension_result(
+ &self,
+ ext_name: &str,
+ user_id: &str,
+ result: Result,
+ ) -> ToolReadiness {
+ match result {
Ok(crate::extensions::EnsureReadyOutcome::Ready { .. }) => ToolReadiness::Ready,
Ok(crate::extensions::EnsureReadyOutcome::NeedsAuth {
auth,
credential_name,
..
}) => {
- let credential_name = credential_name.unwrap_or_else(|| ext_name.clone());
+ let credential_name = credential_name.unwrap_or_else(|| ext_name.to_string());
let described = self
.describe_missing_credential(&credential_name, user_id)
.await;
@@ -446,52 +528,50 @@ impl AuthManager {
let ext_mgr = self.extension_manager.as_ref()?;
let latent = ext_mgr.latent_provider_action(action_name, user_id).await?;
- Some(
- match ext_mgr
- .ensure_extension_ready(
- &latent.provider_extension,
- user_id,
- crate::extensions::EnsureReadyIntent::UseCapability,
- )
- .await
- {
- Ok(crate::extensions::EnsureReadyOutcome::Ready { .. }) => {
- let available_actions = ext_mgr
- .provider_action_names(&latent.provider_extension)
- .await;
- if available_actions.contains(&latent.action_name) {
- Ok(LatentActionExecution::RetryRegisteredAction {
- resolved_action: latent.action_name,
- })
- } else {
- Ok(LatentActionExecution::ProviderReady {
- provider_extension: latent.provider_extension,
- available_actions,
- })
- }
- }
- Ok(crate::extensions::EnsureReadyOutcome::NeedsAuth {
- auth,
- credential_name,
- ..
- }) => Ok(LatentActionExecution::NeedsAuth {
- credential_name: CredentialName::from_trusted(
- credential_name.unwrap_or(latent.provider_extension),
- ),
- instructions: auth
- .instructions()
- .unwrap_or("Complete authentication to continue.")
- .to_string(),
- auth_url: crate::auth::oauth::sanitize_auth_url(auth.auth_url()),
- }),
- Ok(crate::extensions::EnsureReadyOutcome::NeedsSetup { instructions, .. }) => {
- Ok(LatentActionExecution::NeedsSetup {
- message: instructions,
+ let readiness = Self::ensure_extension_ready_for_execution(
+ ext_mgr,
+ &latent.provider_extension,
+ user_id,
+ )
+ .await;
+
+ Some(match readiness {
+ Ok(crate::extensions::EnsureReadyOutcome::Ready { .. }) => {
+ let available_actions = ext_mgr
+ .provider_action_names(&latent.provider_extension)
+ .await;
+ if available_actions.contains(&latent.action_name) {
+ Ok(LatentActionExecution::RetryRegisteredAction {
+ resolved_action: latent.action_name,
+ })
+ } else {
+ Ok(LatentActionExecution::ProviderReady {
+ provider_extension: latent.provider_extension,
+ available_actions,
})
}
- Err(err) => Err(err),
- },
- )
+ }
+ Ok(crate::extensions::EnsureReadyOutcome::NeedsAuth {
+ auth,
+ credential_name,
+ ..
+ }) => Ok(LatentActionExecution::NeedsAuth {
+ credential_name: CredentialName::from_trusted(
+ credential_name.unwrap_or(latent.provider_extension),
+ ),
+ instructions: auth
+ .instructions()
+ .unwrap_or("Complete authentication to continue.")
+ .to_string(),
+ auth_url: crate::auth::oauth::sanitize_auth_url(auth.auth_url()),
+ }),
+ Ok(crate::extensions::EnsureReadyOutcome::NeedsSetup { instructions, .. }) => {
+ Ok(LatentActionExecution::NeedsSetup {
+ message: instructions,
+ })
+ }
+ Err(err) => Err(err),
+ })
}
async fn describe_missing_credential(
diff --git a/src/bridge/effect_adapter.rs b/src/bridge/effect_adapter.rs
index 1ddf276ee6f..6c82c3e9558 100644
--- a/src/bridge/effect_adapter.rs
+++ b/src/bridge/effect_adapter.rs
@@ -17,8 +17,9 @@ use tracing::debug;
use ironclaw_engine::{
ActionDef, ActionResult, CapabilityLease, CapabilityRegistry, EffectExecutor, EngineError,
- MountError, ThreadExecutionContext, WorkspaceMounts,
+ MountError, Store, ThreadExecutionContext, WorkspaceMounts,
};
+use ironclaw_skills::SkillRegistry;
use crate::auth::oauth::sanitize_auth_url;
use crate::bridge::auth_manager::{AuthCheckResult, AuthManager};
@@ -58,6 +59,10 @@ pub struct EffectBridgeAdapter {
/// calls bypass the recorder entirely — recorded traces end up with zero
/// `http_exchanges` and replay can't substitute responses.
http_interceptor: RwLock>>,
+ /// Engine v2 store used to mirror live-installed v1 skills into `DocType::Skill`.
+ engine_store: RwLock>>,
+ /// V1 skill registry used to load the just-installed skill for v2 sync.
+ skill_registry: RwLock>>>,
/// Optional per-project workspace mount table. When set and a sandbox-eligible
/// tool call carries a `/project/...` path, the call is dispatched through
/// the mount backend (passthrough host filesystem in Phase 1; containerized
@@ -89,6 +94,8 @@ impl EffectBridgeAdapter {
mission_manager: RwLock::new(None),
auth_manager: RwLock::new(None),
http_interceptor: RwLock::new(None),
+ engine_store: RwLock::new(None),
+ skill_registry: RwLock::new(None),
workspace_mounts: RwLock::new(None),
capability_registry: RwLock::new(None),
}
@@ -123,6 +130,18 @@ impl EffectBridgeAdapter {
*self.http_interceptor.write().await = Some(interceptor);
}
+ /// Provide the live engine store so `skill_install` can immediately sync
+ /// installed skills into the v2 doc space.
+ pub async fn set_engine_store(&self, store: Arc) {
+ *self.engine_store.write().await = Some(store);
+ }
+
+ /// Provide the v1 skill registry so `skill_install` can resolve the
+ /// canonical installed skill after the tool returns its name.
+ pub async fn set_skill_registry(&self, registry: Arc>) {
+ *self.skill_registry.write().await = Some(registry);
+ }
+
/// Mirror the v1 dispatcher behavior for globally auto-approved tools.
pub fn with_global_auto_approve(mut self, enabled: bool) -> Self {
self.auto_approve_tools = enabled;
@@ -162,6 +181,38 @@ impl EffectBridgeAdapter {
self.mission_manager.read().await.clone()
}
+ async fn sync_skill_install_result(
+ &self,
+ output_value: &serde_json::Value,
+ project_id: ironclaw_engine::ProjectId,
+ ) -> Result<(), EngineError> {
+ let Some(skill_name) = output_value.get("name").and_then(|value| value.as_str()) else {
+ return Ok(());
+ };
+ let Some(store) = self.engine_store.read().await.clone() else {
+ return Ok(());
+ };
+ let Some(registry) = self.skill_registry.read().await.clone() else {
+ return Ok(());
+ };
+
+ let skill = {
+ let guard = registry.read().map_err(|e| EngineError::Store {
+ reason: format!("skill registry lock poisoned: {e}"),
+ })?;
+ guard.find_by_name(skill_name).cloned()
+ }
+ .ok_or_else(|| EngineError::Skill {
+ reason: format!(
+ "skill_install reported '{}', but the installed skill was not found in the registry",
+ skill_name
+ ),
+ })?;
+
+ crate::bridge::skill_migration::sync_v1_skill_to_store(&skill, &store, project_id).await?;
+ Ok(())
+ }
+
fn gate_paused(
gate_name: &str,
action_name: &str,
@@ -1247,6 +1298,84 @@ impl EffectBridgeAdapter {
return Err(err);
}
+ if (lookup_name == "tool_install" || lookup_name == "tool-install")
+ && let Some(auth_mgr) = self.auth_manager.read().await.as_ref()
+ && let Some(ext_name) = output_value.get("name").and_then(|v| v.as_str())
+ {
+ use crate::bridge::auth_manager::ToolReadiness;
+ match auth_mgr
+ .check_tool_readiness(ext_name, &context.user_id)
+ .await
+ {
+ ToolReadiness::NeedsAuth {
+ auth_url,
+ instructions,
+ credential_name,
+ } => {
+ debug!(
+ extension = %ext_name,
+ credential = %credential_name,
+ "Post-install: extension needs auth — entering auth flow"
+ );
+ return Err(Self::gate_paused(
+ "authentication",
+ action_name,
+ context.current_call_id.as_deref(),
+ parameters,
+ ironclaw_engine::ResumeKind::Authentication {
+ credential_name: credential_name.clone(),
+ instructions: instructions.unwrap_or_else(|| {
+ auth_mgr.get_setup_instructions_or_default(
+ credential_name.as_str(),
+ )
+ }),
+ auth_url: sanitize_auth_url(auth_url.as_deref()),
+ },
+ Some(output_value),
+ None,
+ ));
+ }
+ ToolReadiness::NeedsSetup { ref message } => {
+ debug!(
+ extension = %ext_name,
+ "Post-install: extension needs setup"
+ );
+ let mut enriched = output_value.clone();
+ if let Some(obj) = enriched.as_object_mut() {
+ obj.insert(
+ "auth_status".to_string(),
+ serde_json::json!("needs_setup"),
+ );
+ obj.insert(
+ "setup_message".to_string(),
+ serde_json::Value::String(message.clone()),
+ );
+ }
+ return Ok(ActionResult {
+ call_id: context
+ .current_call_id
+ .clone()
+ .unwrap_or_else(|| synthetic_action_call_id(action_name)),
+ action_name: action_name.to_string(),
+ output: enriched,
+ is_error: false,
+ duration,
+ });
+ }
+ ToolReadiness::Ready => {
+ debug!(
+ extension = %ext_name,
+ "Post-install: extension ready — no auth needed"
+ );
+ }
+ }
+ }
+
+ if lookup_name == "skill_install" {
+ self.sync_skill_install_result(&output_value, context.project_id)
+ .await?;
+ }
+
Ok(ActionResult {
call_id: context
.current_call_id
@@ -3562,6 +3691,117 @@ mod tests {
assert!(actions.iter().any(|action| action.name == "latent_tool"));
}
+ #[tokio::test]
+ async fn skill_install_syncs_installed_skill_into_v2_store() {
+ use ironclaw_skills::v2::V2SkillMetadata;
+
+ struct SkillInstallStub;
+
+ #[async_trait]
+ impl Tool for SkillInstallStub {
+ fn name(&self) -> &str {
+ "skill_install"
+ }
+
+ fn description(&self) -> &str {
+ "stub skill install"
+ }
+
+ fn parameters_schema(&self) -> serde_json::Value {
+ serde_json::json!({"type": "object"})
+ }
+
+ async fn execute(
+ &self,
+ _params: serde_json::Value,
+ _ctx: &crate::context::JobContext,
+ ) -> Result {
+ Ok(ToolOutput::success(
+ serde_json::json!({
+ "name": "pikastream-video-meeting",
+ "status": "installed",
+ }),
+ std::time::Duration::from_millis(1),
+ ))
+ }
+ }
+
+ let dir = tempfile::tempdir().expect("temp dir");
+ let mut raw_registry = SkillRegistry::new(dir.path().to_path_buf());
+ raw_registry
+ .install_skill(
+ r#"---
+name: pikastream-video-meeting
+version: "1.0.0"
+description: Pika meeting setup
+keywords:
+ - pika
+ - hangouts
+---
+# Pika Skill
+
+Use this skill to set up a Pika meeting.
+"#,
+ )
+ .await
+ .expect("install test skill");
+ let skill_registry = Arc::new(std::sync::RwLock::new(raw_registry));
+
+ let tools = Arc::new(ToolRegistry::new());
+ tools.register(Arc::new(SkillInstallStub)).await;
+
+ let adapter = EffectBridgeAdapter::new(
+ Arc::clone(&tools),
+ Arc::new(SafetyLayer::new(&ironclaw_safety::SafetyConfig {
+ max_output_length: 10_000,
+ injection_check_enabled: false,
+ })),
+ Arc::new(HookRegistry::default()),
+ );
+ let store: Arc = Arc::new(crate::bridge::store_adapter::HybridStore::new(None));
+ adapter.set_engine_store(Arc::clone(&store)).await;
+ adapter
+ .set_skill_registry(Arc::clone(&skill_registry))
+ .await;
+
+ let ctx = exec_ctx(
+ ironclaw_engine::ThreadId::new(),
+ Some("call_skill_install_sync"),
+ );
+ let result = adapter
+ .execute_action("skill_install", serde_json::json!({}), &lease(), &ctx)
+ .await
+ .expect("skill install should succeed");
+ assert!(!result.is_error);
+
+ let docs = store
+ .list_shared_memory_docs(ctx.project_id)
+ .await
+ .expect("list docs");
+ let doc = docs
+ .into_iter()
+ .find(|doc| doc.title == "skill:pikastream-video-meeting")
+ .expect("synced v2 skill doc");
+ assert_eq!(doc.doc_type, ironclaw_engine::DocType::Skill);
+ assert!(
+ doc.content.contains("Pika Skill"),
+ "doc content: {}",
+ doc.content
+ );
+
+ let metadata: V2SkillMetadata =
+ serde_json::from_value(doc.metadata).expect("valid skill metadata");
+ assert_eq!(metadata.name, "pikastream-video-meeting");
+ assert!(
+ metadata
+ .bundle_path
+ .as_deref()
+ .is_some_and(|path| path.ends_with("/pikastream-video-meeting")),
+ "bundle path: {:?}",
+ metadata.bundle_path
+ );
+ }
+
// ── Caller-level mission action tests ─────────────────────
//
// These drive execute_action("mission_create"/...) through the full
diff --git a/src/bridge/router.rs b/src/bridge/router.rs
index b3695f454de..28f02302668 100644
--- a/src/bridge/router.rs
+++ b/src/bridge/router.rs
@@ -1,5 +1,6 @@
//! Engine v2 router — handles user messages via the engine when enabled.
+use std::path::{Path, PathBuf};
use std::sync::{Arc, OnceLock};
use tokio::sync::RwLock;
@@ -60,6 +61,240 @@ fn engine_err(context: &str, e: impl std::fmt::Display) -> Error {
})
}
+const PROJECT_ATTACHMENT_DIR: &str = ".ironclaw/attachments";
+
+#[derive(Debug, Clone)]
+struct AttachmentIndexNote {
+ title: String,
+ content: String,
+ metadata: serde_json::Value,
+ tags: Vec,
+}
+
+fn sanitize_attachment_segment(raw: &str) -> String {
+ let sanitized: String = raw
+ .chars()
+ .map(|c| {
+ if c.is_ascii_alphanumeric() || matches!(c, '.' | '-' | '_') {
+ c
+ } else {
+ '_'
+ }
+ })
+ .collect();
+ let sanitized = sanitized.trim_matches('.');
+ if sanitized.is_empty() {
+ "attachment".to_string()
+ } else {
+ sanitized.to_string()
+ }
+}
+
+fn fallback_attachment_filename(index: usize, mime_type: &str) -> String {
+ let ext = crate::channels::attachment_extension_for_mime(mime_type);
+ format!("attachment-{}.{}", index + 1, ext)
+}
+
+fn attachment_project_relative_path(
+ message: &IncomingMessage,
+ project_id: ironclaw_engine::ProjectId,
+ attachment: &crate::channels::IncomingAttachment,
+ index: usize,
+) -> String {
+ let date = chrono::Utc::now().format("%Y-%m-%d").to_string();
+ let owner = sanitize_attachment_segment(&message.user_id);
+ let message_id = sanitize_attachment_segment(&message.id.to_string());
+ let filename = attachment
+ .filename
+ .as_deref()
+ .map(sanitize_attachment_segment)
+ .unwrap_or_else(|| fallback_attachment_filename(index, &attachment.mime_type));
+ format!(
+ "{}/{}/{}/{}/{}-{}",
+ PROJECT_ATTACHMENT_DIR, owner, project_id, date, message_id, filename
+ )
+}
+
+/// Collapse anything that could break a markdown title/backtick span in a
+/// user-supplied filename before embedding it. User content in attachment
+/// filenames goes straight into `# Uploaded attachment: ...` and into the
+/// note's `title`, so raw newlines / backticks / odd ASCII control codes
+/// would corrupt the agent-visible transcript (and, for a title, the
+/// searchable memory-doc row).
+fn sanitize_filename_for_display(raw: &str) -> String {
+ let mut out = String::with_capacity(raw.len());
+ for ch in raw.chars() {
+ match ch {
+ '\n' | '\r' | '\t' => out.push(' '),
+ '`' => out.push('\''),
+ c if c.is_control() => {}
+ c => out.push(c),
+ }
+ }
+ let trimmed = out.trim();
+ if trimmed.is_empty() {
+ return "attachment".to_string();
+ }
+ // Clamp so a pathological filename can't flood the agent prompt.
+ const MAX_DISPLAY_LEN: usize = 256;
+ if trimmed.len() <= MAX_DISPLAY_LEN {
+ trimmed.to_string()
+ } else {
+ let mut t = trimmed.to_string();
+ t.truncate(MAX_DISPLAY_LEN);
+ t
+ }
+}
+
+fn attachment_index_note(
+ message: &IncomingMessage,
+ attachment: &crate::channels::IncomingAttachment,
+ relative_path: &str,
+) -> AttachmentIndexNote {
+ let raw_filename = attachment.filename.as_deref().unwrap_or("attachment");
+ let filename = sanitize_filename_for_display(raw_filename);
+ let attachment_type = match attachment.kind {
+ crate::channels::AttachmentKind::Audio => "audio",
+ crate::channels::AttachmentKind::Image => "image",
+ crate::channels::AttachmentKind::Document => "document",
+ };
+ let mut content = format!(
+ "# Uploaded attachment: {filename}\n\n\
+ - Project file: `{relative_path}`\n\
+ - Attachment type: `{attachment_type}`\n\
+ - MIME type: `{}`\n\
+ - Size: `{}` bytes\n\
+ - Uploaded by: `{}` via `{}`\n",
+ attachment.mime_type,
+ attachment
+ .size_bytes
+ .unwrap_or(attachment.data.len() as u64),
+ message.user_id,
+ message.channel,
+ );
+
+ match attachment.kind {
+ crate::channels::AttachmentKind::Audio => {
+ if let Some(text) = attachment.extracted_text.as_deref() {
+ content.push_str("\n## Transcript\n\n");
+ content.push_str(text);
+ } else {
+ content.push_str("\nTranscript unavailable. The original audio file is stored at the project file path above.");
+ }
+ }
+ crate::channels::AttachmentKind::Image => {
+ content.push_str(
+ "\nThe original image file is stored at the project file path above. Use that file path in later shell or skill commands if needed.",
+ );
+ }
+ crate::channels::AttachmentKind::Document => {
+ if let Some(text) = attachment.extracted_text.as_deref() {
+ content.push_str("\n## Extracted text\n\n");
+ content.push_str(text);
+ } else {
+ content.push_str("\nText extraction unavailable. The original document file is stored at the project file path above.");
+ }
+ }
+ }
+
+ AttachmentIndexNote {
+ title: format!("attachment:{filename}"),
+ content,
+ metadata: serde_json::json!({
+ "kind": "project_attachment",
+ "attachment_type": attachment_type,
+ "filename": filename,
+ "mime_type": attachment.mime_type,
+ "project_path": relative_path,
+ "message_id": message.id.to_string(),
+ }),
+ tags: vec![
+ "attachment".to_string(),
+ "upload".to_string(),
+ attachment_type.to_string(),
+ ],
+ }
+}
+
+async fn persist_project_attachments(
+ project_root: &Path,
+ message: &IncomingMessage,
+ project_id: ironclaw_engine::ProjectId,
+ attachments: &mut [crate::channels::IncomingAttachment],
+) -> Vec {
+ let mut notes = Vec::new();
+
+ for (index, attachment) in attachments.iter_mut().enumerate() {
+ if attachment.data.is_empty() || attachment.local_path.is_some() {
+ continue;
+ }
+
+ let relative_path =
+ attachment_project_relative_path(message, project_id, attachment, index);
+ let absolute_path = project_root.join(Path::new(&relative_path));
+ let Some(parent) = absolute_path.parent() else {
+ tracing::warn!(path = %absolute_path.display(), "engine v2: attachment path had no parent");
+ continue;
+ };
+
+ if let Err(e) = tokio::fs::create_dir_all(parent).await {
+ tracing::warn!(path = %parent.display(), error = %e, "engine v2: failed to create attachment directory");
+ continue;
+ }
+
+ if let Err(e) = tokio::fs::write(&absolute_path, &attachment.data).await {
+ tracing::warn!(path = %absolute_path.display(), error = %e, "engine v2: failed to persist attachment file");
+ continue;
+ }
+
+ attachment.local_path = Some(relative_path.clone());
+ // Build the index note while `data` is still populated so the
+ // fallback to `data.len()` in `attachment_index_note` reports the
+ // real payload size when `size_bytes` wasn't pre-filled.
+ notes.push(attachment_index_note(message, attachment, &relative_path));
+ // Intentionally *don't* clear `attachment.data` here. The caller
+ // (`handle_with_engine_inner` in this file) immediately feeds the
+ // same slice to `augment_with_attachments`, which only emits
+ // multimodal `image_parts` for images when `att.data` is non-empty.
+ // Clearing the buffer here would silently drop every uploaded image
+ // from the engine-v2 LLM request — the file is on disk but the
+ // model never sees the bytes. The `persisted_attachments` Vec is
+ // local to the request and is dropped once the engine dispatch
+ // returns, so "storage hygiene" is a no-op anyway.
+ }
+
+ notes
+}
+
+fn resolve_project_root() -> PathBuf {
+ let base_dir = crate::bootstrap::ironclaw_base_dir();
+ base_dir.parent().map(PathBuf::from).unwrap_or(base_dir)
+}
+
+async fn save_attachment_index_notes(
+ store: &Arc,
+ project_id: ironclaw_engine::ProjectId,
+ user_id: &str,
+ thread_id: ironclaw_engine::ThreadId,
+ notes: Vec,
+) {
+ for note in notes {
+ let mut doc = ironclaw_engine::MemoryDoc::new(
+ project_id,
+ user_id,
+ ironclaw_engine::DocType::Note,
+ note.title,
+ note.content,
+ );
+ doc.metadata = note.metadata;
+ doc.tags = note.tags;
+ doc.source_thread_id = Some(thread_id);
+ if let Err(e) = store.save_memory_doc(&doc).await {
+ tracing::warn!(error = %e, title = %doc.title, "engine v2: failed to save attachment index note");
+ }
+ }
+}
+
fn gate_display_parameters(pending: &PendingGate) -> serde_json::Value {
pending
.display_parameters
@@ -909,6 +1144,8 @@ struct EngineState {
auth_manager: Option>,
/// Extension manager for extension-backed auth/setup when no auth manager exists.
extension_manager: Option>,
+ /// Filesystem root for project-local attachment persistence.
+ project_root: PathBuf,
}
/// Global engine state, initialized on first use.
@@ -1195,6 +1432,10 @@ pub async fn init_engine(agent: &Agent) -> Result<(), Error> {
let store = Arc::new(HybridStore::new(agent.workspace().cloned()));
store.load_state_from_workspace().await;
+ effect_adapter.set_engine_store(store.clone()).await;
+ if let Some(skill_registry) = agent.deps.skill_registry.clone() {
+ effect_adapter.set_skill_registry(skill_registry).await;
+ }
// Clean up completed threads and dead leases from prior runs
let cleaned = store
@@ -1597,6 +1838,7 @@ pub async fn init_engine(agent: &Agent) -> Result<(), Error> {
secrets_store: agent.tools().secrets_store().cloned(),
auth_manager,
extension_manager: agent.deps.extension_manager.clone(),
+ project_root: resolve_project_root(),
});
Ok(())
@@ -3093,18 +3335,25 @@ async fn handle_with_engine_inner(
}
// Safety checks — mirror the v1 pipeline in thread_ops::process_user_input
- // so both engine paths enforce the same inbound protections.
- let validation = agent.safety().validate_input(content);
- if !validation.is_valid {
- let details = validation
- .errors
- .iter()
- .map(|e| format!("{}: {}", e.field, e.message))
- .collect::>()
- .join("; ");
- return Ok(BridgeOutcome::Respond(format!(
- "Input rejected by safety validation: {details}"
- )));
+ // so both engine paths enforce the same inbound protections. When the
+ // message carries attachments, an empty text body is legitimate (the
+ // attachment is the payload); skip the validator's empty-input rejection
+ // but still apply length / policy checks against the text.
+ let trimmed_content = content.trim();
+ let skip_empty_check = trimmed_content.is_empty() && !message.attachments.is_empty();
+ if !skip_empty_check {
+ let validation = agent.safety().validate_input(content);
+ if !validation.is_valid {
+ let details = validation
+ .errors
+ .iter()
+ .map(|e| format!("{}: {}", e.field, e.message))
+ .collect::>()
+ .join("; ");
+ return Ok(BridgeOutcome::Respond(format!(
+ "Input rejected by safety validation: {details}"
+ )));
+ }
}
let violations = agent.safety().check_policy(content);
@@ -3129,6 +3378,30 @@ async fn handle_with_engine_inner(
return Ok(BridgeOutcome::Respond(warning));
}
+ // Resolve per-user project (creates if needed).
+ let project_id =
+ resolve_user_project(&state.store, &message.user_id, state.default_project_id).await?;
+
+ let mut persisted_attachments = message.attachments.clone();
+ let attachment_notes = persist_project_attachments(
+ &state.project_root,
+ message,
+ project_id,
+ &mut persisted_attachments,
+ )
+ .await;
+
+ // Engine v2 threads are text-only today, so attachments must be folded
+ // into the effective user content before routing to the engine. This
+ // preserves extracted document text, project-local file paths, and
+ // attachment metadata in both the engine thread and the dual-written
+ // gateway history.
+ let augmented = crate::agent::augment_with_attachments(content, &persisted_attachments);
+ let effective_content = augmented
+ .as_ref()
+ .map(|result| result.text.as_str())
+ .unwrap_or(content);
+
// Fire any active OnEvent missions whose pattern (and optional channel
// filter) match this inbound message. Mission firings here are side
// effects of the message — independent of, and parallel to, the normal
@@ -3139,7 +3412,7 @@ async fn handle_with_engine_inner(
// v1 routine store and are fired by the v1 RoutineEngine in the
// background. Missions created via the routine_create alias live in
// the engine store and are fired here.
- fire_event_missions_for_message(state, message, content).await;
+ fire_event_missions_for_message(state, message, effective_content).await;
// Send "Thinking..." status to the channel
let _ = agent
@@ -3172,10 +3445,6 @@ async fn handle_with_engine_inner(
.await
.map_err(|e| engine_err("conversation error", e))?;
- // Resolve per-user project (creates if needed).
- let project_id =
- resolve_user_project(&state.store, &message.user_id, state.default_project_id).await?;
-
// Validate the channel-supplied timezone before passing it to the engine.
// ValidTimezone::parse rejects empty/invalid strings; we send the canonical
// IANA name (not the raw input) so downstream consumers see a known-good
@@ -3200,7 +3469,7 @@ async fn handle_with_engine_inner(
.conversation_manager
.handle_user_message(
conv_id,
- content,
+ effective_content,
project_id,
&message.user_id,
thread_config,
@@ -3209,6 +3478,17 @@ async fn handle_with_engine_inner(
.await
.map_err(|e| engine_err("thread error", e))?;
+ if !attachment_notes.is_empty() {
+ save_attachment_index_notes(
+ &state.store,
+ project_id,
+ &message.user_id,
+ thread_id,
+ attachment_notes,
+ )
+ .await;
+ }
+
// Dual-write to v1 database so the gateway history API shows messages.
// Use the thread-scoped conversation (from thread_id) when available,
// falling back to the default assistant conversation.
@@ -3233,7 +3513,9 @@ async fn handle_with_engine_inner(
.ok()
};
if let Some(cid) = v1_conv_id {
- let _ = db.add_conversation_message(cid, "user", content).await;
+ let _ = db
+ .add_conversation_message(cid, "user", effective_content)
+ .await;
}
}
@@ -5222,6 +5504,7 @@ mod tests {
use rust_decimal::Decimal;
static ENGINE_STATE_TEST_LOCK: LazyLock> = LazyLock::new(|| TokioMutex::new(()));
+ static CWD_TEST_LOCK: LazyLock> = LazyLock::new(|| TokioMutex::new(()));
struct TestStore {
conversations: TokioRwLock>,
@@ -5241,6 +5524,24 @@ mod tests {
}
}
+ struct CurrentDirGuard {
+ original: std::path::PathBuf,
+ }
+
+ impl CurrentDirGuard {
+ fn enter(path: &std::path::Path) -> Self {
+ let original = std::env::current_dir().expect("capture current dir");
+ std::env::set_current_dir(path).expect("switch current dir");
+ Self { original }
+ }
+ }
+
+ impl Drop for CurrentDirGuard {
+ fn drop(&mut self) {
+ let _ = std::env::set_current_dir(&self.original);
+ }
+ }
+
#[derive(Clone)]
struct RecordingStatusChannel {
name: String,
@@ -6624,6 +6925,7 @@ mod tests {
secrets_store: None,
auth_manager: None,
extension_manager: None,
+ project_root: resolve_project_root(),
}
}
@@ -6763,6 +7065,7 @@ mod tests {
secrets_store: None,
auth_manager: None,
extension_manager: None,
+ project_root: resolve_project_root(),
}
}
@@ -6830,6 +7133,113 @@ mod tests {
outcome.expect("router approval re-emit test");
}
+ #[tokio::test]
+ async fn handle_with_engine_persists_attachment_files_and_indexes_them() {
+ let _engine_guard = ENGINE_STATE_TEST_LOCK.lock().await;
+ let _cwd_guard = CWD_TEST_LOCK.lock().await;
+ let lock = ENGINE_STATE.get_or_init(|| RwLock::new(None));
+ *lock.write().await = None;
+
+ let outcome = async {
+ let store = Arc::new(TestStore::new());
+ let temp_dir = tempfile::tempdir().expect("temp dir");
+ let _cwd = CurrentDirGuard::enter(temp_dir.path());
+ let mut state = make_expected_test_state(store.clone());
+ state.project_root = temp_dir.path().join("projects");
+ *lock.write().await = Some(state);
+
+ let (agent, _statuses) = make_router_test_agent(None).await;
+
+ let message =
+ IncomingMessage::new("gateway", "alice", "Please keep this upload handy.")
+ .with_attachments(vec![crate::channels::IncomingAttachment {
+ id: "att-1".to_string(),
+ kind: crate::channels::AttachmentKind::Document,
+ mime_type: "text/plain".to_string(),
+ filename: Some("notes.txt".to_string()),
+ size_bytes: Some(20),
+ source_url: None,
+ storage_key: None,
+ local_path: None,
+ extracted_text: Some("Remember this file.".to_string()),
+ data: b"Remember this file.\n".to_vec(),
+ duration_secs: None,
+ }]);
+
+ let _ = handle_with_engine_inner(&agent, &message, &message.content, 0)
+ .await
+ .expect("router handled message");
+
+ let thread = store
+ .threads
+ .read()
+ .await
+ .values()
+ .next()
+ .cloned()
+ .expect("thread saved");
+ let user_msg = thread
+ .messages
+ .iter()
+ .find(|msg| msg.role == ironclaw_engine::MessageRole::User)
+ .expect("user message recorded");
+ assert!(
+ user_msg
+ .content
+ .contains("project_path=\".ironclaw/attachments/alice/"),
+ "expected saved project path in user content, got: {}",
+ user_msg.content
+ );
+ assert!(
+ user_msg
+ .content
+ .contains("Saved to project file: .ironclaw/attachments/alice/"),
+ "expected saved path hint in user content, got: {}",
+ user_msg.content
+ );
+
+ let docs = store.docs.read().await;
+ let note = docs.iter().next().cloned().expect("attachment note saved");
+ drop(docs);
+
+ assert_eq!(note.project_id, thread.project_id);
+ assert_eq!(note.user_id, "alice");
+ assert_eq!(note.doc_type, ironclaw_engine::DocType::Note);
+ assert_eq!(note.source_thread_id, Some(thread.id));
+ assert!(note.content.contains("## Extracted text"));
+ assert!(note.content.contains("Remember this file."));
+
+ let relative_path = note
+ .metadata
+ .get("project_path")
+ .and_then(|value| value.as_str())
+ .expect("project_path metadata");
+ let absolute_path = temp_dir.path().join("projects").join(relative_path);
+ assert!(
+ absolute_path.exists(),
+ "expected saved file at {}",
+ absolute_path.display()
+ );
+ let bytes = tokio::fs::read(&absolute_path)
+ .await
+ .expect("read saved attachment");
+ assert_eq!(bytes, b"Remember this file.\n".to_vec());
+ assert!(
+ message
+ .attachments
+ .first()
+ .is_some_and(|attachment| !attachment.data.is_empty()),
+ "source message should remain unchanged"
+ );
+
+ Ok::<(), crate::error::Error>(())
+ }
+ .await;
+
+ *lock.write().await = None;
+ outcome.expect("router attachment persistence test");
+ }
+
#[tokio::test]
async fn resolve_gate_repairs_call_id_for_resume_output_auth_resume() {
struct InspectingLlm {
@@ -7866,6 +8276,7 @@ mod tests {
secrets_store: None,
auth_manager: None,
extension_manager: None,
+ project_root: resolve_project_root(),
}
}
diff --git a/src/bridge/skill_migration.rs b/src/bridge/skill_migration.rs
index 04da29b51eb..65867b61682 100644
--- a/src/bridge/skill_migration.rs
+++ b/src/bridge/skill_migration.rs
@@ -78,7 +78,7 @@ pub async fn migrate_v1_skill_list(
continue;
}
- let doc = v1_skill_to_memory_doc(skill, project_id, owner_id);
+ let doc = v1_skill_to_memory_doc(skill, project_id, owner_id).await;
store.save_memory_doc(&doc).await?;
migrated += 1;
@@ -96,14 +96,68 @@ pub async fn migrate_v1_skill_list(
Ok(migrated)
}
+/// Sync a single v1 skill into the v2 store, updating an existing `skill:`
+/// doc in place when present.
+///
+/// Shared skill docs live under a shared owner and are visible to every project
+/// via `list_skills_global()`; scoping the lookup to `project_id` would create
+/// duplicate shared docs across projects (common with per-user projects). We
+/// use the global skill listing so a shared skill that already exists under a
+/// different project's `project_id` gets updated in place.
+pub async fn sync_v1_skill_to_store(
+ skill: &LoadedSkill,
+ store: &Arc,
+ project_id: ProjectId,
+) -> Result {
+ let title = format!("skill:{}", skill.manifest.name);
+ let existing = store
+ .list_skills_global()
+ .await?
+ .into_iter()
+ .find(|doc| doc.doc_type == DocType::Skill && doc.title == title);
+
+ if let Some(existing) = existing.as_ref()
+ && existing.content == skill.prompt_content
+ && serde_json::from_value::(existing.metadata.clone())
+ .ok()
+ .is_some_and(|meta| meta.content_hash == skill.content_hash)
+ {
+ return Ok(existing.clone());
+ }
+
+ let mut doc = v1_skill_to_memory_doc(skill, project_id, shared_owner_id()).await;
+ if let Some(existing) = existing {
+ doc.id = existing.id;
+ doc.project_id = existing.project_id;
+ doc.created_at = existing.created_at;
+ }
+ store.save_memory_doc(&doc).await?;
+ Ok(doc)
+}
+
/// Convert a single v1 `LoadedSkill` to a v2 `MemoryDoc`.
-fn v1_skill_to_memory_doc(skill: &LoadedSkill, project_id: ProjectId, owner_id: &str) -> MemoryDoc {
+async fn v1_skill_to_memory_doc(
+ skill: &LoadedSkill,
+ project_id: ProjectId,
+ owner_id: &str,
+) -> MemoryDoc {
// User- and workspace-installed skills belong to the owner.
// Bundled and registry-installed skills are shared across all users.
let user_id = match &skill.source {
SkillSource::User(_) | SkillSource::Workspace(_) => owner_id,
SkillSource::Installed(_) | SkillSource::Bundled(_) => shared_owner_id(),
};
+ let (bundle_path, source_url) = match &skill.source {
+ SkillSource::Workspace(path)
+ | SkillSource::User(path)
+ | SkillSource::Installed(path)
+ | SkillSource::Bundled(path) => (
+ Some(path.display().to_string()),
+ ironclaw_skills::registry::SkillRegistry::read_install_metadata(path)
+ .await
+ .and_then(|meta| meta.source_url),
+ ),
+ };
let meta = V2SkillMetadata {
name: skill.manifest.name.clone(),
@@ -124,6 +178,8 @@ fn v1_skill_to_memory_doc(skill: &LoadedSkill, project_id: ProjectId, owner_id:
revisions: vec![],
repairs: vec![],
content_hash: skill.content_hash.clone(),
+ bundle_path,
+ source_url,
};
let mut doc = MemoryDoc::new(
@@ -168,11 +224,11 @@ mod tests {
}
}
- #[test]
- fn test_v1_skill_converts_to_memory_doc() {
+ #[tokio::test]
+ async fn test_v1_skill_converts_to_memory_doc() {
let skill = make_v1_skill("test-skill", "Test prompt content");
let project_id = ProjectId::new();
- let doc = v1_skill_to_memory_doc(&skill, project_id, "alice");
+ let doc = v1_skill_to_memory_doc(&skill, project_id, "alice").await;
assert_eq!(doc.doc_type, DocType::Skill);
assert_eq!(doc.title, "skill:test-skill");
@@ -189,25 +245,195 @@ mod tests {
assert_eq!(meta.trust, SkillTrust::Trusted);
assert!(meta.code_snippets.is_empty());
assert!(!meta.content_hash.is_empty());
+ assert_eq!(meta.bundle_path.as_deref(), Some("/tmp/test"));
+ assert_eq!(meta.source_url, None);
}
- #[test]
- fn test_bundled_skill_migrates_as_shared() {
+ #[tokio::test]
+ async fn test_bundled_skill_migrates_as_shared() {
let mut skill = make_v1_skill("bundled-skill", "Bundled content");
skill.source = SkillSource::Bundled(PathBuf::from("/bundled"));
let project_id = ProjectId::new();
- let doc = v1_skill_to_memory_doc(&skill, project_id, "alice");
+ let doc = v1_skill_to_memory_doc(&skill, project_id, "alice").await;
assert_eq!(doc.user_id, shared_owner_id());
}
- #[test]
- fn test_installed_skill_migrates_as_shared() {
+ #[tokio::test]
+ async fn test_installed_skill_migrates_as_shared() {
let mut skill = make_v1_skill("installed-skill", "Installed content");
skill.source = SkillSource::Installed(PathBuf::from("/installed"));
let project_id = ProjectId::new();
- let doc = v1_skill_to_memory_doc(&skill, project_id, "alice");
+ let doc = v1_skill_to_memory_doc(&skill, project_id, "alice").await;
assert_eq!(doc.user_id, shared_owner_id());
}
+
+ /// Regression: syncing the same shared skill twice from different projects
+ /// must update the existing shared skill doc in place rather than create a
+ /// second doc scoped to the second project. Prior behavior scoped the
+ /// existence check to `list_shared_memory_docs(project_id)` and silently
+ /// duplicated shared docs across per-user projects.
+ #[tokio::test]
+ async fn test_sync_v1_skill_deduplicates_across_projects() {
+ use ironclaw_engine::types::capability::{CapabilityLease, LeaseId};
+ use ironclaw_engine::types::event::ThreadEvent;
+ use ironclaw_engine::types::mission::{Mission, MissionId, MissionStatus};
+ use ironclaw_engine::types::step::Step;
+ use ironclaw_engine::types::thread::{Thread, ThreadId, ThreadState};
+ use ironclaw_engine::{DocId, Project};
+ use tokio::sync::Mutex as TokioMutex;
+
+ #[derive(Default)]
+ struct SharedSkillStore {
+ docs: TokioMutex>,
+ }
+
+ #[async_trait::async_trait]
+ impl Store for SharedSkillStore {
+ async fn save_thread(&self, _: &Thread) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn load_thread(&self, _: ThreadId) -> Result, EngineError> {
+ Ok(None)
+ }
+ async fn list_threads(
+ &self,
+ _: ProjectId,
+ _: &str,
+ ) -> Result, EngineError> {
+ Ok(Vec::new())
+ }
+ async fn update_thread_state(
+ &self,
+ _: ThreadId,
+ _: ThreadState,
+ ) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn save_step(&self, _: &Step) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn load_steps(&self, _: ThreadId) -> Result, EngineError> {
+ Ok(Vec::new())
+ }
+ async fn append_events(&self, _: &[ThreadEvent]) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn load_events(&self, _: ThreadId) -> Result, EngineError> {
+ Ok(Vec::new())
+ }
+ async fn save_project(&self, _: &Project) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn load_project(&self, _: ProjectId) -> Result, EngineError> {
+ Ok(None)
+ }
+ async fn save_memory_doc(&self, doc: &MemoryDoc) -> Result<(), EngineError> {
+ let mut docs = self.docs.lock().await;
+ docs.retain(|d| d.id != doc.id);
+ docs.push(doc.clone());
+ Ok(())
+ }
+ async fn load_memory_doc(&self, id: DocId) -> Result, EngineError> {
+ Ok(self.docs.lock().await.iter().find(|d| d.id == id).cloned())
+ }
+ async fn list_memory_docs(
+ &self,
+ project_id: ProjectId,
+ user_id: &str,
+ ) -> Result, EngineError> {
+ Ok(self
+ .docs
+ .lock()
+ .await
+ .iter()
+ .filter(|d| d.project_id == project_id && d.user_id == user_id)
+ .cloned()
+ .collect())
+ }
+ async fn list_memory_docs_by_owner(
+ &self,
+ user_id: &str,
+ ) -> Result, EngineError> {
+ Ok(self
+ .docs
+ .lock()
+ .await
+ .iter()
+ .filter(|d| d.user_id == user_id)
+ .cloned()
+ .collect())
+ }
+ async fn save_lease(&self, _: &CapabilityLease) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn load_active_leases(
+ &self,
+ _: ThreadId,
+ ) -> Result, EngineError> {
+ Ok(Vec::new())
+ }
+ async fn revoke_lease(&self, _: LeaseId, _: &str) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn save_mission(&self, _: &Mission) -> Result<(), EngineError> {
+ Ok(())
+ }
+ async fn load_mission(&self, _: MissionId) -> Result, EngineError> {
+ Ok(None)
+ }
+ async fn list_missions(
+ &self,
+ _: ProjectId,
+ _: &str,
+ ) -> Result, EngineError> {
+ Ok(Vec::new())
+ }
+ async fn update_mission_status(
+ &self,
+ _: MissionId,
+ _: MissionStatus,
+ ) -> Result<(), EngineError> {
+ Ok(())
+ }
+ }
+
+ let store: Arc = Arc::new(SharedSkillStore::default());
+ let mut skill = make_v1_skill("shared-skill", "shared body");
+ skill.source = SkillSource::Installed(PathBuf::from("/installed"));
+
+ let project_a = ProjectId::new();
+ let project_b = ProjectId::new();
+
+ // First sync creates the shared doc under project A.
+ let first = sync_v1_skill_to_store(&skill, &store, project_a)
+ .await
+ .expect("first sync");
+ assert_eq!(first.project_id, project_a);
+ assert_eq!(first.user_id, shared_owner_id());
+
+ // Second sync from project B must update the existing shared doc
+ // in place — not create a duplicate scoped to project B.
+ let second = sync_v1_skill_to_store(&skill, &store, project_b)
+ .await
+ .expect("second sync");
+ assert_eq!(second.id, first.id, "shared skill doc should be reused");
+ assert_eq!(
+ second.project_id, project_a,
+ "existing project scope must be preserved on in-place update"
+ );
+
+ let all_shared = store.list_skills_global().await.expect("list skills");
+ let by_title: Vec<_> = all_shared
+ .iter()
+ .filter(|d| d.title == "skill:shared-skill")
+ .collect();
+ assert_eq!(
+ by_title.len(),
+ 1,
+ "expected exactly one shared skill doc, got {}",
+ by_title.len()
+ );
+ }
}
diff --git a/src/channels/attachments.rs b/src/channels/attachments.rs
new file mode 100644
index 00000000000..c2b6ce68152
--- /dev/null
+++ b/src/channels/attachments.rs
@@ -0,0 +1,61 @@
+//! Shared attachment helpers for channel ingestion and persistence.
+
+/// Maximum decoded size per inline attachment.
+pub(crate) const MAX_INLINE_ATTACHMENT_BYTES: usize = 5 * 1024 * 1024;
+/// Maximum total decoded size across all inline attachments in a message.
+pub(crate) const MAX_INLINE_TOTAL_ATTACHMENT_BYTES: usize = 10 * 1024 * 1024;
+/// Maximum number of inline attachments in a single message.
+pub(crate) const MAX_INLINE_ATTACHMENTS: usize = 5;
+
+fn base_mime_type(mime: &str) -> &str {
+ mime.split(';').next().unwrap_or(mime).trim()
+}
+
+pub(crate) fn attachment_extension_for_mime(mime: &str) -> &'static str {
+ match base_mime_type(mime) {
+ "image/png" => "png",
+ "image/jpeg" | "image/jpg" => "jpg",
+ "image/webp" => "webp",
+ "image/gif" => "gif",
+ "image/svg+xml" => "svg",
+ "application/pdf" => "pdf",
+ "text/plain" => "txt",
+ "text/markdown" => "md",
+ "text/csv" => "csv",
+ "application/json" => "json",
+ "application/xml" | "text/xml" => "xml",
+ "audio/mpeg" => "mp3",
+ "audio/wav" | "audio/x-wav" => "wav",
+ "audio/ogg" => "ogg",
+ "application/vnd.openxmlformats-officedocument.presentationml.presentation" => "pptx",
+ "application/vnd.ms-powerpoint" => "ppt",
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document" => "docx",
+ "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" => "xlsx",
+ other if other.starts_with("image/") => "jpg",
+ _ => "bin",
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ #[test]
+ fn attachment_extension_handles_common_types_and_parameters() {
+ assert_eq!(
+ super::attachment_extension_for_mime("text/plain; charset=utf-8"),
+ "txt"
+ );
+ assert_eq!(
+ super::attachment_extension_for_mime(
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+ ),
+ "docx"
+ );
+ assert_eq!(
+ super::attachment_extension_for_mime(
+ "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+ ),
+ "xlsx"
+ );
+ assert_eq!(super::attachment_extension_for_mime("audio/x-wav"), "wav");
+ }
+}
diff --git a/src/channels/channel.rs b/src/channels/channel.rs
index b82b6cef386..882b8888bbf 100644
--- a/src/channels/channel.rs
+++ b/src/channels/channel.rs
@@ -53,6 +53,8 @@ pub struct IncomingAttachment {
pub source_url: Option,
/// Opaque key for host-side storage (e.g., after download/caching).
pub storage_key: Option,
+ /// Relative path to a project-local copy saved on disk, if persisted.
+ pub local_path: Option,
/// Extracted text content (e.g., OCR result, PDF text, audio transcript).
pub extracted_text: Option,
/// Raw file bytes (for small files downloaded by the channel).
diff --git a/src/channels/http.rs b/src/channels/http.rs
index ce6d80fa6c1..5d77230ad55 100644
--- a/src/channels/http.rs
+++ b/src/channels/http.rs
@@ -22,6 +22,7 @@ use uuid::Uuid;
use crate::channels::{
AttachmentKind, Channel, ChannelSecretUpdater, IncomingAttachment, IncomingMessage,
+ MAX_INLINE_ATTACHMENT_BYTES, MAX_INLINE_ATTACHMENTS, MAX_INLINE_TOTAL_ATTACHMENT_BYTES,
MessageStream, OutgoingResponse,
};
use crate::config::HttpConfig;
@@ -168,13 +169,6 @@ struct AttachmentData {
url: Option,
}
-/// Maximum size per attachment (5 MB decoded).
-const MAX_ATTACHMENT_BYTES: usize = 5 * 1024 * 1024;
-/// Maximum total attachment size (10 MB decoded).
-const MAX_TOTAL_ATTACHMENT_BYTES: usize = 10 * 1024 * 1024;
-/// Maximum number of attachments per request.
-const MAX_ATTACHMENTS: usize = 5;
-
#[derive(Debug, Serialize)]
struct WebhookResponse {
/// Message ID assigned to this request.
@@ -452,13 +446,16 @@ async fn process_authenticated_request(
let wait_for_response = req.wait_for_response;
let attachments = if !req.attachments.is_empty() {
- if req.attachments.len() > MAX_ATTACHMENTS {
+ if req.attachments.len() > MAX_INLINE_ATTACHMENTS {
return (
StatusCode::BAD_REQUEST,
Json(WebhookResponse {
message_id: Uuid::nil(),
status: "error".to_string(),
- response: Some(format!("Too many attachments (max {})", MAX_ATTACHMENTS)),
+ response: Some(format!(
+ "Too many attachments (max {})",
+ MAX_INLINE_ATTACHMENTS
+ )),
}),
)
.into_response();
@@ -483,7 +480,7 @@ async fn process_authenticated_request(
.into_response();
}
};
- if data.len() > MAX_ATTACHMENT_BYTES {
+ if data.len() > MAX_INLINE_ATTACHMENT_BYTES {
return (
StatusCode::PAYLOAD_TOO_LARGE,
Json(WebhookResponse {
@@ -491,14 +488,14 @@ async fn process_authenticated_request(
status: "error".to_string(),
response: Some(format!(
"Attachment too large (max {} bytes)",
- MAX_ATTACHMENT_BYTES
+ MAX_INLINE_ATTACHMENT_BYTES
)),
}),
)
.into_response();
}
total_bytes += data.len();
- if total_bytes > MAX_TOTAL_ATTACHMENT_BYTES {
+ if total_bytes > MAX_INLINE_TOTAL_ATTACHMENT_BYTES {
return (
StatusCode::PAYLOAD_TOO_LARGE,
Json(WebhookResponse {
@@ -517,6 +514,7 @@ async fn process_authenticated_request(
size_bytes: Some(data.len() as u64),
source_url: None,
storage_key: None,
+ local_path: None,
extracted_text: None,
data,
duration_secs: None,
@@ -530,6 +528,7 @@ async fn process_authenticated_request(
size_bytes: None,
source_url: Some(url.clone()),
storage_key: None,
+ local_path: None,
extracted_text: None,
data: Vec::new(),
duration_secs: None,
diff --git a/src/channels/mod.rs b/src/channels/mod.rs
index 653b0310740..172854fec73 100644
--- a/src/channels/mod.rs
+++ b/src/channels/mod.rs
@@ -27,6 +27,7 @@
//! WASM channels allow dynamic loading of channel implementations at runtime.
//! See the [`wasm`] module for details.
+mod attachments;
mod channel;
mod http;
mod manager;
@@ -41,6 +42,10 @@ mod webhook_server;
#[cfg(feature = "tui")]
pub use self::tui::TuiChannel;
+pub(crate) use attachments::{
+ MAX_INLINE_ATTACHMENT_BYTES, MAX_INLINE_ATTACHMENTS, MAX_INLINE_TOTAL_ATTACHMENT_BYTES,
+ attachment_extension_for_mime,
+};
pub use channel::{
AttachmentKind, Channel, ChannelSecretUpdater, ChatApprovalPrompt, EngineThreadSummary,
HistoryMessage, IncomingAttachment, IncomingMessage, MessageStream, OutgoingResponse,
diff --git a/src/channels/tui.rs b/src/channels/tui.rs
index b13228adee0..119a9c33bd8 100644
--- a/src/channels/tui.rs
+++ b/src/channels/tui.rs
@@ -133,6 +133,7 @@ fn build_tui_incoming_message(
size_bytes: Some(a.data.len() as u64),
source_url: None,
storage_key: None,
+ local_path: None,
extracted_text: None,
data: a.data,
duration_secs: None,
diff --git a/src/channels/wasm/host.rs b/src/channels/wasm/host.rs
index 466cdf78db4..fbec720d84b 100644
--- a/src/channels/wasm/host.rs
+++ b/src/channels/wasm/host.rs
@@ -33,6 +33,8 @@ pub struct Attachment {
pub source_url: Option,
/// Opaque key for host-side storage (e.g., after download/caching).
pub storage_key: Option,
+ /// Relative path to a project-local copy saved on disk, if persisted.
+ pub local_path: Option,
/// Extracted text content (e.g., OCR result, PDF text, audio transcript).
pub extracted_text: Option,
/// Raw file bytes (for small files downloaded by the channel).
@@ -1118,6 +1120,7 @@ mod tests {
size_bytes: size,
source_url: None,
storage_key: None,
+ local_path: None,
extracted_text: None,
data: Vec::new(),
duration_secs: None,
diff --git a/src/channels/wasm/wrapper.rs b/src/channels/wasm/wrapper.rs
index df532ab2465..2f1fbd20cd0 100644
--- a/src/channels/wasm/wrapper.rs
+++ b/src/channels/wasm/wrapper.rs
@@ -614,6 +614,7 @@ impl near::agent::channel_host::Host for ChannelStoreData {
size_bytes: a.size_bytes,
source_url: a.source_url,
storage_key: a.storage_key,
+ local_path: None,
extracted_text: a.extracted_text,
data,
duration_secs,
@@ -2838,6 +2839,7 @@ impl WasmChannel {
size_bytes: a.size_bytes,
source_url: a.source_url.clone(),
storage_key: a.storage_key.clone(),
+ local_path: a.local_path.clone(),
extracted_text: a.extracted_text.clone(),
data: a.data.clone(),
duration_secs: a.duration_secs,
@@ -3234,6 +3236,7 @@ impl WasmChannel {
size_bytes: a.size_bytes,
source_url: a.source_url.clone(),
storage_key: a.storage_key.clone(),
+ local_path: a.local_path.clone(),
extracted_text: a.extracted_text.clone(),
data: a.data.clone(),
duration_secs: a.duration_secs,
@@ -6834,6 +6837,7 @@ mod tests {
size_bytes: Some(50_000),
source_url: Some("https://api.telegram.org/file/photo123".to_string()),
storage_key: None,
+ local_path: None,
extracted_text: None,
data: Vec::new(),
duration_secs: None,
@@ -6845,6 +6849,7 @@ mod tests {
size_bytes: Some(120_000),
source_url: None,
storage_key: Some("store/doc456".to_string()),
+ local_path: None,
extracted_text: Some("Report contents...".to_string()),
data: Vec::new(),
duration_secs: None,
diff --git a/src/channels/web/CLAUDE.md b/src/channels/web/CLAUDE.md
index dddadc3828c..845f104abd7 100644
--- a/src/channels/web/CLAUDE.md
+++ b/src/channels/web/CLAUDE.md
@@ -66,7 +66,7 @@ subset that can later be replaced by a typed `Deps` alias.
### Chat
| Method | Path | Description |
|--------|------|-------------|
-| POST | `/api/chat/send` | Send message → queues to agent loop |
+| POST | `/api/chat/send` | Send message + optional inline attachments → queues to agent loop |
| GET | `/api/chat/events` | SSE stream of agent events |
| GET | `/api/chat/ws` | WebSocket alternative to SSE |
| GET | `/api/chat/history` | Paginated turn history for a thread |
@@ -347,7 +347,7 @@ All responses include:
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
-**Request body limit:** 10 MB (`DefaultBodyLimit::max(10 * 1024 * 1024)`), sized for image uploads (#725). Larger payloads return 413.
+**Request body limit:** 14 MiB (`DefaultBodyLimit::max(14 * 1024 * 1024)`), sized to cover base64-encoded inline attachment uploads plus JSON overhead. The decoded attachment budget remains 5 MiB per file and 10 MiB total; larger payloads return 413 or 400 depending on which limit trips first.
## Pending Gates
diff --git a/src/channels/web/features/chat/mod.rs b/src/channels/web/features/chat/mod.rs
index f69e5b74a6c..426f5a879c7 100644
--- a/src/channels/web/features/chat/mod.rs
+++ b/src/channels/web/features/chat/mod.rs
@@ -113,10 +113,15 @@ pub(crate) async fn chat_send_handler(
msg = msg.with_timezone(tz);
}
- // Convert uploaded images to IncomingAttachments
- if !req.images.is_empty() {
- let attachments = crate::channels::web::util::images_to_attachments(&req.images);
- msg = msg.with_attachments(attachments);
+ // Convert uploaded images + generic file attachments to IncomingAttachments
+ // through the shared budget-aware helper so HTTP and WS paths enforce
+ // identical limits. Empty-text messages with attachments are still valid
+ // here; the v2 engine router relaxes the empty-input guard downstream.
+ let incoming_attachments =
+ crate::channels::web::util::inline_attachments_to_incoming(&req.images, &req.attachments)
+ .map_err(|e| (StatusCode::BAD_REQUEST, e))?;
+ if !incoming_attachments.is_empty() {
+ msg = msg.with_attachments(incoming_attachments);
}
let msg_id = msg.id;
diff --git a/src/channels/web/handlers/skills.rs b/src/channels/web/handlers/skills.rs
index db62fac42de..2262e29e13c 100644
--- a/src/channels/web/handlers/skills.rs
+++ b/src/channels/web/handlers/skills.rs
@@ -7,6 +7,7 @@ use axum::{
extract::{Path, State},
http::StatusCode,
};
+use futures::future::join_all;
use crate::channels::web::auth::AuthenticatedUser;
use crate::channels::web::server::GatewayState;
@@ -23,34 +24,88 @@ fn install_requested_identifier<'a>(
.unwrap_or(name)
}
+fn skill_setup_hint(skill: &ironclaw_skills::types::LoadedSkill) -> Option {
+ let mut hints = Vec::new();
+ if !skill.manifest.requires.env.is_empty() {
+ hints.push(format!(
+ "Requires env vars: {}",
+ skill.manifest.requires.env.join(", ")
+ ));
+ }
+ if !skill.manifest.requires.bins.is_empty() {
+ hints.push(format!(
+ "Requires binaries on PATH: {}",
+ skill.manifest.requires.bins.join(", ")
+ ));
+ }
+ (!hints.is_empty()).then(|| hints.join(" · "))
+}
+
+async fn skill_info(skill: ironclaw_skills::types::LoadedSkill) -> SkillInfo {
+ let bundle_dir = match &skill.source {
+ ironclaw_skills::types::SkillSource::Workspace(path)
+ | ironclaw_skills::types::SkillSource::User(path)
+ | ironclaw_skills::types::SkillSource::Installed(path)
+ | ironclaw_skills::types::SkillSource::Bundled(path) => Some(path.clone()),
+ };
+ let install_meta = match &bundle_dir {
+ Some(path) => ironclaw_skills::registry::SkillRegistry::read_install_metadata(path).await,
+ None => None,
+ };
+ let has_requirements = match &bundle_dir {
+ Some(path) => tokio::fs::try_exists(path.join("requirements.txt"))
+ .await
+ .unwrap_or(false),
+ None => false,
+ };
+ let has_scripts = match &bundle_dir {
+ Some(path) => tokio::fs::metadata(path.join("scripts"))
+ .await
+ .map(|metadata| metadata.is_dir())
+ .unwrap_or(false),
+ None => false,
+ };
+ let bundle_path = bundle_dir.as_ref().map(|path| path.display().to_string());
+
+ SkillInfo {
+ name: skill.manifest.name.clone(),
+ description: skill.manifest.description.clone(),
+ version: skill.manifest.version.clone(),
+ trust: skill.trust.to_string(),
+ source: format!("{:?}", skill.source),
+ keywords: skill.manifest.activation.keywords.clone(),
+ usage_hint: Some(format!(
+ "Type `/{}` in chat to force-activate this skill.",
+ skill.manifest.name
+ )),
+ setup_hint: skill_setup_hint(&skill),
+ bundle_path,
+ install_source_url: install_meta.and_then(|meta| meta.source_url),
+ has_requirements,
+ has_scripts,
+ }
+}
+
pub async fn skills_list_handler(
State(state): State>,
AuthenticatedUser(_user): AuthenticatedUser,
) -> Result, (StatusCode, String)> {
- let registry = state.skill_registry.as_ref().ok_or((
+ let registry = Arc::clone(state.skill_registry.as_ref().ok_or((
StatusCode::NOT_IMPLEMENTED,
"Skills system not enabled".to_string(),
- ))?;
+ ))?);
- let guard = registry.read().map_err(|e| {
- (
- StatusCode::INTERNAL_SERVER_ERROR,
- format!("Skill registry lock poisoned: {}", e),
- )
- })?;
+ let skill_snapshot = {
+ let guard = registry.read().map_err(|e| {
+ (
+ StatusCode::INTERNAL_SERVER_ERROR,
+ format!("Skill registry lock poisoned: {}", e),
+ )
+ })?;
+ guard.skills().to_vec()
+ };
- let skills: Vec = guard
- .skills()
- .iter()
- .map(|s| SkillInfo {
- name: s.manifest.name.clone(),
- description: s.manifest.description.clone(),
- version: s.manifest.version.clone(),
- trust: s.trust.to_string(),
- source: format!("{:?}", s.source),
- keywords: s.manifest.activation.keywords.clone(),
- })
- .collect();
+ let skills: Vec = join_all(skill_snapshot.into_iter().map(skill_info)).await;
let count = skills.len();
Ok(Json(SkillListResponse { skills, count }))
@@ -61,15 +116,15 @@ pub async fn skills_search_handler(
AuthenticatedUser(_user): AuthenticatedUser,
Json(req): Json,
) -> Result, (StatusCode, String)> {
- let registry = state.skill_registry.as_ref().ok_or((
+ let registry = Arc::clone(state.skill_registry.as_ref().ok_or((
StatusCode::NOT_IMPLEMENTED,
"Skills system not enabled".to_string(),
- ))?;
+ ))?);
- let catalog = state.skill_catalog.as_ref().ok_or((
+ let catalog = Arc::clone(state.skill_catalog.as_ref().ok_or((
StatusCode::NOT_IMPLEMENTED,
"Skill catalog not available".to_string(),
- ))?;
+ ))?);
// Search ClawHub catalog
let catalog_outcome = catalog.search(&req.query).await;
@@ -80,7 +135,10 @@ pub async fn skills_search_handler(
catalog.enrich_search_results(&mut entries, 5).await;
let query_lower = req.query.to_lowercase();
- let (installed_names, installed): (Vec, Vec) = {
+ let (installed_names, matching_skills): (
+ Vec,
+ Vec,
+ ) = {
let guard = registry.read().map_err(|e| {
(
StatusCode::INTERNAL_SERVER_ERROR,
@@ -92,24 +150,18 @@ pub async fn skills_search_handler(
.iter()
.map(|s| s.manifest.name.clone())
.collect();
- let installed = guard
+ let matching_skills = guard
.skills()
.iter()
.filter(|s| {
s.manifest.name.to_lowercase().contains(&query_lower)
|| s.manifest.description.to_lowercase().contains(&query_lower)
})
- .map(|s| SkillInfo {
- name: s.manifest.name.clone(),
- description: s.manifest.description.clone(),
- version: s.manifest.version.clone(),
- trust: s.trust.to_string(),
- source: format!("{:?}", s.source),
- keywords: s.manifest.activation.keywords.clone(),
- })
+ .cloned()
.collect();
- (installed_names, installed)
+ (installed_names, matching_skills)
};
+ let installed: Vec = join_all(matching_skills.into_iter().map(skill_info)).await;
let catalog_json: Vec = entries
.into_iter()
@@ -169,11 +221,14 @@ pub async fn skills_install_handler(
))?;
let mut resolved_download_key = None;
- let content = if let Some(ref raw) = req.content {
- raw.clone()
+ let install_payload = if let Some(ref raw) = req.content {
+ crate::tools::builtin::skill_tools::SkillInstallPayload {
+ skill_md: raw.clone(),
+ ..crate::tools::builtin::skill_tools::SkillInstallPayload::default()
+ }
} else if let Some(ref url) = req.url {
// Fetch from explicit URL (with SSRF protection)
- crate::tools::builtin::skill_tools::fetch_skill_content(url)
+ crate::tools::builtin::skill_tools::fetch_skill_payload(url)
.await
.map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?
} else if let Some(ref catalog) = state.skill_catalog {
@@ -206,7 +261,7 @@ pub async fn skills_install_handler(
let url =
ironclaw_skills::catalog::skill_download_url(catalog.registry_url(), &download_key);
resolved_download_key = Some(download_key);
- crate::tools::builtin::skill_tools::fetch_skill_content(&url)
+ crate::tools::builtin::skill_tools::fetch_skill_payload(&url)
.await
.map_err(|e| (StatusCode::BAD_GATEWAY, e.to_string()))?
} else {
@@ -215,7 +270,7 @@ pub async fn skills_install_handler(
)));
};
- let normalized = ironclaw_skills::normalize_line_endings(&content);
+ let normalized = ironclaw_skills::normalize_line_endings(&install_payload.skill_md);
let requested_identifier = install_requested_identifier(
&req.name,
req.slug.as_deref(),
@@ -254,10 +309,12 @@ pub async fn skills_install_handler(
// Perform async I/O (write to disk, load) with no lock held.
let (skill_name, loaded_skill) =
- ironclaw_skills::registry::SkillRegistry::prepare_install_to_disk(
+ ironclaw_skills::registry::SkillRegistry::prepare_install_bundle_to_disk(
&user_dir,
&skill_name_from_parse,
&install_content,
+ &install_payload.extra_files,
+ install_payload.install_metadata.as_ref(),
)
.await
.map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
@@ -341,6 +398,8 @@ pub async fn skills_remove_handler(
#[cfg(test)]
mod tests {
+ use std::path::Path;
+
#[test]
fn catalog_entry_matches_installed_slug_suffix() {
let installed = vec!["mortgage-calculator".to_string()];
@@ -396,4 +455,46 @@ mod tests {
"finance/mortgage-calculator"
);
}
+
+ #[tokio::test]
+ async fn skill_info_reports_bundle_files() {
+ let install_dir = tempfile::tempdir().expect("tempdir");
+ let metadata = ironclaw_skills::registry::InstalledSkillMetadata {
+ source_url: Some("https://example.com/skill".to_string()),
+ source_subdir: None,
+ };
+ let extra_files = vec![
+ ironclaw_skills::registry::InstallFile {
+ relative_path: Path::new("requirements.txt").to_path_buf(),
+ contents: b"httpx==0.27.0\n".to_vec(),
+ },
+ ironclaw_skills::registry::InstallFile {
+ relative_path: Path::new("scripts/run.py").to_path_buf(),
+ contents: b"print('ok')\n".to_vec(),
+ },
+ ];
+
+ let (_, skill) = ironclaw_skills::registry::SkillRegistry::prepare_install_bundle_to_disk(
+ install_dir.path(),
+ "demo-skill",
+ "---\nname: demo-skill\ndescription: Demo\nversion: 1.0.0\n---\n\n# Demo\n",
+ &extra_files,
+ Some(&metadata),
+ )
+ .await
+ .expect("install bundle");
+
+ let info = super::skill_info(skill).await;
+ assert!(info.has_requirements);
+ assert!(info.has_scripts);
+ assert_eq!(
+ info.install_source_url.as_deref(),
+ Some("https://example.com/skill")
+ );
+ assert!(
+ info.bundle_path
+ .as_deref()
+ .is_some_and(|path| path.ends_with("demo-skill"))
+ );
+ }
}
diff --git a/src/channels/web/platform/router.rs b/src/channels/web/platform/router.rs
index ddeec21e48e..6b9fc9722fe 100644
--- a/src/channels/web/platform/router.rs
+++ b/src/channels/web/platform/router.rs
@@ -497,7 +497,7 @@ pub async fn start_server(
.merge(statics)
.merge(projects)
.merge(protected)
- .layer(DefaultBodyLimit::max(10 * 1024 * 1024)) // 10 MB max request body (image uploads)
+ .layer(DefaultBodyLimit::max(14 * 1024 * 1024)) // 14 MiB request body to cover 10 MiB decoded attachments plus base64/JSON overhead
.layer(tower_http::catch_panic::CatchPanicLayer::custom(
|panic_info: Box| {
let detail = if let Some(s) = panic_info.downcast_ref::() {
diff --git a/src/channels/web/platform/ws.rs b/src/channels/web/platform/ws.rs
index 291c054f9f4..12ba25fa023 100644
--- a/src/channels/web/platform/ws.rs
+++ b/src/channels/web/platform/ws.rs
@@ -164,6 +164,7 @@ async fn handle_client_message(
thread_id,
timezone,
images,
+ attachments,
} => {
let mut incoming = crate::channels::web::util::web_incoming_message(
"gateway",
@@ -175,10 +176,20 @@ async fn handle_client_message(
incoming = incoming.with_timezone(tz);
}
- // Convert uploaded images to IncomingAttachments
- if !images.is_empty() {
- let attachments = crate::channels::web::util::images_to_attachments(&images);
- incoming = incoming.with_attachments(attachments);
+ // Convert uploaded files + images to IncomingAttachments.
+ let incoming_attachments =
+ match crate::channels::web::util::inline_attachments_to_incoming(
+ &images,
+ &attachments,
+ ) {
+ Ok(incoming) => incoming,
+ Err(message) => {
+ let _ = direct_tx.send(WsServerMessage::Error { message }).await;
+ return;
+ }
+ };
+ if !incoming_attachments.is_empty() {
+ incoming = incoming.with_attachments(incoming_attachments);
}
// Clone sender to avoid holding RwLock read guard across send().await
@@ -366,6 +377,7 @@ mod tests {
thread_id: Some("t1".to_string()),
timezone: None,
images: Vec::new(),
+ attachments: Vec::new(),
},
&state,
"user1",
@@ -400,6 +412,7 @@ mod tests {
thread_id: None,
timezone: None,
images: Vec::new(),
+ attachments: Vec::new(),
},
&state,
"user1",
@@ -416,6 +429,40 @@ mod tests {
}
}
+ #[tokio::test]
+ async fn test_handle_client_message_forwards_attachments() {
+ let (agent_tx, mut agent_rx) = mpsc::channel(16);
+ let state = make_test_state(Some(agent_tx)).await;
+ let (direct_tx, _direct_rx) = mpsc::channel(16);
+
+ handle_client_message(
+ WsClientMessage::Message {
+ content: "check attachment".to_string(),
+ thread_id: None,
+ timezone: None,
+ images: Vec::new(),
+ attachments: vec![crate::channels::web::types::AttachmentData {
+ mime_type: "text/plain".to_string(),
+ filename: Some("notes.txt".to_string()),
+ data_base64: "aGVsbG8=".to_string(),
+ }],
+ },
+ &state,
+ "user1",
+ &direct_tx,
+ )
+ .await;
+
+ let incoming = agent_rx.recv().await.unwrap();
+ assert_eq!(incoming.attachments.len(), 1);
+ assert_eq!(incoming.attachments[0].mime_type, "text/plain");
+ assert_eq!(
+ incoming.attachments[0].filename.as_deref(),
+ Some("notes.txt")
+ );
+ assert_eq!(incoming.attachments[0].data, b"hello".to_vec());
+ }
+
#[tokio::test]
async fn test_handle_client_approval_approve() {
let (agent_tx, mut agent_rx) = mpsc::channel::(16);
diff --git a/src/channels/web/types.rs b/src/channels/web/types.rs
index 98947ce0ca3..f4ede474e7f 100644
--- a/src/channels/web/types.rs
+++ b/src/channels/web/types.rs
@@ -14,14 +14,29 @@ pub struct ImageData {
pub data: String,
}
+/// Base64-encoded file attachment sent from the web frontend.
+#[derive(Debug, Clone, Deserialize)]
+pub struct AttachmentData {
+ /// MIME type (e.g., "image/png", "application/pdf").
+ pub mime_type: String,
+ /// Optional original filename.
+ #[serde(default)]
+ pub filename: Option,
+ /// Base64-encoded file data (without data: URL prefix).
+ pub data_base64: String,
+}
+
#[derive(Debug, Deserialize)]
pub struct SendMessageRequest {
pub content: String,
pub thread_id: Option,
pub timezone: Option,
- /// Optional images attached to the message.
+ /// Optional legacy images attached to the message.
#[serde(default)]
pub images: Vec,
+ /// Optional files attached to the message.
+ #[serde(default)]
+ pub attachments: Vec,
}
#[derive(Debug, Serialize)]
@@ -788,6 +803,18 @@ pub struct SkillInfo {
pub trust: String,
pub source: String,
pub keywords: Vec,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub usage_hint: Option,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub setup_hint: Option,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub bundle_path: Option,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub install_source_url: Option,
+ #[serde(default)]
+ pub has_requirements: bool,
+ #[serde(default)]
+ pub has_scripts: bool,
}
#[derive(Debug, Serialize)]
@@ -833,9 +860,12 @@ pub enum WsClientMessage {
content: String,
thread_id: Option,
timezone: Option,
- /// Optional images attached to the message.
+ /// Optional legacy images attached to the message.
#[serde(default)]
images: Vec,
+ /// Optional files attached to the message.
+ #[serde(default)]
+ attachments: Vec,
},
/// Approve or deny a pending tool execution.
#[serde(rename = "approval")]
@@ -1208,10 +1238,44 @@ mod tests {
let msg: WsClientMessage = serde_json::from_str(json).unwrap();
match msg {
WsClientMessage::Message {
- content, thread_id, ..
+ content,
+ thread_id,
+ attachments,
+ ..
} => {
assert_eq!(content, "hi");
assert!(thread_id.is_none());
+ assert!(attachments.is_empty());
+ }
+ _ => panic!("Expected Message variant"),
+ }
+ }
+
+ #[test]
+ fn test_ws_client_message_with_attachments() {
+ let json = r#"{
+ "type":"message",
+ "content":"review these",
+ "attachments":[
+ {
+ "mime_type":"application/pdf",
+ "filename":"deck.pdf",
+ "data_base64":"aGVsbG8="
+ }
+ ]
+ }"#;
+ let msg: WsClientMessage = serde_json::from_str(json).unwrap();
+ match msg {
+ WsClientMessage::Message {
+ content,
+ attachments,
+ ..
+ } => {
+ assert_eq!(content, "review these");
+ assert_eq!(attachments.len(), 1);
+ assert_eq!(attachments[0].mime_type, "application/pdf");
+ assert_eq!(attachments[0].filename.as_deref(), Some("deck.pdf"));
+ assert_eq!(attachments[0].data_base64, "aGVsbG8=");
}
_ => panic!("Expected Message variant"),
}
diff --git a/src/channels/web/util.rs b/src/channels/web/util.rs
index c1b2bfa9960..8934b12e210 100644
--- a/src/channels/web/util.rs
+++ b/src/channels/web/util.rs
@@ -1,7 +1,12 @@
//! Shared utility functions for the web gateway.
use crate::channels::IncomingMessage;
-use crate::channels::web::types::{GeneratedImageInfo, ImageData, ToolCallInfo, TurnInfo};
+use crate::channels::web::types::{
+ AttachmentData, GeneratedImageInfo, ImageData, ToolCallInfo, TurnInfo,
+};
+use crate::channels::{
+ MAX_INLINE_ATTACHMENT_BYTES, MAX_INLINE_ATTACHMENTS, MAX_INLINE_TOTAL_ATTACHMENT_BYTES,
+};
use crate::generated_images::GeneratedImageSentinel;
pub use ironclaw_common::truncate_preview;
@@ -37,6 +42,7 @@ pub(crate) fn images_to_attachments(
size_bytes: Some(data.len() as u64),
source_url: None,
storage_key: None,
+ local_path: None,
extracted_text: None,
data,
duration_secs: None,
@@ -55,6 +61,107 @@ fn mime_to_ext(mime: &str) -> &str {
}
}
+fn normalize_attachment_filename(filename: &str) -> Option<&str> {
+ let trimmed = filename.trim();
+ if trimmed.is_empty() {
+ None
+ } else {
+ Some(trimmed)
+ }
+}
+
+fn attachment_ext(mime: &str) -> &str {
+ crate::channels::attachment_extension_for_mime(mime)
+}
+
+/// Convert web gateway `AttachmentData` (generic file upload) to
+/// `IncomingAttachment` objects. Unlike `images_to_attachments`, this path is
+/// strict: a malformed base64 payload is surfaced as an error to the caller so
+/// the client gets a concrete rejection instead of a silent drop.
+pub(crate) fn web_attachments_to_incoming(
+ attachments: &[AttachmentData],
+) -> Result, String> {
+ use base64::Engine;
+ attachments
+ .iter()
+ .enumerate()
+ .map(|(i, attachment)| {
+ let data = base64::engine::general_purpose::STANDARD
+ .decode(&attachment.data_base64)
+ .map_err(|e| format!("Invalid attachment {i}: base64 decode failed: {e}"))?;
+ let filename = attachment
+ .filename
+ .as_deref()
+ .and_then(normalize_attachment_filename)
+ .map(str::to_owned)
+ .unwrap_or_else(|| {
+ format!("attachment-{i}.{}", attachment_ext(&attachment.mime_type))
+ });
+ Ok(crate::channels::IncomingAttachment {
+ id: format!("web-attachment-{i}"),
+ kind: crate::channels::AttachmentKind::from_mime_type(&attachment.mime_type),
+ mime_type: attachment.mime_type.clone(),
+ filename: Some(filename),
+ size_bytes: Some(data.len() as u64),
+ source_url: None,
+ storage_key: None,
+ local_path: None,
+ extracted_text: None,
+ data,
+ duration_secs: None,
+ })
+ })
+ .collect()
+}
+
+fn validate_inline_attachment_budget(
+ attachments: &[crate::channels::IncomingAttachment],
+) -> Result<(), String> {
+ if attachments.len() > MAX_INLINE_ATTACHMENTS {
+ return Err(format!(
+ "Too many attachments: maximum {} files per message",
+ MAX_INLINE_ATTACHMENTS
+ ));
+ }
+
+ let mut total_bytes = 0usize;
+ for attachment in attachments {
+ let size = attachment.data.len();
+ if size > MAX_INLINE_ATTACHMENT_BYTES {
+ return Err(format!(
+ "Attachment '{}' exceeds the {} byte per-file limit",
+ attachment.filename.as_deref().unwrap_or("attachment"),
+ MAX_INLINE_ATTACHMENT_BYTES
+ ));
+ }
+ total_bytes += size;
+ }
+
+ if total_bytes > MAX_INLINE_TOTAL_ATTACHMENT_BYTES {
+ return Err(format!(
+ "Total attachment size exceeds the {} byte per-message limit",
+ MAX_INLINE_TOTAL_ATTACHMENT_BYTES
+ ));
+ }
+
+ Ok(())
+}
+
+/// Combine uploaded images and generic attachments into one batch, validating
+/// the inline budget before returning. Used by both `features/chat::send` and
+/// `platform/ws` so the HTTP and WebSocket paths enforce identical limits.
+pub(crate) fn inline_attachments_to_incoming(
+ images: &[ImageData],
+ attachments: &[AttachmentData],
+) -> Result, String> {
+ let mut incoming = web_attachments_to_incoming(attachments)?;
+ if !images.is_empty() {
+ incoming.extend(images_to_attachments(images));
+ }
+ validate_inline_attachment_budget(&incoming)?;
+ Ok(incoming)
+}
+
const MAX_HISTORY_IMAGE_DATA_URL_BYTES_PER_IMAGE: usize = 512 * 1024;
const MAX_HISTORY_IMAGE_DATA_URL_BYTES_PER_RESPONSE: usize = 1024 * 1024;
const MAX_TOOL_RESULT_DISPLAY_BYTES: usize = 1000;
diff --git a/src/document_extraction/mod.rs b/src/document_extraction/mod.rs
index 9376c17cf38..d33cee7287d 100644
--- a/src/document_extraction/mod.rs
+++ b/src/document_extraction/mod.rs
@@ -159,6 +159,7 @@ mod tests {
size_bytes: Some(data.len() as u64),
source_url: None,
storage_key: None,
+ local_path: None,
extracted_text: None,
data,
duration_secs: None,
diff --git a/src/llm/transcription/mod.rs b/src/llm/transcription/mod.rs
index ab2e43f94bc..d6750d7bd39 100644
--- a/src/llm/transcription/mod.rs
+++ b/src/llm/transcription/mod.rs
@@ -193,6 +193,7 @@ mod tests {
size_bytes: Some(data.len() as u64),
source_url: None,
storage_key: None,
+ local_path: None,
extracted_text: None,
data,
duration_secs: Some(5),
diff --git a/src/tools/builtin/skill_tools.rs b/src/tools/builtin/skill_tools.rs
index 43215802729..26b8d38a51b 100644
--- a/src/tools/builtin/skill_tools.rs
+++ b/src/tools/builtin/skill_tools.rs
@@ -5,6 +5,8 @@
use std::collections::{HashSet, VecDeque};
use std::future::Future;
+use std::io::Read;
+use std::path::{Component, Path, PathBuf};
use std::sync::Arc;
use async_trait::async_trait;
@@ -20,6 +22,9 @@ use ironclaw_skills::catalog::{
use ironclaw_skills::registry::SkillRegistry;
const MAX_CHAIN_DEPS: usize = 10;
+const MAX_DOWNLOAD_BYTES: usize = 10 * 1024 * 1024;
+const MAX_ZIP_ENTRY_BYTES: u64 = 2 * 1024 * 1024;
+const MAX_TOTAL_UNZIPPED_BYTES: u64 = 20 * 1024 * 1024;
/// Hard cap on the chain-installer BFS queue to prevent unbounded growth
/// from nested `requires.skills` fan-out. Even though we stop enqueueing
@@ -61,6 +66,86 @@ impl From for ToolError {
}
}
+#[derive(Debug, Clone, Default)]
+pub(crate) struct SkillInstallPayload {
+ pub(crate) skill_md: String,
+ pub(crate) extra_files: Vec,
+ pub(crate) install_metadata: Option,
+}
+
+#[derive(Debug)]
+struct ZipSkillBundle {
+ skill_md: String,
+ extra_files: Vec,
+ bundle_subdir: Option,
+}
+
+#[derive(Debug, Clone)]
+struct GitHubRepoRef {
+ owner: String,
+ repo: String,
+ branch: String,
+ subdir: Option,
+}
+
+#[derive(Debug, Clone)]
+struct GitHubRepoRequest {
+ owner: String,
+ repo: String,
+ tree_segments: Option>,
+}
+
+#[derive(Debug, Clone)]
+struct GitHubBlobRequest {
+ owner: String,
+ repo: String,
+ blob_segments: Vec,
+}
+
+fn is_safe_github_component(component: &str) -> bool {
+ !component.is_empty()
+ && component
+ .bytes()
+ .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'))
+}
+
+fn validate_github_repo_components(owner: &str, repo: &str) -> Result<(), SkillFetchError> {
+ if !is_safe_github_component(owner) {
+ return Err(SkillFetchError::from_message(format!(
+ "Invalid GitHub owner in skill URL: {}",
+ owner
+ )));
+ }
+ if !is_safe_github_component(repo) {
+ return Err(SkillFetchError::from_message(format!(
+ "Invalid GitHub repository in skill URL: {}",
+ repo
+ )));
+ }
+ Ok(())
+}
+
+fn validate_github_repo_ref(repo: &GitHubRepoRef) -> Result<(), SkillFetchError> {
+ validate_github_repo_components(&repo.owner, &repo.repo)
+}
+
+fn validate_derived_fetch_url(url: &str) -> Result {
+ validate_fetch_url(url).map_err(|e| SkillFetchError::from_message(e.to_string()))
+}
+
+fn validate_payload_skill_size(
+ payload: SkillInstallPayload,
+) -> Result {
+ if payload.skill_md.len() as u64 > ironclaw_skills::MAX_PROMPT_FILE_SIZE {
+ return Err(SkillFetchError::from_message(format!(
+ "Skill content too large: {} bytes (max {} bytes)",
+ payload.skill_md.len(),
+ ironclaw_skills::MAX_PROMPT_FILE_SIZE
+ )));
+ }
+ Ok(payload)
+}
+
#[derive(Debug, Default)]
struct ChainInstallReport {
installed: Vec,
@@ -122,7 +207,7 @@ async fn install_missing_skill_dependencies(
) -> Result
where
F: Fn(String) -> Fut,
- Fut: Future