@antelopejs/dms-ai 0.1.5 → 0.2.0

package/frontend-vue/app/runtime/assistant-commands.ts

@@ -0,0 +1,210 @@
+import type { Ref } from "vue";
+import type { Translate } from "../chat/composables/useChatI18n";
+import type { CurrentPage } from "../chat/types/conversation";
+import { shortcutLabel } from "../chat/utils/platform";
+import {
+	type PageSuggestion,
+	pageName,
+	pageSuggestions,
+} from "../chat/utils/suggestions";
+import {
+	CHAT_PANEL_COMPONENT_NAME,
+	COMMAND_PALETTE_ASSISTANT_ID,
+	COMMAND_PALETTE_ORDER,
+	COMMAND_PALETTE_SOURCE_ID,
+	LAUNCHER_ACTION_ID,
+	LAUNCHER_ICON,
+	LAUNCHER_LABEL_KEY,
+	LAUNCHER_ORDER,
+	PALETTE_ANSWER_COMPONENT_NAME,
+	PALETTE_ASSISTANT_LABEL,
+	PALETTE_ASSISTANT_PLACEHOLDER,
+	PANEL_ARIA_LABEL,
+	PANEL_DEFAULT_WIDTH_PX,
+	PANEL_MAX_WIDTH_PX,
+	PANEL_MIN_WIDTH_PX,
+	SIDE_PANEL_ID,
+	TOGGLE_SHORTCUT_KEY,
+} from "./constants";
+
+/** The panel, in the shape `registerSidePanel` takes. */
+export interface AssistantSidePanel {
+	id: string;
+	component: string;
+	ariaLabel: string;
+	defaultWidth: number;
+	minWidth: number;
+	maxWidth: number;
+}
+
+/** The header button, in the shape `registerHeaderAction` takes. */
+export interface LauncherAction {
+	id: string;
+	icon: string;
+	label: string;
+	order: number;
+	sidePanelId: string;
+}
+
+/** One entry of the command palette. */
+interface PaletteItem {
+	id: string;
+	label: string;
+	icon: string;
+	suffix?: string;
+	onSelect: () => void;
+}
+
+interface PaletteGroup {
+	id: string;
+	label: string;
+	items: PaletteItem[];
+}
+
+/** A command palette source, in the shape `registerCommandPaletteSource` takes. */
+export interface PaletteSource {
+	id: string;
+	order: number;
+	groups: () => PaletteGroup[];
+}
+
+/** A first prompt the palette's assistant mode offers. */
+interface PaletteSuggestion {
+	label: string;
+	icon: string;
+}
+
+/** The palette's assistant mode, in the shape `registerCommandPaletteAssistant` takes. */
+export interface PaletteAssistant {
+	id: string;
+	label: string;
+	icon: string;
+	placeholder: string;
+	suggestions: () => PaletteSuggestion[];
+	answerComponent: string;
+}
+
+/** What the palette's entries do. */
+export interface AssistantCommandActions {
+	ask: () => void;
+	startConversation: () => void;
+	reviewApprovals: () => void;
+	openChanges: () => void;
+}
+
+/** The panel docked on the right of the dashboard; the DMS owns its state. */
+export function assistantSidePanel(): AssistantSidePanel {
+	return {
+		id: SIDE_PANEL_ID,
+		component: CHAT_PANEL_COMPONENT_NAME,
+		ariaLabel: PANEL_ARIA_LABEL,
+		defaultWidth: PANEL_DEFAULT_WIDTH_PX,
+		minWidth: PANEL_MIN_WIDTH_PX,
+		maxWidth: PANEL_MAX_WIDTH_PX,
+	};
+}
+
+/**
+ * "Assistant (⌘⇧K)": the launcher's label with its shortcut. The DMS toggles
+ * the panel from it and draws it engaged while the panel is open.
+ */
+export function launcherAction(t: Translate): LauncherAction {
+	return {
+		id: LAUNCHER_ACTION_ID,
+		icon: LAUNCHER_ICON,
+		label: `${t(LAUNCHER_LABEL_KEY)} (${shortcutLabel(TOGGLE_SHORTCUT_KEY, true)})`,
+		order: LAUNCHER_ORDER,
+		sidePanelId: SIDE_PANEL_ID,
+	};
+}
+
+/** The palette answers read-only: what it can answer in place comes first. */
+function byReadOnlyFirst(
+	suggestions: readonly PageSuggestion[],
+): PageSuggestion[] {
+	return [...suggestions].sort(
+		(left, right) => Number(right.isReadOnly) - Number(left.isReadOnly),
+	);
+}
+
+/**
+ * The palette's assistant mode (Tab in ⌘K): first prompts that fit the page on
+ * screen, as the panel's empty chat offers them, and an answer drawn by
+ * `DmsAiPaletteAnswer`.
+ */
+export function paletteAssistant(
+	t: Translate,
+	currentPage: Readonly<Ref<CurrentPage | null>>,
+): PaletteAssistant {
+	return {
+		id: COMMAND_PALETTE_ASSISTANT_ID,
+		label: PALETTE_ASSISTANT_LABEL,
+		icon: LAUNCHER_ICON,
+		placeholder: PALETTE_ASSISTANT_PLACEHOLDER,
+		suggestions: () => {
+			const page = currentPage.value;
+			return byReadOnlyFirst(pageSuggestions(page)).map((suggestion) => ({
+				label: t(suggestion.textKey, { page: pageName(page) }),
+				icon: suggestion.icon,
+			}));
+		},
+		answerComponent: PALETTE_ANSWER_COMPONENT_NAME,
+	};
+}
+
+/**
+ * The assistant's commands among the palette's search results: ways into the
+ * panel and its pages. Asking a question inline is the palette's assistant
+ * mode, registered apart.
+ */
+export function paletteSource(
+	t: Translate,
+	pendingApprovals: Readonly<Ref<number>>,
+	actions: AssistantCommandActions,
+): PaletteSource {
+	return {
+		id: COMMAND_PALETTE_SOURCE_ID,
+		order: COMMAND_PALETTE_ORDER,
+		groups: () => [
+			{
+				id: `${COMMAND_PALETTE_SOURCE_ID}-assistant`,
+				label: t("dms_ai.panel.palette.group"),
+				items: [
+					{
+						id: "dms-ai-ask",
+						label: t("dms_ai.panel.palette.ask"),
+						icon: "i-ph-sparkle",
+						suffix: shortcutLabel(TOGGLE_SHORTCUT_KEY, true),
+						onSelect: actions.ask,
+					},
+					{
+						id: "dms-ai-new",
+						label: t("dms_ai.panel.palette.new"),
+						icon: "i-ph-note-pencil",
+						onSelect: actions.startConversation,
+					},
+					{
+						id: "dms-ai-approvals",
+						label: t("dms_ai.panel.palette.approvals"),
+						icon: "i-ph-hand-palm",
+						suffix:
+							pendingApprovals.value > 0
+								? t(
+										"dms_ai.panel.palette.waiting",
+										{ count: pendingApprovals.value },
+										pendingApprovals.value,
+									)
+								: undefined,
+						onSelect: actions.reviewApprovals,
+					},
+					{
+						id: "dms-ai-changes",
+						label: t("dms_ai.panel.palette.changes"),
+						icon: "i-ph-git-diff",
+						onSelect: actions.openChanges,
+					},
+				],
+			},
+		],
+	};
+}

