@huanlin/dsh-plugin-better-plan 0.4.0

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

@@ -0,0 +1,35 @@
+/**
+ * The Plan tab view: a status header (title, path, actions), the review
+ * action bar (the sidebar approval surface — the chat shows no popup), and
+ * the plan rendered through DSH's shared `MarkdownText`.
+ *
+ * The file content comes from better-sidebar's `/sidebar/api/fs.read` route
+ * (same-origin, browser-authenticated) — the plan file lives in the session
+ * workspace, and the host half has no route of its own for reading it. The
+ * path is `tab.meta.path` (persisted with the tab, so a refresh restores the
+ * view) falling back to `tab.path`.
+ *
+ * The review state comes from the delivery WebSocket's review frames (via
+ * the shared review store, restored by the attach replay after a refresh).
+ * While a review is pending the bar offers Approve / Execute in new chat /
+ * Keep planning; a decision POSTs to the host's review route and the echo
+ * updates the store. The delegation choice then launches the execution
+ * conversation through the sessions service (see execution-launch.ts) and
+ * navigates there.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/client/PlanView
+ */
+import { createElement } from 'react';
+import type { TabComponentProps } from 'dsh-better-sidebar/client/service';
+/**
+ * Extract the plan path from a tab (meta first, then the seed path).
+ * @param tab - the sidebar tab instance.
+ * @returns the plan file path, or undefined when the tab carries none.
+ */
+export declare function planPathOf(tab: TabComponentProps['tab']): string | undefined;
+/**
+ * The Plan tab component (better-sidebar TabDescriptor.component).
+ * @param props - the tab component props (ctx/store/scope/tab/visible).
+ * @returns the rendered view.
+ */
+export declare function PlanView(props: TabComponentProps): ReturnType<typeof createElement>;

