mulmoclaude 0.9.2 → 0.9.4

package/server/remoteHost/handlers/collectionPage.ts

@@ -2,25 +2,23 @@
 //
 // The command channel writes the result INSIDE the command document, and
 // Firestore caps a document at 1 MiB. offset/limit slice the records; limit is
-// clamped to [1, MAX_LIMIT] (default 50) so a runaway page can't blow that
-// budget. Params arrive as JSON over the channel, so coerce defensively.
-import type { JsonObject, JsonValue } from "../commandChannel.js";
+// clamped to [1, MAX_PAGE_LIMIT] (default 50) so a runaway page can't blow
+// that budget. The clamps live in @mulmoclaude/core/remote-view (params arrive
+// as untyped JSON there too) so the record handlers and the remote-view bridge
+// serve identical page semantics — re-exported here for the handlers.
+import { clampLimit, clampOffset } from "@mulmoclaude/core/remote-view";
+import { deriveAll, type DerivableFieldSpec, type DerivableRecord } from "@mulmoclaude/core/collection";
+import type { JsonObject } from "../commandChannel.js";
 
-const DEFAULT_LIMIT = 50;
-const MAX_LIMIT = 200;
+export { clampLimit, clampOffset };
 
-const toInt = (value: JsonValue): number | null => {
-  const num = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
-  return Number.isFinite(num) ? Math.floor(num) : null;
-};
-
-export const clampOffset = (value: JsonValue): number => Math.max(0, toInt(value) ?? 0);
-
-export const clampLimit = (value: JsonValue): number => {
-  const num = toInt(value);
-  if (num === null || num <= 0) return DEFAULT_LIMIT;
-  return Math.min(num, MAX_LIMIT);
-};
+/** Resolve record-local computed fields (derived formulas) before paging, so
+ *  channel consumers — the phase-2 card list and a remote view's `getItems` —
+ *  see the same numbers the desktop renders. There is no ref cache over the
+ *  channel, so formulas that dereference `ref` fields stay absent; the desktop
+ *  phone-frame preview derives with the same empty cache (parity). */
+export const deriveItems = (schema: { fields?: Record<string, DerivableFieldSpec> }, items: unknown[]): DerivableRecord[] =>
+  items.map((item) => deriveAll({ fields: schema.fields ?? {} }, item as DerivableRecord, {}));
 
 // Build the paginated result. `detail` (a CollectionDetail) and `items`
 // (CollectionItem[]) are plain JSON, but their interfaces lack an index

package/server/remoteHost/handlers/getCollection.ts

@@ -9,7 +9,7 @@
 // stubbed; the default export wires the real engine functions.
 import { listItems, loadCollection, toDetail } from "../../workspace/collections/index.js";
 import type { CommandHandler, JsonObject } from "../commandChannel.js";
-import { clampLimit, clampOffset, pageResult } from "./collectionPage.js";
+import { clampLimit, clampOffset, deriveItems, pageResult } from "./collectionPage.js";
 
 export interface GetCollectionDeps {
   loadCollection: typeof loadCollection;
@@ -25,7 +25,7 @@ export const createGetCollection =
     const limit = clampLimit(params.limit);
     const collection = await deps.loadCollection(slug);
     if (!collection) throw new Error(`collection '${slug}' not found`);
-    const all = await deps.listItems(collection.dataDir);
+    const all = deriveItems(collection.schema, await deps.listItems(collection.dataDir));
     return pageResult(deps.toDetail(collection), all, offset, limit);
   };
 

package/server/remoteHost/handlers/getFeed.ts

@@ -10,7 +10,7 @@ import { listFeeds as listFeedsRegistry } from "@mulmoclaude/core/feeds/server";
 import { listItems, toDetail } from "../../workspace/collections/index.js";
 import { workspacePath } from "../../workspace/workspace.js";
 import type { CommandHandler, JsonObject } from "../commandChannel.js";