package/frontend-vue/app/runtime/assistant-notifications.ts

@@ -0,0 +1,181 @@
+import { type Ref, watch } from "vue";
+import type { Translate } from "../chat/composables/useChatI18n";
+import type { ChangeSetSummary } from "../chat/types/protocol";
+import type { ChatTransport } from "./chat-transport";
+import { TOAST_DURATION_MS } from "./constants";
+import { isTypedMessage } from "./typed-message";
+
+/** One button of a toast, as Nuxt UI's `useToast().add` takes it. */
+interface ToastAction {
+	label: string;
+	color?: "secondary" | "neutral";
+	variant?: "solid" | "outline";
+	onClick: () => void;
+}
+
+interface ToastInput {
+	title: string;
+	description?: string;
+	icon: string;
+	color: "secondary";
+	duration: number;
+	actions: ToastAction[];
+}
+
+export interface AssistantNotificationsOptions {
+	chat: ChatTransport;
+	isPanelOpen: Readonly<Ref<boolean>>;
+	pendingApprovals: Readonly<Ref<number>>;
+	t: Translate;
+	toast: (input: ToastInput) => void;
+	reviewApprovals: (conversationId?: string) => void;
+	undoChangeSet: (changeSet: ChangeSetSummary) => void;
+	reviewChangeSet: (changeSetId: string) => void;
+}
+
+interface PermissionRequestFrame {
+	type: "permission_request";
+	conversationId?: string;
+	summary?: string;
+}
+
+interface ChangeSetFrame {
+	type: "change_set";
+	changeSet?: ChangeSetSummary;
+}
+
+interface SettingsFrame {
+	type: "settings_update";
+	settings?: SettingsFlags;
+}
+
+interface SettingsFlags {
+	notifyRequests?: boolean;
+}
+
+const ICON = "i-ph-sparkle";
+
+interface NotifierState {
+	options: AssistantNotificationsOptions;
+	isEnabled: boolean;
+	announcedApprovals: number;
+	seenChangeSets: Set<string>;
+}
+
+function approvalToast(
+	state: NotifierState,
+	title: string,
+	conversationId?: string,
+): void {
+	const { t, toast, reviewApprovals, pendingApprovals } = state.options;
+	const count = Math.max(pendingApprovals.value, 1);
+	state.announcedApprovals = count;
+	toast({
+		title,
+		description: t("dms_ai.panel.toast.approvals_waiting", { count }, count),
+		icon: ICON,
+		color: "secondary",
+		duration: TOAST_DURATION_MS,
+		actions: [
+			{
+				label: t("dms_ai.panel.toast.review"),
+				color: "secondary",
+				onClick: () => reviewApprovals(conversationId),
+			},
+			{
+				label: t("dms_ai.panel.toast.later"),
+				color: "neutral",
+				variant: "outline",
+				onClick: () => undefined,
+			},
+		],
+	});
+}
+
+function onPermissionRequest(
+	state: NotifierState,
+	frame: PermissionRequestFrame,
+): void {
+	if (state.options.isPanelOpen.value || !state.isEnabled) return;
+	const title = frame.summary
+		? t(state, "dms_ai.panel.toast.request_title", { summary: frame.summary })
+		: t(state, "dms_ai.panel.toast.request_generic");
+	approvalToast(state, title, frame.conversationId);
+}
+
+function t(
+	state: NotifierState,
+	key: string,
+	params?: Record<string, string | number>,
+): string {
+	return state.options.t(key, params);
+}
+
+function onChangeSet(state: NotifierState, frame: ChangeSetFrame): void {
+	const set = frame.changeSet;
+	if (set === undefined || state.seenChangeSets.has(set.id)) return;
+	state.seenChangeSets.add(set.id);
+	if (set.state !== "applied" || state.options.isPanelOpen.value) return;
+	const { toast, undoChangeSet, reviewChangeSet } = state.options;
+	toast({
+		title: t(state, "dms_ai.panel.toast.applied", { number: set.number }),
+		description: set.title,
+		icon: ICON,
+		color: "secondary",
+		duration: TOAST_DURATION_MS,
+		actions: [
+			{
+				label: t(state, "dms_ai.panel.change.undo"),
+				color: "neutral",
+				variant: "outline",
+				onClick: () => undoChangeSet(set),
+			},
+			{
+				label: t(state, "dms_ai.panel.change.review"),
+				color: "secondary",
+				onClick: () => reviewChangeSet(set.id),
+			},
+		],
+	});
+}
+
+const FRAME_HANDLERS: Record<
+	string,
+	(state: NotifierState, frame: never) => void
+> = {
+	permission_request: onPermissionRequest,
+	change_set: onChangeSet,
+	settings_update: (state, frame: SettingsFrame) => {
+		state.isEnabled = frame.settings?.notifyRequests !== false;
+	},
+};
+
+/**
+ * DMS toasts for what happens while the panel is closed: a request waiting
+ * for the user (when the settings allow it) and a change set just applied,
+ * with Undo. A request the stream did not carry is caught by the polled count.
+ */
+export function installAssistantNotifications(
+	options: AssistantNotificationsOptions,
+): () => void {
+	const state: NotifierState = {
+		options,
+		isEnabled: true,
+		announcedApprovals: options.pendingApprovals.value,
+		seenChangeSets: new Set(),
+	};
+	const stopListening = options.chat.onMessage((msg) => {
+		if (!isTypedMessage(msg)) return;
+		FRAME_HANDLERS[msg.type]?.(state, msg as never);
+	});
+	const stopWatching = watch(options.pendingApprovals, (count) => {
+		const isNew = count > state.announcedApprovals;
+		if (!isNew) state.announcedApprovals = count;
+		if (!isNew || options.isPanelOpen.value || !state.isEnabled) return;
+		approvalToast(state, t(state, "dms_ai.panel.toast.request_generic"));
+	});
+	return () => {
+		stopListening();
+		stopWatching();
+	};
+}

