@agent-native/core 0.146.7 → 0.147.0

package/dist/client/chat-first/surface-tabs.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from "@agent-native/toolkit/ui";
+import { IconFiles, IconGitCompare, IconMessageCircle, IconTerminal2, IconUsersGroup, IconWorld, IconX, } from "@tabler/icons-react";
+import { CHAT_FIRST_SURFACE_CATALOG, } from "../chat-first.js";
+import { cn } from "../utils.js";
+import { defaultChatFirstCopy } from "./copy.js";
+const ICONS = {
+    app: IconFiles,
+    browser: IconWorld,
+    terminal: IconTerminal2,
+    diff: IconGitCompare,
+    files: IconFiles,
+    "side-chat": IconMessageCircle,
+    agents: IconUsersGroup,
+};
+function SurfaceIcon({ kind }) {
+    const Icon = ICONS[kind];
+    return _jsx(Icon, { size: 14, "aria-hidden": "true" });
+}
+export function ChatFirstSurfaceTabs({ tabs, activeTabId, onActivate, onClose, onCloseOthers, onCloseToRight, onCloseAll, onOpenSurface, copy = defaultChatFirstCopy, }) {
+    return (_jsx(TooltipProvider, { delayDuration: 400, children: _jsx("div", { "data-chat-first-surface-tabs": true, className: "shrink-0 border-b border-border bg-card", children: tabs.length > 0 ? (_jsx("div", { className: "flex min-w-0 items-center gap-1 overflow-x-auto px-2 py-1.5", role: "tablist", "aria-label": copy("openSideSurfaces"), children: tabs.map((tab, index) => (_jsxs(ContextMenu, { children: [_jsx(ContextMenuTrigger, { asChild: true, children: _jsxs("div", { role: "tab", tabIndex: activeTabId === tab.id ? 0 : -1, "aria-selected": activeTabId === tab.id, "data-surface-tab-id": tab.id, "data-active": activeTabId === tab.id ? "true" : "false", className: cn("group flex h-8 min-w-0 max-w-48 shrink-0 items-center rounded-md text-xs transition-colors", activeTabId === tab.id
+                                    ? "bg-accent text-foreground"
+                                    : "text-muted-foreground hover:bg-accent hover:text-foreground"), onKeyDown: (event) => {
+                                    const nextIndex = event.key === "ArrowRight"
+                                        ? (index + 1) % tabs.length
+                                        : event.key === "ArrowLeft"
+                                            ? (index - 1 + tabs.length) % tabs.length
+                                            : event.key === "Home"
+                                                ? 0
+                                                : event.key === "End"
+                                                    ? tabs.length - 1
+                                                    : -1;
+                                    if (nextIndex < 0)
+                                        return;
+                                    event.preventDefault();
+                                    onActivate(tabs[nextIndex]);
+                                    requestAnimationFrame(() => {
+                                        document
+                                            .querySelector(`[data-chat-first-surface-tab-id="${CSS.escape(tabs[nextIndex].id)}"]`)
+                                            ?.focus();
+                                    });
+                                }, "data-chat-first-surface-tab-id": tab.id, onMouseDown: (event) => {
+                                    if (event.button === 1) {
+                                        event.preventDefault();
+                                        onClose(tab);
+                                    }
+                                }, title: tab.title, children: [_jsxs("button", { type: "button", className: "flex min-w-0 flex-1 items-center gap-1.5 truncate px-2 text-start", onClick: () => onActivate(tab), tabIndex: -1, children: [_jsx(SurfaceIcon, { kind: tab.kind }), _jsx("span", { className: "truncate", children: tab.title })] }), _jsx("button", { type: "button", className: "mr-1 flex size-5 shrink-0 items-center justify-center rounded text-muted-foreground/65 opacity-0 transition-opacity hover:bg-background/70 hover:text-foreground group-hover:opacity-100 focus-visible:opacity-100", "aria-label": copy("closeTab", { name: tab.title }), title: copy("closeTab", { name: tab.title }), onClick: (event) => {
+                                            event.stopPropagation();
+                                            onClose(tab);
+                                        }, children: _jsx(IconX, { size: 12, "aria-hidden": "true" }) })] }) }), _jsxs(ContextMenuContent, { children: [_jsx(ContextMenuItem, { onSelect: () => onClose(tab), children: copy("close") }), _jsx(ContextMenuItem, { disabled: tabs.length < 2, onSelect: () => onCloseOthers(tab), children: copy("closeOthers") }), _jsx(ContextMenuItem, { disabled: tabs[tabs.length - 1]?.id === tab.id, onSelect: () => onCloseToRight(tab), children: copy("closeToRight") }), _jsx(ContextMenuSeparator, {}), _jsx(ContextMenuItem, { onSelect: onCloseAll, children: copy("closeAll") })] })] }, tab.id))) })) : (_jsx("div", { className: "flex flex-col px-2 py-1", "data-surface-empty-state": true, "aria-label": copy("openSideSurfaces"), children: CHAT_FIRST_SURFACE_CATALOG.map((surface) => {
+                    const label = copy(`surface.${surface.kind}.label`);
+                    const reason = surface.availability === "deferred"
+                        ? copy(`surface.${surface.kind}.reason`)
+                        : copy(`surface.${surface.kind}.reason`);
+                    const isDeferred = surface.availability === "deferred";
+                    const row = (_jsxs("div", { className: cn("flex h-7 min-w-0 items-center gap-2 rounded px-2 text-xs transition-colors", surface.kind === "agents" && onOpenSurface
+                            ? "text-foreground hover:bg-accent"
+                            : isDeferred
+                                ? "text-muted-foreground/60"
+                                : "text-muted-foreground hover:bg-accent hover:text-foreground"), title: !isDeferred ? reason : undefined, "aria-label": `${label}: ${reason}`, children: [_jsx(SurfaceIcon, { kind: surface.kind }), _jsx("span", { className: "min-w-0 flex-1 truncate", children: label }), isDeferred ? (_jsx("span", { "data-surface-availability": "deferred", className: "size-1.5 shrink-0 rounded-full bg-muted-foreground/45", "aria-label": copy("deferred") })) : null] }));
+                    if (surface.kind === "agents" && onOpenSurface) {
+                        return (_jsx("button", { type: "button", className: "text-start", title: copy("openActivity"), "aria-label": copy("openActivity"), onClick: () => onOpenSurface(surface.kind), children: row }, surface.kind));
+                    }
+                    if (!isDeferred)
+                        return _jsx("div", { children: row }, surface.kind);
+                    return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("div", { className: "text-start", children: row }) }), _jsx(TooltipContent, { side: "left", className: "max-w-72", children: reason })] }, surface.kind));
+                }) })) }) }));
+}
+export function ChatFirstSurfaceContent({ tabs, activeTabId, renderTab, }) {
+    return (_jsx("div", { className: "min-h-0 flex-1 overflow-hidden", children: tabs.map((tab) => {
+            const active = tab.id === activeTabId;
+            return (_jsx("div", { "data-chat-first-surface-content": tab.id, "aria-hidden": !active, className: cn("h-full min-h-0", !active && "hidden"), children: renderTab(tab) }, tab.id));
+        }) }));
+}