-import { clampLimit, clampOffset, pageResult } from "./collectionPage.js";
+import { clampLimit, clampOffset, deriveItems, pageResult } from "./collectionPage.js";
 
 export interface GetFeedDeps {
   listFeeds: typeof listFeedsRegistry;
@@ -28,7 +28,7 @@ export const createGetFeed =
     const feeds = await deps.listFeeds(deps.workspaceRoot);
     const feed = feeds.find((entry) => entry.slug === slug);
     if (!feed) throw new Error(`feed '${slug}' not found`);
-    const all = await deps.listItems(feed.dataDir);
+    const all = deriveItems(feed.schema, await deps.listItems(feed.dataDir));
     return pageResult(deps.toDetail(feed), all, offset, limit);
   };
 

package/server/remoteHost/handlers/getRemoteView.ts

@@ -0,0 +1,37 @@
+// getRemoteView command handler (remote-host phase 3 —
+// plans/feat-remote-custom-view.md).
+//
+// Returns one mobile (`target: "mobile"`) custom view wrapped HOST-side into
+// its sandboxed srcdoc (CSP + postMessage bootstrap), so the phone renders the
+// artifact verbatim — the same builder the desktop phone-frame preview reads
+// over HTTP, keeping preview === phone structural. The srcdoc travels inside
+// the Firestore command document; the builder enforces the 1 MiB budget.
+//
+// Factory (createGetRemoteView) keeps the mapping unit-testable with the
+// engine stubbed; the default export wires the real functions.
+import { loadCollection } from "../../workspace/collections/index.js";
+import { buildRemoteView, remoteViewFailureMessage } from "../../workspace/collections/remoteView.js";
+import type { CommandHandler, JsonObject } from "../commandChannel.js";
+
+export interface GetRemoteViewDeps {
+  loadCollection: typeof loadCollection;
+  buildRemoteView: typeof buildRemoteView;
+}
+
+export const createGetRemoteView =
+  (deps: GetRemoteViewDeps): CommandHandler =>
+  async (params: JsonObject) => {
+    const slug = String(params.slug ?? "");
+    const viewId = String(params.viewId ?? "");
+    const locale = typeof params.locale === "string" ? params.locale : "";
+    const collection = await deps.loadCollection(slug);
+    if (!collection) throw new Error(`collection '${slug}' not found`);
+    const result = await deps.buildRemoteView(collection, viewId, locale);
+    if (result.kind !== "ok") throw new Error(remoteViewFailureMessage(result, slug));
+    const { view, srcdoc, bytes } = result;
+    // Plain JSON, but the interface lacks an index signature — cast like the
+    // phase-2 handlers.
+    return { view, srcdoc, bytes } as unknown as JsonObject;
+  };
+
+export const getRemoteView = createGetRemoteView({ loadCollection, buildRemoteView });

package/server/remoteHost/handlers/getRemoteViewItems.ts

@@ -0,0 +1,38 @@
+// getRemoteViewItems command handler (remote-host phase 5 —
+// plans/feat-remote-view-images.md).
+//
+// One page of a mobile view's records, view-aware so the host can inline the
+// view's declared `imageFields` as `data:` URL thumbnails (a phone can't reach
+// the workspace to render an image path). Same builder the desktop phone-frame
+// preview reads over HTTP, so preview === phone. Supersedes the phase-2
+// getCollection for a custom view's getItems: the page is already projected +
+// image-inlined, so the mulmoserver client passes it straight to the view.
+//
+// Factory (createGetRemoteViewItems) keeps the mapping unit-testable with the
+// engine stubbed; the default export wires the real functions.
+import { clampLimit, clampOffset, normalizeFields } from "@mulmoclaude/core/remote-view";
+import { loadCollection } from "../../workspace/collections/index.js";
+import { remoteViewItems, remoteViewItemsFailureMessage } from "../../workspace/collections/remoteView.js";
+import type { CommandHandler, JsonObject } from "../commandChannel.js";
+
+export interface GetRemoteViewItemsDeps {
+  loadCollection: typeof loadCollection;
+  remoteViewItems: typeof remoteViewItems;
+}
+
+export const createGetRemoteViewItems =
+  (deps: GetRemoteViewItemsDeps): CommandHandler =>
+  async (params: JsonObject) => {
+    const slug = String(params.slug ?? "");
+    const viewId = String(params.viewId ?? "");
+    const request = { offset: clampOffset(params.offset), limit: clampLimit(params.limit), fields: normalizeFields(params.fields) };
+    const collection = await deps.loadCollection(slug);
+    if (!collection) throw new Error(`collection '${slug}' not found`);
+    const result = await deps.remoteViewItems(collection, viewId, request);
+    if (result.kind !== "ok") throw new Error(remoteViewItemsFailureMessage(result, slug));
+    // Plain JSON, but the interface lacks an index signature — cast like the
+    // phase-2/3 handlers.
+    return { page: result.page, inlined: result.inlined, omitted: result.omitted } as unknown as JsonObject;
+  };
+
+export const getRemoteViewItems = createGetRemoteViewItems({ loadCollection, remoteViewItems });

