@qilin-agent/client-ui-workspace 0.0.0-stage → 3.1.4

package/lib/index.js

@@ -0,0 +1,11 @@
+//#region lib/types/index.js
+/**
+* Workspace picker plugin, node half. Pure UI plugin: the empty apply exists
+* so the plugin appears in the host cordis.yml / Loader (load and lifecycle
+* follow the host; the browser half ships via exports["./client"], discovered
+* through the package.json qilin.client declaration).
+*/
+/** Host plugin body — no host-side behavior for the workspace picker plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/WorkspacePicker.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace pick/add flow. WorkspacePickFlow is the reusable core (menu +
+ * path error dialog) consumed directly by WorkspaceBrowser (same package) and
+ * wrapped by WorkspacePicker for the conversation empty-state slot
+ * registration. Directory picking itself lives in the composed flow package's
+ * slot occupant (see the contract module doc): this core only opens the flow,
+ * adopts the picked path, and owns the error surface. Adding a workspace has
+ * exactly one route — pick a host directory, new or existing — because the
+ * occupant's own create-folder affordance already covers creating one.
+ */
+import type { ReactNode, RefObject } from 'react';
+import type { WorkspaceId, WorkspaceSnapshot, WorkspaceView } from '@qilin-agent/api-workspace-controller/client';
+import type { SnapshotSelectorHook } from '@qilin-agent/client-ui-slots';
+import type { DirectoryFlowOwnerProps, WorkspacePickerProps } from './contract/slots.ts';
+/** Core flow props: the owner supplies popover control and pick semantics. */
+export interface WorkspacePickFlowProps {
+    /** The standard locale seat, forwarded by whichever slot entry hosts the flow. */
+    t: WorkspacePickerProps['t'];
+    /** Popover visibility (anchor button toggle state, owner-local). */
+    open: boolean;
+    /** The anchor button element — the popover's placement anchor. */
+    anchorRef?: RefObject<HTMLElement | null> | undefined;
+    /** Selector hook over the workspace list (framework standard hook). */
+    useWorkspaces: <S>(selector: (state: WorkspaceSnapshot) => S) => S;
+    /** Adopt a picked host directory as a real Workspace. */
+    createWorkspace: (input: {
+        path: string;
+    }) => Promise<WorkspaceView>;
+    /** Bound occupancy selector hook for this surface's directory-flow hole (empty leaves the surface with no add action). */
+    useDirectoryFlow: SnapshotSelectorHook<boolean>;
+    /** Render this surface's directory-flow hole with the owner conversation (the entry's narrowed renderSlot). */
+    renderDirectoryFlow: (owner: DirectoryFlowOwnerProps) => ReactNode;
+    /** A real Workspace was picked or created. */
+    onPick: (workspaceId: WorkspaceId) => void;
+    /** Close the popover (outside click / Escape / post-pick). */
+    onClose: () => void;
+    /** Only offer the add action, hide existing workspaces. */
+    addOnly?: boolean;
+    /** Menu opening direction relative to the anchor. */
+    side?: 'bottom' | 'top' | 'right';
+    /** Currently active workspace (trailing check in the picker list). */
+    selectedId?: WorkspaceId | undefined;
+}
+/**
+ * Render the pick menu plus the adoption error dialog.
+ * @param props - owner-controlled flow props.
+ * @returns menu + dialog elements.
+ */
+export declare function WorkspacePickFlow({ t, open, anchorRef, useWorkspaces, createWorkspace, useDirectoryFlow, renderDirectoryFlow, onPick, onClose, addOnly, side, selectedId, }: WorkspacePickFlowProps): import("react").JSX.Element;
+/**
+ * The conversation empty-state registration: adapts the owner share to the
+ * core flow (all state and semantics live in the flow / the owner).
+ * @param props - empty-state slot props (owner share + injected creation callback).
+ * @returns the flow element.
+ */
+export declare function WorkspacePicker({ open, anchorRef, useWorkspaces, selectedId, onPick, onClose, createWorkspace, useDirectoryFlow, renderSlot, t, }: WorkspacePickerProps): import("react").JSX.Element;
+//# sourceMappingURL=WorkspacePicker.d.ts.map

package/lib/types/client/contract/slots.d.ts

