@antelopejs/dms-ai 0.0.1

package/frontend-vue/app/plugins/ai.client.ts

@@ -0,0 +1,109 @@
+import { defineDmsPlugin, useDmsRouter } from '#dms-inertia/frontend-module'
+import {
+	SIDECAR_HOST_NAME,
+	SIDECAR_INFO_PATH,
+	SIDECAR_PROBE_HOST,
+	SIDECAR_STATUS_CONNECTED,
+	SIDECAR_STATUS_REVIVING,
+	SIDECAR_STATUS_UNAVAILABLE,
+	WS_STATUS_CONNECTED,
+	WS_STATUS_CONNECTING,
+} from '../runtime/constants'
+import { installCurrentPageTracker } from '../runtime/current-page'
+import { registerLauncherAction } from '../runtime/header-action'
+import { createHostCommandDispatcher } from '../runtime/host-commands'
+import { installNavigationCompleteEmitter } from '../runtime/navigation-complete'
+import { injectOverlay } from '../runtime/overlay'
+import { installToggleShortcut } from '../runtime/shortcuts'
+import {
+	createSidecarStatusController,
+	type SidecarStatus,
+} from '../runtime/sidecar-status'
+import { createHostWsClient } from '../runtime/ws-client'
+
+function buildIframeUrl(port: number, token: string): string {
+	// Seed the chatbox with the host's current light/dark mode so its very first
+	// paint matches; the theme bridge keeps it in sync from there on.
+	const mode = document.documentElement.classList.contains('dark')
+		? 'dark'
+		: 'light'
+	return `${SIDECAR_PROBE_HOST}:${port}/?theme=${mode}#token=${encodeURIComponent(token)}`
+}
+
+export default defineDmsPlugin(async ({ vueApp }) => {
+	if (!import.meta.env.DEV) return
+	const { loggedIn } = useUserSession()
+	if (!loggedIn.value) return
+	const { $authFetch } = useAuthFetch()
+	const controller = createSidecarStatusController(() =>
+		$authFetch(SIDECAR_INFO_PATH),
+	)
+	// A null/disabled first probe means the assistant shouldn't appear at all —
+	// preserve the previous "no icon, no overlay" behavior in that case.
+	if (!(await controller.init())) return
+	const overlay = injectOverlay()
+	if (overlay === null) return
+
+	installToggleShortcut({ onToggle: () => overlay.toggleOpen() })
+	// Registered unconditionally (even while reviving) so the launcher is present
+	// through an outage; opening it surfaces the panel's own status placeholder.
+	registerLauncherAction(() => overlay.toggleFromLauncher())
+
+	const router = useDmsRouter()
+	// Host-side dev hot reload. A page the agent just wrote is re-registered
+	// asynchronously, so every overlay-driven navigation waits for the committed
+	// site layout to serve the route before pushing it.
+	const devReload = useDmsDevReload()
+	// Serialized so a burst of navigate commands cannot land out of order.
+	const dispatchHostCommand = createHostCommandDispatcher({ router, devReload })
+	const hostWs = createHostWsClient({
+		sidecarHost: SIDECAR_HOST_NAME,
+		getPort: () => controller.getPort(),
+		getClientToken: () => controller.getClientToken(),
+		onMessage: dispatchHostCommand,
+		onStatusChange: (status) => {
+			// A socket drop means the sidecar likely idle-exited/crashed: ask the
+			// controller to re-probe (relearning a possibly-new port) rather than let
+			// the socket keep retrying the dead one.
+			if (status !== WS_STATUS_CONNECTED && status !== WS_STATUS_CONNECTING) {
+				controller.reportWsDown()
+			}
+		},
+	})
+
+	let firstApply = true
+	const applyStatus = (status: SidecarStatus): void => {
+		if (status === SIDECAR_STATUS_CONNECTED) {
+			const port = controller.getPort()
+			const token = controller.getClientToken()
+			if (port !== null && token) overlay.repoint(buildIframeUrl(port, token))
+			// On the first apply the socket was just created and is connecting to the
+			// right port; only later connects (after a drop or port change) need a
+			// forced, backoff-skipping reconnect.
+			if (!firstApply) hostWs.reconnectNow()
+		} else if (status === SIDECAR_STATUS_REVIVING) {
+			overlay.showPlaceholder('reviving')
+		} else if (status === SIDECAR_STATUS_UNAVAILABLE) {
+			overlay.showPlaceholder('unavailable')
+		} else {
+			overlay.showPlaceholder('connecting')
+		}
+		firstApply = false
+	}
+	controller.subscribe(applyStatus)
+
+	const sendWhenConnected = (msg: unknown): void => {
+		if (!hostWs.isConnected()) return
+		hostWs.send(msg)
+	}
+	const stopTracking = installCurrentPageTracker({ send: sendWhenConnected })
+	const stopNavigation = installNavigationCompleteEmitter({
+		send: sendWhenConnected,
+	})
+	const stop = (): void => {
+		stopTracking()
+		stopNavigation()
+	}
+	vueApp.onUnmount(stop)
+	import.meta.hot?.dispose(stop)
+})

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