package/server/remoteHost/handlers/index.ts

@@ -4,16 +4,26 @@
 import type { CommandHandlers } from "../commandChannel.js";
 import { getCollection } from "./getCollection.js";
 import { getFeed } from "./getFeed.js";
+import { getRemoteView } from "./getRemoteView.js";
+import { getRemoteViewItems } from "./getRemoteViewItems.js";
+import { listAccountingBooks } from "./listAccountingBooks.js";
 import { listCollections } from "./listCollections.js";
 import { listFeeds } from "./listFeeds.js";
 import { listShortcuts } from "./listShortcuts.js";
+import { listSkills } from "./listSkills.js";
+import { mutateRemoteViewItem } from "./mutateRemoteView.js";
 import { startChat } from "./startChat.js";
 
 export const handlers: CommandHandlers = {
   listCollections,
   getCollection,
   listShortcuts,
+  listSkills,
   listFeeds,
   getFeed,
+  getRemoteView,
+  getRemoteViewItems,
+  mutateRemoteViewItem,
+  listAccountingBooks,
   startChat,
 };

package/server/remoteHost/handlers/ingestAttachments.ts

@@ -0,0 +1,88 @@
+// Attachment ingest for remote chat (plans/feat-remote-chat-image-attachments.md).
+//
+// The phone can't carry full-res attachment bytes over the Firestore command
+// channel (a command doc caps at ~1 MiB), so it uploads each file — photo,
+// video, or PDF — to Firebase Storage at `users/{uid}/uploads/{storage_id}` and
+// sends only the `storage_id` on startChat. This module — signed in as the same
+// user — pulls each staged object, persists it into the workspace attachment
+// store via `saveAttachment` (so it lands in `data/attachments/YYYY/MM/`, gets a
+// correct mime, and is accepted by the same attachment pipeline Vue uploads
+// use), deletes the Storage object (staging only), and returns a path-only
+// `Attachment` per file for startChat to hand to the spawned chat.
+//
+// Factory (createIngestAttachments) keeps the flow unit-testable with the
+// Storage + attachment-store deps stubbed; the default export wires the real ones.
+import { deleteObject, getBytes, getMetadata, ref } from "firebase/storage";
+import type { Attachment } from "@mulmobridge/protocol";
+
+import { saveAttachment } from "../../utils/files/attachment-store.js";
+import { errorMessage } from "../../utils/errors.js";
+import { log } from "../../system/logger/index.js";
+import { currentUid } from "../auth.js";
+import { storage } from "../firebase.js";
+
+const PREFIX = "remote-host";
+
+// `storage_id` is a bare UUID minted by the remote (`crypto.randomUUID()`).
+// Accept only a safe token so it can never reshape the Storage path (no `/`,
+// no `..`) before it is interpolated into `users/{uid}/uploads/{storage_id}`.
+const STORAGE_ID_RE = /^[A-Za-z0-9-]+$/;
+
+// Belt-and-suspenders cap matching the remote's 100 MiB upload rule (full-res
+// photos + short mobile videos), so a mis-sized object can't balloon host memory
+// on download. A little headroom over the rule's ceiling.
+const MAX_DOWNLOAD_BYTES = 110 * 1024 * 1024;
+
+export interface IngestDeps {
+  uid: () => string | null;
+  fetchObject: (storagePath: string) => Promise<{ base64: string; contentType: string }>;
+  saveAttachment: (base64: string, mimeType: string) => Promise<{ relativePath: string; mimeType: string }>;
+  deleteObject: (storagePath: string) => Promise<void>;
+}
+
+// storage_ids -> path-only Attachments, in order. Rejects the whole batch on the
+// first failure to get bytes INTO the workspace (host not signed in, malformed
+// id, or a download/save that fails): the remote already uploaded and is waiting
+// on the result, so a surfaced error beats silently starting a chat with a
+// missing file. The subsequent Storage delete is best-effort — the bytes are
+// already safe in the workspace, so a failed delete only logs and leaves an
+// orphan for the Storage TTL sweep; it must NOT drop an already-ingested file.
+export const createIngestAttachments =
+  (deps: IngestDeps) =>
+  async (storageIds: string[]): Promise<Attachment[]> => {
+    if (storageIds.length === 0) return [];
+    const uid = deps.uid();
+    if (!uid) throw new Error("remote host is not signed in");
+    const attachments: Attachment[] = [];
+    for (const storageId of storageIds) {
+      if (!STORAGE_ID_RE.test(storageId)) throw new Error(`invalid storage_id: ${storageId}`);
+      const storagePath = `users/${uid}/uploads/${storageId}`;
+      const { base64, contentType } = await deps.fetchObject(storagePath);
+      const saved = await deps.saveAttachment(base64, contentType);
+      // Staging cleanup — best-effort. The file is already in the workspace, so
+      // a delete failure must not abort the batch (that would drop an ingested
+      // attachment); log and let the Storage TTL sweep reap the orphan.
+      try {
+        await deps.deleteObject(storagePath);
+      } catch (error) {
+        log.warn(PREFIX, "failed to delete staged upload after ingest; leaving orphan for TTL sweep", { storagePath, error: errorMessage(error) });
+      }
+      attachments.push({ path: saved.relativePath, mimeType: saved.mimeType });
+    }
+    return attachments;
+  };
+
+// Pull an object's bytes + content type from Storage. `getBytes` (not the
+// browser-only `getBlob`) returns an ArrayBuffer that works on the Node host.
+const fetchObject = async (storagePath: string): Promise<{ base64: string; contentType: string }> => {
+  const objectRef = ref(storage, storagePath);
+  const [bytes, metadata] = await Promise.all([getBytes(objectRef, MAX_DOWNLOAD_BYTES), getMetadata(objectRef)]);
+  return { base64: Buffer.from(bytes).toString("base64"), contentType: metadata.contentType ?? "application/octet-stream" };
+};
+
+export const ingestAttachments = createIngestAttachments({
+  uid: currentUid,
+  fetchObject,
+  saveAttachment,
+  deleteObject: (storagePath) => deleteObject(ref(storage, storagePath)),
+});

