auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/apps/desktop/chat/src/lib/agent-refs.ts

@@ -0,0 +1,105 @@
+/**
+ * What an agent points at in Studio, in its reply. The agent writes a token in its text (src/agents.mjs tells it how)
+ * and the chat draws it as a pill, the same pill the person's own references are, which opens the thing in Studio:
+ *
+ *   [[clip:<id>]]            a clip, by its film.html id
+ *   [[t:<seconds>]]          a moment of the film
+ *   [[range:<start>-<end>]]  a stretch of the film, in seconds (start before end)
+ *   [[track:<index>]]        a track, by its place in film.html (0 is the first)
+ *   [[file:<path>]]          a file of the project, by its path in the project
+ *
+ * Anything else between double brackets (an unknown kind, a number that is not one, a path out of the project) stays
+ * as the agent wrote it: a pill that leads nowhere would be worse than the words.
+ *
+ * Pure: no React, no bridge, so `node --test` runs it (src/agent-refs.test.mjs).
+ */
+import type { PromptReference as StoredPromptReference } from '@openfilm/shared';
+import type { StudioRef } from '../app-bridge';
+import { kindOf, soundRole } from 'openfilm/film-doc';
+import { refPill } from '../studio-refs.ts';
+
+export type AgentRefSegment = { kind: 'text'; text: string } | { kind: 'ref'; ref: StudioRef; raw: string };
+
+const TOKEN = /\[\[([a-z]+):([^\[\]\n]{1,300})\]\]/g;
+const SECONDS = /^\d+(?:\.\d+)?$/;
+
+/** The reference a token's kind and value name, or null when they name none. */
+function refOf(kind: string, value: string): StudioRef | null {
+  const v = value.trim();
+  switch (kind) {
+    case 'clip':
+      return /^[^\s"'<>`]{1,120}$/.test(v)
+        ? { kind: 'clip', id: v, loc: null, label: v, clipKind: 'mg', src: null, start: 0, end: 0 }
+        : null;
+    case 't':
+      return SECONDS.test(v) ? { kind: 'time', time: Number(v) } : null;
+    case 'range': {
+      /* an agent writes an en dash as often as a hyphen */
+      const m = /^(\d+(?:\.\d+)?)\s*[-–]\s*(\d+(?:\.\d+)?)$/.exec(v);
+      if (!m) return null;
+      const start = Number(m[1]);
+      const end = Number(m[2]);
+      return end > start ? { kind: 'range', start, end, clipIds: [] } : null;
+    }
+    case 'track':
+      return /^\d{1,3}$/.test(v) ? { kind: 'track', track: Number(v), label: '', clipIds: [] } : null;
+    case 'file': {
+      /* a path in the project: not from the disk's root, not out of the folder, not an address */
+      const path = v.replace(/^\.\//, '');
+      if (!path || path.startsWith('/') || /^[a-z]:[\\/]/i.test(path) || /^[a-z][a-z0-9+.-]*:/i.test(path)) return null;
+      if (path.split(/[\\/]/).some((part) => part === '..')) return null;
+      return { kind: 'file', path, fileKind: '' };
+    }
+    default:
+      return null;
+  }
+}
+
+/** A piece of the agent's text, split into its words and the references in it. */
+export function parseAgentRefs(text: string): AgentRefSegment[] {
+  const out: AgentRefSegment[] = [];
+  const pushText = (chunk: string) => {
+    if (!chunk) return;
+    const last = out[out.length - 1];
+    if (last?.kind === 'text') last.text += chunk;
+    else out.push({ kind: 'text', text: chunk });
+  };
+  let cursor = 0;
+  for (const match of text.matchAll(TOKEN)) {
+    const ref = refOf(match[1]!, match[2]!);
+    if (!ref) continue;
+    pushText(text.slice(cursor, match.index));
+    out.push({ kind: 'ref', ref, raw: match[0] });
+    cursor = match.index! + match[0].length;
+  }
+  pushText(text.slice(cursor));
+  return out;
+}
+
+/**
+ * The pill for a reference an agent wrote. A clip's kind (and so its icon) comes from its file, when the film it is in
+ * is known (`clipSrc`); a clip the film does not have gets the neutral icon. `trackLabel` names a track in the chat's
+ * language.
+ */
+export function agentRefPill(ref: StudioRef, { clipSrc, trackLabel }: { clipSrc?: string | null; trackLabel?: (track: number) => string } = {}): StoredPromptReference {
+  if (ref.kind === 'clip') {
+    const target: StudioRef = { ...ref, ...(clipSrc ? { src: clipSrc } : {}) };
+    return { id: `agent:clip:${ref.id}`, kind: clipSrc ? clipPillKind(clipSrc) : 'clip', label: ref.id ?? ref.label, target: target as unknown as Record<string, unknown> };
+  }
+  const pill = refPill(undefined, ref);
+  return { ...pill, id: `agent:${pill.id}`, ...(ref.kind === 'track' && trackLabel ? { label: trackLabel(ref.track) } : {}) };
+}
+
+/**
+ * The kind of pill (and so its icon) for a clip of this file, as the timeline colors it: a page is a motion graphic,
+ * a video or a still is a picture, a sound is a voice, a sound effect or music by where it lives.
+ */
+export function clipPillKind(src: string, sound = false): 'clipMg' | 'clipVideo' | 'clipVoice' | 'clipSfx' | 'clipMusic' {
+  const kind = kindOf({ src, ...(sound ? { sound: true } : {}) });
+  if (kind === 'page') return 'clipMg';
+  if (kind === 'sound') {
+    const role = soundRole(src);
+    return role === 'sfx' ? 'clipSfx' : role === 'music' ? 'clipMusic' : 'clipVoice';
+  }
+  return 'clipVideo';
+}

package/skill/assets/upstream/apps/desktop/chat/src/lib/agent-transcript.ts

@@ -0,0 +1,440 @@
+/**
+ * What the agent did this turn: what it said and what it did.
+ *
+ * Two sources feed one shape:
+ *   - the running turn: agent-text / agent-act / agent-act-done from the public SSE stream
+ *   - finished turns: the server-projected PublicProgressSnapshot.steps
+ * Both reduce to the same item, so the panel has one rendering path, not one for live and one for
+ * history, which are two readings of the same process.
+ *
+ * This layer has no filtering and should not: tool names, inputs, command lines and reasoning are
+ * already left out of the events on the server (see agent-activity and public-stream in
+ * @openfilm/shared). Filtering again on the client would leave the raw fields in the network panel:
+ * hidden, not absent.
+ */
+import {
+  TRANSCRIPT_TEXT_MAX,
+  clipTranscriptText,
+  mergeStreamText,
+  type AgentAct,
+  type AgentActAsset,
+  type AgentAsk,
+  type PublicGenerationEvent,
+  type PublicProgressSnapshot,
+  type PublicTimelineStep,
+} from '@openfilm/shared';
+import type { AgentActivityItem } from '@/components/AgentActivityRow';
+
+export interface TranscriptItem {
+  /** Merge key: text by partId, acts by callId. */
+  id: string;
+  /**
+   * `thought` / `plan` only come from an agent on the user's machine (Codex / Claude Code, see
+   * local-agent-run): the built-in agent's reasoning is not sent, and it has no plan tool.
+   */
+  kind: 'text' | 'act' | 'notice' | 'thought' | 'plan';
+  /** What it is doing (a closed set); absent for text / notice. */
+  act?: AgentAct;
+  /** The short visible text after the act (search query / picture description), picked by the server. */
+  query?: string;
+  /**
+   * The short tail after a local agent's file or command act: the file name or the command. Local
+   * sources only: that is the user's own agent working in the user's own folder.
+   */
+  detail?: string;
+  /** The plan checklist (each ACP plan update is the whole list, replaced in place). */
+  plan?: TranscriptPlanEntry[];
+  /** The `chat.ask` row: the question and options the agent stopped to ask. */
+  ask?: AgentAsk;
+  /** The asset this step made (image / sound / shot), seen and heard right in the conversation. Picked by the server. */
+  asset?: AgentActAsset;
+  /**
+   * The notice row's i18n key (the full token, resolved by t() when rendering).
+   *
+   * These rows are not the agent speaking but a note the platform leaves in the conversation; today
+   * there is one: earlier messages were summarized. It belongs in the conversation, because what it
+   * says is that the agent no longer has the original of the text above it.
+   *
+   * A local agent's own notice (ACP `notice`, such as a Codex warning) has no key: its words are in `text`.
+   */
+  noticeKey?: string;
+  text?: string;
+  turnNo?: number;
+  /** Still running: text not final, or an act sent but not yet back. */
+  pending: boolean;
+  /** When the client first saw it, to time running rows; history has none. */
+  startedAt?: number;
+  /** When thinking ended (thought only: "Thought for 6s"). */
+  endedAt?: number;
+}
+
+export interface TranscriptPlanEntry {
+  content: string;
+  status: 'pending' | 'in_progress' | 'completed';
+}
+
+/**
+ * Merges one public stream event into the record.
+ *
+ * Pure, returning a new array: on an SSE reconnect the server replays from the start, so this must be
+ * idempotent; the same partId / callId again updates in place rather than adding a row.
+ */
+export function reduceTranscript(
+  items: TranscriptItem[],
+  event: PublicGenerationEvent,
+  now: number = Date.now(),
+): TranscriptItem[] {
+  switch (event.type) {
+    case 'agent-text': {
+      const id = `text:${event.partId ?? event.turnNo}`;
+      const at = items.findIndex((item) => item.id === id);
+      // No partId (older servers) means the whole text came at once: final.
+      const pending = event.partId != null && event.done !== true;
+      if (at >= 0) {
+        const next = [...items];
+        next[at] = {
+          ...next[at]!,
+          text: mergeStreamText(next[at]!.text ?? '', event.text),
+          pending,
+        };
+        return next;
+      }
+      return [...items, {
+        id,
+        kind: 'text',
+        text: event.text,
+        turnNo: event.turnNo,
+        pending,
+        startedAt: now,
+      }];
+    }
+
+    case 'agent-act': {
+      const id = `act:${event.callId}`;
+      const at = items.findIndex((item) => item.id === id);
+      if (at >= 0) {
+        const next = [...items];
+        next[at] = {
+          ...next[at]!,
+          act: event.act,
+          ...(event.query !== undefined ? { query: event.query } : {}),
+          ...(event.ask ? { ask: event.ask } : {}),
+        };
+        return next;
+      }
+      return [...items, {
+        id,
+        kind: 'act',
+        act: event.act,
+        ...(event.query ? { query: event.query } : {}),
+        ...(event.ask ? { ask: event.ask } : {}),
+        turnNo: event.turnNo,
+        pending: true,
+        startedAt: now,
+      }];
+    }
+
+    /* Only stops that row.
+       A callId with no match is normal: the server sends this for every tool_result, and most of those
+       acts (read / grep / glob) drew no row. Then do nothing; never stop another row instead. */
+    case 'agent-act-done': {
+      const at = event.callId
+        ? items.findIndex((item) => item.id === `act:${event.callId}`)
+        : findLastPendingAct(items);
+      if (at < 0 || items[at]!.kind !== 'act') return items;
+      const next = [...items];
+      next[at] = { ...next[at]!, pending: false, ...(event.asset ? { asset: event.asset } : {}) };
+      return next;
+    }
+
+    /* Thinking only drives the status line underneath. Drafts are not sent and vanish when done: not in the conversation, not in the summary. */
+    case 'agent-thinking':
+      return items;
+
+    /* The agent's question settled (answered / skipped / timed out): write it back to its row, so the conversation
+       reads "asked what · answered what". The question's id is not the tool call's callId, so match the latest
+       unsettled question; a turn asks at most once. */
+    case 'ask-settled': {
+      for (let at = items.length - 1; at >= 0; at -= 1) {
+        const item = items[at]!;
+        if (item.kind !== 'act' || item.act !== 'chat.ask' || !item.ask || item.ask.status) continue;
+        const next = [...items];
+        next[at] = { ...item, ask: { ...item.ask, status: event.status, ...(event.answer ? { answer: event.answer } : {}) } };
+        return next;
+      }
+      return items;
+    }
+
+    /* Most context events only update the percentage (the caller reads it) and leave the record alone.
+       Only "just compacted" leaves a mark in the conversation, with a fixed id so a replay never adds a second. */
+    case 'context': {
+      if (!event.compacted) return items;
+      const id = 'notice:context-compacted';
+      if (items.some((item) => item.id === id)) return items;
+      return [...items, {
+        id,
+        kind: 'notice',
+        noticeKey: 'agent.contextCompacted',
+        pending: false,
+        startedAt: now,
+      }];
+    }
+
+    default:
+      return items;
+  }
+}
+
+function findLastPendingAct(items: TranscriptItem[]): number {
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    if (items[index]!.kind === 'act' && items[index]!.pending) return index;
+  }
+  return -1;
+}
+
+/**
+ * Server-projected snapshot → the same items. History has no timing, so no startedAt.
+ *
+ * No second trim here: it was projected before it was sent (publicProgressSnapshot), and the shape
+ * this function receives has no tool name or input fields to cut.
+ */
+export function transcriptFromSteps(
+  steps: PublicTimelineStep[] | undefined,
+): TranscriptItem[] {
+  if (!steps?.length) return [];
+  return steps.map((step) => {
+    if (step.kind === 'act') {
+      return {
+        id: step.id,
+        kind: 'act' as const,
+        act: step.act,
+        ...(step.query ? { query: step.query } : {}),
+        ...(step.asset ? { asset: step.asset } : {}),
+        ...(step.ask ? { ask: step.ask } : {}),
+        ...(step.turnNo != null ? { turnNo: step.turnNo } : {}),
+        pending: step.running === true,
+      };
+    }
+    return {
+      id: step.id,
+      kind: 'text' as const,
+      text: clipTranscriptText(step.text, TRANSCRIPT_TEXT_MAX),
+      ...(step.turnNo != null ? { turnNo: step.turnNo } : {}),
+      pending: step.running === true,
+    };
+  });
+}
+
+export function transcriptFromSnapshot(
+  snapshot: PublicProgressSnapshot | null | undefined,
+): TranscriptItem[] {
+  return transcriptFromSteps(snapshot?.steps);
+}
+
+/**
+ * Rows already mapped, keyed by source object identity.
+ *
+ * This is what lets the whole list memoize. `reduceTranscript` replaces only the row a delta touched
+ * and passes the rest through, so which rows did not change is already exact in the data. If this step
+ * built new objects every time, that would be lost: two hundred rows with new identities, `React.memo`
+ * stops none, and every token is a full re-render.
+ *
+ * A WeakMap rather than a Map: the keys are the rows themselves, so the cache is collected with them.
+ */
+const TRACE_ITEMS = new WeakMap<TranscriptItem, AgentActivityItem>();
+
+/**
+ * Render adapter: AgentActivityList already draws these rows; this only maps the field names.
+ *
+ * The output must be cacheable: the same TranscriptItem must always give the same object (see the map
+ * above). So this depends only on its input, never on the clock or randomness, which would quietly
+ * corrupt the cache.
+ */
+export function toTraceLogItems(items: TranscriptItem[]): AgentActivityItem[] {
+  return items.map((item) => {
+    const cached = TRACE_ITEMS.get(item);
+    if (cached) return cached;
+    const mapped = traceLogItem(item);
+    TRACE_ITEMS.set(item, mapped);
+    return mapped;
+  });
+}
+
+function traceLogItem(item: TranscriptItem): AgentActivityItem {
+  if (item.kind === 'notice') {
+    return { kind: 'notice' as const, id: item.id, label: item.noticeKey ?? '', ...(item.text ? { text: item.text } : {}) };
+  }
+  if (item.kind === 'thought') {
+    return {
+      kind: 'thought' as const,
+      id: item.id,
+      label: 'thought',
+      text: item.text ?? '',
+      pending: item.pending,
+      ...(item.startedAt != null ? { startedAt: item.startedAt } : {}),
+      ...(item.endedAt != null ? { endedAt: item.endedAt } : {}),
+    };
+  }
+  if (item.kind === 'plan') {
+    return { kind: 'plan' as const, id: item.id, label: 'plan', plan: item.plan ?? [], pending: item.pending };
+  }
+  if (item.kind === 'act') {
+    return {
+      kind: 'act' as const,
+      id: item.id,
+      // The copy key is the act itself. An unknown key renders an empty row, and acts are a closed set,
+      // so a missing line of copy is a slip tests can catch, not a leak in production.
+      label: `act.${item.act ?? 'working'}`,
+      ...(item.query ? { query: item.query } : {}),
+      ...(item.detail ? { detail: item.detail } : {}),
+      ...(item.ask ? { ask: item.ask } : {}),
+      ...(item.asset ? { asset: item.asset } : {}),
+      ...(item.turnNo != null ? { turnNo: item.turnNo } : {}),
+      pending: item.pending,
+      ...(item.startedAt != null ? { startedAt: item.startedAt } : {}),
+    };
+  }
+  return {
+    kind: 'text' as const,
+    id: item.id,
+    label: 'text',
+    text: item.text ?? '',
+    ...(item.turnNo != null ? { turnNo: item.turnNo } : {}),
+    pending: item.pending,
+    ...(item.startedAt != null ? { startedAt: item.startedAt } : {}),
+  };
+}
+
+/**
+ * Whether the line underneath should show.
+ *
+ * Do not give each activity its own caption. While an act runs, its row is lit with its own label;
+ * while text streams, the words appear on screen. A caption underneath would repeat what the user
+ * already sees.
+ *
+ * The one case that needs the line is when nothing runs: the message is sent and the model has not
+ * started. Then the screen really is empty, and without a word it looks frozen.
+ *
+ * Returns true when something is running, so no line is needed.
+ */
+export function transcriptBusy(items: TranscriptItem[]): boolean {
+  return items.some((item) => item.pending);
+}
+
+/**
+ * Whether the agent has finished talking this turn: is the last item a finished paragraph.
+ *
+ * A turn does not end with the agent's last sentence: the platform still wraps up for some seconds,
+ * with the transcript still and the task still running. Without this check a "planning the next step"
+ * line would hang there after the agent has signed off; the work left is the platform's and not worth
+ * announcing.
+ *
+ * When the last item is a finished act (or there is none), the model is about to speak, and that really
+ * is waiting for it.
+ */
+export function transcriptDoneTalking(items: TranscriptItem[]): boolean {
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    const item = items[index]!;
+    // Marks such as dividers are not the agent's doing: look at the item before.
+    if (item.kind === 'notice') continue;
+    return item.kind === 'text' && !item.pending;
+  }
+  return false;
+}
+
+/**
+ * Reconciles the live cache with the saved transcript, keeping what is more complete.
+ *
+ * Comparing counts alone fails in one concrete case: a Q&A turn is usually one paragraph; if SSE stops
+ * mid-way, the live copy is half a sentence and the saved one the full text, both with a count of 1, so
+ * keeping the live copy leaves the client stopped mid-sentence. Merge by id instead, text through
+ * mergeStreamText: a longer prefix wins.
+ *
+ * The ids must be aligned too: live uses `text:4:1` / `act:call`, saved uses `text-4:1` / `tool-call`.
+ * Unaligned, they never merge and the half and the full text show side by side.
+ */
+export function preferTranscript(live: TranscriptItem[], disk: TranscriptItem[]): TranscriptItem[] {
+  if (live.length === 0) return disk;
+  if (disk.length === 0) return live;
+  /* Order follows the saved copy (written in the order things happened), so steps the live copy missed
+     land where they belong, not at the end. Items only in the live copy follow the item before them there. */
+  const liveByKey = new Map<string, TranscriptItem>();
+  for (const item of live) {
+    const key = transcriptMergeKey(item);
+    const prev = liveByKey.get(key);
+    liveByKey.set(key, prev ? pickRicherTranscript(prev, item) : item);
+  }
+  const diskKeys = new Set(disk.map(transcriptMergeKey));
+  const trailing = new Map<string | null, TranscriptItem[]>();
+  let anchor: string | null = null;
+  const placed = new Set<string>();
+  for (const item of live) {
+    const key = transcriptMergeKey(item);
+    if (diskKeys.has(key)) { anchor = key; continue; }
+    if (placed.has(key)) continue;
+    placed.add(key);
+    const list = trailing.get(anchor) ?? [];
+    list.push(liveByKey.get(key)!);
+    trailing.set(anchor, list);
+  }
+  const out: TranscriptItem[] = [...(trailing.get(null) ?? [])];
+  const seen = new Set<string>();
+  for (const item of disk) {
+    const key = transcriptMergeKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const prev = liveByKey.get(key);
+    out.push(prev ? pickRicherTranscript(prev, item) : item);
+    out.push(...(trailing.get(key) ?? []));
+  }
+  return out;
+}
+
+function transcriptMergeKey(item: TranscriptItem): string {
+  if (item.kind === 'text') return item.id.replace(/^text[-:]/, 'text:');
+  if (item.kind === 'act') return item.id.replace(/^(?:act:|tool-)/, 'act:');
+  return item.id;
+}
+
+function pickRicherTranscript(a: TranscriptItem, b: TranscriptItem): TranscriptItem {
+  /* Same content: return the original. Downstream memoizes by object identity (each row, each run), so a new object with the same content re-renders the whole turn. */
+  if (a === b) return a;
+  if (a.kind === 'text' && b.kind === 'text') {
+    if ((a.text ?? '') === (b.text ?? '') && Boolean(a.pending) === Boolean(b.pending)) return a;
+    const text = mergeStreamText(a.text ?? '', b.text ?? '');
+    const base = (b.text ?? '').length > (a.text ?? '').length ? b : a;
+    return { ...base, text, pending: a.pending && b.pending };
+  }
+  if (a.kind === 'act' && b.kind === 'act') {
+    if (a.pending && !b.pending) return b;
+    if (b.pending && !a.pending) return a;
+    // The live copy often lacks the asset (its receipt was missed); the saved copy has it.
+    if (!a.asset && b.asset) return { ...a, asset: b.asset };
+  }
+  return a;
+}
+
+/**
+ * Finalizes the text when the turn ends.
+ *
+ * `replied.text` is the agent's whole last message. Snapshots stream in 80-byte steps and the last
+ * cumulative one may miss the live cache, but the final event carries the full text. An empty string
+ * must not overwrite: a reply the server rebuilds from storage is often empty, which means the text is
+ * in the process record, not that the agent said nothing.
+ */
+export function sealTranscriptText(items: TranscriptItem[], text: string): TranscriptItem[] {
+  const sealed = items.some((item) => item.pending)
+    ? items.map((item) => (item.pending ? { ...item, pending: false } : item))
+    : items;
+  if (!text.trim()) return sealed;
+  for (let i = sealed.length - 1; i >= 0; i -= 1) {
+    const item = sealed[i]!;
+    if (item.kind !== 'text') continue;
+    const merged = mergeStreamText(item.text ?? '', text);
+    if (merged === (item.text ?? '')) return sealed;
+    const next = [...sealed];
+    next[i] = { ...item, text: merged, pending: false };
+    return next;
+  }
+  return [...sealed, { id: 'text:reply', kind: 'text', text, pending: false }];
+}