package/dist/client/chat-first/types.d.ts

@@ -0,0 +1,74 @@
+import type { ReactNode } from "react";
+import type { ChatFirstAgentActivity, ChatFirstAppLayoutPreference, ChatFirstSessionReference, ChatFirstSurfaceKind, ChatFirstSurfaceTab } from "../chat-first.js";
+export type { ChatFirstAgentActivity, ChatFirstSurfaceTab };
+export interface ChatFirstAppItem {
+    id: string;
+    name: string;
+    icon?: string;
+    color?: string;
+}
+export type ChatFirstCopy = (key: string, values?: Record<string, string>) => string;
+export interface ChatFirstEmbedTarget {
+    url: string;
+    title?: string;
+    key?: string | number;
+}
+export interface ChatFirstAppPaneProps {
+    app: ChatFirstAppItem | null;
+    status: "loading" | "ready" | "unresolved" | "error";
+    embedUrl?: string | null;
+    errorMessage?: string | null;
+    onRetry?: () => void;
+    renderEmbed: (target: ChatFirstEmbedTarget) => ReactNode;
+    copy?: ChatFirstCopy;
+}
+export interface ChatFirstSurfaceTabsProps {
+    tabs: ChatFirstSurfaceTab[];
+    activeTabId: string | null;
+    onActivate: (tab: ChatFirstSurfaceTab) => void;
+    onClose: (tab: ChatFirstSurfaceTab) => void;
+    onCloseOthers: (tab: ChatFirstSurfaceTab) => void;
+    onCloseToRight: (tab: ChatFirstSurfaceTab) => void;
+    onCloseAll: () => void;
+    onOpenSurface?: (kind: ChatFirstSurfaceKind) => void;
+    copy?: ChatFirstCopy;
+}
+export interface ChatFirstAppRailProps {
+    apps: readonly ChatFirstAppItem[];
+    activeAppId?: string;
+    loading?: boolean;
+    error?: string | null;
+    collapsed?: boolean;
+    layout?: ChatFirstAppLayoutPreference;
+    onLayoutChange?: (layout: ChatFirstAppLayoutPreference) => void;
+    onLayoutError?: (reason: "unavailable" | "write-failed") => void;
+    onRetry?: () => void;
+    onOpenApp: (app: ChatFirstAppItem) => void;
+    onCreateApp?: () => void;
+    createAppTrigger?: ReactNode;
+    renderIcon: (app: ChatFirstAppItem) => ReactNode;
+    copy?: ChatFirstCopy;
+}
+export interface ChatFirstBrowserPaneProps {
+    url: string;
+    title?: string;
+    status?: "starting" | "ready" | "error";
+    statusMessage?: string;
+    onClose: () => void;
+    renderEmbed: (target: ChatFirstEmbedTarget) => ReactNode;
+    copy?: ChatFirstCopy;
+}
+export interface ChatFirstSessionWatchPaneProps {
+    target: ChatFirstSessionReference | null;
+    onClose: () => void;
+    renderChat: (target: ChatFirstSessionReference) => ReactNode;
+    copy?: ChatFirstCopy;
+}
+export interface ChatFirstAgentsPaneProps {
+    activities: readonly ChatFirstAgentActivity[];
+    loading?: boolean;
+    error?: string | null;
+    onRefresh?: () => void;
+    onWatch: (activity: ChatFirstAgentActivity) => void;
+    copy?: ChatFirstCopy;
+}