package/server/remoteHost/handlers/listAccountingBooks.ts

@@ -0,0 +1,31 @@
+// listAccountingBooks command handler (remote-host).
+//
+// Returns { books: [{ id, name }] } so the mobile remote can show a book picker
+// (e.g. before starting an accounting chat). Runs in-process on the host, so it
+// bypasses the HTTP bearer layer and calls the accounting engine's listBooks
+// directly. Only id + name travel — the remote doesn't need currency / country /
+// fiscalYearEnd / createdAt, and trimming keeps the command-channel payload
+// minimal (same "only what the client needs" discipline as listSkills).
+//
+// Exposed as a factory (createListAccountingBooks) so the mapping is
+// unit-testable with listBooks stubbed; the default export wires the real
+// engine function.
+import { listBooks } from "@mulmoclaude/accounting-plugin/server";
+import type { CommandHandler, JsonObject } from "../commandChannel.js";
+
+export interface ListAccountingBooksDeps {
+  listBooks: typeof listBooks;
+}
+
+export const createListAccountingBooks =
+  (deps: ListAccountingBooksDeps): CommandHandler =>
+  // Takes no params (the `__` prefix marks it intentionally unused per lint).
+  async (__params: JsonObject) => {
+    const { books } = await deps.listBooks();
+    // { id, name } are always present on a BookSummary. The cast only satisfies
+    // the channel's structural JsonValue type, which the BookSummary interface
+    // (no index signature) can't match directly.
+    return { books: books.map((book) => ({ id: book.id, name: book.name })) } as unknown as JsonObject;
+  };
+
+export const listAccountingBooks = createListAccountingBooks({ listBooks });

package/server/remoteHost/handlers/listCollections.ts