package/skill/assets/upstream/apps/desktop/chat/src/lib/asset-lists.ts

@@ -0,0 +1,75 @@
+'use client';
+
+/**
+ * Merging the lists of turns on the client.
+ *
+ * A server snapshot and local optimistic entries live side by side; every view must merge them the same way, or
+ * a just-created item shows in one place and vanishes in another.
+ */
+import type { Turn } from '@openfilm/shared';
+import { shareListById } from '@/lib/structural-share';
+
+/** Merges the server list with optimistic local entries, so a refresh doesn't wipe a just-created turn. */
+export function mergeAssetLists(server: Turn[], local: Turn[]): Turn[] {
+  const map = new Map<string, Turn>();
+  for (const a of local) map.set(a.id, a);
+  for (const a of server) {
+    const prev = map.get(a.id);
+    map.set(
+      a.id,
+      prev
+        ? {
+            ...prev,
+            ...a,
+            title: a.title || prev.title,
+            sessionTitle: a.sessionTitle || prev.sessionTitle,
+            prompt: a.prompt || prev.prompt,
+          }
+        : a,
+    );
+  }
+  /* Unchanged entries keep their reference, and an unchanged list returns `local`, so polling doesn't re-render it. */
+  return shareListById(local, [...map.values()].sort(
+    (a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt),
+  ));
+}
+
+export function makePlaceholder(
+  assetId: string,
+  modality: Turn['modality'],
+  prompt?: string,
+  ids?: { projectId: string; sessionId: string },
+): Turn {
+  const now = new Date().toISOString();
+  return {
+    id: assetId,
+    ownerId: '',
+    projectId: ids?.projectId ?? assetId,
+    sessionId: ids?.sessionId ?? assetId,
+    sessionTitle: '',
+    baseVideoId: null,
+    modality,
+    title: '',
+    status: 'generating',
+    prompt: prompt?.trim() ?? '',
+    result: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * A turn that has no real id yet.
+ *
+ * Between Send and the server's answer there is a real wait. Showing nothing reads as "nothing happened", and
+ * the person clicks again. So a client-only entry goes up at once, is swapped for the real id when the answer
+ * comes, and is removed on failure.
+ *
+ * The prefix must be recognizable: the entry doesn't exist on the server, so anything that asks the server by id
+ * (the progress stream) must skip it, or every send starts with a 404.
+ */
+const PENDING_ASSET_PREFIX = 'pending:';
+
+export function isPendingAssetId(id: string): boolean {
+  return id.startsWith(PENDING_ASSET_PREFIX);
+}

package/skill/assets/upstream/apps/desktop/chat/src/lib/attachment-place.ts

@@ -0,0 +1,17 @@
+/**
+ * Where an attached folder is, short enough for its card: the folder it sits in, the home folder written as "~", and
+ * only the last two folders of a deep path ("…/Projects/2026"). Empty for a folder at the top of a disk.
+ */
+export function attachmentPlace(path: string): string {
+  const windows = /^[A-Za-z]:[\\/]/.test(path) || path.includes('\\');
+  const sep = windows ? '\\' : '/';
+  const trimmed = path.replace(/[\\/]+$/, '');
+  const cut = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+  if (cut <= 0) return '';
+  const parent = trimmed.slice(0, cut);
+  const home = parent.match(/^(?:\/Users\/[^/]+|\/home\/[^/]+|[A-Za-z]:[\\/]Users[\\/][^\\/]+)(?=$|[\\/])/);
+  const rest = (home ? parent.slice(home[0].length) : parent).split(/[\\/]/).filter(Boolean);
+  if (rest.length > 2) return ['…', ...rest.slice(-2)].join(sep);
+  if (home) return ['~', ...rest].join(sep);
+  return `${windows ? '' : '/'}${rest.join(sep)}`;
+}

package/skill/assets/upstream/apps/desktop/chat/src/lib/balance.ts

@@ -0,0 +1,16 @@
+/**
+ * A turn of the app's own agent that stopped because the service its model runs on has no balance left (the shell
+ * says so: src/pi-config.mjs `outOfBalance`), the same for every service: which one, and its page to top it up (null
+ * when the service is not one the app knows). Kept with the saved turn, so its footer still says it.
+ */
+export interface Balance { provider: string; url: string | null }
+
+/** What a saved turn keeps of this (lib/chat-store's Turn, extended here: older turns have none). */
+export interface TurnBalance { balance?: Balance }
+
+/** A balance as the shell or a saved turn gives it, or null. */
+export function readBalance(value: unknown): Balance | null {
+  const v = value as Partial<Balance> | null | undefined;
+  if (!v || typeof v.provider !== 'string' || !v.provider) return null;
+  return { provider: v.provider, url: typeof v.url === 'string' && /^https:\/\//.test(v.url) ? v.url : null };
+}

package/skill/assets/upstream/apps/desktop/chat/src/lib/chat-layer.ts

@@ -0,0 +1,10 @@
+/**
+ * Where the chat draws what floats over the window (menus, tooltips, previews): its own layer at the end of the page,
+ * inside the chat's styles (`.of-chat`), so a menu opened from the composer can reach over Studio and still look like
+ * the chat's. The chat itself sits in Studio's page (apps/desktop/shell), not on a page of its own.
+ */
+export const chatLayer = (): HTMLElement => document.getElementById('of-chat-layer') ?? document.body;
+
+/** Whether a key or pointer event happened in the chat (its column or its layer), not in Studio around it. */
+export const inChat = (target: EventTarget | null): boolean =>
+  Boolean(target && (target as Element).closest?.('.of-chat'));

package/skill/assets/upstream/apps/desktop/chat/src/lib/chat-menu.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether a menu of the chat's is open (the model menu, the @ list…). While the project's assets are open the chat's
+ * view keeps only its composer, and a menu opening above it needs the whole column back: the app is told (main.mjs
+ * `assets.menu`). Counted, since one menu can open from another.
+ */
+import React from 'react';
+
+let open = 0;
+const tell = () => (window as unknown as { openfilmDesktop?: { setMenuOpen?: (open: boolean) => void } }).openfilmDesktop?.setMenuOpen?.(open > 0);
+
+export function useChatMenu(shown: boolean) {
+  React.useEffect(() => {
+    if (!shown) return undefined;
+    open += 1;
+    tell();
+    return () => { open -= 1; tell(); };
+  }, [shown]);
+}