@@ -0,0 +1,30 @@
+export interface BackoffState {
+	index: number
+}
+
+export function createBackoff(): BackoffState {
+	return { index: 0 }
+}
+
+function readScheduleAt(
+	schedule: readonly number[],
+	index: number,
+): number {
+	const value = schedule[index]
+	if (value === undefined) return 0
+	return value
+}
+
+export function nextDelay(
+	state: BackoffState,
+	schedule: readonly number[],
+): number {
+	const cappedIndex = Math.min(state.index, schedule.length - 1)
+	const delay = readScheduleAt(schedule, cappedIndex)
+	state.index += 1
+	return delay
+}
+
+export function resetBackoff(state: BackoffState): void {
+	state.index = 0
+}

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

@@ -0,0 +1,66 @@
+export const OVERLAY_DEFAULT_WIDTH_PX = 460
+export const OVERLAY_Z_INDEX = 999_999
+export const OVERLAY_DOM_ID = 'dms-ai-overlay-root'
+export const OVERLAY_IFRAME_ID = 'dms-ai-overlay-iframe'
+export const SIDECAR_INFO_PATH = '/ai/sidecar-info'
+export const SIDECAR_PROBE_PORT = 5010
+export const SIDECAR_PROBE_HOST = 'http://localhost'
+export const OVERLAY_BOX_SHADOW = '0 8px 24px rgba(0, 0, 0, 0.18)'
+export const SIDECAR_HOST_NAME = 'localhost'
+export const WS_HOST_PATH = '/ws/host'
+export const WS_RECONNECT_DELAYS_MS = [
+	1000, 2000, 4000, 8000, 15000, 30000,
+] as const
+// Sidecar reachability, as seen by the host. `reviving` is the self-healing
+// state (idle-exited / crashed-respawning): the probe loop is relearning the new
+// random port and will repoint the frame. `unavailable` is terminal (the crash
+// budget is spent) and needs a reload.
+export const SIDECAR_STATUS_CONNECTING = 'connecting'
+export const SIDECAR_STATUS_CONNECTED = 'connected'
+export const SIDECAR_STATUS_REVIVING = 'reviving'
+export const SIDECAR_STATUS_UNAVAILABLE = 'unavailable'
+// Re-probe cadence while reviving. Each probe also revives the daemon backend
+// 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 OVERLAY_PLACEHOLDER_ID = 'dms-ai-overlay-placeholder'
+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 WS_STATUS_CONNECTING = 'connecting'
+export const WS_STATUS_CONNECTED = 'connected'
+export const WS_STATUS_DISCONNECTED = 'disconnected'
+export const WS_STATUS_RECONNECTING = 'reconnecting'
+export const WS_PROTOCOL_SECURE = 'wss:'
+export const WS_PROTOCOL_INSECURE = 'ws:'
+export const PAGE_PROTOCOL_SECURE = 'https:'
+export const HOST_ROLE = 'host'
+export const HELLO_MESSAGE_TYPE = 'hello'
+export const LOG_PREFIX = '[dms-ai]'
+export const HOST_STATE_UPDATE_TYPE = 'host_state_update'
+export const HOST_NAVIGATION_COMPLETE_TYPE = 'host_navigation_complete'
+export const HOST_COMMAND_NAVIGATE_TYPE = 'host_command_navigate'
+export const OVERLAY_RESIZE_HANDLE_SIZE_PX = 6
+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 Nuxt state key; the core renders
+// it with no knowledge of who registered it.
+export const HEADER_ACTIONS_STATE_KEY = 'dms:header-actions'
+export const LAUNCHER_ACTION_ID = 'dms-ai-launcher'
+export const LAUNCHER_ICON = 'i-ph-robot'
+export const LAUNCHER_LABEL = 'AI assistant'
+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'