@@ -0,0 +1,213 @@
+/**
+ * ui-workspace contracts. Two registrations share this package:
+ *
+ * - WorkspaceBrowser fills the sidebar shell's `sidebar.workspaces` hole —
+ *   the whole browsing region (section header, search, grouped/flat session
+ *   list, workspace dialogs). It registers this package's viewing store and
+ *   consumes the shell's two-fact owner share (wide / expandSidebar).
+ * - WorkspacePicker fills the conversation empty-state hole (menu + error
+ *   dialog shared with the browser).
+ *
+ * Each registration also declares one **directory-flow hole** (`single`
+ * kind): the slot a composed picker package's client half fills with its
+ * picking interaction — a renderless native-chooser driver or an in-app
+ * browsing dialog. ui-workspace owns the trigger (the "Add workspace…"
+ * entry, present only while the hole is occupied) and the adoption
+ * semantics (`createWorkspace({ path })`, the retryable error dialog,
+ * Choose again); the occupant owns everything between `open` and the picked path,
+ * including creating a new directory to hand back. That occupant-owned
+ * creation is why adding a workspace has a single route: an unoccupied hole
+ * leaves the surface with no add affordance at all.
+ * Two holes exist because the two menu surfaces are independent slot entries
+ * and a hole has exactly one declaring entry — they carry the same owner
+ * contract and the same occupant.
+ */
+import type { HostObservable, PropsHooks, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { SessionSearchResultItem } from '@qilin-agent/api-session-controller/client';
+import type { RemoteHostFacts } from '@qilin-agent/api-remotes/client';
+import type { WorkspaceId, WorkspaceView } from '@qilin-agent/api-workspace-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { createWorkspaceViewStore } from '../stores.ts';
+import type { ShortcutCatalogEntry } from '@qilin-agent/client-shortcuts/client';
+import type { WorkspaceShortcutState } from '../shortcuts.ts';
+/**
+ * Owner share of the directory-flow holes: the complete conversation between
+ * the trigger surface and the picking interaction. The occupant reads `open`
+ * to run/render its interaction and reports exactly one outcome per open.
+ */
+export interface DirectoryFlowOwnerProps {
+    /** True while a picking interaction is requested; flipping back to false withdraws the request. */
+    open: boolean;
+    /** True while the owner adopts a picked path (`createWorkspace` in flight); occupants disable their commit affordances. */
+    busy: boolean;
+    /** The operator picked a directory (absolute host path); the owner adopts it. */
+    onPicked: (path: string) => void;
+    /** The operator dismissed the interaction; the owner just closes the flow. */
+    onCancel: () => void;
+    /** The interaction itself failed (chooser missing, listing denied); the owner shows its error surface. */
+    onError: (message: string) => void;
+}
+/**
+ * Owner share of the two Session-row schedule seats. Both receive only the
+ * row's Session identity: the occupant reads that Session's own scheduled
+ * tasks, and reading them activates nothing.
+ */
+export interface SessionRowScheduleOwnerProps {
+    /** Session this row shows; the occupant addresses its own data by this id. */
+    readonly sessionId: SessionId;
+}
+declare module '@qilin-agent/client-ui-slots' {
+    interface SlotMap {
+        /** Directory-flow hole under the conversation empty-state picker (declared by the WorkspacePicker entry). */
+        'conversation.hero.workspace.directoryFlow': {
+            kind: 'single';
+            scope: 'root';
+            owner: DirectoryFlowOwnerProps;
+        };
+        /** Directory-flow hole under the sidebar browsing region (declared by the WorkspaceBrowser entry). */
+        'sidebar.workspaces.directoryFlow': {
+            kind: 'single';
+            scope: 'root';
+            owner: DirectoryFlowOwnerProps;
+        };
+        /**
+         * Leading decoration of one Session row, in the 16px cell before the title
+         * that the row's own state dot otherwise occupies. A higher-priority state
+         * (a pending interaction, a new message, live activity) replaces the seat
+         * with that dot for the same row, so an occupant here never renders beside
+         * a status dot and is mounted only by a row whose primary state is idle.
+         * An archived row keeps that cell blank — neither its status dot nor this
+         * seat renders there, and its live status appears on the hover card only.
+         */
+        'sidebar.session.row.leading': {
+            kind: 'list';
+            scope: 'root';
+            owner: SessionRowScheduleOwnerProps;
+        };
+        /**
+         * Section of the Session row's hover card between its relative time and
+         * its trailing status line. Mounted only while that card is open.
+         */
+        'sidebar.session.row.hover': {
+            kind: 'list';
+            scope: 'root';
+            owner: SessionRowScheduleOwnerProps;
+        };
+    }
+}
+/** The two directory-flow holes; a flow package's client half registers its one component into both. */
+export type DirectoryFlowSlotName = 'conversation.hero.workspace.directoryFlow' | 'sidebar.workspaces.directoryFlow';
+/**
+ * Directory-picking share both trigger surfaces consume. Occupancy rides the
+ * inject face's reserved `hooks` compartment: the renderer binds the source
+ * into the `useDirectoryFlow` selector hook, so an empty hole hides the
+ * "Add workspace…" entry reactively and the surface withdraws an open
+ * flow whose occupant unloaded mid-interaction (nobody is left to cancel).
+ */
+export type DirectoryPickingInjected = {
+    hooks: {
+        /** True while this surface's directory-flow hole is occupied. */
+        directoryFlow: HostObservable<boolean>;
+    };
+};
+/** Component-side view of the picking share: the bound occupancy selector hook. */
+export type DirectoryPickingHooks = PropsHooks<DirectoryPickingInjected['hooks']>;
+/**
+ * Browser-private injected share (arrives via the register inject factory).
+ * Data reads use the global framework hooks; these are the Host actions the
+ * browsing region drives.
+ */
+export type WorkspaceBrowserInjected = {
+    hooks: DirectoryPickingInjected['hooks'] & {
+        /**
+         * Fixed Host facts, reached through a hook rather than injected as values:
+         * the renderer memoizes an entry's inject result for the registration's
+         * lifetime, so facts read there would freeze at whatever the first render
+         * saw. Select the field the surface needs (`info => info.home`).
+         */
+        hostInfo: HostObservable<RemoteHostFacts>;
+        /** Keyboard-command opening requests the browser consumes. */
+        workspaceShortcuts: HostObservable<WorkspaceShortcutState>;
+        /** Effective command catalog for row shortcut hints. */
+        shortcuts: HostObservable<readonly ShortcutCatalogEntry[]>;
+    };
+    /** Open the browser search and focus its input. */
+    requestSearch: () => void;
+    /** Request the existing directory picker. */
+    requestAddWorkspace: () => void;
+    /** Consume the directory-picker opening request. */
+    closeAddWorkspace: () => void;
+    /** Consume the rename-dialog opening request. */
+    closeRenameRequest: () => void;
+    /** Publish directory interaction occupancy for command availability. */
+    setDirectoryBusy: (busy: boolean) => void;
+    /**
+     * Start a New Session in a Workspace: reuse-or-create its blank session and
+     * open it; without an explicit workspace, inherit the current Session
+     * Workspace, then the recent Workspace, or clear into the New Session view.
+     */
+    startSession: (workspaceId?: WorkspaceId) => void;
+    /** Open a real Session. */
+    open: (sessionId: SessionId) => void;
+    /**
+     * Search current visible conversation messages. The Host fixes the result
+     * bound; `hasMore` means the query needs narrowing.
+     */
+    searchSessions: (query: string, signal: AbortSignal) => Promise<{
+        items: readonly SessionSearchResultItem[];
+        hasMore: boolean;
+    }>;
+    /** Maximum number of merged rows rendered for one search. */
+    searchResultLimit: number;
+    /** Rename a Session (explicit user title; resolves on host acceptance). */
+    renameSession: (sessionId: SessionId, title: string) => Promise<void>;
+    /** Fork a Session at its last completed turn and open the child. */
+    forkSession: (sessionId: SessionId) => void;
+    /** Rename a Host Workspace (rejects on name conflict; resolves on durability). */
+    renameWorkspace: (workspaceId: WorkspaceId, title: string) => Promise<void>;
+    /** Delete only a Host Workspace registration; directory and Session logs remain. */
+    deleteWorkspace: (workspaceId: WorkspaceId) => Promise<void>;
+    /**
+     * Reorder a Workspace in the durable registry display order.
+     * Omitted anchor appends to the end.
+     */
+    insertWorkspaceBefore: (workspaceId: WorkspaceId, beforeWorkspaceId?: WorkspaceId) => Promise<void>;
+    /**
+     * Archive a Session into the registry-global set: hidden from grouping
+     * surfaces, log and accounting slot retained. Archiving the current
+     * session clears the selection into the New Session view state.
+     */
+    archiveSession: (sessionId: SessionId) => Promise<void>;
+    /**
+     * Pin a Session ahead of unpinned ones in its group and the flat list, and
+     * front its saved manual position. Rejects on Host failure so the caller
+     * can report it.
+     */
+    pinSession: (sessionId: SessionId) => Promise<void>;
+    /** Drop one Session's pin; saved positions stay as they are. */
+    unpinSession: (sessionId: SessionId) => Promise<void>;
+    /** Adopt a picked host directory as a real Workspace before targeting a Session. */
+    createWorkspace: (input: {
+        path: string;
+    }) => Promise<WorkspaceView>;
+};
+/** Full browser props: shell owner share + viewing store + injected actions + the locale seat. */
+export type WorkspaceBrowserProps = PropsRuntime<'sidebar.workspaces'> & PropsRenderSlots<'sidebar.workspaces.directoryFlow' | 'sidebar.session.row.leading' | 'sidebar.session.row.hover'> & PropsStore<ReturnType<typeof createWorkspaceViewStore>> & Omit<WorkspaceBrowserInjected, 'hooks'> & PropsHooks<WorkspaceBrowserInjected['hooks']> & PropsLocale<'workspace'>;
+/**
+ * Picker-private injected share. Pick semantics remain in the owner's onPick
+ * callback; this callback creates only the real Host Workspace. A type alias
+ * supplies the implicit index signature required by the registry.
+ */
+export type WorkspacePickerInjected = DirectoryPickingInjected & {
+    /** Adopt a picked host directory as a real Workspace before targeting a Session. */
+    createWorkspace: (input: {
+        path: string;
+    }) => Promise<WorkspaceView>;
+};
+/**
+ * Full picker props: the owner share plus the creation callback and the
+ * locale seat. The two picker holes (blank-session hero / New-Session view)
+ * share one owner currency, so one composed type serves both registrations.
+ */
+export type WorkspacePickerProps = PropsRuntime<'conversation.hero.workspace'> & PropsRenderSlots<'conversation.hero.workspace.directoryFlow'> & Omit<WorkspacePickerInjected, 'hooks'> & DirectoryPickingHooks & PropsLocale<'workspace'>;
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Workspace plugin, browser half. Two registrations: WorkspaceBrowser fills
+ * the sidebar shell's `sidebar.workspaces` hole (the whole browsing region),
+ * and WorkspacePicker fills the conversation hero's picker hole
+ * (`conversation.hero.workspace` — both hero forms). Both read real Host
+ * Workspaces through the global useWorkspaces hook, and each declares its
+ * own `single` directory-flow child hole for the composed picker package's
+ * client half (see the contract module doc). Export discipline:
+ * packages/client/AGENTS.md.
+ */
+import type { Context } from '@qilin-agent/kylin';
+import type { WorkspaceSnapshot } from '@qilin-agent/api-workspace-controller/client';
+import type { SnapshotSelectorHook } from '@qilin-agent/client-ui-slots';
+import { type WorkspaceKey } from './locales.ts';
+export type { MainSelection, UiWorkspace } from './navigation.ts';
+export type { DirectoryFlowOwnerProps, DirectoryFlowSlotName, DirectoryPickingHooks, DirectoryPickingInjected, SessionRowScheduleOwnerProps, WorkspaceBrowserInjected, WorkspaceBrowserProps, WorkspacePickerInjected, WorkspacePickerProps, } from './contract/slots.ts';
+export type { WorkspaceKey } from './locales.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface GlobalStandardProps {
+        /** Selector hook over the pure Workspace Controller snapshot. */
+        useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>;
+    }
+    interface LocaleNamespaceMap {
+        /** The workspace browsing region and pick/create flow copy. */
+        workspace: WorkspaceKey;
+    }
+}
+declare module '@qilin-agent/api-session-controller/client' {
+    interface SessionReferenceSourceMap {
+        workspaceOperation: unknown;
+    }
+}
+/**
+ * Required services (cordis fiber inject). The target slots are declared by
+ * the ui-sidebar / ui-conversation applies, whose activation order relative
+ * to this one is NOT constrained: qilin.client.inject edges are informational
+ * (loading/prefetch metadata, never apply sequencing) and neither owner
+ * provides a waitable service. apply therefore depends on each slot
+ * declaration through `slots.inject()` instead of assuming order.
+ */
+export declare const inject: string[];
+/**
+ * Register the browser and picker once their slot declarations are on the
+ * ledger. Inject factories return plain callbacks; data reads use the
+ * framework's global hooks.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `workspace` namespace dictionaries: the browsing region (section header,
+ * search, tree rows, dialogs) and the pick/add flow. Runtime failure
+ * messages (wire error strings) pass through untranslated by policy.
+ */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'group.ungrouped': string;
+    'session.new': string;
+    'session.untitled': string;
+    'shortcut.noSession': string;
+    'shortcut.noPicker': string;
+    'shortcut.directoryBusy': string;
+    'shortcut.noCompletedTurn': string;
+    'section.workspaces': string;
+    'section.sessions': string;
+    'viewOptions.label': string;
+    'groupBy.label': string;
+    'groupBy.workspace': string;
+    'groupBy.workspaceTree': string;
+    'groupBy.flat': string;
+    'orderBy.label': string;
+    'orderBy.manual': string;
+    'orderBy.updated': string;
+    'sessions.expand': string;
+    'sessions.collapse': string;
+    'empty.none': string;
+    'empty.noMatches': string;
+    'workspace.add': string;
+    'search.sessions.aria': string;
+    'search.placeholder': string;
+    'search.clear': string;
+    'search.results.aria': string;
+    'search.pending': string;
+    'search.unavailable': string;
+    'search.noMatches': string;
+    'search.hasMore': string;
+    'menu.addWorkspace': string;
+    'picker.loading': string;
+    'conflict.named': string;
+    'folderError.title': string;
+    'folderError.retry': string;
+    rename: string;
+    'rename.workspace.title': string;
+    'rename.session.title': string;
+    'field.workspaceName': string;
+    'field.sessionName': string;
+    'delete.workspace': string;
+    'delete.desc': string;
+    'delete.pending': string;
+    'menu.pinSession': string;
+    'menu.unpinSession': string;
+    'menu.fork': string;
+    'menu.archiveSession': string;
+    'row.pinned': string;
+    'sessions.count.one': string;
+    'sessions.count.other': string;
+    'actions.workspace.aria': string;
+    'actions.session.aria': string;
+    'actions.newSession.aria': string;
+    'actions.pin': string;
+    'actions.unpin': string;
+    'status.running': string;
+    'status.subagentsRunning.one': string;
+    'status.subagentsRunning.other': string;
+    'status.idle': string;
+    'status.waitingApproval': string;
+    'status.planReview': string;
+    'status.waitingAnswer': string;
+    'status.completed': string;
+    'hover.created': string;
+    'hover.copied': string;
+    'date.ymd': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': string;
+    'time.ago': string;
+};
+/** The workspace namespace key union. */
+export type WorkspaceKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'group.ungrouped': string;
+    'session.new': string;
+    'session.untitled': string;
+    'shortcut.noSession': string;
+    'shortcut.noPicker': string;
+    'shortcut.directoryBusy': string;
+    'shortcut.noCompletedTurn': string;
+    'section.workspaces': string;
+    'section.sessions': string;
+    'viewOptions.label': string;
+    'groupBy.label': string;
+    'groupBy.workspace': string;
+    'groupBy.workspaceTree': string;
+    'groupBy.flat': string;
+    'orderBy.label': string;
+    'orderBy.manual': string;
+    'orderBy.updated': string;
+    'sessions.expand': string;
+    'sessions.collapse': string;
+    'empty.none': string;
+    'empty.noMatches': string;
+    'workspace.add': string;
+    'search.sessions.aria': string;
+    'search.placeholder': string;
+    'search.clear': string;
+    'search.results.aria': string;
+    'search.pending': string;
+    'search.unavailable': string;
+    'search.noMatches': string;
+    'search.hasMore': string;
+    'menu.addWorkspace': string;
+    'picker.loading': string;
+    'conflict.named': string;
+    'folderError.title': string;
+    'folderError.retry': string;
+    rename: string;
+    'rename.workspace.title': string;
+    'rename.session.title': string;
+    'field.workspaceName': string;
+    'field.sessionName': string;
+    'delete.workspace': string;
+    'delete.desc': string;
+    'delete.pending': string;
+    'menu.pinSession': string;
+    'menu.unpinSession': string;
+    'menu.fork': string;
+    'menu.archiveSession': string;
+    'row.pinned': string;
+    'sessions.count.one': string;
+    'sessions.count.other': string;
+    'actions.workspace.aria': string;
+    'actions.session.aria': string;
+    'actions.newSession.aria': string;
+    'actions.pin': string;
+    'actions.unpin': string;
+    'status.running': string;
+    'status.subagentsRunning.one': string;
+    'status.subagentsRunning.other': string;
+    'status.idle': string;
+    'status.waitingApproval': string;
+    'status.planReview': string;
+    'status.waitingAnswer': string;
+    'status.completed': string;
+    'hover.created': string;
+    'hover.copied': string;
+    'date.ymd': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': string;
+    'time.ago': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/navigation.d.ts