package/frontend-vue/app/runtime/assistant-session.ts

@@ -1,12 +1,27 @@
-import type { InjectionKey, Ref } from "vue";
+import type { InjectionKey, Ref, ShallowRef } from "vue";
+import type { ChatApi } from "../chat/composables/useChangeSetActions";
+import type { CurrentPage } from "../chat/types/conversation";
 import type { ChatTransport } from "./chat-transport";
-import type { ChatPanelState } from "./panel-state";
+import type { PanelIntents } from "./panel-intents";
 import type { SidecarStatus } from "./sidecar-status";
 
 /**
- * What the chat panel needs from the plugin that owns the tab's assistant: the
- * sidecar's reachability, the chat's side of the tab's stream, the panel's own
- * state, and the dashboard's router.
+ * Whether the assistant panel is open, and the ways to change it. The DMS owns
+ * the state (`useSidePanel`): it remembers it in a cookie, renders the panel
+ * docked next to the page, and the header launcher toggles it.
+ */
+export interface ChatPanelState {
+	isOpen: Readonly<Ref<boolean>>;
+	open: () => void;
+	close: () => void;
+	toggle: () => void;
+}
+
+/**
+ * The tab's assistant, as the plugin that owns it hands it to the panel, the
+ * command palette's answer and the workspace pages: the sidecar's
+ * reachability, the chat's side of the tab's stream, the panel's state, and
+ * ways to open it on a chat.
  */
 export interface AssistantSession {
 	status: Readonly<Ref<SidecarStatus>>;
@@ -14,8 +29,36 @@ export interface AssistantSession {
 	panel: ChatPanelState;
 	/** Opens a page of the dashboard, as its own links do. */
 	navigate: (path: string) => void;
+	/** Opens the panel on that conversation. */
+	openConversation: (conversationId: string) => void;
+	/** Opens the panel on a new conversation, the composer optionally prefilled. */
+	startConversation: (prompt?: string) => void;
+	/**
+	 * Keeps the tab's stream open while the panel is closed, until the returned
+	 * function releases it: the command palette's answer streams through it.
+	 */
+	holdStream: () => () => void;
+	/** Requests waiting for an answer, across every chat. */
+	pendingApprovals: Readonly<Ref<number>>;
+	/** What the panel was asked to do and has not done yet. */
+	intents: PanelIntents;
+	/** The page the dashboard shows. */
+	currentPage: Readonly<Ref<CurrentPage | null>>;
+	/** The dashboard's authenticated requests, for the panel's own HTTP calls. */
+	api: ChatApi;
+	/** Why the sidecar last failed to start, when the backend knows. */
+	lastError: Readonly<Ref<string | null>>;
+	/** Asks the backend to restart the sidecar, then probes it again. */
+	restart: () => Promise<void>;
 }
 
-export const ASSISTANT_SESSION_KEY: InjectionKey<AssistantSession> = Symbol(
+/**
+ * The tab's assistant session, provided from the start: `null` until the
+ * sidecar answered its first probe, and for good when the assistant does not
+ * run in this tab (production, a guest, the sidecar disabled).
+ */
+export type AssistantSessionRef = Readonly<ShallowRef<AssistantSession | null>>;
+
+export const ASSISTANT_SESSION_KEY: InjectionKey<AssistantSessionRef> = Symbol(
 	"dms-ai:assistant-session",
 );

package/frontend-vue/app/runtime/channel-client.ts

@@ -26,13 +26,10 @@ export type ChannelStatus =
 	| typeof CHANNEL_STATUS_RECONNECTING;
 
 /** Posts one message as JSON; `$authFetch` in the dashboard refreshes a stale session. */
-export type PostMessage = (path: string, body: unknown) => Promise<unknown>;
+type PostMessage = (path: string, body: unknown) => Promise<unknown>;
 
 /** Opens the tab's event stream. */
-export type OpenStream = (
-	path: string,
-	signal: AbortSignal,
-) => Promise<Response>;
+type OpenStream = (path: string, signal: AbortSignal) => Promise<Response>;
 
 export interface ChannelClientOptions {
 	post: PostMessage;
@@ -80,7 +77,7 @@ interface ClientState {
 	backoff: BackoffState;
 }
 
-export function channelMessagesPath(connectionId: string): string {
+function channelMessagesPath(connectionId: string): string {
 	return `${CHANNEL_PATH}/${encodeURIComponent(connectionId)}/${CHANNEL_MESSAGES_SEGMENT}`;
 }
 

package/frontend-vue/app/runtime/constants.ts

@@ -1,12 +1,3 @@
-export const OVERLAY_DEFAULT_WIDTH_PX = 460;
-/**
- * Above the dashboard's header and the builder's overlay (z-50), below what the
- * dashboard portals out of the app: the DMS paints its popovers, modals and
- * toasts in an isolated layer after the app, whatever this value is.
- */
-export const OVERLAY_Z_INDEX = 55;
-export const OVERLAY_DOM_ID = "dms-ai-overlay-root";
-export const DMS_OVERLAYS_DOM_ID = "dms-overlays";
 export const SIDECAR_INFO_PATH = "/ai/sidecar-info";
 /** Event stream to receive, POST to send: HTTP the DMS frontend server relays. */
 export const CHANNEL_PATH = "/ai/channel";
@@ -39,10 +30,6 @@ export const SIDECAR_STATUS_UNAVAILABLE = "unavailable";
 // side, so this doubles as the respawn heartbeat; capped so a genuinely stuck
 // sidecar is polled sparingly rather than hammered.
 export const SIDECAR_POLL_DELAYS_MS = [500, 1000, 2000, 4000, 8000] as const;
-export const PLACEHOLDER_CONNECTING_TEXT = "Connecting the assistant…";
-export const PLACEHOLDER_REVIVING_TEXT = "Reconnecting the assistant…";
-export const PLACEHOLDER_UNAVAILABLE_TITLE = "Assistant unavailable";
-export const PLACEHOLDER_UNAVAILABLE_TEXT = "Reload the page to try again.";
 
 export const CHANNEL_STATUS_CONNECTING = "connecting";
 export const CHANNEL_STATUS_CONNECTED = "connected";
@@ -58,34 +45,41 @@ export const HOST_COMMAND_NAVIGATE_TYPE = "host_command_navigate";
 export const HOST_COMMAND_TYPES: ReadonlySet<string> = new Set([
 	HOST_COMMAND_NAVIGATE_TYPE,
 ]);
-export const OVERLAY_MIN_WIDTH_PX = 320;
-export const OVERLAY_PREFS_STORAGE_KEY = "dms-ai:overlay-prefs";
-export const OVERLAY_OUTSIDE_TOGGLE_SUPPRESS_MS = 300;
-export const OVERLAY_PREFS_DEBOUNCE_MS = 300;
 export const TOGGLE_SHORTCUT_KEY = "k";
 export const MODAL_OPEN_SELECTOR = '[role="dialog"][aria-modal="true"]';
 
-// Generic header-action registry exposed by the DMS core (dms-back). Any module
-// can push a button by writing to this shared `useDmsState` key; the core renders
-// it with no knowledge of who registered it.
-export const HEADER_ACTIONS_STATE_KEY = "dms:header-actions";
-/**
- * The DMS's persistent overlays: components rendered on every page, inside the
- * app but outside the routed page, so they live through Inertia navigations.
- * The state key and the component name are the whole contract.
- */
-export const APP_OVERLAYS_STATE_KEY = "dms-app-overlays";
 export const CHAT_PANEL_COMPONENT_NAME = "DmsAiChatPanel";
+/** The panel's id among the dashboard's docked side panels. */
+export const SIDE_PANEL_ID = "dms-ai:assistant";
+export const PANEL_DEFAULT_WIDTH_PX = 460;
+export const PANEL_MIN_WIDTH_PX = 360;
+/** Wide enough for a diff side by side; the DMS caps it at 60% of the window too. */
+export const PANEL_MAX_WIDTH_PX = 820;
+export const COMMAND_PALETTE_ASSISTANT_ID = "dms-ai:assistant";
+export const PALETTE_ANSWER_COMPONENT_NAME = "DmsAiPaletteAnswer";
+export const PALETTE_ASSISTANT_LABEL = "$dms_ai.panel.palette.assistant";
+export const PALETTE_ASSISTANT_PLACEHOLDER =
+	"$dms_ai.panel.palette.placeholder";
 export const LAUNCHER_ACTION_ID = "dms-ai-launcher";
 /**
  * The chat panel's header shows the same icon, which is what gets it into the
- * renderer's icon bundle: it only scans `.vue` files for icon names.
+ * renderer's icon bundle.
  */
-export const LAUNCHER_ICON = "i-ph-robot";
-export const LAUNCHER_LABEL = "AI assistant";
-export const PANEL_LABEL = LAUNCHER_LABEL;
+export const LAUNCHER_ICON = "i-ph-sparkle";
 export const LAUNCHER_ORDER = 50;
-// Toggle shortcut, shown in the launcher tooltip. The combo is meta/ctrl + shift
-// + k, so render it the way each platform expects.
-export const TOGGLE_SHORTCUT_LABEL_MAC = "⌘⇧K";
-export const TOGGLE_SHORTCUT_LABEL_OTHER = "Ctrl+Shift+K";
+export const LAUNCHER_LABEL_KEY = "dms_ai.panel.launcher";
+/** The panel landmark's name, as an i18n key the DMS resolves. */
+export const PANEL_ARIA_LABEL = `$${LAUNCHER_LABEL_KEY}`;
+export const COMMAND_PALETTE_SOURCE_ID = "dms-ai";
+export const COMMAND_PALETTE_ORDER = 60;
+/** The backend's view of the sidecar: pending approvals, last start error. */
+export const STATUS_PATH = "/ai/status";
+export const RESTART_PATH = "/ai/sidecar/restart";
+export const CHANGES_PATH = "/modules/ai/changes";
+/**
+ * How often a closed panel re-reads the pending approvals, so a request that
+ * arrives while no stream is open still gets its toast.
+ */
+export const STATUS_POLL_MS = 15_000;
+/** How long the panel's toasts stay up. */
+export const TOAST_DURATION_MS = 8_000;

package/frontend-vue/app/runtime/host-commands.ts

@@ -6,7 +6,7 @@ interface RouterLike {
 }
 
 /**
- * The slice of the host's `useDmsDevReload()` composable this module needs:
+ * The slice of the host's `useDevReload()` composable this module needs:
  * resolve `true` once the committed site layout serves `path`, `false` on
  * timeout.
  */
@@ -19,12 +19,12 @@ export interface HostCommandContext {
 	devReload: DevReloadWaiter;
 }
 
-export interface HostCommandNavigateMessage {
+interface HostCommandNavigateMessage {
 	type: typeof HOST_COMMAND_NAVIGATE_TYPE;
 	path: string;
 }
 
-export type HostCommandMessage = HostCommandNavigateMessage;
+type HostCommandMessage = HostCommandNavigateMessage;
 
 /** Takes a sidecar message already parsed; anything that is not a host command is ignored. */
 export type HostCommandDispatcher = (msg: unknown) => void;
@@ -84,7 +84,7 @@ async function runNavigate(state: DispatcherState): Promise<void> {
  * Whether the agent may send the dashboard to `path`. What it asks for comes
  * from model output, so it may only ever lead to a page of this origin.
  */
-export function isInAppPath(path: unknown): path is string {
+function isInAppPath(path: unknown): path is string {
 	if (typeof path !== "string" || !IN_APP_PATH.test(path)) return false;
 	try {
 		const origin = globalThis.location.origin;

package/frontend-vue/app/runtime/listeners.ts

@@ -1,6 +1,6 @@
 import { LOG_PREFIX } from "./constants";
 
-export type Listener<T> = (value: T) => void;
+type Listener<T> = (value: T) => void;
 
 export interface Listeners<T> {
 	add: (listener: Listener<T>) => () => void;

package/frontend-vue/app/runtime/navigation-complete.ts

@@ -1,7 +1,7 @@
 import { router } from "@inertiajs/vue3";
 import { HOST_NAVIGATION_COMPLETE_TYPE } from "./constants";
 
-export interface HostNavigationCompleteMessage {
+interface HostNavigationCompleteMessage {
 	type: typeof HOST_NAVIGATION_COMPLETE_TYPE;
 	path: string;
 }

package/frontend-vue/app/runtime/panel-intents.ts

@@ -0,0 +1,55 @@
+import { type Ref, ref } from "vue";
+
+/** Opens the panel on a stored conversation. */
+interface OpenConversationIntent {
+	kind: "open";
+	conversationId: string;
+}
+
+/** Opens the panel on a new conversation, the composer optionally prefilled. */
+interface StartConversationIntent {
+	kind: "start";
+	prompt?: string;
+}
+
+/** Puts the caret in the composer of the current conversation. */
+interface FocusComposerIntent {
+	kind: "focus";
+}
+
+/** Brings the approvals dock forward. */
+interface ReviewApprovalsIntent {
+	kind: "approvals";
+}
+
+export type PanelIntent =
+	| OpenConversationIntent
+	| StartConversationIntent
+	| FocusComposerIntent
+	| ReviewApprovalsIntent;
+
+/**
+ * What the dashboard asked the panel to do: open a chat, start one, focus the
+ * composer. The chat may not be mounted yet when it is asked, so the latest
+ * request waits here until the chat takes it.
+ */
+export interface PanelIntents {
+	pending: Readonly<Ref<PanelIntent | null>>;
+	push: (intent: PanelIntent) => void;
+	take: () => PanelIntent | null;
+}
+
+export function createPanelIntents(): PanelIntents {
+	const pending = ref<PanelIntent | null>(null);
+	return {
+		pending,
+		push: (intent) => {
+			pending.value = intent;
+		},
+		take: () => {
+			const intent = pending.value;
+			pending.value = null;
+			return intent;
+		},
+	};
+}