package/frontend-vue/app/runtime/current-page.ts

@@ -0,0 +1,28 @@
+import { router } from '@inertiajs/vue3'
+import { HOST_STATE_UPDATE_TYPE } from './constants'
+
+interface CurrentPagePayload {
+	path: string
+}
+
+interface HostStateUpdateMessage {
+	type: typeof HOST_STATE_UPDATE_TYPE
+	currentPage: CurrentPagePayload
+}
+
+interface InstallCurrentPageTrackerOptions {
+	send: (msg: HostStateUpdateMessage) => void
+}
+
+export function installCurrentPageTracker(
+	options: InstallCurrentPageTrackerOptions,
+): () => void {
+	const pushFor = (url: string): void =>
+		options.send({
+			type: HOST_STATE_UPDATE_TYPE,
+			currentPage: { path: new URL(url, window.location.origin).pathname },
+		})
+	const stop = router.on('navigate', (event) => pushFor(event.detail.page.url))
+	pushFor(window.location.href)
+	return stop
+}

package/frontend-vue/app/runtime/header-action.ts

@@ -0,0 +1,64 @@
+import { useDmsState as useState } from '#dms-inertia/frontend-module'
+import {
+	HEADER_ACTIONS_STATE_KEY,
+	LAUNCHER_ACTION_ID,
+	LAUNCHER_ICON,
+	LAUNCHER_LABEL,
+	LAUNCHER_ORDER,
+	TOGGLE_SHORTCUT_LABEL_MAC,
+	TOGGLE_SHORTCUT_LABEL_OTHER,
+} from './constants'
+
+interface UserAgentData {
+	platform?: string
+}
+
+interface NavigatorUserAgentData {
+	userAgentData?: UserAgentData
+}
+
+// The shortcut combo accepts meta OR ctrl, so show the modifier each platform
+// actually uses (⌘ on Apple, Ctrl elsewhere).
+function isApplePlatform(): boolean {
+	const nav = globalThis.navigator as
+		| (Navigator & NavigatorUserAgentData)
+		| undefined
+	if (nav === undefined) return false
+	const platform = nav.userAgentData?.platform ?? nav.platform ?? ''
+	return /mac|iphone|ipad|ipod/i.test(platform)
+}
+
+function launcherLabel(): string {
+	const shortcut = isApplePlatform()
+		? TOGGLE_SHORTCUT_LABEL_MAC
+		: TOGGLE_SHORTCUT_LABEL_OTHER
+	return `${LAUNCHER_LABEL} (${shortcut})`
+}
+
+// Our view of the shared header-action shape the DMS core renders. Declared
+// locally so this layer has no build-time dependency on the core layer; the
+// only contract is the state key and these fields.
+interface HeaderAction {
+	id: string
+	icon: string
+	label: string
+	onSelect: () => void
+	order?: number
+}
+
+// Register the assistant launcher in the core's generic header-action registry.
+// Idempotent so a re-running plugin can't add a duplicate button.
+export function registerLauncherAction(onSelect: () => void): void {
+	const actions = useState<HeaderAction[]>(HEADER_ACTIONS_STATE_KEY, () => [])
+	if (actions.value.some((action) => action.id === LAUNCHER_ACTION_ID)) return
+	actions.value = [
+		...actions.value,
+		{
+			id: LAUNCHER_ACTION_ID,
+			icon: LAUNCHER_ICON,
+			label: launcherLabel(),
+			order: LAUNCHER_ORDER,
+			onSelect,
+		},
+	]
+}

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