@@ -0,0 +1,148 @@
+/** Workspace archive and directory UI capability. */
+import { Service, type Context } from '@qilin-agent/kylin';
+import type { ClientRemote, DirectoryListing, RemoteFailure } from '@qilin-agent/api-remotes/client';
+import type { ISessions, SessionTarget } from '@qilin-agent/api-session-controller/client';
+import { type ObservableSnapshot } from '@qilin-agent/client-store';
+import type { SubagentAddress } from '@qilin-agent/subagent/client';
+import type { IWorkspaces, WorkspaceId } from '@qilin-agent/api-workspace-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { WorkspaceViewStoreActions } from './stores.ts';
+/** The main-pane selection a navigation action publishes: one Session, or one direct-parent subagent address. */
+export interface MainSelection {
+    readonly sessionId?: SessionId;
+    readonly subagentAddress?: SubagentAddress;
+}
+/** Workspace archive and directory operations consumed by Client UI domains. */
+export interface UiWorkspace {
+    /**
+     * The persisted main-pane selection. The Session Controller owns the catalog and
+     * leaves view selection to navigation, so surfaces that need "the Session the
+     * shell is showing" read it here.
+     */
+    readonly selection: ObservableSnapshot<MainSelection>;
+    /**
+     * Select a Session and show its Conversation as one UI navigation action.
+     * @param target - known Session identity or durable direct-parent subagent address to display.
+     */
+    openSession(target: SessionTarget): void;
+    /**
+     * Connect a Workspace and open its Session unless a later navigation supersedes it.
+     * @param workspaceId - target Workspace.
+     * @param beforeOpen - optional synchronous preparation for the selected Session,
+     * skipped after supersession; a throw aborts the open and releases the retained reference.
+     * @returns completion; a superseded request may create a Session but does not open it.
+     */
+    openWorkspace(workspaceId: WorkspaceId, beforeOpen?: (sessionId: SessionId) => void): Promise<void>;
+    /**
+     * Fork a Session and open the child unless a later navigation supersedes it.
+     * @param sessionId - source Session.
+     * @returns completion; a superseded request leaves its child available without selecting it.
+     */
+    forkSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Resolve the reusable or newly created blank Session for a Workspace.
+     * @param workspaceId - target Workspace.
+     * @returns a Session already addressable through the Session Controller.
+     */
+    connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId>;
+    /**
+     * Start a New Session flow and navigate to its Session.
+     * @param workspaceId - explicit target; absent inherits the current or most recent Workspace.
+     */
+    startSession(workspaceId?: WorkspaceId): void;
+    /**
+     * Archive a Session and clear it when it is the current selection.
+     * @param sessionId - Session to archive.
+     */
+    archiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Unarchive a Session, restoring it to its recorded Workspace position.
+     * @param sessionId - Session to unarchive.
+     */
+    unarchiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Pin a Session on the Host and front its saved position in every account that owns it.
+     * @param sessionId - Session to pin.
+     */
+    pinSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Unpin a Session on the Host; saved positions stay as they are.
+     * @param sessionId - Session to unpin.
+     */
+    unpinSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Open the Host-native directory picker.
+     * @returns the selected directory, or null when cancelled.
+     */
+    pickDirectory(): Promise<string | null>;
+    /**
+     * List one Host directory level.
+     * @param path - directory path; absent selects the Host home.
+     * @param signal - cancellation for a superseded scan.
+     * @returns directory entries and breadcrumb ancestry.
+     */
+    listDirectory(path?: string, signal?: AbortSignal): Promise<DirectoryListing>;
+    /**
+     * Create a child directory.
+     * @param path - existing parent directory.
+     * @param name - child directory name.
+     * @returns created absolute path.
+     */
+    createDirectory(path: string, name: string): Promise<string>;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Cross-Controller Workspace navigation and directory UI capability. */
+        uiWorkspace: UiWorkspace;
+    }
+}
+/** Structured directory failure exposed to directory UI consumers. */
+export declare class DirectoryBrowseError extends Error {
+    readonly rpcError: RemoteFailure;
+    readonly name = "DirectoryBrowseError";
+    /** @param rpcError - Host directory business failure. */
+    constructor(rpcError: RemoteFailure);
+}
+/** Implements Workspace archive and directory UI operations. */
+declare class UiWorkspaceService extends Service implements UiWorkspace {
+    private readonly directoryPicker;
+    private readonly workspaces;
+    private readonly sessions;
+    private readonly view;
+    private readonly connecting;
+    private readonly lifetime;
+    /**
+     * The persisted main-pane selection. Published as the `mainSelection` root
+     * standard source, because the Session Controller owns the catalog and leaves
+     * view selection to navigation.
+     */
+    readonly selection: import("@qilin-agent/client-store").SnapshotStore<MainSelection>;
+    private mainReference;
+    /**
+     * @param ctx - Client root Context.
+     * @param directoryPicker - the directory-picking Remote namespace.
+     * @param workspaces - pure Workspace Controller.
+     * @param sessions - pure Session Controller.
+     * @param view - the browser's viewing-store write set, which owns saved Session order.
+     */
+    constructor(ctx: Context, directoryPicker: ClientRemote['directoryPicker'], workspaces: IWorkspaces, sessions: ISessions, view: Pick<WorkspaceViewStoreActions, 'pinSessionOrder'>);
+    connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId>;
+    openSession(target: SessionTarget): void;
+    openWorkspace(workspaceId: WorkspaceId, beforeOpen?: (sessionId: SessionId) => void): Promise<void>;
+    forkSession(sessionId: SessionId): Promise<void>;
+    startSession(workspaceId?: WorkspaceId): void;
+    archiveSession(sessionId: SessionId): Promise<void>;
+    unarchiveSession(sessionId: SessionId): Promise<void>;
+    pinSession(sessionId: SessionId): Promise<void>;
+    unpinSession(sessionId: SessionId): Promise<void>;
+    pickDirectory(): Promise<string | null>;
+    listDirectory(path?: string, signal?: AbortSignal): Promise<DirectoryListing>;
+    createDirectory(path: string, name: string): Promise<string>;
+    private watchNavigation;
+    /** @returns true when an archived current selection was cleared. */
+    private clearArchivedCurrent;
+    private clearMain;
+    private replaceMain;
+}
+export { UiWorkspaceService };
+//# sourceMappingURL=navigation.d.ts.map

package/lib/types/client/pin-order.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The account memberships a pin order write reconciles against, derived from
+ * the same Host snapshots the browser orders by, so the UiWorkspace service
+ * completes the write without the browser in the loop.
+ */
+import type { SessionListState } from '@qilin-agent/api-session-controller/client';
+import type { WorkspaceView } from '@qilin-agent/api-workspace-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+/**
+ * Every account's complete membership: each Workspace, Ungrouped, and the flat list.
+ * @param workspaces - current Host Workspaces.
+ * @param list - current Session list snapshot.
+ * @returns membership per account key plus the summaries a reconciliation orders by.
+ */
+export declare function pinOrderSource(workspaces: readonly WorkspaceView[], list: SessionListState): {
+    members: Readonly<Record<string, readonly SessionId[]>>;
+    summaries: SessionListState['byId'];
+};
+/**
+ * The accounts a pinned Session leads: its group (or Ungrouped) and the flat list.
+ * @param workspaces - current Host Workspaces.
+ * @param sessionId - the Session being pinned.
+ * @returns the account keys a pin write fronts.
+ */
+export declare function pinOrderAccounts(workspaces: readonly WorkspaceView[], sessionId: SessionId): readonly string[];
+//# sourceMappingURL=pin-order.d.ts.map