@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/builtin-views/chat/core.mjs

@@ -0,0 +1,725 @@
+// @ts-check
+/**
+ * Chat view — the portable CORE for the crtr `chat` builtin view.
+ *
+ * Import-free, dual-target, plain JS only. The core owns the state shape, the
+ * stream declaration, the broker frame fold, and the drive intents; presenters
+ * only read state and dispatch intents.
+ *
+ * @module chat/core
+ */
+
+/** @typedef {'controller'|'observer'} ChatRole */
+/** @typedef {'idle'|'connecting'|'open'|'closed'|'no-broker'|'no-node'|'invalid'|'error'} ChatConn */
+/** @typedef {'info'|'action'|'error'} NoticeLevel */
+
+/** @typedef {Object} ChatTranscript
+ * @property {any[]} messages
+ * @property {number|null} streamingIndex
+ * @property {string[]} executingToolIds
+ * @property {string|null} activity
+ * @property {string|null} lastAssistantText
+ */
+
+/** @typedef {Object} ChatSession
+ * @property {string|null} sessionId
+ * @property {string|null} sessionFile
+ * @property {string|null} model
+ * @property {boolean} isStreaming
+ * @property {string} thinkingLevel
+ * @property {string} steeringMode
+ * @property {string} followUpMode
+ * @property {string|null} sessionName
+ * @property {boolean} autoCompactionEnabled
+ * @property {number} pendingMessageCount
+ */
+
+/** @typedef {Object} ChatNotice
+ * @property {string} id
+ * @property {NoticeLevel} level
+ * @property {string} text
+ * @property {number} at
+ */
+
+/** @typedef {Object} ChatState
+ * @property {string|null} target
+ * @property {ChatRole} desiredRole
+ * @property {any|null} channel
+ * @property {string|null} clientId
+ * @property {ChatConn} conn
+ * @property {ChatRole} role
+ * @property {string|null} controllerId
+ * @property {ChatSession|null} session
+ * @property {ChatTranscript} transcript
+ * @property {string} draft
+ * @property {ChatNotice[]} notices
+ * @property {any|null} pendingDialog
+ * @property {string[]} queued
+ * @property {number|undefined} contextTokens
+ */
+
+/** @typedef {Object} ChatCloseReason
+ * @property {string=} reason
+ * @property {string=} message
+ * @property {string=} kind
+ */
+
+function uid() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === 'function') return c.randomUUID();
+  return `n-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+/** @param {unknown} value @returns {string} */
+function asText(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+/** @param {unknown} value @returns {string|null} */
+function asMaybeText(value) {
+  return typeof value === 'string' && value !== '' ? value : null;
+}
+
+/** @param {unknown} value @returns {string|null} */
+function messageRole(value) {
+  return isRecord(value) && typeof value.role === 'string' ? value.role : null;
+}
+
+/** @param {unknown} content @returns {string} */
+function textFromContent(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((block) => isRecord(block) && block.type === 'text')
+    .map((block) => asText(block.text))
+    .join('');
+}
+
+/** @param {unknown} message @returns {string} */
+export function messageText(message) {
+  if (!isRecord(message)) return '';
+  const fromContent = textFromContent(message.content);
+  if (fromContent) return fromContent;
+  return asText(message.text);
+}
+
+/** @param {any[]} messages @returns {string|null} */
+export function lastAssistantText(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (messageRole(message) !== 'assistant') continue;
+    const text = messageText(message).trim();
+    if (text) return text;
+  }
+  return null;
+}
+
+/** @returns {ChatTranscript} */
+export function initialTranscript() {
+  return {
+    messages: [],
+    streamingIndex: null,
+    executingToolIds: [],
+    activity: null,
+    lastAssistantText: null,
+  };
+}
+
+/** @param {any} snapshot @returns {ChatTranscript} */
+export function applySnapshot(snapshot) {
+  const messages = Array.isArray(snapshot?.messages) ? snapshot.messages.slice() : [];
+  return {
+    messages,
+    streamingIndex: null,
+    executingToolIds: [],
+    activity: snapshot?.state?.isStreaming === true ? 'Working…' : null,
+    lastAssistantText: lastAssistantText(messages),
+  };
+}
+
+/** @param {ChatTranscript} transcript @param {unknown} event @returns {ChatTranscript} */
+export function reduceAgentEvent(transcript, event) {
+  switch (event?.type) {
+    case 'agent_start':
+      return transcript.activity === 'Working…' ? transcript : { ...transcript, activity: 'Working…' };
+
+    case 'agent_end':
+      return {
+        ...transcript,
+        streamingIndex: null,
+        activity: null,
+        executingToolIds: transcript.executingToolIds.length ? [] : transcript.executingToolIds,
+      };
+
+    case 'message_start': {
+      const messages = transcript.messages.concat(event.message);
+      const streamingIndex = messageRole(event.message) === 'assistant' ? messages.length - 1 : transcript.streamingIndex;
+      return {
+        ...transcript,
+        messages,
+        streamingIndex,
+        lastAssistantText: lastAssistantText(messages),
+      };
+    }
+
+    case 'message_update': {
+      let idx = transcript.streamingIndex;
+      if (idx === null) {
+        const last = transcript.messages.length - 1;
+        if (last >= 0 && messageRole(transcript.messages[last]) === 'assistant') idx = last;
+      }
+      if (idx === null) return transcript;
+      const messages = transcript.messages.slice();
+      messages[idx] = event.message;
+      return {
+        ...transcript,
+        messages,
+        streamingIndex: idx,
+        lastAssistantText: lastAssistantText(messages),
+      };
+    }
+
+    case 'message_end': {
+      let idx = transcript.streamingIndex;
+      if (idx === null) {
+        const last = transcript.messages.length - 1;
+        if (last >= 0 && messageRole(transcript.messages[last]) === 'assistant') idx = last;
+      }
+      if (idx === null) return transcript;
+      const messages = transcript.messages.slice();
+      messages[idx] = event.message;
+      return {
+        ...transcript,
+        messages,
+        streamingIndex: null,
+        lastAssistantText: lastAssistantText(messages),
+      };
+    }
+
+    case 'tool_execution_start': {
+      if (transcript.executingToolIds.includes(event.toolCallId)) return transcript;
+      return { ...transcript, executingToolIds: transcript.executingToolIds.concat(event.toolCallId) };
+    }
+
+    case 'tool_execution_end': {
+      if (!transcript.executingToolIds.includes(event.toolCallId)) return transcript;
+      return {
+        ...transcript,
+        executingToolIds: transcript.executingToolIds.filter((id) => id !== event.toolCallId),
+      };
+    }
+
+    case 'compaction_start':
+      return transcript.activity === 'Compacting context…' ? transcript : { ...transcript, activity: 'Compacting context…' };
+
+    case 'compaction_end':
+      return { ...transcript, activity: transcript.activity === 'Working…' ? 'Working…' : null };
+
+    case 'auto_retry_start': {
+      const attempt = typeof event.attempt === 'number' ? event.attempt : 0;
+      const maxAttempts = typeof event.maxAttempts === 'number' ? event.maxAttempts : 0;
+      const delaySeconds = typeof event.delayMs === 'number' ? Math.ceil(event.delayMs / 1000) : 0;
+      return {
+        ...transcript,
+        activity: `Retrying (${attempt}/${maxAttempts}) in ${delaySeconds}s…`,
+      };
+    }
+
+    case 'auto_retry_end':
+      return { ...transcript, activity: transcript.activity === 'Working…' ? 'Working…' : null };
+
+    default:
+      return transcript;
+  }
+}
+
+/** @param {ChatTranscript} transcript @param {string} command @param {boolean|undefined} excludeFromContext @returns {ChatTranscript} */
+export function applyBashStart(transcript, command, excludeFromContext) {
+  const message = {
+    role: 'bashExecution',
+    command,
+    output: '',
+    exitCode: undefined,
+    cancelled: false,
+    truncated: false,
+    excludeFromContext,
+    timestamp: Date.now(),
+  };
+  return { ...transcript, messages: transcript.messages.concat(message) };
+}
+
+/** @param {ChatTranscript} transcript @param {string} chunk @returns {ChatTranscript} */
+export function applyBashOutput(transcript, chunk) {
+  for (let i = transcript.messages.length - 1; i >= 0; i--) {
+    const message = transcript.messages[i];
+    if (messageRole(message) !== 'bashExecution') continue;
+    const messages = transcript.messages.slice();
+    const current = isRecord(messages[i]) ? messages[i] : {};
+    messages[i] = { ...current, output: `${asText(current.output)}${chunk}` };
+    return { ...transcript, messages };
+  }
+  return transcript;
+}
+
+/** @param {ChatTranscript} transcript @param {{exitCode:number|undefined,cancelled:boolean,truncated:boolean,fullOutputPath?:string}} result @returns {ChatTranscript} */
+export function applyBashEnd(transcript, result) {
+  for (let i = transcript.messages.length - 1; i >= 0; i--) {
+    const message = transcript.messages[i];
+    if (messageRole(message) !== 'bashExecution') continue;
+    const messages = transcript.messages.slice();
+    const current = isRecord(messages[i]) ? messages[i] : {};
+    messages[i] = {
+      ...current,
+      exitCode: result.exitCode,
+      cancelled: result.cancelled,
+      truncated: result.truncated,
+      fullOutputPath: result.fullOutputPath,
+    };
+    return { ...transcript, messages };
+  }
+  return transcript;
+}
+
+/** @param {unknown} state @returns {ChatSession} */
+export function normalizeSessionState(state) {
+  const s = isRecord(state) ? state : {};
+  return {
+    sessionId: asMaybeText(s.sessionId),
+    sessionFile: asMaybeText(s.sessionFile),
+    model: asMaybeText(s.model),
+    isStreaming: s.isStreaming === true,
+    thinkingLevel: asText(s.thinkingLevel) || 'off',
+    steeringMode: asText(s.steeringMode) || 'all',
+    followUpMode: asText(s.followUpMode) || 'all',
+    sessionName: asMaybeText(s.sessionName),
+    autoCompactionEnabled: s.autoCompactionEnabled === true,
+    pendingMessageCount: typeof s.pendingMessageCount === 'number' ? s.pendingMessageCount : 0,
+  };
+}
+
+/** @param {ChatState} state @param {Partial<ChatSession>} patch @returns {ChatState} */
+export function patchSession(state, patch) {
+  const base = state.session ?? normalizeSessionState(null);
+  let changed = false;
+  /** @type {ChatSession} */
+  const nextSession = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue;
+    // @ts-ignore - key is constrained by ChatSession at call sites.
+    nextSession[key] = value;
+    changed = true;
+  }
+  return changed ? { ...state, session: nextSession } : state;
+}
+
+/** @param {ChatState} state @param {NoticeLevel} level @param {string} text @returns {ChatState} */
+export function addNotice(state, level, text) {
+  return {
+    ...state,
+    notices: state.notices.concat({ id: uid(), level, text, at: Date.now() }),
+  };
+}
+
+/** @param {unknown} reason @returns {string} */
+function closeReasonText(reason) {
+  if (typeof reason === 'string') return reason;
+  if (!isRecord(reason)) return '';
+  if (typeof reason.reason === 'string') return reason.reason;
+  if (typeof reason.message === 'string') return reason.message;
+  if (typeof reason.kind === 'string') return reason.kind;
+  return '';
+}
+
+/** @param {unknown} reason @returns {'no-broker'|'no-node'|'invalid'|'closed'} */
+export function classifyClose(reason) {
+  const text = closeReasonText(reason).toLowerCase();
+  if (text.includes('no running broker')) return 'no-broker';
+  if (text.includes('does not exist') || text.includes('no node')) return 'no-node';
+  if (text.includes('invalid') || text.includes('rejected')) return 'invalid';
+  return 'closed';
+}
+
+/** @param {any} message @returns {number|undefined} */
+function assistantContextTokens(message) {
+  if (!isRecord(message) || message.role !== 'assistant') return undefined;
+  const usage = isRecord(message.usage) ? message.usage : null;
+  if (!usage) return undefined;
+  const input = typeof usage.input === 'number' ? usage.input : null;
+  const cacheRead = typeof usage.cacheRead === 'number' ? usage.cacheRead : null;
+  const cacheWrite = typeof usage.cacheWrite === 'number' ? usage.cacheWrite : null;
+  if (input === null || cacheRead === null || cacheWrite === null) return undefined;
+  return input + cacheRead + cacheWrite;
+}
+
+/** @param {ChatState} state @param {string} text @param {NoticeLevel} level @returns {ChatState} */
+function notice(state, text, level = 'info') {
+  return addNotice(state, level, text);
+}
+
+/** @type {any} */
+const core = {
+  manifest: {
+    id: 'chat',
+    title: 'Chat',
+    description: 'Portable chat-as-a-view core',
+  },
+
+  /** @param {Readonly<Record<string, string>>} opts @returns {ChatState} */
+  init(opts) {
+    const target = typeof opts.target === 'string' && opts.target.trim() !== '' ? opts.target : null;
+    return {
+      target,
+      desiredRole: 'controller',
+      channel: null,
+      clientId: null,
+      conn: 'idle',
+      role: 'observer',
+      controllerId: null,
+      session: null,
+      transcript: initialTranscript(),
+      draft: '',
+      notices: [],
+      pendingDialog: null,
+      queued: [],
+      contextTokens: undefined,
+    };
+  },
+
+  streams: {
+    chat: {
+      id: 'chat',
+      request: ({ target, role }) => ({ kind: 'stream', target, role }),
+      onOpen: 'streamOpen',
+      onFrame: 'streamFrame',
+      onClose: 'streamClose',
+    },
+  },
+
+  intents: {
+    /** @param {any} ctx */
+    refresh(ctx) {
+      const state = ctx.state;
+      if (state.channel != null) return;
+      if (state.target == null) {
+        ctx.set((prev) => ({ ...prev, conn: 'error' }));
+        ctx.set((prev) => notice(prev, 'missing target — run crtr view run chat --target <node-id>', 'action'));
+        ctx.signal.setBanner('missing target — run crtr view run chat --target <node-id>', 'action');
+        ctx.signal.setStatus(null);
+        return;
+      }
+      ctx.signal.setStatus('connecting…');
+      try {
+        const channel = ctx.connect(core.streams.chat, { target: state.target, role: state.desiredRole });
+        ctx.set((prev) => ({
+          ...prev,
+          channel,
+          clientId: channel.id,
+          conn: 'connecting',
+        }));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.set((prev) => ({ ...prev, conn: 'error' }));
+        ctx.set((prev) => notice(prev, `stream connect failed — ${message}`, 'error'));
+        ctx.signal.setBanner(`stream connect failed — ${message}`, 'error');
+        ctx.signal.setStatus(null);
+      }
+    },
+
+    /** @param {any} ctx @param {any} channel */
+    streamOpen(ctx, channel) {
+      if (!isRecord(channel)) return;
+      ctx.set((prev) => ({
+        ...prev,
+        channel: prev.channel ?? channel,
+        clientId: prev.clientId ?? asMaybeText(channel.id),
+        conn: 'connecting',
+      }));
+      ctx.signal.setStatus('connected — waiting for welcome');
+    },
+
+    /** @param {any} ctx @param {unknown} payload */
+    streamClose(ctx, payload) {
+      // Fence: ignore stale closes from a channel that has already been replaced.
+      // Both hosts now include channelId in the close payload; if it doesn't match
+      // the current channel the close arrived from an old handle and must not
+      // clear the replacement.
+      const channelId = isRecord(payload) && typeof payload.channelId === 'string' ? payload.channelId : undefined;
+      if (channelId !== undefined && ctx.state.channel != null && ctx.state.channel.id !== channelId) return;
+      const kind = classifyClose(payload);
+      if (kind === 'closed' && ctx.state.channel == null && ctx.state.conn === 'connecting') return;
+      const banner =
+        kind === 'no-broker'
+          ? 'node is asleep / focus or revive it first'
+          : kind === 'no-node'
+            ? 'node not found / check the target'
+            : kind === 'invalid'
+              ? 'invalid target / check the target'
+              : 'stream closed / reconnect';
+      ctx.set((prev) => ({
+        ...prev,
+        channel: null,
+        conn: kind,
+      }));
+      ctx.set((prev) => notice(prev, banner, 'action'));
+      ctx.signal.setBanner(banner, 'action');
+      ctx.signal.setStatus(null);
+    },
+
+    /** @param {any} ctx */
+    reconnect(ctx) {
+      const channel = ctx.state.channel;
+      ctx.set((prev) => ({
+        ...prev,
+        channel: null,
+        conn: 'connecting',
+      }));
+      if (channel && typeof channel.close === 'function') {
+        try {
+          channel.close();
+        } catch {
+          /* best-effort close */
+        }
+      }
+      void ctx.dispatch('refresh');
+    },
+
+    /** @param {any} ctx @param {unknown} frame */
+    streamFrame(ctx, frame) {
+      if (!isRecord(frame)) return;
+      switch (frame.type) {
+        case 'welcome': {
+          const snapshot = frame.snapshot;
+          const transcript = applySnapshot(snapshot);
+          const session = normalizeSessionState(snapshot?.state);
+          const stats = snapshot?.stats;
+          const contextTokens =
+            typeof stats?.contextUsage?.tokens === 'number'
+              ? stats.contextUsage.tokens
+              : typeof stats?.tokens?.total === 'number'
+                ? stats.tokens.total
+                : undefined;
+          ctx.set((prev) => ({
+            ...prev,
+            conn: 'open',
+            controllerId: asMaybeText(frame.controller_id),
+            role: frame.controller_id === prev.clientId ? 'controller' : (frame.role ?? 'observer'),
+            session,
+            transcript,
+            pendingDialog: frame.pending_dialog ?? null,
+            contextTokens,
+          }));
+          ctx.signal.clearBanner();
+          ctx.signal.setStatus(null);
+          ctx.signal.setSubtitle(session.sessionName ?? ctx.state.target);
+          return;
+        }
+
+        case 'control_changed': {
+          ctx.set((prev) => {
+            const nextRole = frame.controller_id === prev.clientId ? 'controller' : 'observer';
+            const changed = nextRole !== prev.role;
+            const demoted = prev.role === 'controller' && nextRole === 'observer';
+            let next = {
+              ...prev,
+              controllerId: asMaybeText(frame.controller_id),
+              role: nextRole,
+              desiredRole: demoted ? 'observer' : prev.desiredRole,
+            };
+            if (changed) {
+              next = notice(next, nextRole === 'controller' ? 'control changed — you are controller' : 'control changed — read-only', 'info');
+            }
+            return next;
+          });
+          return;
+        }
+
+        case 'model_changed': {
+          ctx.set((prev) => patchSession(prev, { model: asMaybeText(frame.model) }));
+          return;
+        }
+
+        case 'error': {
+          if (frame.code === 'not_controller') {
+            const text = 'read-only — take control before sending';
+            ctx.set((prev) => ({ ...prev, role: 'observer' }));
+            ctx.set((prev) => notice(prev, text, 'action'));
+            ctx.signal.setBanner(text, 'action');
+            return;
+          }
+          const text = frame.message || frame.code || 'stream error';
+          ctx.set((prev) => notice(prev, text, 'error'));
+          ctx.signal.setBanner(text, 'error');
+          return;
+        }
+
+        case 'ack': {
+          if (frame.ok) return;
+          const text = frame.detail ? `${frame.for} failed — ${frame.detail}` : `${frame.for} failed`;
+          ctx.set((prev) => notice(prev, text, 'error'));
+          ctx.signal.setBanner(text, 'error');
+          return;
+        }
+
+        case 'extension_ui_request': {
+          const text = 'cannot answer dialogs yet';
+          ctx.set((prev) => ({ ...prev, pendingDialog: frame }));
+          ctx.set((prev) => notice(prev, text, 'action'));
+          ctx.signal.setBanner(text, 'action');
+          return;
+        }
+
+        case 'display_status': {
+          const text = frame.text === undefined ? `${frame.key} cleared` : `${frame.key}: ${frame.text}`;
+          ctx.set((prev) => notice(prev, text, 'info'));
+          return;
+        }
+
+        case 'display_widget': {
+          const text = frame.lines === undefined ? `${frame.key} cleared` : `${frame.key}: ${frame.lines.join(' | ')}`;
+          ctx.set((prev) => notice(prev, text, 'info'));
+          return;
+        }
+
+        case 'display_title': {
+          ctx.set((prev) => notice(prev, `title: ${frame.title}`, 'info'));
+          return;
+        }
+
+        case 'bash_start': {
+          ctx.set((prev) => ({ ...prev, transcript: applyBashStart(prev.transcript, frame.command, frame.excludeFromContext) }));
+          return;
+        }
+
+        case 'bash_output': {
+          ctx.set((prev) => ({ ...prev, transcript: applyBashOutput(prev.transcript, frame.chunk) }));
+          return;
+        }
+
+        case 'bash_end': {
+          ctx.set((prev) => ({ ...prev, transcript: applyBashEnd(prev.transcript, frame) }));
+          return;
+        }
+
+        default: {
+          ctx.set((prev) => {
+            const transcript = reduceAgentEvent(prev.transcript, frame);
+            let next = { ...prev, transcript };
+            if (frame.type === 'agent_start') {
+              next = patchSession(next, { isStreaming: true });
+            } else if (frame.type === 'agent_end') {
+              next = patchSession(next, { isStreaming: false });
+            } else if (frame.type === 'session_info_changed') {
+              next = patchSession(next, { sessionName: asMaybeText(frame.name) });
+            } else if (frame.type === 'thinking_level_changed') {
+              next = patchSession(next, { thinkingLevel: asText(frame.level) || next.session?.thinkingLevel || 'off' });
+            } else if (frame.type === 'queue_update') {
+              const queued = [
+                ...(Array.isArray(frame.steering) ? frame.steering : []),
+                ...(Array.isArray(frame.followUp) ? frame.followUp : []),
+              ].map((value) => String(value));
+              next = {
+                ...next,
+                queued,
+              };
+              next = patchSession(next, { pendingMessageCount: queued.length });
+            }
+            const assistantTokens = frame.type === 'message_end' ? assistantContextTokens(frame.message) : undefined;
+            if (assistantTokens !== undefined) {
+              next = { ...next, contextTokens: assistantTokens };
+            }
+            return next;
+          });
+        }
+      }
+    },
+
+    /** @param {any} ctx @param {string} draft */
+    setDraft(ctx, draft) {
+      ctx.set((prev) => ({ ...prev, draft }));
+    },
+
+    /** @param {any} ctx */
+    submitDraft(ctx) {
+      const text = ctx.state.draft.trim();
+      if (!text) return;
+      const channel = ctx.state.channel;
+      if (!channel || ctx.state.conn !== 'open') {
+        const noticeText = 'not connected — reconnect';
+        ctx.set((prev) => notice(prev, noticeText, 'error'));
+        ctx.signal.setBanner(noticeText, 'error');
+        return;
+      }
+      if (ctx.state.role !== 'controller') {
+        const text = 'read-only — take control before sending';
+        ctx.set((prev) => notice(prev, text, 'action'));
+        ctx.signal.setBanner(text, 'action');
+        return;
+      }
+      const frame = ctx.state.session?.isStreaming === true ? { type: 'steer', text } : { type: 'prompt', text };
+      channel.send(frame);
+      ctx.set((prev) => ({ ...prev, draft: '' }));
+    },
+
+    /** @param {any} ctx */
+    abort(ctx) {
+      if (ctx.state.role !== 'controller') {
+        const text = 'read-only — take control before sending';
+        ctx.set((prev) => notice(prev, text, 'action'));
+        ctx.signal.setBanner(text, 'action');
+        return;
+      }
+      if (!ctx.state.channel || ctx.state.conn !== 'open') {
+        const text = 'not connected — reconnect';
+        ctx.set((prev) => notice(prev, text, 'error'));
+        ctx.signal.setBanner(text, 'error');
+        return;
+      }
+      ctx.state.channel.send({ type: 'abort' });
+    },
+
+    /** @param {any} ctx */
+    requestControl(ctx) {
+      ctx.set((prev) => ({ ...prev, desiredRole: 'controller' }));
+      if (ctx.state.channel && ctx.state.conn === 'open') ctx.state.channel.send({ type: 'request_control' });
+    },
+
+    /** @param {any} ctx */
+    releaseControl(ctx) {
+      ctx.set((prev) => ({ ...prev, desiredRole: 'observer' }));
+      const channel = ctx.state.channel;
+      if (channel && ctx.state.conn === 'open') {
+        channel.send({ type: 'release_control' });
+      }
+      // Close and reopen as observer so transport-level auto-reconnect cannot
+      // silently reclaim controller role (transports capture role at open time).
+      void ctx.dispatch('reconnect');
+    },
+
+    /** @param {any} ctx @param {string|undefined} id */
+    clearNotice(ctx, id) {
+      ctx.set((prev) => {
+        if (id === undefined || id === null || id === '') return { ...prev, notices: [] };
+        return { ...prev, notices: prev.notices.filter((notice) => notice.id !== id) };
+      });
+    },
+
+    /** @param {any} ctx */
+    quit(ctx) {
+      if (ctx.state.channel) {
+        try {
+          ctx.state.channel.close();
+        } catch {
+          /* best-effort */
+        }
+      }
+      ctx.signal.quit();
+    },
+  },
+};
+
+export default core;