@@ -0,0 +1,127 @@
+import { HOST_COMMAND_NAVIGATE_TYPE, LOG_PREFIX } from './constants'
+
+interface RouterLike {
+	push: (path: string) => unknown
+}
+
+/**
+ * The slice of the host's `useDmsDevReload()` composable this module needs:
+ * resolve `true` once the committed site layout serves `path`, `false` on
+ * timeout.
+ */
+export interface DevReloadWaiter {
+	awaitRoute: (path: string) => Promise<boolean>
+}
+
+export interface HostCommandContext {
+	router: RouterLike
+	devReload: DevReloadWaiter
+}
+
+export interface HostCommandNavigateMessage {
+	type: typeof HOST_COMMAND_NAVIGATE_TYPE
+	path: string
+}
+
+export type HostCommandMessage = HostCommandNavigateMessage
+
+export type HostCommandDispatcher = (raw: unknown) => void
+
+/**
+ * Commands run one at a time on `tail`. `nextPath` holds the newest navigation
+ * target still waiting for a slot, so a burst collapses into a single trip to
+ * the latest path instead of racing and landing on the oldest one.
+ */
+interface DispatcherState {
+	ctx: HostCommandContext
+	tail: Promise<void>
+	nextPath: string | null
+}
+
+type HostCommandHandler = (
+	msg: HostCommandMessage,
+	state: DispatcherState,
+) => void
+
+function enqueue(state: DispatcherState, job: () => Promise<void>): void {
+	state.tail = state.tail.then(job).catch((err: unknown) => {
+		console.error(`${LOG_PREFIX} host command failed`, err)
+	})
+}
+
+// The agent asks to navigate right after writing the page, while the host is
+// still re-registering modules: the route can be momentarily unserved and
+// pushing now would flash a 404. Wait for the committed layout to serve it.
+// Navigate whatever the wait reports — a lapsed deadline or a broken waiter
+// must not strand the user on the previous page; a genuinely missing page then
+// 404s as it did before.
+async function awaitRouteThenPush(
+	path: string,
+	ctx: HostCommandContext,
+): Promise<void> {
+	try {
+		await ctx.devReload.awaitRoute(path)
+	} catch (err: unknown) {
+		console.error(`${LOG_PREFIX} dev reload wait failed for ${path}`, err)
+	}
+	void ctx.router.push(path)
+}
+
+async function runNavigate(state: DispatcherState): Promise<void> {
+	const path = state.nextPath
+	// A newer navigate already claimed this slot's target: this one is superseded
+	// and must not drag the user back to the older path.
+	if (path === null) return
+	state.nextPath = null
+	await awaitRouteThenPush(path, state.ctx)
+}
+
+function handleNavigate(
+	msg: HostCommandMessage,
+	state: DispatcherState,
+): void {
+	if (msg.type !== HOST_COMMAND_NAVIGATE_TYPE) return
+	state.nextPath = msg.path
+	enqueue(state, () => runNavigate(state))
+}
+
+const COMMAND_HANDLERS: Record<string, HostCommandHandler> = {
+	[HOST_COMMAND_NAVIGATE_TYPE]: handleNavigate,
+}
+
+function isHostCommand(value: unknown): value is HostCommandMessage {
+	if (value === null || typeof value !== 'object') return false
+	const candidate = value as { type?: unknown }
+	return typeof candidate.type === 'string'
+}
+
+function parseRaw(raw: unknown): HostCommandMessage | null {
+	if (typeof raw !== 'string') return null
+	try {
+		const parsed = JSON.parse(raw) as unknown
+		if (!isHostCommand(parsed)) return null
+		return parsed
+	} catch {
+		return null
+	}
+}
+
+export function createHostCommandDispatcher(
+	ctx: HostCommandContext,
+): HostCommandDispatcher {
+	const state: DispatcherState = {
+		ctx,
+		tail: Promise.resolve(),
+		nextPath: null,
+	}
+	return (raw: unknown): void => {
+		const msg = parseRaw(raw)
+		if (msg === null) return
+		const handler = COMMAND_HANDLERS[msg.type]
+		if (handler === undefined) {
+			console.warn(`${LOG_PREFIX} unknown host command type=${msg.type}`)
+			return
+		}
+		handler(msg, state)
+	}
+}

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