package/dist/client/chat-first/types.js

@@ -0,0 +1 @@
+export {};

package/dist/client/chat-first-agent-activity.d.ts

@@ -0,0 +1,11 @@
+import type { ChatFirstAgentActivity } from "./chat-first.js";
+import type { ChatFirstCopy } from "./chat-first/types.js";
+export interface ChatFirstAgentActivityPanelProps {
+    activities: readonly ChatFirstAgentActivity[];
+    loading?: boolean;
+    error?: string | null;
+    onRefresh?: () => void;
+    onWatch?: (activity: ChatFirstAgentActivity) => void;
+    copy?: ChatFirstCopy;
+}
+export declare function ChatFirstAgentActivityPanel({ activities, loading, error, onRefresh, onWatch, copy, }: ChatFirstAgentActivityPanelProps): import("react").JSX.Element;

package/dist/client/chat-first-agent-activity.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { IconAlertCircle, IconAsteriskSimple, IconCopy, IconDiamond, IconEye, IconFlower, IconHexagon, IconRosette, IconRefresh, IconSparkles, } from "@tabler/icons-react";
+import { useState } from "react";
+import { defaultChatFirstCopy } from "./chat-first/copy.js";
+import { writeClipboardText } from "./clipboard.js";
+import { cn } from "./utils.js";
+const STATUS_KEYS = {
+    queued: "agentActivityStatusQueued",
+    running: "agentActivityStatusRunning",
+    paused: "agentActivityStatusPaused",
+    "needs-approval": "agentActivityStatusNeedsApproval",
+    completed: "agentActivityStatusCompleted",
+    errored: "agentActivityStatusErrored",
+    recent: "agentActivityStatusRecent",
+    unknown: "agentActivityStatusUnknown",
+};
+const AGENT_GLYPHS = [
+    { icon: IconSparkles, color: "text-primary" },
+    { icon: IconFlower, color: "text-destructive" },
+    { icon: IconRosette, color: "text-accent-foreground" },
+    { icon: IconHexagon, color: "text-ring" },
+    { icon: IconDiamond, color: "text-primary/70" },
+    { icon: IconAsteriskSimple, color: "text-muted-foreground" },
+];
+function glyphForSession(sessionId) {
+    let hash = 0;
+    for (const character of sessionId) {
+        hash = (hash * 31 + character.codePointAt(0)) | 0;
+    }
+    return AGENT_GLYPHS[Math.abs(hash) % AGENT_GLYPHS.length];
+}
+export function ChatFirstAgentActivityPanel({ activities, loading = false, error = null, onRefresh, onWatch, copy = defaultChatFirstCopy, }) {
+    const [copiedSessionId, setCopiedSessionId] = useState(null);
+    async function copySessionId(sessionId) {
+        const copied = await writeClipboardText(sessionId);
+        if (!copied)
+            return;
+        setCopiedSessionId(sessionId);
+        window.setTimeout(() => {
+            setCopiedSessionId((current) => (current === sessionId ? null : current));
+        }, 1600);
+    }
+    const statusLabel = (status) => copy(STATUS_KEYS[status]);
+    return (_jsxs("section", { className: "flex min-h-0 flex-col overflow-auto px-3 pb-3 pt-2", "data-chat-first-agents-surface": true, "aria-label": copy("agentsTitle"), children: [_jsxs("header", { className: "flex min-h-7 items-center justify-between gap-2 px-2", children: [_jsx("p", { className: "m-0 text-[11px] font-medium text-muted-foreground", children: copy("agentsTitle") }), onRefresh ? (_jsx("button", { type: "button", className: "flex size-6 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", onClick: onRefresh, "aria-label": copy("refreshAgentActivity"), title: copy("refreshAgentActivity"), children: _jsx(IconRefresh, { size: 15, "aria-hidden": "true" }) })) : null] }), error ? (_jsxs("div", { className: "flex items-center gap-1.5 px-2 py-2 text-[11px] text-destructive", role: "alert", "data-chat-first-agents-error": true, children: [_jsx(IconAlertCircle, { size: 15, "aria-hidden": "true" }), _jsx("span", { children: error }), onRefresh ? (_jsx("button", { type: "button", className: "font-semibold underline underline-offset-2", onClick: onRefresh, children: copy("retry") })) : null] })) : null, loading && activities.length === 0 ? (_jsx("div", { className: "grid min-h-0 gap-px", "aria-busy": "true", children: Array.from({ length: 4 }, (_, index) => (_jsxs("div", { className: "flex h-7 items-center gap-2 px-2", children: [_jsx("span", { className: "size-3 animate-pulse rounded-full bg-muted" }), _jsx("span", { className: "h-2.5 w-28 animate-pulse rounded bg-muted" })] }, index))) })) : activities.length === 0 ? (_jsx("p", { className: "m-0 px-2 py-3 text-[11px] text-muted-foreground", children: copy("noAgentSessions") })) : (_jsx("div", { className: "grid min-h-0 gap-px", children: activities.map((activity) => {
+                    const { icon: AgentGlyph, color } = glyphForSession(activity.sessionId);
+                    const copied = copiedSessionId === activity.sessionId;
+                    return (_jsxs("div", { className: "group flex min-h-7 items-center gap-2 rounded-md px-2 py-0.5 transition-colors hover:bg-accent/50 focus-within:bg-accent/50", children: [_jsx(AgentGlyph, { size: 14, strokeWidth: 1.9, "aria-hidden": "true", className: cn("shrink-0", color) }), _jsx("strong", { className: "min-w-0 flex-1 truncate text-[12px] font-medium text-foreground", title: activity.title, children: activity.title }), _jsx("span", { className: "shrink-0 text-[10px] text-muted-foreground group-hover:hidden group-focus-within:hidden", children: statusLabel(activity.status) }), _jsxs("div", { className: "ms-auto flex shrink-0 items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 group-focus-within:opacity-100", children: [onWatch ? (_jsx("button", { type: "button", onClick: () => onWatch(activity), className: "flex size-6 items-center justify-center rounded text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": copy("watchSession"), title: copy("watchSession"), children: _jsx(IconEye, { size: 14, "aria-hidden": "true" }) })) : null, _jsx("button", { type: "button", onClick: () => void copySessionId(activity.sessionId), className: "flex size-6 items-center justify-center rounded text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", "aria-label": copy("copySessionIdFor", {
+                                            name: activity.title,
+                                        }), title: copied ? copy("sessionIdCopied") : copy("copySessionId"), children: _jsx(IconCopy, { size: 14, "aria-hidden": "true" }) })] })] }, activity.sessionId));
+                }) }))] }));
+}