package/lib/types/client/execution-launch.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The delegation flow's client half: after a review settles as
+ * `delegated`, create the execution conversation through DSH's public
+ * sessions service (`ctx.get('sessions')`), queue the kickoff prompt into
+ * it, and navigate there.
+ *
+ * The faces below are STRUCTURAL (the minimal subset of
+ * `@deepseek-ai/dsh-api-session-controller/client`'s `ISessions` /
+ * `SessionFace` this flow calls) — the same pattern better-sidebar uses for
+ * cross-plugin services: no value import crosses the client-bundle purity
+ * gate and no new tsconfig path is needed; the runtime service arrives
+ * through the context proxy. The planning session's list summary supplies
+ * the new conversation's cwd, so the fresh agent runs on the same
+ * workspace the plan was written for.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/client/execution-launch
+ */
+/** One admitted prompt's outcome (the client-result face of `prompt`). */
+export interface PromptOutcome {
+    ok: boolean;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+/** The structural session face the kickoff needs (the `prompt` verb). */
+export interface ExecutionSessionFace {
+    prompt(content: {
+        type: 'text';
+        text: string;
+    }[], mode: 'queue'): Promise<PromptOutcome>;
+}
+/** The structural `ctx.sessions` face the delegation flow consumes. */
+export interface SessionsServiceFace {
+    /** Create a blank session (in the workspace of `cwd` when given). */
+    create(opts?: {
+        cwd?: string;
+    }): Promise<string>;
+    /** Select a session as the current conversation. */
+    open(id: string): void;
+    /** The session list snapshot (the planning session's cwd source). */
+    list: {
+        getSnapshot(): {
+            byId: Record<string, {
+                cwd?: string;
+            } | undefined>;
+        };
+    };
+    /** The live session face for a locally addressable session. */
+    binding(id: string): {
+        session: ExecutionSessionFace;
+    } | undefined;
+}
+/**
+ * Launch the execution conversation for a delegated plan: create a blank
+ * session in the planning session's workspace, queue the kickoff prompt
+ * pointing at the approved plan file, then navigate to the new
+ * conversation. Every failure rejects with an Error whose message the
+ * plan panel shows (the plan path stays visible there, so the user can
+ * always start a conversation and send the plan manually).
+ * @param sessions - the sessions service (`ctx.get('sessions')`).
+ * @param planPath - the approved plan file's absolute path.
+ * @param sessionId - the planning session (its summary carries the cwd).
+ */
+export declare function launchExecutionConversation(sessions: SessionsServiceFace, planPath: string, sessionId: string): Promise<void>;

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

@@ -0,0 +1,16 @@
+/**
+ * Inline SVG icon for the Plan tab (client bundles must not value-import
+ * other plugins' internals, and a one-glyph icon does not justify a
+ * react-icons dependency).
+ *
+ * @module @huanlin/dsh-plugin-better-plan/client/icons
+ */
+import { createElement } from 'react';
+/**
+ * The Plan tab glyph: a checklist document.
+ * @param props - size in pixels.
+ * @returns the icon element.
+ */
+export declare function IconPlanOutline16(props: {
+    size: number;
+}): ReturnType<typeof createElement>;

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

@@ -0,0 +1,56 @@
+/**
+ * Client half of @huanlin/dsh-plugin-better-plan: registers the sidebar's
+ * "Plan" tab through better-sidebar's service and subscribes the per-session
+ * delivery WebSocket that opens it and feeds its review action bar.
+ *
+ * The tab is `single: true` (one Plan tab per session, dedupe-focused on
+ * repeat deliveries). Because the dedupe focus does NOT overwrite an already
+ * open tab's path, every push is followed by `updateTab` (feature-gated,
+ * v0.12.0+) so a re-delivered plan replaces the tab's content, then
+ * `activateTab` focuses it. `meta` rides the tab into better-sidebar's
+ * localStorage persistence, so a refresh restores the view and PlanView
+ * re-reads the file from `tab.meta.path`. Review frames feed the shared
+ * review store; the tab's action bar posts decisions back to
+ * `POST /better-plan/api/review` — the sidebar IS the approval surface, the
+ * chat shows no popup.
+ *
+ * With better-sidebar absent this half stays pending on its inject (legal
+ * per the client runner) and, defensively, apply() skips everything when the
+ * service is unreachable — the host half's `delivered: false` path covers
+ * the no-sidebar deployment.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { BetterSidebarService } from 'dsh-better-sidebar/client/service';
+import { ReviewStore } from './review-store.ts';
+/** The Plan tab type id (also the minted tab id — single instance). */
+export declare const TAB_ID = "better-plan:plan";
+/** The delivery WebSocket path (mirror of the host half's route). */
+export declare const DELIVERY_WS_PATH = "/better-plan/ws/delivery";
+/**
+ * Apply one delivery push to the sidebar: open (or focus) the Plan tab, then
+ * overwrite its content via updateTab and focus it (both v0.12.0+; on an
+ * older host the plain openTab dedupe-focus still lands the FIRST delivery).
+ * @param service - the better-sidebar service.
+ * @param payload - the parsed WS frame.
+ * @param sessionId - the session the socket is subscribed to.
+ */
+export declare function applyDeliveryPush(service: BetterSidebarService, payload: unknown, sessionId: string): void;
+/**
+ * Route one WS frame: `deliver` opens/updates the Plan tab, `review` feeds
+ * the review store (the Plan tab's action bar). Malformed frames are ignored
+ * (the next push carries its own state).
+ * @param service - the better-sidebar service.
+ * @param store - the review store the review frames feed.
+ * @param frame - the parsed WS frame.
+ * @param sessionId - the session the socket is subscribed to.
+ */
+export declare function applyDeliveryFrame(service: BetterSidebarService, store: ReviewStore, frame: unknown, sessionId: string): void;
+/** The betterSidebar and locale services this half resolves through the context proxy. */
+export declare const inject: string[];
+/**
+ * Client plugin body.
+ * @param ctx - the client cordis context.
+ */
+export declare function apply(ctx: Context): void;

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

@@ -0,0 +1,94 @@
+/**
+ * Client-half copy for the Plan tab, following the DSH i18n system: the
+ * dictionaries register into the shared locale registry (namespace
+ * `betterPlan`), and `t()` resolves the active locale from the attached
+ * `ctx.locale` service (`@deepseek-ai/dsh-client-locale`) — the Host-backed
+ * `locale.preference` wins over the raw browser language and switches live.
+ * Absent the service (locale plugin not mounted), the browser language is
+ * the fallback.
+ *
+ * The module-level attach mirrors better-sidebar's own locales.ts: the Plan
+ * tab renders inside the sidebar's React tree, so the component reads copy
+ * through `t()` at render time; the sidebar re-renders tab content on locale
+ * switches (its tab-content memo keys on the locale revision), so no extra
+ * subscription is needed here.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/client/locales
+ */
+/** The zh dictionary (source of truth for the key set). */
+export declare const zhDict: {
+    readonly tabTitle: "计划";
+    readonly openInEditor: "在编辑器中打开";
+    readonly copyPath: "复制路径";
+    readonly copied: "已复制";
+    readonly copy: "复制";
+    readonly copiedLabel: "已复制";
+    readonly reviewHint: "在此审阅计划——聊天中不会弹出审批卡。点「批准」在本对话执行，点「新开对话执行」移到全新对话执行，或附反馈选择「继续规划」。";
+    readonly feedbackPlaceholder: "「继续规划」时可附反馈（可选）…";
+    readonly approve: "批准";
+    readonly keepPlanning: "继续规划";
+    readonly approveNewSession: "新开对话执行";
+    readonly delegatingStatus: "计划已批准——正在新建执行对话…";
+    readonly delegatedStatus: "计划已批准——执行已移交到新对话。";
+    readonly errDelegateFailed: "新开执行对话失败";
+    readonly approvedStatus: "计划已批准——模型正在执行该计划。";
+    readonly keptStatus: "反馈已发送——模型正在修改计划。";
+    readonly loading: "正在读取计划…";
+    readonly readFailed: "读取计划失败";
+    readonly retry: "重试";
+    readonly truncated: "文件因侧边栏读取上限被截断；其余内容请在编辑器中查看。";
+    readonly noPath: "该计划标签页未携带文件路径";
+    readonly binaryFile: "计划文件是二进制文件；请在编辑器中查看";
+    readonly unexpectedRead: "fs.read 响应格式异常";
+    readonly errStale: "当前面板已过期——有更新的计划正在审批。";
+    readonly errNoPending: "当前没有等待审批的计划。";
+    readonly errSubmitFailed: "提交决定失败";
+};
+/** The en dictionary (key-set-equal to zh, enforced by the type annotation). */
+export declare const enDict: Record<keyof typeof zhDict, string>;
+/** The dictionary type every future locale must satisfy. */
+export type PlanCopy = Record<keyof typeof zhDict, string>;
+/** The locale namespace this plugin owns in the DSH locale registry. */
+export declare const LOCALE_NS = "betterPlan";
+/** The minimal face of the DSH locale service this module needs. */
+interface LocaleServiceFace {
+    getSnapshot(): {
+        active: string;
+    };
+}
+/**
+ * Attach (or detach, with undefined) the DSH locale service.
+ * @param service - the client context's locale service.
+ */
+export declare function attachLocale(service: LocaleServiceFace | undefined): void;
+/**
+ * The active copy locale: the DSH locale service's snapshot when attached
+ * (zh → zh, anything else → en), else the browser language.
+ * @returns `'zh'` or `'en'`.
+ */
+export declare function activeLocale(): 'zh' | 'en';
+/**
+ * Translate one copy key in the active locale.
+ * @param key - the copy key.
+ * @returns the localized string.
+ */
+export declare function t(key: keyof PlanCopy): string;
+/**
+ * The kickoff prompt the delegation flow queues into the NEW conversation:
+ * the model there has no context, so the message anchors it on the approved
+ * plan file (an absolute path) and orders execution. It is both
+ * user-visible (a chat bubble) and model-directed, so it localizes with the
+ * view like the steer copy does.
+ * @param path - the absolute plan file path.
+ * @returns the kickoff prompt text.
+ */
+export declare function executionKickoffPrompt(path: string): string;
+/**
+ * Localize one review-route error for the action bar: known error codes map
+ * to copy; unknown codes fall back to the route's raw English message.
+ * @param code - the route's stable error code, when present.
+ * @param raw - the route's raw error message (or an HTTP fallback).
+ * @returns the text the action bar shows.
+ */
+export declare function submitErrorText(code: string | undefined, raw: string): string;
+export {};

package/lib/types/client/markdown-props.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Chrome labels for DSH's shared `MarkdownText`, shaped for BOTH prop
+ * generations the plugin supports (inlined from the sidebar's
+ * markdown-labels helper — client bundles must not value-import other
+ * plugins' internals):
+ *
+ * - 0.1.1-rc.x: optional flat prop `codeLabels` — the renderer reads
+ *   `labels.copyLabel` / `labels.copiedLabel` directly.
+ * - 0.1.2-alpha.1+: a REQUIRED nested `labels` prop
+ *   (`labels.code.copyLabel` + a screen-reader-only `labels.footnotes`
+ *   heading). Passing only the old prop crashes the fence render with
+ *   "Cannot read properties of undefined (reading 'code')".
+ *
+ * The union object satisfies both readers, and {@link markdownTextProps}
+ * passes it under BOTH prop names — each host ignores the one it does not
+ * know.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/client/markdown-props
+ */
+import type { ComponentProps } from 'react';
+import { MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives';
+/** The flat copy-button pair. */
+export interface MarkdownCopyLabels {
+    copyLabel: string;
+    copiedLabel: string;
+}
+/** The dual-generation chrome labels object. */
+export interface MarkdownChromeLabels extends MarkdownCopyLabels {
+    /** 0.1.2-alpha.1+ nested reads. */
+    code: MarkdownCopyLabels;
+    /** 0.1.2-alpha.1+ sr-only footnotes heading. */
+    footnotes: string;
+}
+/** Build the dual-shape chrome labels from a flat copy-button pair. */
+export declare function markdownChromeLabels(labels: MarkdownCopyLabels): MarkdownChromeLabels;
+/**
+ * MarkdownText props carrying the labels under BOTH prop names. The cast is
+ * load-bearing: this plugin builds against one generation's declaration where
+ * the other prop does not exist.
+ * @param text - the markdown source.
+ * @param labels - the flat copy-button pair.
+ * @returns props spreadable onto `MarkdownText`.
+ */
+export declare function markdownTextProps(text: string, labels: MarkdownCopyLabels): ComponentProps<typeof MarkdownText>;

package/lib/types/client/review-store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The client-side review state: a tiny external store fed by the delivery
+ * WebSocket's `{ kind: 'review', review }` frames and by the decision POST's
+ * echoed response, consumed by the Plan tab's action bar through
+ * `useSyncExternalStore`.
+ *
+ * The state mirrors the host gate's per-session review; a session switch
+ * resets it (the reconnect's attach replay restores the current state).
+ *
+ * @module @huanlin/dsh-plugin-better-plan/client/review-store
+ */
+/** Mirrors the host gate's ReviewState (the wire face of a review frame). */
+export interface ReviewState {
+    id: string;
+    path: string;
+    title: string;
+    status: 'pending' | 'approved' | 'delegated' | 'kept' | 'cancelled';
+}
+/** The server→view frame carrying review state. */
+export interface ReviewFrame {
+    kind: 'review';
+    review: ReviewState | null;
+}
+/** The sidebar decision vocabulary the panel posts (mirrors the gate's). */
+export type ReviewDecision = 'approve' | 'keep' | 'approve_new_session';
+/** Whether an unknown wire value is a well-formed review state. */
+export declare function isReviewState(value: unknown): value is ReviewState;
+type Listener = () => void;
+/** External store for the current session's review state. */
+export declare class ReviewStore {
+    private state;
+    private listeners;
+    /** The current review state (null = nothing to review). */
+    get: () => ReviewState | null;
+    /** Replace the state and notify subscribers. */
+    set: (next: ReviewState | null) => void;
+    /** Clear the state (session switch); attach replay restores it. */
+    reset: () => void;
+    /** @returns the unsubscribe disposer. */
+    subscribe: (listener: Listener) => (() => void);
+}
+/** The singleton store the WS handler writes and the Plan tab reads. */
+export declare const reviewStore: ReviewStore;
+/** The exact pathname of the host's review decision route. */
+export declare const REVIEW_API_PATH = "/better-plan/api/review";
+/** The outcome of one review decision POST. */
+export type ReviewDecisionOutcome = {
+    ok: true;
+    review: ReviewState;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Bootstrap the review state over HTTP (the WS attach replay remains the
+ * live channel): fills the bar when a review frame was missed (stale bundle,
+ * reconnect gap). A live frame already in the store wins — the GET result is
+ * only applied while the store is empty, so a late null response can never
+ * clear a pending bar. The request reports the view's active locale so the
+ * host's user-facing copy follows the browser.
+ * @param sessionId - the session whose review state to read.
+ */
+export declare function fetchReviewState(sessionId: string): Promise<void>;
+/**
+ * Post one review decision to the host route and, on success, echo the
+ * settled state into the store (the submitting view updates immediately;
+ * other views follow over the WebSocket). The body reports the view's active
+ * locale; failures map the route's stable error codes to localized copy.
+ * @param sessionId - the session whose plan is under review.
+ * @param decision - the user's choice.
+ * @param feedback - optional keep-planning feedback.
+ * @param reviewId - the reviewed delivery's id (stale-click guard).
+ * @returns the outcome; failures keep the pending bar up for a retry.
+ */
+export declare function submitReviewDecision(sessionId: string, decision: ReviewDecision, feedback: string | undefined, reviewId: string): Promise<ReviewDecisionOutcome>;
+export {};

package/lib/types/config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Config schema for the better-plan plugin (Schemastery, strict).
+ *
+ * The plugin injects no extra system-prompt section: the new delivery contract
+ * travels entirely inside the shadowed `exit_plan_mode` tool description, so
+ * the built-in `plan:policy` section stays verbatim and these two knobs are
+ * the whole configuration surface.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/config
+ */
+import type { LocaleSetting } from './locale.ts';
+/** Deployment-tunable configuration for the better-plan plugin. */
+export interface BetterPlanConfig {
+    /**
+     * Plan-directory suggestion interpolated into the shadow tool's description
+     * (the example path the model is told to write plans under).
+     */
+    planDir: string;
+    /**
+     * Read cap of one plan file (bytes). A larger file is refused with guidance
+     * to trim the plan, so an unbounded write cannot flood the review channel.
+     */
+    maxPlanBytes: number;
+    /**
+     * Locale of the user-facing copy the host generates (the delivery render
+     * text, the steer messages, the no-sidebar review question). `auto`
+     * follows the connected sidebar view's reported locale (the browser's
+     * active DSH locale) and falls back to English; `zh` / `en` force one.
+     * Model-contract text (tool description, prompt rewrite, execute errors)
+     * stays English regardless.
+     */
+    locale: LocaleSetting;
+}
+/** Schemastery schema validated by the cordis Loader. */
+export declare const Config: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types/index").default<Schemastery.ObjectS<{
+    planDir: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types/index").default<string, string>;
+    maxPlanBytes: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types/index").default<number, number>;
+    locale: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types/index").default<"zh" | "en" | "auto", "zh" | "en" | "auto">;
+}>, Schemastery.ObjectT<{
+    planDir: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types/index").default<string, string>;
+    maxPlanBytes: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types/index").default<number, number>;
+    locale: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types/index").default<"zh" | "en" | "auto", "zh" | "en" | "auto">;
+}>>;
+/**
+ * Resolve a raw config patch through the schema, returning a full
+ * {@link BetterPlanConfig} with defaults applied. Unknown keys are rejected
+ * here so a mistyped cordis.yml row fails loud at load instead of being
+ * silently ignored.
+ * @param input - a partial or complete config object.
+ * @returns the schema-resolved config.
+ * @throws when the input carries an unknown key or a value the schema rejects.
+ */
+export declare function resolveBetterPlanConfig(input: Partial<BetterPlanConfig>): BetterPlanConfig;

package/lib/types/context.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The Context face this plugin's host half consumes: the vendored cordis
+ * `Context` intersected with structural mirrors of the services it touches.
+ *
+ * Intersection (not `declare module` augmentation) mirrors the sidebar's
+ * approach: DSH's own packages already augment `@deepseek-ai/cordis`, and
+ * restating members structurally avoids TS2717 merge conflicts with any
+ * other plugin's augmentation. The augmentations that DO reach this program
+ * through workspace types (the typed `agent/session-start` /
+ * `agent/pre-step` events from `@deepseek-ai/dsh-agent`) stay untouched.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/context
+ */
+import type { Context as CordisContext } from '@deepseek-ai/cordis';
+import type { PersistenceStat } from './resolve-cwd.ts';
+/** The upgrade route face this plugin registers on the host webServer. */
+export interface BetterPlanUpgradeRoute {
+    path: string;
+    handler: (req: {
+        url?: string;
+        headers: Record<string, string | string[] | undefined>;
+    }, socket: {
+        destroy(): void;
+    }, head: Uint8Array) => void | Promise<void>;
+}
+/** The exact HTTP route face this plugin registers on the host webServer. */
+export interface BetterPlanHttpRoute {
+    kind: 'exact';
+    path: string;
+    handler: (req: never, res: never) => void | Promise<void>;
+}
+/** The webServer service face this plugin uses. */
+export interface BetterPlanWebServer {
+    registerUpgrade(route: BetterPlanUpgradeRoute): () => void;
+    register(route: BetterPlanHttpRoute): () => void;
+}
+/** The web runtime trust list (bind-derived; absent on non-web hosts). */
+export interface BetterPlanWebRuntime {
+    trustedHosts: readonly string[];
+}
+/** The user-questions service face (structural mirror of the ask seam). */
+export interface BetterPlanUserQuestions {
+    ask(request: {
+        questions: {
+            id: string;
+            question: string;
+            detail?: string;
+            header?: string;
+            options?: {
+                label: string;
+                description?: string;
+            }[];
+            intent?: {
+                kind: 'plan-review';
+                approve: string;
+            };
+        }[];
+        agent?: unknown;
+        signal?: AbortSignal;
+    }): Promise<{
+        answers: {
+            id: string;
+            selected: string[];
+            custom?: string;
+        }[];
+    }>;
+}
+/** The shape this plugin consumes. */
+export interface BetterPlanContextShape {
+    /** The host webserver (upgrade routes). */
+    webServer: BetterPlanWebServer;
+    /** The web runtime trust list (optional: non-web hosts have none). */
+    webRuntime?: BetterPlanWebRuntime;
+    /** The user-questions seam (optional: review degrades without it). */
+    userQuestions?: BetterPlanUserQuestions;
+    /** The session-persistence service (optional: cwd fallback source). */
+    sessionPersistence?: PersistenceStat;
+}
+/** The Context this plugin's host half sees. */
+export type Context = CordisContext & BetterPlanContextShape;

package/lib/types/delivery-registry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The plan-delivery registry: a per-session queue of plan pushes plus the
+ * connected sidebar views, following the sidebar's AgentOpenRegistry pattern
+ * (consume-on-send) with one addition — a bounded queue.
+ *
+ * `enqueue` adds a delivery and, when at least one view for the session is
+ * attached, pushes it immediately and clears the queue (`delivered: true`).
+ * With no attached view the delivery stays queued and `attach` replays it on
+ * connect. The queue holds at most {@link DELIVERY_QUEUE_LIMIT} entries per
+ * session (oldest dropped first): a session delivered while no browser is
+ * open must not accumulate unbounded plan pushes that all replay at once on
+ * the next attach — the newest plan is the one under review.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/delivery-registry
+ */
+/** One plan push (the wire face over the delivery WebSocket). */
+export interface PlanDelivery {
+    /** Opaque id (host-generated; the client uses it only for dedupe/debug). */
+    id: string;
+    /** Absolute path of the plan file. */
+    path: string;
+    /** Sidebar tab title: the plan's first heading, else the file basename. */
+    title: string;
+}
+/** Maximum queued deliveries per session (oldest dropped beyond this). */
+export declare const DELIVERY_QUEUE_LIMIT = 8;
+/** One subscribed sidebar view's sender. */
+type Sender = (delivery: PlanDelivery) => void;
+/**
+ * Per-session delivery queues plus the connected views.
+ */
+export declare class PlanDeliveryRegistry {
+    private pending;
+    private subscribers;
+    /**
+     * Queue one delivery and push it immediately when a view is attached.
+     * @param sessionId - the session whose plan panel is targeted.
+     * @param path - absolute path of the plan file.
+     * @param title - sidebar tab title for the plan.
+     * @returns the delivery id and whether a connected view received it now.
+     */
+    enqueue(sessionId: string, path: string, title: string): {
+        id: string;
+        delivered: boolean;
+    };
+    /**
+     * Attach one sidebar view; queued deliveries replay immediately
+     * (consume-on-send: a reconnect must never re-show a plan already open).
+     * @param sessionId - the session the view displays.
+     * @param send - the push callback for this view.
+     * @returns the disposer detaching the view.
+     */
+    attach(sessionId: string, send: Sender): () => void;
+    /** Drop every queued delivery (kept for symmetry with the sidebar registry). */
+    drainAll(): void;
+    /** Drop every queue and subscriber (plugin teardown). */
+    dispose(): void;
+}
+export {};

package/lib/types/first-heading.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Plan-title extraction, shared by the delivery registry (sidebar tab title),
+ * the WS push payload, and the canonical tool value.
+ *
+ * `firstHeading` mirrors the built-in plan mode's regex so both tools name a
+ * plan the same way. D2 keeps validation loose: a plan without any heading is
+ * accepted and falls back to the file basename.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/first-heading
+ */
+/**
+ * The plan's first markdown heading (any level), or `undefined` when the plan
+ * has none. Tolerates leading whitespace before `#` and trailing whitespace
+ * after the text; a 7-`#` run is not a heading.
+ * @param plan - the full plan markdown.
+ * @returns the heading text, or `undefined` when no line matches.
+ */
+export declare function firstHeading(plan: string): string | undefined;
+/**
+ * The last path segment of a POSIX or Windows path (mirror of the sidebar
+ * client's FileTree baseName), used as the fallback plan title.
+ * @param path - the path to shorten.
+ * @returns the basename without trailing separators.
+ */
+export declare function basenameOf(path: string): string;