pilotswarm 0.5.17 → 0.5.18

package/ui/core/src/controller.js

@@ -765,9 +765,20 @@ function stripPromptAttachmentTokens(prompt, attachments = []) {
         .trim();
 }
 
+// Raster types + caps for image prompt attachments. Mirrors the SDK's
+// IMAGE_ATTACHMENT_CONTENT_TYPES / ATTACHMENT_MAX_BYTES — the server is the
+// enforcement point; these exist so the composer rejects early with a clear
+// message instead of a failed send.
+export const IMAGE_PROMPT_ATTACHMENT_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+export const IMAGE_PROMPT_ATTACHMENT_MAX_BYTES = 4 * 1024 * 1024;
+export const IMAGE_PROMPT_ATTACHMENT_MAX_COUNT = 4;
+
 function expandPromptAttachments(prompt, attachments = []) {
     const validAttachments = Array.isArray(attachments)
-        ? attachments.filter((attachment) => attachment?.sessionId && attachment?.filename)
+        // Image attachments are model-visible (sent as blob attachments by the
+        // worker) — they inject NO text ref. Only legacy artifact references
+        // still expand into artifact:// pointers.
+        ? attachments.filter((attachment) => attachment?.sessionId && attachment?.filename && attachment?.kind !== "image")
         : [];
     if (validAttachments.length === 0) return String(prompt || "");
 
@@ -1324,12 +1335,157 @@ export class PilotSwarmUiController {
         return await this.cancelOutboxItem(sessionId, target.id);
     }
 
-    queuePromptInOutbox(sessionId, prompt) {
+    queuePromptInOutbox(sessionId, prompt, extras = null) {
         const item = this.buildOutboxItem(prompt, "pending");
+        if (Array.isArray(extras?.attachments) && extras.attachments.length > 0) {
+            item.attachments = extras.attachments;
+        }
         this.setSessionOutboxItems(sessionId, [...this.getSessionOutbox(sessionId), item]);
         return item;
     }
 
+    /**
+     * Stage image files (paste / drop / picker) as pending prompt attachments.
+     * Client-side pre-validation only — the API edge re-validates on send.
+     * Returns { accepted, rejected: [{name, reason}] } for UI feedback.
+     */
+    addPendingImageFiles(files) {
+        const incoming = Array.from(files || []).filter(Boolean);
+        const current = this.getPromptAttachments();
+        const existingImages = current.filter((a) => a?.kind === "image");
+        const accepted = [];
+        const rejected = [];
+        for (const file of incoming) {
+            const contentType = String(file.type || "").toLowerCase();
+            if (!IMAGE_PROMPT_ATTACHMENT_TYPES.has(contentType)) {
+                rejected.push({ name: file.name || "image", reason: "unsupported type" });
+                continue;
+            }
+            if ((Number(file.size) || 0) > IMAGE_PROMPT_ATTACHMENT_MAX_BYTES) {
+                rejected.push({ name: file.name || "image", reason: "over 4 MB" });
+                continue;
+            }
+            if (existingImages.length + accepted.length >= IMAGE_PROMPT_ATTACHMENT_MAX_COUNT) {
+                rejected.push({ name: file.name || "image", reason: `max ${IMAGE_PROMPT_ATTACHMENT_MAX_COUNT} images` });
+                continue;
+            }
+            accepted.push({
+                kind: "image",
+                file,
+                filename: String(file.name || "image"),
+                contentType,
+                sizeBytes: Number(file.size) || 0,
+            });
+        }
+        if (accepted.length > 0) {
+            this.setPromptAttachments([...current, ...accepted]);
+        }
+        if (rejected.length > 0) {
+            this.dispatch({
+                type: "ui/status",
+                text: `Skipped ${rejected.map((r) => `${r.name} (${r.reason})`).join(", ")}`,
+            });
+        }
+        return { accepted: accepted.length, rejected };
+    }
+
+    /**
+     * Stage an already-uploaded raster artifact as a prompt image attachment
+     * (uploaded:true entries skip re-upload at send). Returns whether staged.
+     * Shared by the TUI upload modal and clipboard paste.
+     */
+    stageUploadedImageAttachment(result, sessionId) {
+        const contentType = String(result?.contentType || "").toLowerCase();
+        if (!IMAGE_PROMPT_ATTACHMENT_TYPES.has(contentType)) return false;
+        if ((Number(result?.sizeBytes) || 0) > IMAGE_PROMPT_ATTACHMENT_MAX_BYTES) return false;
+        const stagedImages = this.getPromptAttachments().filter((a) => a?.kind === "image");
+        if (stagedImages.length >= IMAGE_PROMPT_ATTACHMENT_MAX_COUNT) return false;
+        this.setPromptAttachments([
+            ...this.getPromptAttachments(),
+            {
+                kind: "image",
+                uploaded: true,
+                sessionId,
+                filename: result.filename,
+                contentType,
+                sizeBytes: Number(result?.sizeBytes) || 0,
+            },
+        ]);
+        return true;
+    }
+
+    /**
+     * TUI Ctrl+V: read an image off the OS clipboard (the transport shells to
+     * the platform clipboard tool — terminals never deliver image bytes),
+     * upload it as a session artifact, and stage it on the next message.
+     */
+    async pasteImageFromClipboard() {
+        if (typeof this.transport.captureClipboardImage !== "function"
+            || typeof this.transport.uploadArtifactFromPath !== "function") {
+            this.dispatch({ type: "ui/status", text: "Clipboard image paste is not supported by this transport" });
+            return false;
+        }
+        let capture = null;
+        try {
+            capture = await this.transport.captureClipboardImage();
+        } catch (error) {
+            this.dispatch({ type: "ui/status", text: `Clipboard read failed: ${error?.message || error}` });
+            return false;
+        }
+        if (!capture?.path) {
+            this.dispatch({ type: "ui/status", text: "No image on the clipboard" });
+            return false;
+        }
+        this.dispatch({ type: "ui/status", text: "Attaching clipboard image..." });
+        try {
+            const sessionId = this.getPromptDraftSessionId() || await this.ensurePromptAttachmentSessionId();
+            const upload = await this.transport.uploadArtifactFromPath(sessionId, capture.path);
+            const result = await this.finalizeArtifactUpload(upload, { sessionId, suppressStatus: true });
+            if (this.stageUploadedImageAttachment(result, sessionId)) {
+                this.dispatch({ type: "ui/status", text: `Clipboard image attached to your next message (${result.filename})` });
+                return true;
+            }
+            this.dispatch({ type: "ui/status", text: `Uploaded ${result.filename} (not attachable: type/size/count limit)` });
+            return false;
+        } catch (error) {
+            this.dispatch({ type: "ui/status", text: `Clipboard image attach failed: ${error?.message || error}` });
+            return false;
+        }
+    }
+
+    removePendingImageAttachment(index) {
+        const current = this.getPromptAttachments();
+        const images = current.filter((a) => a?.kind === "image");
+        const target = images[index];
+        if (!target) return;
+        this.setPromptAttachments(current.filter((a) => a !== target));
+    }
+
+    /**
+     * Upload staged image attachments as session artifacts and return send
+     * refs. Filenames are derived from the outbox client-message id so a
+     * retry overwrites the same artifact instead of duplicating it.
+     * Entries staged from an already-uploaded artifact (TUI attach-by-path,
+     * marked uploaded:true with no File) skip the upload and ref directly.
+     */
+    async uploadPendingImageAttachments(sessionId, images, clientMessageId) {
+        const refs = [];
+        const idStem = String(clientMessageId || Date.now()).replace(/[^a-zA-Z0-9_-]/g, "").slice(-24) || "img";
+        let uploadIndex = 0;
+        for (const image of images) {
+            if (!image.file) {
+                if (image.uploaded && image.filename) refs.push({ filename: image.filename });
+                continue;
+            }
+            uploadIndex += 1;
+            const ext = { "image/png": "png", "image/jpeg": "jpg", "image/gif": "gif", "image/webp": "webp" }[image.contentType] || "png";
+            const filename = `attach-${idStem}-${uploadIndex}.${ext}`;
+            await this.transport.uploadArtifactFromFile(sessionId, image.file, filename);
+            refs.push({ filename });
+        }
+        return refs;
+    }
+
     acknowledgeOutboxPrompt(sessionId, promptText, clientMessageId = null) {
         if (!sessionId) return false;
         const items = this.getSessionOutbox(sessionId);
@@ -1446,6 +1602,9 @@ export class PilotSwarmUiController {
                 : [item.id]
         ));
         const mergedText = pendingItems.map((item) => String(item.text || "")).join("\n\n");
+        const mergedAttachments = pendingItems.flatMap((item) => (
+            Array.isArray(item.attachments) ? item.attachments : []
+        ));
         const mergedItem = {
             id: pendingItems[0].id,
             text: mergedText,
@@ -1453,6 +1612,7 @@ export class PilotSwarmUiController {
             phase: "pending",
             attempted: true,
             clientMessageIds: mergedClientMessageIds,
+            ...(mergedAttachments.length > 0 ? { attachments: mergedAttachments } : {}),
         };
         const pendingIdSet = new Set(pendingItems.map((item) => item.id));
         const otherItems = this.getSessionOutbox(sessionId).filter((item) => !pendingIdSet.has(item.id));
@@ -1469,6 +1629,9 @@ export class PilotSwarmUiController {
             await this.transport.sendMessage(sessionId, mergedItem.text, {
                 enqueueOnly: true,
                 clientMessageIds: mergedItem.clientMessageIds,
+                ...(Array.isArray(mergedItem.attachments) && mergedItem.attachments.length > 0
+                    ? { attachments: mergedItem.attachments }
+                    : {}),
             });
 
             // Promote pending → queued for the merged item.
@@ -4294,6 +4457,16 @@ export class PilotSwarmUiController {
             const upload = await this.transport.uploadArtifactFromPath(sessionId, filePath);
             const result = await this.finalizeArtifactUpload(upload, { sessionId, suppressStatus: true });
             this.dispatch({ type: "ui/modal", modal: null });
+            // TUI attach-by-path: an uploaded raster image is also staged as a
+            // prompt attachment so the next message shows it to the model —
+            // same send path as the portal's paste/drop chips.
+            if (this.stageUploadedImageAttachment(result, sessionId)) {
+                this.dispatch({
+                    type: "ui/status",
+                    text: `Uploaded ${result.filename} — attached to your next message`,
+                });
+                return;
+            }
             this.dispatch({
                 type: "ui/status",
                 text: `Uploaded ${result.filename}`,
@@ -5208,7 +5381,10 @@ export class PilotSwarmUiController {
 
         // Empty Enter on a session with pending outbox items forces an immediate
         // dispatch of any pending merge group; this is the "send batch" affordance.
-        if (!prompt.trim()) {
+        // Staged image attachments make an empty prompt sendable (a default
+        // caption is filled in below), so they bypass this early return.
+        const hasStagedImages = promptAttachments.some((a) => a?.kind === "image");
+        if (!prompt.trim() && !hasStagedImages) {
             if (sessionId && this.getPendingOutboxItems(sessionId).length > 0) {
                 await this.dispatchPendingOutbox(sessionId).catch(() => {});
             }
@@ -5296,7 +5472,32 @@ export class PilotSwarmUiController {
         // `controller.sendPrompt()` calls without intervening `await`s) still
         // merge because the second call enters before the first dispatcher
         // microtask runs.
-        this.queuePromptInOutbox(sessionId, prompt);
+        //
+        // Image attachments upload FIRST (artifact = source of truth), then the
+        // message references them by filename. A failed upload keeps the prompt
+        // and the staged images — a message never goes out half-attached.
+        const pendingImages = promptAttachments.filter((a) => a?.kind === "image");
+        let attachmentRefs = null;
+        if (pendingImages.length > 0) {
+            const needsUpload = pendingImages.some((a) => a.file);
+            if (needsUpload && typeof this.transport.uploadArtifactFromFile !== "function") {
+                this.dispatch({ type: "ui/status", text: "This transport does not support image attachments." });
+                return;
+            }
+            const uploadItem = this.buildOutboxItem("", "pending");
+            this.dispatch({ type: "ui/status", text: `Uploading ${pendingImages.length} image${pendingImages.length > 1 ? "s" : ""}...` });
+            try {
+                attachmentRefs = await this.uploadPendingImageAttachments(sessionId, pendingImages, uploadItem.id);
+                this.dispatch({ type: "ui/status", text: "" });
+            } catch (error) {
+                this.dispatch({ type: "ui/status", text: `Image upload failed: ${error?.message || error}` });
+                return;
+            }
+        }
+        const outboundPrompt = prompt.trim()
+            ? prompt
+            : (attachmentRefs && attachmentRefs.length > 0 ? "See the attached image(s)." : prompt);
+        this.queuePromptInOutbox(sessionId, outboundPrompt, attachmentRefs ? { attachments: attachmentRefs } : null);
         this.setPrompt("", 0);
         this.setPromptAttachments([]);
         await this.dispatchPendingOutbox(sessionId).catch(() => {});

package/ui/core/src/history.js

@@ -380,6 +380,11 @@ function buildChatMessage(event, role) {
     const sender = event?.data?.sender && typeof event.data.sender === "object"
         ? event.data.sender
         : null;
+    // Image attachment refs recorded by the runTurn activity — rendered as
+    // chips under the user message (bytes stay in the artifact store).
+    const attachments = Array.isArray(event?.data?.attachments)
+        ? event.data.attachments.filter((a) => a && typeof a.filename === "string" && a.filename)
+        : [];
     return {
         id: `${event.sessionId}:${event.seq}`,
         role: deriveChatRole(event, role, text),
@@ -388,6 +393,7 @@ function buildChatMessage(event, role) {
         createdAt: event.createdAt instanceof Date ? event.createdAt.getTime() : new Date(event.createdAt).getTime(),
         ...(clientMessageIds.length > 0 ? { clientMessageIds } : {}),
         ...(sender ? { sender } : {}),
+        ...(attachments.length > 0 ? { attachments } : {}),
     };
 }
 

package/ui/core/src/reducer.js

@@ -224,15 +224,33 @@ const TERMINAL_SESSION_STATUSES = new Set(["completed", "failed", "cancelled", "
 // update is genuinely newer. Deliberately not restricted to idle-like
 // statuses: the status actually observed clobbering a live run was "waiting",
 // and an earlier version of this guard missed the bug by excluding it.
-// Terminal statuses are exempt so a finished run can never be stranded, and
-// the timestamp test means a real transition (which carries a newer
-// updatedAt) still lands immediately.
+// Terminal statuses are exempt so a finished run can never be stranded.
+//
+// "Genuinely newer" is decided by the server's monotonic statusVersion when
+// both sides carry one — wall-clock updatedAt is only the fallback. The
+// timestamp heuristic alone can WEDGE a finished turn as "running" forever:
+// client-side event merges (turn_completed, context usage) inflate the held
+// session's updatedAt past the server row's idle-write timestamp, so every
+// subsequent idle poll compares as stale and only a terminal status could
+// ever land. Observed live (2026-07-21, local portal): server row idle at
+// statusVersion 5 while the client showed "Working.." indefinitely.
 function shouldPreserveRunningStatus(previousSession, nextSession) {
     const nextStatus = String(nextSession?.status ?? "").toLowerCase();
-    return previousSession?.status === "running"
-        && nextStatus !== "running"
-        && !TERMINAL_SESSION_STATUSES.has(nextStatus)
-        && isSameOrOlderSessionUpdate(previousSession, nextSession);
+    if (previousSession?.status !== "running"
+        || nextStatus === "running"
+        || TERMINAL_SESSION_STATUSES.has(nextStatus)) {
+        return false;
+    }
+    const previousVersion = Number(previousSession?.statusVersion);
+    const nextVersion = Number(nextSession?.statusVersion);
+    if (Number.isFinite(previousVersion) && previousVersion > 0
+        && Number.isFinite(nextVersion) && nextVersion > 0) {
+        // Monotonic server counter: a higher version is authoritative and
+        // must land; a same-or-lower version is provably stale and is held
+        // regardless of what the timestamps claim.
+        return nextVersion <= previousVersion;
+    }
+    return isSameOrOlderSessionUpdate(previousSession, nextSession);
 }
 
 function mergeDefinedSessionFields(previousSession = {}, nextSession = {}) {
@@ -543,6 +561,9 @@ function normalizePromptAttachments(prompt, attachments) {
     const safePrompt = String(prompt || "");
     const list = Array.isArray(attachments) ? attachments.filter(Boolean) : [];
     return list.filter((attachment) => {
+        // Image attachments are chip-managed (staged File objects, no inline
+        // token in the prompt) — they live until sent or explicitly removed.
+        if (attachment?.kind === "image") return true;
         const token = String(attachment?.token || "").trim();
         return token && safePrompt.includes(token);
     });

package/ui/core/src/selectors.js

@@ -2017,13 +2017,16 @@ function buildChatMessageLines(message, maxWidth, options = {}) {
             : message?.role === "user" ? USER_CHAT_COLOR : null,
     );
     const prefix = options.skipPrefix ? [] : buildChatMessagePrefix(message, options);
+    const attachmentChipLines = buildAttachmentChipLines(message, options);
 
     if (tintedMarkdownLines.length === 0) {
-        return prefix.length > 0 ? [prefix] : [];
+        const bare = prefix.length > 0 ? [prefix] : [];
+        return attachmentChipLines.length > 0 ? [...bare, ...attachmentChipLines] : bare;
     }
 
     if (startsWithStructuredBlock(tintedMarkdownLines)) {
-        return prefix.length > 0 ? [prefix, ...tintedMarkdownLines] : tintedMarkdownLines;
+        const structured = prefix.length > 0 ? [prefix, ...tintedMarkdownLines] : tintedMarkdownLines;
+        return attachmentChipLines.length > 0 ? [...structured, ...attachmentChipLines] : structured;
     }
 
     const renderedLines = [];
@@ -2044,9 +2047,35 @@ function buildChatMessageLines(message, maxWidth, options = {}) {
             renderedLines.push(lineRuns);
         }
     }
+    renderedLines.push(...attachmentChipLines);
     return renderedLines;
 }
 
+// Image attachment chips under a message. In sentinel mode (browser portal)
+// a single structured line carries the refs so the web renderer can show
+// authenticated thumbnails; everywhere else (TUI) each file renders as a
+// `[image: name · 312 KB]` text chip.
+function buildAttachmentChipLines(message, options = {}) {
+    const attachments = Array.isArray(message?.attachments) ? message.attachments : [];
+    if (attachments.length === 0) return [];
+    if (options.tableMode === "sentinel") {
+        // message.id is `${sessionId}:${seq}` — the renderer needs the session
+        // to fetch artifact bytes through the authenticated transport.
+        const sessionId = String(message?.id || "").split(":")[0] || null;
+        return [{ kind: "imageAttachments", sessionId, attachments }];
+    }
+    return attachments.map((attachment) => {
+        const size = Number(attachment?.sizeBytes) || 0;
+        const sizeLabel = size >= 1024 * 1024
+            ? `${(size / (1024 * 1024)).toFixed(1)} MB`
+            : size >= 1024 ? `${Math.round(size / 1024)} KB` : `${size} B`;
+        return [
+            { text: "  ", color: null },
+            { text: `[image: ${attachment.filename}${size > 0 ? ` · ${sizeLabel}` : ""}]`, color: "cyan" },
+        ];
+    });
+}
+
 // Activity-log event types that are not surfaced as live "recent action" lines
 // in the chat pane: bookkeeping, high-frequency streaming noise, and the turn
 // bracket markers (which don't read well as prose).