package/dist/client/chat-first-surface-panel-toggle.d.ts

@@ -0,0 +1,5 @@
+export declare function ChatFirstSurfacePanelToggle({ open, onToggle, className, }: {
+    open: boolean;
+    onToggle: () => void;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/client/chat-first-surface-panel-toggle.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { IconLayoutSidebarRightCollapse } from "@tabler/icons-react";
+import { cn } from "./utils.js";
+export function ChatFirstSurfacePanelToggle({ open, onToggle, className, }) {
+    return (_jsx("button", { type: "button", className: cn("flex size-7 items-center justify-center rounded-md border border-border bg-card/95 text-muted-foreground shadow-sm transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", className), "data-chat-first-surface-toggle": true, "aria-label": open ? "Hide side surface" : "Show side surface", "aria-pressed": open, title: `${open ? "Hide" : "Show"} side surface · ⌘⌥B`, onClick: onToggle, children: _jsx(IconLayoutSidebarRightCollapse, { size: 15, "aria-hidden": "true" }) }));
+}

package/dist/client/chat-first.d.ts

@@ -0,0 +1,208 @@
+export declare const CHAT_FIRST_MODE_STORAGE_KEY = "agent-native:chat-first-mode:v1";
+export declare const CHAT_FIRST_APP_LAYOUT_STORAGE_KEY = "agent-native:chat-first-app-layout:v1";
+export declare const CHAT_FIRST_SURFACE_TABS_STORAGE_KEY = "agent-native:chat-first-surface-tabs:v1";
+export declare const CHAT_FIRST_SURFACE_WIDTH_STORAGE_KEY = "agent-native:chat-first-surface-width:v2";
+export declare const CHAT_FIRST_SURFACE_PANEL_STORAGE_KEY = "agent-native:chat-first-surface-panel:v1";
+export declare const CHAT_FIRST_MODE_CHANGED_EVENT = "agentNative:chatFirstModeChanged";
+export declare const CHAT_FIRST_OPEN_APP_EVENT = "agentNative:openApp";
+export declare const CHAT_FIRST_OPEN_BROWSER_EVENT = "agentNative:openBrowser";
+export declare const CHAT_FIRST_WATCH_SESSION_EVENT = "agentNative:watchSession";
+export type ChatFirstOpenAppDetail = {
+    app?: string;
+    path?: string;
+    url?: string;
+    view?: string;
+};
+export type ChatFirstOpenBrowserDetail = {
+    url?: string;
+    title?: string;
+};
+export type ChatFirstSessionKind = "code-agent" | "agent-chat" | "external";
+export interface ChatFirstSessionReference {
+    sessionId: string;
+    title?: string;
+    kind?: ChatFirstSessionKind;
+    goalId?: string;
+    sourceSessionId?: string;
+}
+export type ChatFirstSessionWatchState = {
+    target: ChatFirstSessionReference | null;
+};
+export interface ChatFirstSessionWatchStore {
+    getSnapshot: () => ChatFirstSessionWatchState;
+    subscribe: (listener: () => void) => () => void;
+    hasSubscribers: () => boolean;
+    open: (target: ChatFirstSessionReference) => void;
+    close: () => void;
+}
+export type ChatFirstSurfaceKind = "app" | "browser" | "terminal" | "diff" | "files" | "side-chat" | "agents";
+export interface ChatFirstSurfaceTab {
+    id: string;
+    kind: ChatFirstSurfaceKind;
+    title: string;
+    appId?: string;
+    path?: string;
+    view?: string;
+    url?: string;
+    session?: ChatFirstSessionReference;
+    disabledReason?: string;
+}
+export type ChatFirstAgentActivityStatus = "queued" | "running" | "paused" | "needs-approval" | "completed" | "errored" | "recent" | "unknown";
+/** The renderer-neutral subset used by the shared agent activity surface. */
+export interface ChatFirstAgentActivity {
+    sessionId: string;
+    title: string;
+    subtitle?: string;
+    status: ChatFirstAgentActivityStatus;
+    updatedAt?: string | number;
+    progressPercent?: number;
+    goalId?: string;
+}
+export interface ChatFirstSurfaceTabsState {
+    tabs: ChatFirstSurfaceTab[];
+    activeTabId: string | null;
+}
+export interface ChatFirstSurfaceTabsStore {
+    getSnapshot: () => ChatFirstSurfaceTabsState;
+    subscribe: (listener: () => void) => () => void;
+    open: (tab: ChatFirstSurfaceTab) => void;
+    activate: (tabId: string) => void;
+    close: (tabId: string) => void;
+    closeOthers: (tabId: string) => void;
+    closeToRight: (tabId: string) => void;
+    closeAll: () => void;
+}
+export interface ChatFirstSurfacePanelState {
+    open: boolean;
+}
+export interface ChatFirstSurfacePanelStore {
+    getSnapshot: () => ChatFirstSurfacePanelState;
+    subscribe: (listener: () => void) => () => void;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+}
+export declare const CHAT_FIRST_SURFACE_CATALOG: readonly {
+    kind: ChatFirstSurfaceKind;
+    label: string;
+    description: string;
+    availability: "both" | "desktop" | "deferred";
+    disabledReason?: string;
+}[];
+export declare function chatFirstSurfaceTabId(kind: ChatFirstSurfaceKind, value: string): string;
+export declare const CHAT_FIRST_SURFACE_WIDTH_DEFAULT = 380;
+export declare const CHAT_FIRST_SURFACE_WIDTH_MIN = 320;
+/**
+ * The first-run rail is intentionally opinionated. These are the five
+ * everyday workspace apps shown before the user expands the rest of the
+ * catalog; an explicit ordered layout still wins after the first change.
+ */
+export declare const CHAT_FIRST_DEFAULT_APP_IDS: readonly ["content", "design", "mail", "calendar", "clips"];
+export declare function clampChatFirstSurfaceWidth(value: number, viewportWidth?: number): number;
+export declare function readChatFirstSurfaceWidth(scope?: string, storage?: StringStorage | null): number;
+export declare function writeChatFirstSurfaceWidth(width: number, scope?: string, storage?: StringStorage | null): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unavailable" | "write-failed";
+};
+export declare function useChatFirstSurfaceResize(scope?: string): {
+    width: number;
+    isResizing: boolean;
+    onPointerDown: (event: {
+        clientX: number;
+        preventDefault: () => void;
+    }) => void;
+};
+export declare function getChatFirstSurfacePanelStore(scope?: string): ChatFirstSurfacePanelStore;
+export declare function useChatFirstSurfacePanel(scope?: string): {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+};
+export interface ChatFirstSessionWatchDelivery {
+    delivered: boolean;
+    reason?: "empty-detail" | "no-listener";
+}
+export type ChatFirstBrowserResolution = {
+    status: "ready";
+    target: {
+        url: string;
+        title?: string;
+    };
+} | {
+    status: "unresolved";
+    reason: "empty-detail" | "invalid-url";
+};
+export interface ChatFirstAppRegistration {
+    id: string;
+    name?: string;
+    enabled?: boolean;
+    /** The app's current production or mounted URL. */
+    url?: string | null;
+    /** Optional local development URL used by the desktop shell. */
+    devUrl?: string | null;
+    /** Mounted path used when an app has no absolute URL. */
+    path?: string | null;
+}
+export interface ChatFirstAppTarget {
+    appId: string;
+    path?: string;
+    view?: string;
+}
+export type ChatFirstAppResolution = {
+    status: "ready";
+    target: ChatFirstAppTarget;
+} | {
+    status: "unresolved";
+    reason: "empty-detail" | "unknown-app" | "invalid-url";
+};
+export interface ChatFirstOpenAppDelivery {
+    delivered: boolean;
+    reason?: "empty-detail" | "no-listener";
+}
+export interface ChatFirstAppLayoutPreference {
+    pinnedIds: string[];
+    orderedIds: string[];
+}
+export interface ChatFirstModeReadResult {
+    enabled: boolean;
+    availability: "available" | "unavailable";
+}
+type StringStorage = Pick<Storage, "getItem" | "setItem">;
+export declare function readChatFirstModeState(storage?: StringStorage | null): ChatFirstModeReadResult;
+export declare function readChatFirstMode(storage?: StringStorage | null): boolean;
+export declare function writeChatFirstMode(enabled: boolean, storage?: StringStorage | null): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unavailable" | "write-failed";
+};
+export declare function readChatFirstAppLayout(storage?: StringStorage | null): ChatFirstAppLayoutPreference;
+export declare function writeChatFirstAppLayout(layout: ChatFirstAppLayoutPreference, storage?: StringStorage | null): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unavailable" | "write-failed";
+};
+export declare function orderChatFirstAppIds(appIds: readonly string[], layout: ChatFirstAppLayoutPreference): string[];
+export declare function resolveChatFirstBrowserTarget(detail: ChatFirstOpenBrowserDetail): ChatFirstBrowserResolution;
+type ChatFirstOpenAppListener = (detail: ChatFirstOpenAppDetail) => void;
+type ChatFirstOpenBrowserListener = (detail: ChatFirstOpenBrowserDetail) => void;
+/** Resolve ids from run/thread payloads without treating an absent id as a session. */
+export declare function resolveChatFirstSessionId(value: unknown): string | null;
+export declare function normalizeChatFirstSessionReference(value: unknown): ChatFirstSessionReference | null;
+export declare function getChatFirstSessionWatchStore(): ChatFirstSessionWatchStore;
+export declare function useChatFirstSessionWatch(): ChatFirstSessionWatchState;
+export declare function subscribeChatFirstSessionWatch(listener: (target: ChatFirstSessionReference) => void): () => void;
+export declare function emitChatFirstSessionWatch(detail: unknown): ChatFirstSessionWatchDelivery;
+export declare function closeChatFirstSessionWatch(): void;
+export declare function getChatFirstSurfaceTabsStore(scope?: string): ChatFirstSurfaceTabsStore;
+export declare function useChatFirstSurfaceTabs(scope?: string): ChatFirstSurfaceTabsState;
+export declare function subscribeChatFirstOpenApp(listener: ChatFirstOpenAppListener): () => void;
+export declare function emitChatFirstOpenApp(detail: ChatFirstOpenAppDetail): ChatFirstOpenAppDelivery;
+export declare function subscribeChatFirstOpenBrowser(listener: ChatFirstOpenBrowserListener): () => void;
+export declare function emitChatFirstOpenBrowser(detail: ChatFirstOpenBrowserDetail): ChatFirstOpenAppDelivery;
+export declare function resolveChatFirstAppTarget(detail: ChatFirstOpenAppDetail, apps: readonly ChatFirstAppRegistration[], options?: {
+    currentOrigin?: string;
+}): ChatFirstAppResolution;
+export {};