@alia.onl/sdk 15.8.0 → 19.0.0

package/src/lib/work-log.ts

@@ -8,12 +8,12 @@ import {
 } from '@oxy.so/bloom/icons';
 import type { TaskListChip, TaskListStep, TaskListTask } from '@oxy.so/bloom/task-list';
 import type { WebSearchBrand, WebSearchSource, WebSearchStep } from '@oxy.so/bloom/web-search';
-import type { ToolInvocation } from '../types';
+import type { ToolInvocation } from '../runtime/types';
 import { extractCitationSources } from './citations';
 import { domainOf } from './domain';
 import { getToolDoneLabel, getToolPillLabel } from './task-labels';
 import { toolCallStatus } from './tool-call-status';
-import { englishWorkLog, type Translate } from './work-log-copy';
+import { englishCopy, type Translate } from './copy';
 
 /**
  * A turn's tool calls, as the two Bloom logs draw them.
@@ -32,7 +32,7 @@ import { englishWorkLog, type Translate } from './work-log-copy';
 
 /** What a host can swap: the words, and where a site's icon is served from. */
 export interface WorkLogOptions {
-  /** Translator for the log's words (see `work-log-copy.ts`). Default: English. */
+  /** Translator for the log's words (see `copy.ts`). Default: English. */
   t?: Translate;
   /** The URL of a site's cached icon, or nothing for Bloom's quiet dot. */
   faviconUrl?: (url: string) => string | null | undefined;
@@ -154,7 +154,7 @@ function webStep(
   live: LiveResearch | undefined,
   options: WorkLogOptions,
 ): MappedStep {
-  const t = options.t ?? englishWorkLog;
+  const t = options.t ?? englishCopy;
   const arrived = inv.state !== 'partial-call';
   const ok = succeeded(inv);
   const res = resultOf(inv);
@@ -256,7 +256,7 @@ export function webSearchLog(
   research: LiveResearch | undefined,
   options: WorkLogOptions = {},
 ): WebSearchLog {
-  const t = options.t ?? englishWorkLog;
+  const t = options.t ?? englishCopy;
   const web = (invocations ?? []).filter(isWebInvocation);
   const mapped = web.map((inv) => webStep(inv, research, options));
 
@@ -333,7 +333,7 @@ export function taskListLog(
   live: boolean,
   options: WorkLogOptions = {},
 ): TaskListLog {
-  const t = options.t ?? englishWorkLog;
+  const t = options.t ?? englishCopy;
   let revealed = 0;
   let open = true;
   const tasks = (invocations ?? [])

package/src/runtime/agents.ts

@@ -0,0 +1,151 @@
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useQuery } from '@tanstack/react-query';
+import { useAliaApi } from './api';
+import { aliaQueryKeys } from './query-keys';
+import { API_ROUTES } from './routes';
+
+/**
+ * The agent a chat is opened on, as `GET /v1/agents/:id/profile` answers it
+ * (`docs/agent-embedding.md` §1). Alia herself has no profile: she is the lead when no agent is
+ * named.
+ */
+export interface AliaAgentProfile {
+  id: string;
+  name: string;
+  handle?: string;
+  /** Its look, as Oxy stores a character (JSON); drawn through `readAgentCharacter`. */
+  character?: unknown;
+  color?: string;
+  description?: string;
+  /** What the empty chat says; omitted, the chat's own greeting. */
+  greeting?: string;
+  /** The lines offered over the composer of an empty chat. */
+  starters: AliaAgentStarter[];
+  access?: 'private' | 'public';
+  /** Which of Alia's features this agent gates behind an app's own check. */
+  features: Array<{ key: string; gated: boolean }>;
+}
+
+export interface AliaAgentStarter {
+  title: string;
+  prompt: string;
+}
+
+/** One of Alia's features, for one agent and the person present (`GET /v1/agents/:id/features`). */
+export interface AliaAgentFeature {
+  key: string;
+  state: 'available' | 'locked';
+  /** How many uses are left, when the publishing app counts them. */
+  remaining?: number;
+}
+
+/** The feature keys the chat itself reads: the attach menu's two rows. */
+export const ALIA_FEATURES = {
+  documents: 'attachments.documents',
+  images: 'attachments.images',
+} as const;
+
+const FIVE_MINUTES = 1000 * 60 * 5;
+
+/** A string, or nothing: the profile is read field by field rather than cast. */
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' && value !== '' ? value : undefined;
+
+/** The profile the server sent, kept only where it has the shape the contract names. */
+export function readAgentProfile(value: unknown): AliaAgentProfile | null {
+  if (value === null || typeof value !== 'object') return null;
+  const raw = value as Record<string, unknown>;
+  const id = text(raw.id);
+  const name = text(raw.name);
+  if (id === undefined || name === undefined) return null;
+  const starters = Array.isArray(raw.starters)
+    ? raw.starters.flatMap((starter): AliaAgentStarter[] => {
+        if (starter === null || typeof starter !== 'object') return [];
+        const { title, prompt } = starter as Record<string, unknown>;
+        const line = text(prompt);
+        return line === undefined ? [] : [{ title: text(title) ?? line, prompt: line }];
+      })
+    : [];
+  const features = Array.isArray(raw.features)
+    ? raw.features.flatMap((feature): Array<{ key: string; gated: boolean }> => {
+        if (feature === null || typeof feature !== 'object') return [];
+        const { key, gated } = feature as Record<string, unknown>;
+        return typeof key === 'string' ? [{ key, gated: gated === true }] : [];
+      })
+    : [];
+  return {
+    id,
+    name,
+    handle: text(raw.handle),
+    character: raw.character ?? undefined,
+    color: text(raw.color),
+    description: text(raw.description),
+    greeting: text(raw.greeting),
+    starters,
+    access: raw.access === 'public' || raw.access === 'private' ? raw.access : undefined,
+    features,
+  };
+}
+
+/** The feature states the server sent; an entry of any other shape is not a state. */
+export function readAgentFeatures(value: unknown): AliaAgentFeature[] {
+  const list =
+    value !== null && typeof value === 'object'
+      ? (value as { features?: unknown }).features
+      : undefined;
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((feature): AliaAgentFeature[] => {
+    if (feature === null || typeof feature !== 'object') return [];
+    const { key, state, remaining } = feature as Record<string, unknown>;
+    if (typeof key !== 'string' || (state !== 'available' && state !== 'locked')) return [];
+    return [{ key, state, ...(typeof remaining === 'number' ? { remaining } : {}) }];
+  });
+}
+
+/** The profile of the agent `agentId`, or nothing for Alia (no id) and while it loads. */
+export function useAgentProfile(agentId: string | undefined) {
+  const { isAuthenticated } = useOxy();
+  const api = useAliaApi();
+  return useQuery({
+    queryKey: aliaQueryKeys.agents.profile(agentId ?? ''),
+    queryFn: async () =>
+      readAgentProfile((await api.get<unknown>(API_ROUTES.agents.profile(agentId ?? ''))).data),
+    enabled: agentId !== undefined && isAuthenticated,
+    staleTime: FIVE_MINUTES,
+    retry: 1,
+  });
+}
+
+/**
+ * What of Alia's features the agent `agentId` offers the person present. Alia (no id) gates
+ * nothing, so she has no answer to wait for; see `featureRows` for what the chat makes of it.
+ */
+export function useAgentFeatures(agentId: string | undefined) {
+  const { isAuthenticated } = useOxy();
+  const api = useAliaApi();
+  return useQuery({
+    queryKey: aliaQueryKeys.agents.features(agentId ?? ''),
+    queryFn: async () =>
+      readAgentFeatures((await api.get<unknown>(API_ROUTES.agents.features(agentId ?? ''))).data),
+    enabled: agentId !== undefined && isAuthenticated,
+    // A gate's state moves with the person's plan in another app: read it each time the chat opens.
+    staleTime: 0,
+    retry: 1,
+  });
+}
+
+/** How an attachment feature is offered: attached, an upsell, or not at all. */
+export type FeatureOffer = 'available' | 'locked' | 'absent';
+
+/**
+ * What the attach menu offers for `key`. Alia's own chat (`features === undefined`) offers every
+ * attachment; an agent offers what its feature answer lists — `locked` is still offered, as the
+ * host's upsell — and nothing it does not list.
+ */
+export function featureOffer(
+  features: readonly AliaAgentFeature[] | undefined,
+  key: string,
+): FeatureOffer {
+  if (features === undefined) return 'available';
+  return features.find((feature) => feature.key === key)?.state ?? 'absent';
+}

package/src/runtime/api.ts

@@ -0,0 +1,123 @@
+import { useOxy } from '@oxy.so/services/ui/client';
+import { useMemo } from 'react';
+import { useAliaRuntime } from './config';
+
+/**
+ * A refusal or failure from Alia's API, shaped so the helpers in
+ * `error-utils.ts` read it: `status`, and the parsed body under
+ * `response.data`.
+ */
+export class AliaApiError extends Error {
+  readonly status: number;
+  readonly response: { status: number; data: unknown };
+
+  constructor(status: number, data: unknown, message?: string) {
+    super(message ?? `Alia request failed with status ${status}.`);
+    this.name = 'AliaApiError';
+    this.status = status;
+    this.response = { status, data };
+  }
+}
+
+export interface AliaApiResult<T> {
+  status: number;
+  data: T;
+}
+
+export interface AliaApiRequest {
+  params?: Record<string, string | number | undefined>;
+  body?: unknown;
+  signal?: AbortSignal;
+}
+
+/**
+ * Alia's REST API for the signed-in person. Authentication, the preflight
+ * refresh and the single 401 replay belong to the linked Oxy client; this
+ * layer never reads or writes a bearer itself.
+ */
+export interface AliaApi {
+  get<T>(path: string, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+  post<T>(path: string, body?: unknown, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+  patch<T>(path: string, body?: unknown, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+  delete<T>(path: string, request?: AliaApiRequest): Promise<AliaApiResult<T>>;
+}
+
+function withParams(path: string, params: AliaApiRequest['params']): string {
+  if (!params) return path;
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) search.append(key, String(value));
+  }
+  const query = search.toString();
+  return query === '' ? path : `${path}${path.includes('?') ? '&' : '?'}${query}`;
+}
+
+async function readBody(response: Response): Promise<unknown> {
+  const text = await response.text().catch(() => '');
+  if (text === '') return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/** The structural slice of `OxyServices` the API layer needs. */
+export interface LinkableOxy {
+  createLinkedClient(config: { baseURL: string }): {
+    client: {
+      requestAuthenticatedResponse(config: {
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        url: string;
+        body?: string;
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+        fetch?: typeof fetch;
+      }): Promise<Response>;
+    };
+    dispose(): void;
+  };
+}
+
+/** Build the API over an Oxy client for `apiUrl`. Exposed for tests and for non-React callers. */
+export function createAliaApi(oxyServices: LinkableOxy, apiUrl: string): AliaApi {
+  async function send<T>(
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
+    path: string,
+    request: AliaApiRequest = {},
+  ): Promise<AliaApiResult<T>> {
+    const linked = oxyServices.createLinkedClient({ baseURL: apiUrl });
+    try {
+      const response = await linked.client.requestAuthenticatedResponse({
+        method,
+        url: withParams(path, request.params),
+        ...(request.body === undefined
+          ? {}
+          : {
+              body: JSON.stringify(request.body),
+              headers: { 'Content-Type': 'application/json' },
+            }),
+        ...(request.signal ? { signal: request.signal } : {}),
+      });
+      const data = await readBody(response);
+      if (!response.ok) throw new AliaApiError(response.status, data);
+      return { status: response.status, data: data as T };
+    } finally {
+      linked.dispose();
+    }
+  }
+
+  return {
+    get: (path, request) => send('GET', path, request),
+    post: (path, body, request) => send('POST', path, { ...request, body: body ?? {} }),
+    patch: (path, body, request) => send('PATCH', path, { ...request, body: body ?? {} }),
+    delete: (path, request) => send('DELETE', path, request),
+  };
+}
+
+/** Alia's REST API for the nearest runtime's `apiUrl`, as the signed-in person. */
+export function useAliaApi(): AliaApi {
+  const { oxyServices } = useOxy();
+  const { apiUrl } = useAliaRuntime();
+  return useMemo(() => createAliaApi(oxyServices as LinkableOxy, apiUrl), [oxyServices, apiUrl]);
+}

package/src/runtime/attachment-utils.ts

@@ -0,0 +1,96 @@
+import type { AliaAttachment } from '../types';
+
+export type MessageContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string } }
+  | { type: 'file'; file: { file_id: string; filename: string; mime: string } };
+
+export interface BuiltMessageContent {
+  content: string | MessageContentPart[];
+  /**
+   * Attachments the request does NOT carry, so the caller can say so.
+   *
+   * Never empty silently: everything here was visibly attached in the composer,
+   * and a file that appears attached and then is not sent is the failure #608
+   * §1.6 is about — a visible state that does not correspond to a real
+   * capability.
+   */
+  dropped: DroppedAttachment[];
+}
+
+export interface DroppedAttachment {
+  name: string;
+  /**
+   * `unsupported` — the chat has no way to send a document (no upload was given).
+   * `unreadable` — an image whose bytes could not be read off the device, or a
+   * document that could not be uploaded.
+   */
+  reason: 'unsupported' | 'unreadable';
+}
+
+/** Puts a document in the person's Oxy Files and answers its id. */
+export type UploadDocument = (attachment: AliaAttachment) => Promise<string>;
+
+/**
+ * The request body for a turn that carries attachments, and an account of what
+ * it could not carry.
+ *
+ * A photo travels inline, as an `image_url` part with its `data:` URL. A
+ * document travels as a `file` part naming an Oxy Files id
+ * (`docs/agent-embedding.md` §5): it is uploaded to the person's Files first,
+ * with `upload`, and a chat given no `upload` cannot send documents and says so.
+ */
+export async function buildMessageContent(
+  text: string,
+  attachments: AliaAttachment[],
+  upload?: UploadDocument,
+): Promise<BuiltMessageContent> {
+  const dropped: DroppedAttachment[] = [];
+
+  const usable = attachments.filter((att) => {
+    if (!att.uri) return false;
+    if (att.type !== 'image' && upload === undefined) {
+      dropped.push({ name: att.name, reason: 'unsupported' });
+      return false;
+    }
+    return true;
+  });
+
+  if (usable.length === 0) return { content: text, dropped };
+
+  const parts: MessageContentPart[] = [{ type: 'text', text }];
+
+  // The readers need the platform's file access, loaded on the first attachment: a turn of plain
+  // text (and everything that imports this module) never touches it.
+  const { imageUriToDataUrl } = await import('../lib/image-data-url');
+  for (const att of usable) {
+    if (att.type !== 'image' && upload !== undefined) {
+      try {
+        const fileId = await upload(att);
+        parts.push({
+          type: 'file',
+          file: { file_id: fileId, filename: att.name, mime: att.mimeType },
+        });
+      } catch {
+        dropped.push({ name: att.name, reason: 'unreadable' });
+      }
+      continue;
+    }
+    try {
+      parts.push({
+        type: 'image_url',
+        image_url: { url: await imageUriToDataUrl(att.uri, att.mimeType) },
+      });
+    } catch {
+      // Reported rather than skipped. A picture that did not arrive is worth
+      // a sentence; it used to be a `continue`.
+      dropped.push({ name: att.name, reason: 'unreadable' });
+    }
+  }
+
+  // Every attachment failed, so the parts array is a text part and nothing
+  // else — which is just the text, said in a more expensive way.
+  if (parts.length === 1) return { content: text, dropped };
+
+  return { content: parts, dropped };
+}

package/src/runtime/composer-draft-store.ts

@@ -0,0 +1,270 @@
+import { useMemo } from 'react';
+import { create } from 'zustand';
+import type { AliaAttachment } from '../types';
+
+/**
+ * What a composer is holding before it is sent: the text, the attachments and
+ * the turn's own choices (connector, skills). One record per account and
+ * composer, and the only place any of it lives.
+ *
+ * ## Why this replaced three owners
+ *
+ * The text was `useState` inside each mounted chat screen, the attachments
+ * were ONE global list in `global-store.ts`, and a draft handed from elsewhere
+ * (a failed send, the memory settings) travelled through a third slot,
+ * `composerDraft`, that every mounted screen read on every render and matched
+ * against its own id with a sequence number. The drawer keeps each visited
+ * chat mounted, so the attachment list was on every one of them at once — a
+ * picture added in one chat was sitting in the composer of the next — and
+ * nothing reset any of it when the account changed, so profile B was handed
+ * profile A's half-written message and files (#608 §4).
+ *
+ * Now each composer names its draft by {@link DraftTarget}, reads only that
+ * one, and a hand-off is a write to the target's record: there is nothing to
+ * broadcast and nothing to "consume".
+ *
+ * ## Accounts
+ *
+ * The store holds the drafts of ONE account, the one bound by the app layout
+ * (`bindAccount`). Moving to a different account, or signing out, drops every
+ * draft and releases what their attachments were holding. The one exception
+ * is signing IN from signed-out: the drafts carry over, because they were
+ * typed by the person now signing in — "continue without an account" leaves
+ * a draft that must still be there after the sign-in its send opened (#608
+ * §3.2).
+ *
+ * Every write names the account it was made for ({@link DraftAddress}). A
+ * write for an account that is no longer bound — a send that fails after the
+ * switch, a picker that resolves after it — is refused and its attachments
+ * released, so a slow answer for A cannot land in B's composer.
+ *
+ * ## Not persisted
+ *
+ * A picture is a `data:` or `blob:` URL; writing megabytes of base64 into
+ * AsyncStorage on every keystroke is not a draft feature worth its cost, and a
+ * `blob:` URL does not survive a reload anyway.
+ */
+
+/**
+ * Which composer: a conversation's id, `null` for the new-chat screen (ghost
+ * included — it is the same screen), or a `surface:` name for a screen that
+ * asks Alia something outside a chat.
+ */
+export type DraftTarget = string | null;
+
+/** A draft's owner at the time the address was taken. */
+export interface DraftAddress {
+  account: string | null;
+  target: DraftTarget;
+}
+
+export interface ComposerDraft {
+  text: string;
+  attachments: AliaAttachment[];
+  /** The connector chosen for the next turn. */
+  mcpServerId: string | null;
+  /** The skills chosen for the next turn. */
+  skillNames: string[];
+  /**
+   * Set while the composer is rewriting a turn already sent rather than
+   * writing a new one: its send replaces that turn and everything after it.
+   * Absent for an ordinary draft.
+   */
+  editing?: DraftEdit;
+}
+
+export type DraftTurn = Pick<ComposerDraft, 'mcpServerId' | 'skillNames'>;
+
+/** What the composer held before an edit took it over, for a cancel to give back. */
+export type DraftBeforeEdit = Pick<ComposerDraft, 'text' | 'mcpServerId' | 'skillNames'>;
+
+export interface DraftEdit {
+  /** The user turn being rewritten. */
+  messageId: string;
+  before: DraftBeforeEdit;
+}
+
+/** The turn an edit loads into the composer: its words and the options it was sent with. */
+export interface EditedTurn extends DraftTurn {
+  messageId: string;
+  text: string;
+}
+
+export const EMPTY_DRAFT: ComposerDraft = Object.freeze({
+  text: '',
+  attachments: [],
+  mcpServerId: null,
+  skillNames: [],
+}) as ComposerDraft;
+
+/**
+ * Give back a temporary URL, if this one is temporary.
+ *
+ * On web both pickers — and a dropped document — hand back
+ * `URL.createObjectURL(file)`, which pins the file's bytes in the page until
+ * it is revoked. `data:` and `file://` URLs are plain strings: nothing to give
+ * back.
+ */
+export function releaseAttachmentUri(uri: string | undefined): void {
+  if (uri === undefined || !uri.startsWith('blob:')) return;
+  if (typeof URL === 'undefined' || typeof URL.revokeObjectURL !== 'function') return;
+  URL.revokeObjectURL(uri);
+}
+
+export function releaseAttachments(attachments: readonly AliaAttachment[]): void {
+  for (const attachment of attachments) releaseAttachmentUri(attachment.uri);
+}
+
+const keyOf = (target: DraftTarget) => target ?? '';
+
+interface DraftStoreState {
+  /** The account whose drafts these are; `null` while signed out. */
+  account: string | null;
+  drafts: Record<string, ComposerDraft>;
+
+  bindAccount: (userId: string | null) => void;
+  /** The address of `target` under the account bound now. */
+  address: (target: DraftTarget) => DraftAddress;
+
+  setText: (address: DraftAddress, text: string) => void;
+  addAttachment: (address: DraftAddress, attachment: AliaAttachment) => void;
+  /** Takes the tile away and releases its URL. */
+  removeAttachment: (address: DraftAddress, id: string) => void;
+  /** Change the turn's connector and skills, from what the draft holds now. */
+  updateTurn: (address: DraftAddress, change: (turn: DraftTurn) => DraftTurn) => void;
+  /**
+   * Put a draft back — a send that failed, or text another screen hands to a
+   * composer. The fields given replace the draft's; attachments given are put
+   * back in front of any added since, which are kept.
+   */
+  restore: (address: DraftAddress, draft: Partial<ComposerDraft>) => void;
+  /**
+   * Empty the draft for a send. The attachments are NOT released: the send
+   * still needs them, and a failed one hands them back through `restore`.
+   */
+  clear: (address: DraftAddress) => void;
+  /**
+   * Load a sent turn into the composer to be rewritten. What the composer held
+   * is kept aside (attachments stay where they are), and a second edit started
+   * before the first is sent or cancelled keeps the ORIGINAL draft aside, not
+   * the first edit's text.
+   */
+  startEdit: (address: DraftAddress, turn: EditedTurn) => void;
+  /** Leave edit mode and give the composer back what it held before. */
+  cancelEdit: (address: DraftAddress) => void;
+}
+
+export const useComposerDraftStore = create<DraftStoreState>((set, get) => {
+  /** Apply `change` to the target's draft, if the address is still current. */
+  const write = (
+    address: DraftAddress,
+    change: (draft: ComposerDraft) => ComposerDraft | null,
+    rejected?: () => void,
+  ) => {
+    if (address.account !== get().account) {
+      rejected?.();
+      return;
+    }
+    set((state) => {
+      const key = keyOf(address.target);
+      const next = change(state.drafts[key] ?? EMPTY_DRAFT);
+      const drafts = { ...state.drafts };
+      if (next === null) delete drafts[key];
+      else drafts[key] = next;
+      return { drafts };
+    });
+  };
+
+  return {
+    account: null,
+    drafts: {},
+
+    bindAccount: (userId) => {
+      const { account, drafts } = get();
+      if (userId === account) return;
+      // Signed out -> signed in: the same person, carrying what they typed.
+      if (account === null) {
+        set({ account: userId });
+        return;
+      }
+      for (const draft of Object.values(drafts)) releaseAttachments(draft.attachments);
+      set({ account: userId, drafts: {} });
+    },
+
+    address: (target) => ({ account: get().account, target }),
+
+    setText: (address, text) => write(address, (draft) => ({ ...draft, text })),
+
+    addAttachment: (address, attachment) =>
+      write(
+        address,
+        (draft) => ({ ...draft, attachments: [...draft.attachments, attachment] }),
+        () => releaseAttachmentUri(attachment.uri),
+      ),
+
+    removeAttachment: (address, id) =>
+      write(address, (draft) => {
+        const removed = draft.attachments.find((a) => a.id === id);
+        if (removed === undefined) return draft;
+        releaseAttachmentUri(removed.uri);
+        return { ...draft, attachments: draft.attachments.filter((a) => a.id !== id) };
+      }),
+
+    updateTurn: (address, change) =>
+      write(address, (draft) => ({
+        ...draft,
+        ...change({ mcpServerId: draft.mcpServerId, skillNames: draft.skillNames }),
+      })),
+
+    restore: (address, restored) =>
+      write(
+        address,
+        (draft) => {
+          const returning = restored.attachments ?? [];
+          const ids = new Set(returning.map((a) => a.id));
+          return {
+            ...draft,
+            ...restored,
+            attachments: [...returning, ...draft.attachments.filter((a) => !ids.has(a.id))],
+          };
+        },
+        () => releaseAttachments(restored.attachments ?? []),
+      ),
+
+    clear: (address) => write(address, () => null),
+
+    startEdit: (address, turn) =>
+      write(address, (draft) => ({
+        ...draft,
+        text: turn.text,
+        mcpServerId: turn.mcpServerId,
+        skillNames: turn.skillNames,
+        editing: {
+          messageId: turn.messageId,
+          before: draft.editing?.before ?? {
+            text: draft.text,
+            mcpServerId: draft.mcpServerId,
+            skillNames: draft.skillNames,
+          },
+        },
+      })),
+
+    cancelEdit: (address) =>
+      write(address, (draft) => {
+        if (draft.editing === undefined) return draft;
+        const { editing, ...rest } = draft;
+        return { ...rest, ...editing.before };
+      }),
+  };
+});
+
+/** The draft of `target`, as a component reads it. */
+export function useComposerDraft(target: DraftTarget): ComposerDraft {
+  return useComposerDraftStore((state) => state.drafts[keyOf(target)] ?? EMPTY_DRAFT);
+}
+
+/** The address of `target` under the account bound now, as a component takes it. */
+export function useDraftAddress(target: DraftTarget): DraftAddress {
+  const account = useComposerDraftStore((state) => state.account);
+  return useMemo(() => ({ account, target }), [account, target]);
+}