@@ -4,6 +4,11 @@
 // calls the collection engine directly, returning the same shape as
 // GET /api/collections: { collections: CollectionSummary[] }.
 //
+// Feeds (`source: "feed"`) are excluded: `discoverCollections` merges the
+// feeds registry as a third root (so the desktop can show them together), but
+// the mobile remote serves feeds through the dedicated listFeeds / getFeed
+// handlers, so surfacing them here too would double-list them.
+//
 // Exposed as a factory (createListCollections) so the mapping is unit-testable
 // with discovery stubbed; the default export wires the real engine functions.
 import { discoverCollections, toSummary } from "../../workspace/collections/index.js";
@@ -19,7 +24,7 @@ export const createListCollections =
   // Handlers receive the command's params; listCollections takes none (the
   // `__` prefix marks it intentionally unused per the lint config).
   async (__params: JsonObject) => {
-    const collections = (await deps.discover()).map(deps.toSummary);
+    const collections = (await deps.discover()).filter((collection) => collection.source !== "feed").map(deps.toSummary);
     // CollectionSummary is plain JSON (slug/title/icon/source strings), so this
     // is safe — the cast only satisfies the channel's structural JsonValue type,
     // which an interface without an index signature can't match directly.

package/server/remoteHost/handlers/listSkills.ts

@@ -0,0 +1,39 @@
+// listSkills command handler (remote-host).
+//
+// Returns just the ids (names) of the discoverable Claude Code skills as a
+// flat string[], mirroring the id column of GET /api/skills. Read-only:
+// creating/editing skills stays desktop-only (like listShortcuts / listFeeds).
+// Only ids travel — the phone asks for the detail it needs by other means, so
+// there is no reason to carry descriptions/source over the channel.
+//
+// Collection skills are excluded: a skill dir that ships a `schema.json` is a
+// collection (the same set `discoverCollections` finds under user/project
+// scope), and the mobile remote serves those through listCollections. Listing
+// them here too would double-list them, so we subtract the collection slugs.
+import { discoverCollections } from "../../workspace/collections/index.js";
+import { discoverSkills } from "../../workspace/skills/index.js";
+import { workspacePath } from "../../workspace/workspace.js";
+import type { CommandHandler, JsonObject } from "../commandChannel.js";
+
+export interface ListSkillsDeps {
+  discoverSkills: typeof discoverSkills;
+  discoverCollections: typeof discoverCollections;
+  workspaceRoot: string;
+}
+
+export const createListSkills =
+  (deps: ListSkillsDeps): CommandHandler =>
+  // Handler receives the command's params; listSkills takes none (the `__`
+  // prefix marks it intentionally unused per the lint config).
+  async (__params: JsonObject) => {
+    const [skills, collections] = await Promise.all([
+      deps.discoverSkills({ workspaceRoot: deps.workspaceRoot }),
+      deps.discoverCollections({ workspaceRoot: deps.workspaceRoot }),
+    ]);
+    // Feeds aren't skills, so only the skill-backed (user/project) collections
+    // can shadow a skill id — subtract those.
+    const collectionSlugs = new Set(collections.filter((collection) => collection.source !== "feed").map((collection) => collection.slug));
+    return { skills: skills.map((skill) => skill.name).filter((name) => !collectionSlugs.has(name)) };
+  };
+
+export const listSkills = createListSkills({ discoverSkills, discoverCollections, workspaceRoot: workspacePath });

package/server/remoteHost/handlers/mutateRemoteView.ts

@@ -0,0 +1,40 @@
+// mutateRemoteViewItem command handler (remote-host phase 4 —
+// plans/feat-remote-writable-view.md).
+//
+// Applies one update/delete requested by a `target: "mobile"` custom view on
+// the phone, authorized by that view's OWN declared surface
+// (editableFields / allowDelete) and enforced HOST-side (createMutateRemoteView)
+// — the sandboxed view is never trusted. The parent (mulmoserver) supplies the
+// `viewId` it mounted; the sandboxed document cannot spoof a different view's
+// policy. Shares the builder with the desktop preview's HTTP route so both
+// transports apply identical policy.
+//
+// Factory (createMutateRemoteView-backed) keeps the mapping unit-testable with
+// the engine stubbed; the default export wires the real functions.
+import { normalizeMutate } from "@mulmoclaude/core/remote-view";
+import { loadCollection } from "../../workspace/collections/index.js";
+import { mutateRemoteView, mutateRemoteViewFailureMessage } from "../../workspace/collections/remoteView.js";
+import type { CommandHandler, JsonObject } from "../commandChannel.js";
+
+export interface MutateRemoteViewHandlerDeps {
+  loadCollection: typeof loadCollection;
+  mutateRemoteView: typeof mutateRemoteView;
+}
+
+export const createMutateRemoteViewHandler =
+  (deps: MutateRemoteViewHandlerDeps): CommandHandler =>
+  async (params: JsonObject) => {
+    const slug = String(params.slug ?? "");
+    const viewId = String(params.viewId ?? "");
+    const request = normalizeMutate({ op: params.op, id: params.id, patch: params.patch });
+    if (!request) throw new Error("invalid mutate request — expected { op: 'update'|'delete', id, patch? }");
+    const collection = await deps.loadCollection(slug);
+    if (!collection) throw new Error(`collection '${slug}' not found`);
+    const result = await deps.mutateRemoteView(collection, viewId, request);
+    if (result.kind !== "ok") throw new Error(mutateRemoteViewFailureMessage(result, slug));
+    // Plain JSON, but the interface lacks an index signature — cast like the
+    // other phase-2/3 handlers.
+    return (result.op === "delete" ? { op: "delete", id: result.id } : { op: "update", item: result.item }) as unknown as JsonObject;
+  };
+
+export const mutateRemoteViewItem = createMutateRemoteViewHandler({ loadCollection, mutateRemoteView });

package/server/remoteHost/handlers/startChat.ts

@@ -1,78 +1,142 @@
 // startChat command handler (remote-host — start a chat from the mobile remote).
 //
-// Fire-and-forget: composes the collection's slash command as a prefix on the
-// user's message (`/<slug> <message>` for a collection, `/<slug> id=<itemId>
-// <message>` for one record), then spawns a VISIBLE host chat session (origin
-// `skill`, openable from history) via spawnSystemWorker, and returns the new
-// chatId. No streaming back — starting the chat on the host is enough.
+// The remote sends text; the host starts a new VISIBLE chat session (origin
+// `skill`, openable from desktop history) seeded with it, and returns the new
+// chatId. Fire-and-forget: no streaming back — starting the chat on the host is
+// enough.
 //
-// Mirrors the desktop's two entry points over the command channel: the
-// collection-level `__MC_VIEW.startChat` and the per-record chat box in
-// CollectionRecordPanel.vue (`/<slug> id=<itemId> <message>`).
+// ┌─────────────────────────────────────────────────────────────────────────┐
+// │ THE CONTRACT — read this before touching the params.                      │
+// │                                                                           │
+// │ CURRENT clients send ONLY `{ message }`. The message is seeded VERBATIM   │
+// │ as the first user turn. The host does NOT interpret it, so the client is  │
+// │ free to put a slash command (`/<slug> …`), a plain question, or anything  │
+// │ else in the text. This is the ONLY form new code should emit.             │
+// │                                                                           │
+// │ `slug` (and its optional companion `itemId`) is LEGACY-ONLY. Older        │
+// │ clients still send `{ slug, itemId?, message }` to target a collection    │
+// │ or one record; we keep composing `/<slug> [id=<itemId>] <message>` for    │
+// │ them so they don't break. DO NOT add new features to this branch, and DO  │
+// │ NOT teach new clients to send `slug` — put the slash command in           │
+// │ `message` instead. The whole legacy path can be deleted once no deployed  │
+// │ client sends `slug` anymore.                                              │
+// └─────────────────────────────────────────────────────────────────────────┘
 //
-// Role is intentionally NOT part of the remote API — the caller passes only
-// message + slug + optional itemId. The host runs the chat in its default role
-// (spawnSystemWorker → startChat requires a concrete roleId; empty is rejected).
+// Optional `role` — the id of the role the chat should run in (built-in or
+// custom). Absent / null / "" ⇒ the host default role. A provided id MUST match
+// an existing role: spawnSystemWorker requires a concrete roleId and the
+// downstream getRole silently falls back to `general` on a miss, so we validate
+// here and reject an unknown role rather than seed the wrong assistant.
 //
-// Feeds are refused: a feed (`source === "feed"`) has no `/<slug>` skill
-// command, so a slash-command seed would invoke nothing (see desktop
-// `CollectionView.buildChatSeed`). The mobile remote doesn't offer chat for
-// feeds; this is the host-side backstop so a stray feed slug can't produce a
-// broken chat.
+// Optional `attachments` — full-res files (photos, videos, PDFs) the remote
+// staged to Storage, carried as `[{ storage_id }]`. The host ingests them into
+// the workspace (ingestAttachments) and hands the resulting path-only
+// Attachments to the spawned chat. Absent / empty ⇒ byte-for-byte the prior
+// text-only behaviour.
 //
 // Factory (createStartChat) keeps composition/wiring unit-testable with the
 // engine + spawner stubbed; the default export wires the real ones.
 import { spawnSystemWorker } from "../../api/routes/agent.js";
 import { loadCollection } from "../../workspace/collections/index.js";
+import { loadAllRoles } from "../../workspace/roles.js";
 import { DEFAULT_ROLE_ID } from "../../../src/config/roles.js";
 import type { CommandHandler, JsonObject, JsonValue } from "../commandChannel.js";
+import { ingestAttachments } from "./ingestAttachments.js";
 
 export interface StartChatDeps {
   spawn: typeof spawnSystemWorker;
   loadCollection: typeof loadCollection;
+  ingest: typeof ingestAttachments;
+  loadRoles: typeof loadAllRoles;
 }
 
-// Prefix the message with the collection's slash command. `itemId` scopes the
-// chat to one record; empty ⇒ the whole collection. Matches the desktop
-// item-chat format documented in CollectionRecordPanel.vue.
+// Parse the optional `attachments` param into a list of storage_ids. Absent ⇒ no
+// attachments. A malformed shape (not an array, or an element without a string
+// `storage_id`) rejects the whole command: the remote already uploaded the
+// bytes and is waiting, so a surfaced error beats a chat with a missing file.
+const readStorageIds = (attachments: JsonValue | undefined): string[] => {
+  if (attachments == null) return [];
+  if (!Array.isArray(attachments)) throw new Error("attachments must be an array of { storage_id }");
+  return attachments.map((entry) => {
+    const storageId = entry && typeof entry === "object" && !Array.isArray(entry) ? entry.storage_id : undefined;
+    if (typeof storageId !== "string" || storageId.length === 0) throw new Error("each attachments entry must be { storage_id: string }");
+    return storageId;
+  });
+};
+
+// LEGACY. Prefix the message with the collection's slash command. `itemId`
+// scopes the chat to one record; empty ⇒ the whole collection. Matches the
+// desktop item-chat format documented in CollectionRecordPanel.vue. Only the
+// legacy `slug` path calls this — new clients put the slash command in
+// `message` themselves.
 export const composeMessage = (slug: string, itemId: string, message: string): string => {
   const prefix = itemId ? `/${slug} id=${itemId}` : `/${slug}`;
   return `${prefix} ${message}`;
 };
 
-// slug and itemId become single tokens in the slash command (`/<slug>`,
-// `id=<itemId>`), so a whitespace-containing or non-string value would break
-// the command parse (e.g. `/   hello`). Accept only a trimmed, whitespace-free
-// string; anything else ⇒ "" so the caller rejects it.
+// LEGACY. slug and itemId become single tokens in the slash command
+// (`/<slug>`, `id=<itemId>`), so a whitespace-containing or non-string value
+// would break the command parse (e.g. `/   hello`). Accept only a trimmed,
+// whitespace-free string; anything else ⇒ "" so the caller rejects it.
 const asToken = (value: JsonValue): string => {
   if (typeof value !== "string") return "";
   const trimmed = value.trim();
   return /\s/.test(trimmed) ? "" : trimmed;
 };
 
+// LEGACY collection/record targeting for older clients that still send `slug`.
+// Compose the `/<slug> [id=<itemId>] <message>` seed the desktop uses; reject a
+// malformed or unknown slug and refuse feeds, so we never seed a `/<slug>`
+// command that resolves to nothing. New clients skip all of this by sending the
+// slash command (or plain text) in `message`.
+const composeCollectionSeed = async (deps: StartChatDeps, params: JsonObject, message: string): Promise<string> => {
+  const slug = asToken(params.slug);
+  const itemId = asToken(params.itemId);
+  if (!slug) throw new Error("slug must be a non-empty, whitespace-free string");
+  if (params.itemId != null && !itemId) throw new Error("itemId must be a non-empty, whitespace-free string when provided");
+  const target = await deps.loadCollection(slug);
+  if (!target) throw new Error(`collection '${slug}' not found`);
+  if (target.source === "feed") throw new Error("chat is not available for feeds");
+  return composeMessage(slug, itemId, message);
+};
+
+// A `slug` is "provided" (⇒ LEGACY targeting) only when it is a non-empty
+// value. Omitted / null / "" ⇒ the current free-text form. New clients never
+// set it, so they always take the verbatim branch below.
+const hasSlug = (value: JsonValue | undefined): boolean => value != null && value !== "";
+
+// Resolve the optional `role` param to a concrete roleId. Absent / null / "" ⇒
+// the host default. A provided id must be a string that matches an existing
+// role (built-in or custom) — reject an unknown one so we never seed the chat
+// with the wrong (default-fallback) assistant. `isDebugRole` roles are excluded:
+// the desktop picker hides them from new sessions outside dev mode
+// (RoleSelector.vue), and the remote channel is a production-facing entry point,
+// so a debug role id is treated as not selectable here (rejected as unknown).
+const resolveRoleId = (deps: StartChatDeps, role: JsonValue | undefined): string => {
+  if (role == null || role === "") return DEFAULT_ROLE_ID;
+  if (typeof role !== "string") throw new Error("role must be a string");
+  if (!deps.loadRoles().some((candidate) => candidate.id === role && !candidate.isDebugRole)) throw new Error(`role '${role}' not found`);
+  return role;
+};
+
 export const createStartChat =
   (deps: StartChatDeps): CommandHandler =>
   async (params: JsonObject) => {
     // Params arrive as JSON over the channel — coerce/validate defensively.
-    const slug = asToken(params.slug);
-    const itemId = asToken(params.itemId);
     const message = (typeof params.message === "string" ? params.message : "").trim();
-    if (!slug) throw new Error("slug must be a non-empty, whitespace-free string");
-    if (params.itemId != null && !itemId) throw new Error("itemId must be a non-empty, whitespace-free string when provided");
     if (!message) throw new Error("message is required");
-    // Resolve the target so we never seed a `/<slug>` command that resolves to
-    // nothing: an unknown/stale slug (`null`) is rejected, and a feed
-    // (`source === "feed"`, no skill command) is refused.
-    const target = await deps.loadCollection(slug);
-    if (!target) throw new Error(`collection '${slug}' not found`);
-    if (target.source === "feed") throw new Error("chat is not available for feeds");
-    const result = await deps.spawn({
-      message: composeMessage(slug, itemId, message),
-      roleId: DEFAULT_ROLE_ID,
-      hidden: false,
-    });
+    // Current clients: `message` only ⇒ seed it verbatim. Legacy clients that
+    // still send `slug` ⇒ compose the old `/<slug> [id=<itemId>] <message>` seed.
+    const seed = hasSlug(params.slug) ? await composeCollectionSeed(deps, params, message) : message;
+    // Resolve the role BEFORE ingest/spawn so an unknown role rejects the
+    // command without staging work or launching a chat.
+    const roleId = resolveRoleId(deps, params.role);
+    // Ingest any staged files BEFORE spawning so a download/validation failure
+    // rejects the command instead of starting a chat missing its attachments.
+    const attachments = await deps.ingest(readStorageIds(params.attachments));
+    const result = await deps.spawn({ message: seed, roleId, hidden: false, attachments });
     if (!result.ok) throw new Error(result.error);
     return { started: true, chatId: result.chatId };
   };
 
-export const startChat = createStartChat({ spawn: spawnSystemWorker, loadCollection });
+export const startChat = createStartChat({ spawn: spawnSystemWorker, loadCollection, ingest: ingestAttachments, loadRoles: loadAllRoles });