@@ -0,0 +1,22 @@
+import { router } from '@inertiajs/vue3'
+import { HOST_NAVIGATION_COMPLETE_TYPE } from './constants'
+
+export interface HostNavigationCompleteMessage {
+	type: typeof HOST_NAVIGATION_COMPLETE_TYPE
+	path: string
+}
+
+interface InstallNavigationCompleteEmitterOptions {
+	send: (msg: HostNavigationCompleteMessage) => void
+}
+
+export function installNavigationCompleteEmitter(
+	options: InstallNavigationCompleteEmitterOptions,
+): () => void {
+	return router.on('navigate', (event) =>
+		options.send({
+			type: HOST_NAVIGATION_COMPLETE_TYPE,
+			path: new URL(event.detail.page.url, window.location.origin).pathname,
+		}),
+	)
+}

package/frontend-vue/app/runtime/overlay-prefs.ts

@@ -0,0 +1,89 @@
+import {
+	OVERLAY_PREFS_DEBOUNCE_MS,
+	OVERLAY_PREFS_STORAGE_KEY,
+} from './constants'
+
+export interface OverlayPrefs {
+	width: number
+	isOpen: boolean
+}
+
+let pendingTimer: ReturnType<typeof setTimeout> | null = null
+let pendingPrefs: OverlayPrefs | null = null
+
+function tryReadStorage(): string | null {
+	try {
+		return globalThis.localStorage.getItem(OVERLAY_PREFS_STORAGE_KEY)
+	} catch {
+		return null
+	}
+}
+
+function tryWriteStorage(payload: string): void {
+	try {
+		globalThis.localStorage.setItem(OVERLAY_PREFS_STORAGE_KEY, payload)
+	} catch {
+		return
+	}
+}
+
+function isFiniteNumber(value: unknown): value is number {
+	return typeof value === 'number' && Number.isFinite(value)
+}
+
+function isValidPrefs(value: unknown): value is OverlayPrefs {
+	if (value === null || typeof value !== 'object') return false
+	const candidate = value as Record<string, unknown>
+	if (!isFiniteNumber(candidate.width)) return false
+	if (typeof candidate.isOpen !== 'boolean') return false
+	return true
+}
+
+function parsePrefs(raw: string): OverlayPrefs | null {
+	try {
+		const parsed: unknown = JSON.parse(raw)
+		return isValidPrefs(parsed) ? parsed : null
+	} catch {
+		return null
+	}
+}
+
+export function readPrefs(): OverlayPrefs | null {
+	const raw = tryReadStorage()
+	if (raw === null) return null
+	return parsePrefs(raw)
+}
+
+function flushPending(): void {
+	if (pendingPrefs === null) return
+	tryWriteStorage(JSON.stringify(pendingPrefs))
+	pendingPrefs = null
+	pendingTimer = null
+}
+
+export function writePrefsDebounced(prefs: OverlayPrefs): void {
+	pendingPrefs = prefs
+	if (pendingTimer !== null) clearTimeout(pendingTimer)
+	pendingTimer = setTimeout(flushPending, OVERLAY_PREFS_DEBOUNCE_MS)
+}
+
+export function flushPrefsForTesting(): void {
+	if (pendingTimer !== null) {
+		clearTimeout(pendingTimer)
+		pendingTimer = null
+	}
+	flushPending()
+}
+
+export function resetPrefsForTesting(): void {
+	if (pendingTimer !== null) {
+		clearTimeout(pendingTimer)
+		pendingTimer = null
+	}
+	pendingPrefs = null
+	try {
+		globalThis.localStorage.removeItem(OVERLAY_PREFS_STORAGE_KEY)
+	} catch {
+		return
+	}
+}