auricui-skill 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,291 @@
+/**
+ * The desktop shell's bridge. In the OpenFilm app (Electron) the window's page puts it on
+ * `window.openfilmDesktop`; in a plain browser there is no such object.
+ *
+ * It holds only what a web page cannot do by itself, such as a system folder picker or showing a path
+ * in Finder.
+ *
+ * The shape matches apps/desktop/shell/bridge.ts; change one, change the other.
+ */
+import type { Balance } from './balance';
+
+/** The coding agents the shell can connect to its MCP endpoint. */
+export type DesktopAgentId = 'claude' | 'codex' | 'cursor' | 'copilot' | 'opencode' | 'codebuddy' | 'devin';
+
+/** The chat's agents: the person's own (Codex, Claude Code, Qwen Code, …), and the app's own on their own key. */
+export type LocalAgentId = 'claude' | 'codex' | 'copilot' | 'cursor' | 'opencode' | 'codebuddy' | 'qwen' | 'kimi' | 'minimax' | 'deepseek' | 'byok';
+
+/** One agent as the app's roster has it (apps/desktop/src/agent-roster.mjs; Studio's lib/host.ts HostAgent). */
+export interface RosterAgent {
+  id: LocalAgentId;
+  name: string;
+  shown: boolean;
+  status: 'ready' | 'off' | 'sign-in' | 'waiting' | 'missing' | 'key' | 'checking';
+  install?: string | null;
+  setupRequired?: string | null;
+  error?: string;
+  /**
+   * The own key's models, each set up on its own (its name, its service, the model asked for there), with the reasoning
+   * efforts it offers and the one it starts on (apps/desktop src/pi-config.mjs EFFORTS); the first one to begin with.
+   */
+  byok?: { models: Array<{ id: string; name: string; format: 'responses' | 'chat' | 'anthropic'; baseUrl: string; model: string; levels: string[]; effort: string; last4: string }> };
+}
+
+export interface LocalAgentState {
+  setupRequired?: 'code-tab' | null;
+  id: LocalAgentId;
+  label: string;
+  /** The executable it uses: the one the person chose, one found on the PATH or in installers' folders, or the copy inside the maker's app. null = not installed. */
+  cli: { path: string; source: 'chosen' | 'path' | 'app' } | null;
+  /** Its own reported sign-in state; null when it cannot be asked. */
+  signedIn: boolean | null;
+  /** The official install page. When it is missing the UI points there; the app does not install it for the user. */
+  install: string;
+}
+
+export interface LocalAgentSessionInfo {
+  /** the agent's own id of the conversation: what `start` takes back as `resume` */
+  sessionId: string;
+  /** taken up where it stopped (the agent's own record, or the session still open), not a new one */
+  resumed?: boolean;
+  /** a message sent while it works can join the running turn (`steer`) */
+  steering?: boolean;
+  /** its commands, as a session opened only to ask said them (`probe`): ACP's availableCommands */
+  commands?: unknown[];
+  agentInfo: { name: string; title?: string; version?: string } | null;
+  authMethods: Array<{ id: string; name: string; description?: string }>;
+  /** Whether our MCP tools were handed over (not when the agent does not take HTTP). */
+  mcp: boolean;
+  models: { availableModels: Array<{ modelId: string; name: string; description?: string }>; currentModelId: string } | null;
+  modes: { availableModes: Array<{ id: string; name: string; description?: string }>; currentModeId: string } | null;
+  configOptions: Array<{ id: string; name: string; description?: string; category?: string; type?: string; currentValue?: unknown; options?: Array<{ value: unknown; name: string; description?: string }> }> | null;
+}
+
+/** session/update as is (ACP's SessionUpdate); the UI picks what to draw by `sessionUpdate`. */
+export type LocalAgentEvent =
+  | { key: string; kind: 'update'; update: { sessionUpdate: string } & Record<string, unknown> }
+  | { key: string; kind: 'permission'; requestId: string; params: { toolCall?: { title?: string }; options: Array<{ optionId: string; name: string; kind: string }> } }
+  | { key: string; kind: 'question'; requestId: string; message: string; toolCallId: string | null; questions: LocalAgentQuestion[] }
+  | { key: string; kind: 'exit'; code: number | null; stderr: string }
+  /* the turn settled — also said on the channel, for a page that was reloaded while it ran */
+  | { key: string; kind: 'done'; turnId: string; ok: boolean; stopReason?: string; error?: string; balance?: Balance };
+
+/** A picture given to the agent with a message: base64 bytes and their type (an ACP image block). */
+export interface PromptImage { data: string; mimeType: string }
+
+/** What the page hands the shell with a prompt, so a reloaded page can put the running turn back. */
+export interface LocalAgentTurnMeta {
+  turnId: string;
+  projectId: string;
+  projectTitle: string;
+  sessionId: string;
+  agent: LocalAgentId;
+  /** the user's words (without the attachment note) */
+  prompt: string;
+  turnNo: number;
+  startedAt: number;
+  /** the chat row as it was sent (a Turn) */
+  turn: unknown;
+}
+
+/** A turn the shell still holds: running, or finished and not yet taken by a page. */
+export interface LocalAgentRunningTurn {
+  key: string;
+  agent: LocalAgentId;
+  cwd: string;
+  meta: LocalAgentTurnMeta;
+  done: { ok: true; stopReason: string } | { ok: false; error: string; balance?: Balance } | null;
+  events: Array<Record<string, unknown> & { kind: string }>;
+}
+
+/** A question a local agent asks the user (read by the shell from the ACP form, see formQuestions in apps/desktop/src/agents.mjs). */
+export interface LocalAgentQuestion {
+  id: string;
+  question: string;
+  header: string | null;
+  options: Array<{ label: string; description?: string }>;
+  /** The free-text field; null = options only (except for text-only questions). */
+  customId: string | null;
+  multi: boolean;
+}
+
+/** An answer: the option picked, or the text written. */
+export type LocalAgentAnswer = { label: string } | { text: string };
+
+export interface DesktopBridge {
+  /** The shell's version, to spot an old shell when debugging. */
+  version: string;
+  /** IPC contract version; separate from the installed application's version. */
+  bridgeVersion?: string;
+  /** darwin / win32 / linux. */
+  platform: string;
+  /** Opens the system folder picker. null if the user cancels. */
+  chooseFolder(opts?: { title?: string; defaultPath?: string }): Promise<string | null>;
+  /** Shows this path in the system file manager. */
+  revealPath(path: string): Promise<void>;
+  /**
+   * The system "Save As" dialog (where a local export goes). null if the user cancels.
+   * `defaultPath` defaults to the `exportsRoot()` folder.
+   */
+  saveDialog?(opts: {
+    title?: string;
+    defaultPath?: string;
+    filters?: { name: string; extensions: string[] }[];
+  }): Promise<string | null>;
+  /** Where exports go by default: `~/Movies/OpenFilm/Exports` (created by the shell). null when unavailable. */
+  exportsRoot?(): Promise<string | null>;
+  /** Opens a file or folder with its default app. An empty string on success, else the reason. */
+  openPath?(path: string): Promise<string>;
+  /**
+   * The folder made for a new project in the library (already created, ready to use).
+   *
+   * The shell makes it rather than asking: when the person presses New they do not yet know what the
+   * film will become, and should not be asked where to put it. The library root is fixed under the
+   * system Movies folder.
+   */
+  newProjectDir?(title: string): Promise<{ ok: true; dir: string } | { ok: false; error: string }>;
+  /** Where local projects are stored, shown in Settings. null on an old shell or when unavailable. */
+  libraryRoot?(): Promise<string | null>;
+  /** The menu's File → Open Folder… was clicked. Returns an unsubscribe function. */
+  onOpenLocalFolder?(cb: () => void): () => void;
+  onMenuAction?(cb: (action: 'settings') => void): () => void;
+  /**
+   * The absolute path on disk of a browser File (dragged in, or chosen with `<input type=file>`).
+   * A pasted file has no path and gives an empty string; then its bytes can only be uploaded.
+   */
+  pathForFile(file: File): string;
+  /**
+   * Connects a local coding agent (see DesktopAgentId) to the app's MCP endpoint: the shell edits the
+   * agent's own config file. On success, a sentence saying what to do next; on failure, the reason.
+   */
+  connectAgent?(agent: DesktopAgentId): Promise<
+    | { ok: true; how: string; next: string }
+    /* `code` is 'not-installed' / 'not-ready': the UI words those in its own language; otherwise it shows `error` as is. */
+    | { ok: false; error: string; code?: string; install?: string }
+  >;
+  /**
+   * Disconnects: removes our entry from its config.
+   *
+   * There is no "reconnect": the only case it would fix is a changed address, which disconnecting and
+   * connecting again handles, without one more button to explain. So there are two states: connected or not.
+   */
+  disconnectAgent?(agent: DesktopAgentId): Promise<{ ok: true } | { ok: false; error: string }>;
+  /**
+   * `localAgents`: the user's own Claude Code / Codex in the chat panel (ACP, see
+   * apps/desktop/src/local-agents-ipc.mjs). The thinking runs on the user's own subscription; the doing
+   * is our MCP tools. Events come from `onEvent`.
+   */
+  /** The roster: the agents there are, connected or not, shown in the chat's menu or not. */
+  agents?: {
+    list(): Promise<RosterAgent[]>;
+    connect(id: LocalAgentId): Promise<{ ok: boolean; error?: string }>;
+    onChange(listener: (agents: RosterAgent[]) => void): () => void;
+    /** The diagnostic report (the computer, the last week's problems, the agents) on the clipboard. Older shells lack it. */
+    copyReport?(): Promise<{ ok: boolean }>;
+  };
+  /** Studio's Settings, on Agents (or Providers). */
+  openSettings?(section?: 'agents' | 'providers'): void;
+  /** Studio's language, whenever it changes (its <html lang>). */
+  onLanguage?(listener: (language: string) => void): () => void;
+  localAgents?: {
+    list(): Promise<LocalAgentState[]>;
+    /** Close OpenFilm's open sessions with it (its own login is left alone). Older shells lack it. */
+    disconnect?(agent: LocalAgentId): Promise<{ ok: boolean }>;
+    /** Opens Terminal to run its own sign-in command, which opens Anthropic's / OpenAI's sign-in page. */
+    signIn(agent: LocalAgentId): Promise<{ ok: true } | { ok: false; error: string }>;
+    /** Opens a session and closes it at once, only for its options. Sends no message, so costs nothing. */
+    probe(agent: LocalAgentId): Promise<{ ok: true; info: LocalAgentSessionInfo } | { ok: false; error: string; code?: string }>;
+    /**
+     * `resume`: the agent's own id of a conversation it had (an earlier start's info.sessionId), to go on with.
+     * `meta`: the turn it starts for, whose log says why when it does not start.
+     */
+    start(agent: LocalAgentId, cwd: string, resume?: string | null, meta?: LocalAgentTurnMeta): Promise<
+      | { ok: true; key: string; info: LocalAgentSessionInfo }
+      | { ok: false; error: string; code?: string; install?: string }
+    >;
+    /** `images`: pictures sent after the text, to an agent that takes them (the shell asks the session) */
+    /** `balance`: the service the app's own agent runs on had no balance left for it */
+    /** `model`: the model that answered, for an agent whose session names none (GitHub Copilot's, from its record) */
+    prompt(key: string, text: string, meta?: LocalAgentTurnMeta, images?: PromptImage[]): Promise<{ ok: true; stopReason: string; model?: string } | { ok: false; error: string; balance?: Balance }>;
+    /** Turns still held by the shell (a reload mid-turn). Older shells lack it. */
+    running?(): Promise<LocalAgentRunningTurn[]>;
+    /** The page has put this finished turn back: the shell forgets it. */
+    ack?(key: string, turnId: string): Promise<{ ok: true }>;
+    /** A message sent while a turn runs, into that turn; ok: false when it did not join it. Older shells lack it. */
+    steer?(key: string, text: string, images?: PromptImage[]): Promise<{ ok: boolean; outcome: string }>;
+    /** What the agent does with nobody having written is the turn `turnId` (null: no longer), in its log. */
+    adopt?(key: string, turnId: string | null, meta?: LocalAgentTurnMeta): Promise<{ ok: boolean }>;
+    cancel(key: string): Promise<{ ok: true }>;
+    setOption(key: string, configId: string, value: unknown): Promise<{ ok: boolean; error?: string; result?: { configOptions?: LocalAgentSessionInfo['configOptions'] } }>;
+    answerPermission(key: string, requestId: string, optionId: string | null): Promise<{ ok: boolean }>;
+    /** Answers its question; null = skip. Older shells lack it (and never ask). */
+    answerQuestion?(key: string, requestId: string, answers: Record<string, LocalAgentAnswer> | null): Promise<{ ok: boolean }>;
+    close(key: string): Promise<{ ok: true }>;
+    onEvent(cb: (event: LocalAgentEvent) => void): () => void;
+  };
+  /** System notifications, the Dock badge, and coming back from a notification. */
+  tasks?: {
+    notify(payload: { title: string; body?: string; href?: string }): Promise<{ ok: boolean }>;
+    setBadge(count: number): void;
+    onNavigate(cb: (href: string) => void): () => void;
+  };
+  /** OpenFilm Studio only: the page runs in a plain browser */
+  studio?: boolean;
+  /**
+   * The agents' status: the MCP endpoint's half (who is connected, who is remembered) plus each agent's
+   * config file (who was connected). When the endpoint is not running the first half is empty;
+   * `configured` still holds, since it reads files on disk.
+   */
+  agentStatus?(): Promise<DesktopAgentStatus | null>;
+}
+
+export interface DesktopAgentStatus {
+  /** Executable/app detection; leftover configuration is not installation evidence. */
+  installed?: Partial<Record<DesktopAgentId, boolean>>;
+  url: string;
+  /** Whether the MCP endpoint is open (off by default; Connect opens it). */
+  enabled?: boolean;
+  sessions: Array<{
+    id: string;
+    clientName: string;
+    clientVersion: string;
+    createdAt: number;
+    lastSeenAt: number;
+    /** How it got in: the shell's pairing secret / approved in a dialog / test pass-through. */
+    paired?: 'secret' | 'dialog' | 'auto';
+    projectId?: string;
+  }>;
+  trusted: Array<{ name: string; approvedAt: number; expiresAt: number; secret?: true }>;
+  audit: string;
+  /**
+   * The openfilm address each agent's config holds now; null if never connected.
+   *
+   * Not the same as `sessions`: connected only means the config is written; the agent connects on its
+   * next start. The UI tells three states from the two: never connected / connected (waiting for the
+   * agent) / live. An address that differs from `url` means the port changed: that entry is broken and
+   * must be connected again.
+   */
+  configured?: Partial<Record<DesktopAgentId, string | null>>;
+}
+
+declare global {
+  interface Window {
+    openfilmDesktop?: DesktopBridge;
+  }
+}
+
+/**
+ * For a file with no path in a local project (a pasted image): the size up to which its bytes go in one
+ * request; larger ones are streamed in parts. Not an upload limit. Files with a path (dragged from
+ * Finder) are copied by path.
+ */
+export const LOCAL_PUT_MAX_BYTES = 15 * 1024 * 1024;
+
+/** Whether this runs in the desktop shell. Always false during SSR. */
+export function isDesktop(): boolean {
+  return typeof window !== 'undefined' && !!window.openfilmDesktop;
+}
+
+export function desktopBridge(): DesktopBridge | null {
+  return typeof window !== 'undefined' ? window.openfilmDesktop ?? null : null;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Settings → Developer, as the chat follows it: `logs` on, each turn shows its full log (components/TurnLog.tsx);
+ * `changes` on (unless turned off), what each turn changed in the files, under its reply (components/FileChangesList).
+ * The app keeps the choice; Studio's Settings switches it.
+ */
+import React from 'react';
+import { app, type DeveloperPrefs } from '../app-bridge';
+
+let prefs: DeveloperPrefs = { logs: false, changes: true };
+const listeners = new Set<() => void>();
+const set = (next: DeveloperPrefs) => {
+  if (next.logs === prefs.logs && next.changes === prefs.changes) return;
+  prefs = next;
+  for (const listener of listeners) listener();
+};
+let started = false;
+function start() {
+  if (started) return;
+  started = true;
+  void app.developer.get().then(set).catch(() => {});
+  app.developer.onChange(set);
+}
+const subscribe = (listener: () => void) => { start(); listeners.add(listener); return () => { listeners.delete(listener); }; };
+
+/** each turn's full log, from its footer */
+export function useDeveloperMode(): boolean {
+  return React.useSyncExternalStore(subscribe, () => prefs.logs, () => false);
+}
+
+/** what each turn changed in the files, under its reply */
+export function useShowChanges(): boolean {
+  return React.useSyncExternalStore(subscribe, () => prefs.changes, () => true);
+}
+
+/** The project the chat shows (its folder): where a turn's log is. */
+export const ChatProjectContext = React.createContext<string | null>(null);
+
+/** Whether something waits for the person's answer now (a question, a permission, a spend): the status line says so. */
+export const WaitingContext = React.createContext(false);

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

@@ -0,0 +1,23 @@
+/**
+ * Which Esc stops the turn while it runs (the send button's other half): one pressed in the chat (chat-layer.ts
+ * `inChat`). One in Studio closes Studio's menu or dialog, and one already handled is its handler's; neither stops the
+ * agent. Nor does an Esc held down, or pressed again just after one of those: Studio's Settings gives the focus back to
+ * the chat as it closes, so the key held, or pressed twice to close it, would land in the chat and stop the agent.
+ *
+ * Pure: no React, no bridge, so `node --test` runs it (src/esc-stop.test.mjs).
+ */
+
+/** An Esc this soon after one that was not the chat's is still closing, not stopping. */
+export const ESC_AGAIN_MS = 1000;
+
+type EscKey = Pick<KeyboardEvent, 'key' | 'repeat' | 'defaultPrevented' | 'timeStamp'>;
+
+/** Hears every key pressed (`inChat`: where it was) and says whether it stops the turn. */
+export function escStopper(): (event: EscKey, inChat: boolean) => boolean {
+  let elsewhereAt = -Infinity;
+  return (event, inChat) => {
+    if (event.key !== 'Escape') return false;
+    if (event.defaultPrevented || !inChat) { elsewhereAt = event.timeStamp; return false; }
+    return !event.repeat && event.timeStamp - elsewhereAt >= ESC_AGAIN_MS;
+  };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * What a turn changed in the project's files (src/file-changes.mjs reads the folder as the turn starts and settles):
+ * each file added, removed or changed, its lines added and removed, and the changed lines in hunks. Kept with the
+ * turn (`fileChanges` on the saved turn), since afterwards nothing can tell what the files were before.
+ *
+ * Pure: no React, no bridge, so `node --test` runs it (src/file-changes.test.mjs).
+ */
+
+export interface FileHunk { oldStart: number; oldLines: number; newStart: number; newLines: number; lines: string[] }
+
+export interface FileChange {
+  /** its path in the project, with `/` */
+  path: string;
+  change: 'added' | 'removed' | 'changed';
+  /** lines added and removed: none for a file that is not text (media, a large file) */
+  added?: number;
+  removed?: number;
+  /** the changed lines, with three around each; `cut`: only the first of them are kept */
+  hunks?: FileHunk[];
+  cut?: boolean;
+}
+
+/** What a saved turn keeps of this (lib/chat-store's Turn, extended here: older turns have none). */
+export interface TurnFileChanges { fileChanges?: FileChange[] }
+
+/** A saved turn's file changes, as read back from its file: what does not look like one is left out. */
+export function readFileChanges(value: unknown): FileChange[] | null {
+  if (!Array.isArray(value)) return null;
+  const list = value.filter((c): c is FileChange => Boolean(c) && typeof c.path === 'string'
+    && (c.change === 'added' || c.change === 'removed' || c.change === 'changed'));
+  return list.length ? list : null;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The line under the running turn: "Thinking" while it thinks, nothing while a step or its words are showing,
+ * "Planning next moves" in the gaps between.
+ */
+import React from 'react';
+import { useT } from '@/i18n';
+import { transcriptBusy, transcriptDoneTalking } from '@/lib/agent-transcript';
+import type { LocalTranscriptStore } from '@/lib/local-agent-run';
+
+export function useLiveActivityFromStore(store: LocalTranscriptStore, thinking = false, planning = true): string | null {
+  const t = useT();
+  const read = (): string => {
+    const transcript = store.get();
+    if (transcriptBusy(transcript)) return '';
+    if (thinking) return 'act.thinking';
+    return !planning || transcriptDoneTalking(transcript) ? '' : 'act.planning';
+  };
+  const key = React.useSyncExternalStore(store.subscribe, read, read);
+  return key ? t(key) : null;
+}