@huanlin/dsh-plugin-better-plan 0.4.0

package/lib/types/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @huanlin/dsh-plugin-better-plan — replaces the built-in plan mode's plan
+ * DELIVERY while keeping everything else about plan mode intact.
+ *
+ * The model writes the complete plan to a markdown file (guided by the tool
+ * description) and calls the same-name `exit_plan_mode` with its path. This
+ * plugin registers that same-name tool into EVERY agent's scope at
+ * `agent/session-start` (`agent.ctx.tools.register`) — per-agent scoped
+ * registrations shadow the preset-mounted built-in across scope layers, so
+ * the built-in plan-mode plugin stays mounted and untouched (its `plan:policy`
+ * section, `/plan` command, projection, and composer badge keep working).
+ *
+ * Delivery pipeline (execute): validate plan mode → resolve the path against
+ * the session cwd → stat/read with a byte cap → enqueue a push on the
+ * per-session delivery registry (consumed by the `/better-plan/ws/delivery`
+ * WebSocket when a sidebar view is attached) → when the push reached a view,
+ * PARK the call on the review gate: the conversation stops with no approval
+ * popup and the user decides in the plan panel (`POST /better-plan/api/review`
+ * settles it); when no view is attached, ask the SAME plan-review question
+ * the built-in tool asks, with the full plan as the detail (D3: without the
+ * sidebar the user still reviews the plan on the card).
+ *
+ * Approval queueing the mode flip: the preset realm's `planMode` service is
+ * invisible to this plugin, so the approved `plan/mode: false` append is
+ * deferred to the next accepted `agent/pre-step` boundary here — the same
+ * mechanism the built-in controller uses (the tool result is the narration).
+ *
+ * The preset's static `plan:policy` section still teaches the ORIGINAL
+ * inline-plan contract and bans file writes, so a `system-prompt/assemble`
+ * waterfall listener rewrites those sentences to the file-first contract on
+ * every assembled prompt (see `prompt-override.ts`).
+ *
+ * User-facing copy follows the session's locale (see `locale.ts`): the
+ * delivery render text (via the tool's `finalizeContent` seam), the steer
+ * messages, and the no-sidebar review question localize to the sidebar
+ * view's reported locale; the model contract (description, prompt rewrite,
+ * execute errors) stays English.
+ *
+ * @module @huanlin/dsh-plugin-better-plan
+ */
+import type { Context } from './context.ts';
+import { type BetterPlanConfig } from './config.ts';
+import { PlanDeliveryRegistry } from './delivery-registry.ts';
+import { LocaleDirectory } from './locale.ts';
+import { PlanReviewGate } from './review-gate.ts';
+export declare const name = "dsh-plugin-better-plan";
+/**
+ * Services required before mounting: the tool registry (its availability
+ * gates scoped registrations), the webserver (the delivery push route), and
+ * the system-prompt registry (the assemble waterfall this plugin rewrites
+ * plan-mode guidance through).
+ */
+export declare const inject: string[];
+/** Loader schema (schemastery, strict) — validated by the cordis Loader. */
+export { Config } from './config.ts';
+export type { BetterPlanConfig } from './config.ts';
+/**
+ * Wire the plugin onto a host context. Everything this registers is bound to
+ * `ctx`'s own fiber and cleans up on disposal (HMR-safe).
+ * @param ctx - the host plugin context.
+ * @param config - the resolved plugin config.
+ * @returns the created delivery registry and review gate (exposed for tests).
+ */
+export declare function createBetterPlan(ctx: Context, config: BetterPlanConfig): {
+    registry: PlanDeliveryRegistry;
+    reviewGate: PlanReviewGate;
+    locales: LocaleDirectory;
+};
+/**
+ * Plugin entry.
+ * @param ctx - the host plugin context.
+ * @param config - the composition entry config (defaults fill in via the schema).
+ */
+export declare function apply(ctx: Context, config?: Partial<BetterPlanConfig>): void;

package/lib/types/locale.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Locale vocabulary and resolution for the host half, plus the localized
+ * user-facing copy the host generates: the delivery render text (through the
+ * tool's `finalizeContent` seam), the steer messages that announce the
+ * sidebar decision, and the no-sidebar review question.
+ *
+ * Deliberately NOT localized (model contract, English only): the shadow
+ * tool's description, the `plan:policy` prompt rewrite, and every execute
+ * error message — those are instructions the model must parse reliably, and
+ * the built-in presets keep the same English-only contract.
+ *
+ * The active locale resolves per session: the plugin config's `locale`
+ * override wins, else the locale the sidebar view reported (the browser's
+ * active DSH locale, carried on the delivery WS connect and every review
+ * request), else English.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/locale
+ */
+/** The locales this plugin ships copy for. */
+export type PlanLocale = 'zh' | 'en';
+/** The plugin config's locale knob: a forced locale or browser following. */
+export type LocaleSetting = 'auto' | PlanLocale;
+/**
+ * Normalize one client-reported locale tag (BCP 47-style, e.g. `zh-CN`)
+ * to a shipped {@link PlanLocale}, or undefined when unsupported.
+ * @param value - the raw reported value (query param / body field).
+ * @returns `'zh'` / `'en'`, or undefined when the value is not a supported tag.
+ */
+export declare function normalizeReportedLocale(value: unknown): PlanLocale | undefined;
+/**
+ * Per-session directory of sidebar-reported locales. The browser view is the
+ * authority on the user's language (the DSH locale preference is Host-backed
+ * and already reflected in the client's active locale), so the host learns
+ * the locale from the client instead of reading settings itself.
+ */
+export declare class LocaleDirectory {
+    private reported;
+    /**
+     * Record one view-reported locale for a session (invalid values ignored).
+     * @param sessionId - the session the view is subscribed to.
+     * @param value - the raw reported locale tag.
+     */
+    report(sessionId: string, value: unknown): void;
+    /**
+     * The locale a session's connected view reported, if any.
+     * @param sessionId - the session to look up.
+     */
+    known(sessionId: string | undefined): PlanLocale | undefined;
+    /** Drop every report (plugin disposal). */
+    dispose(): void;
+}
+/**
+ * Resolve the locale for one session's user-facing copy.
+ * @param setting - the plugin config's locale knob.
+ * @param directory - the sidebar-reported locale directory.
+ * @param sessionId - the session the copy is generated for.
+ * @returns the resolved locale (English when nothing better is known).
+ */
+export declare function resolvePlanLocale(setting: LocaleSetting, directory: LocaleDirectory, sessionId: string | undefined): PlanLocale;
+/**
+ * The localized render content for a delivered plan (the pending and approved
+ * branches of the shadow tool's render). English returns undefined — the
+ * caller preserves the render's own baseline content.
+ * @param path - the delivered plan file path (for the approved note).
+ * @param value - the canonical exit value.
+ * @param locale - the resolved session locale.
+ * @returns the localized content blocks, or undefined to keep the baseline.
+ */
+export declare function localizedRenderContent(path: string, value: {
+    delivered?: unknown;
+    decision?: unknown;
+}, locale: PlanLocale): {
+    type: 'text';
+    text: string;
+}[] | undefined;
+/**
+ * The steer message fired when the sidebar approval lands.
+ * @param locale - the resolved session locale.
+ * @returns the steer text.
+ */
+export declare function approvalSteerText(locale: PlanLocale): string;
+/**
+ * The steer message fired when the sidebar approval delegates execution to a
+ * new conversation: the planning session is closed out (plan mode off) and
+ * must NOT execute the plan itself.
+ * @param locale - the resolved session locale.
+ * @returns the steer text.
+ */
+export declare function delegatedSteerText(locale: PlanLocale): string;
+/**
+ * The steer message fired when the sidebar keeps planning.
+ * @param feedback - the user's optional feedback (already trimmed).
+ * @param locale - the resolved session locale.
+ * @returns the steer text.
+ */
+export declare function keepPlanningSteerText(feedback: string | undefined, locale: PlanLocale): string;
+/** The localized copy of the no-sidebar plan-review question. */
+export interface PlanReviewCopy {
+    header: string;
+    question: string;
+    approveLabel: string;
+    approveDescription: string;
+    keepLabel: string;
+    keepDescription: string;
+}
+/**
+ * The no-sidebar plan-review question's copy (the popup fallback surface).
+ * @param locale - the resolved session locale.
+ * @returns the question copy; labels pair with the ask intent so the
+ *   plan-review takeover matches the approve option by label.
+ */
+export declare function planReviewCopy(locale: PlanLocale): PlanReviewCopy;

package/lib/types/plan-fold.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Local fold of the logged plan-mode state (last `plan/mode` wins; a log
+ * with none folds to inactive). Replaces the `foldPlanMode` export that
+ * dsh 0.1.2-alpha.2 removed from @deepseek-ai/dsh-plan-mode when plan
+ * state moved into the `plan` session projection.
+ *
+ * dsh 0.1.2-rc.1 removed the public `session.events` array (seq/offset
+ * split, commit 27bf1039db): callers now pass the session itself and the
+ * fold reads `snapshotEvents()`.
+ * @module @huanlin/dsh-plugin-better-plan/plan-fold
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** The session-log face this fold reads (structural mirror of `Session`). */
+export interface SessionEventLog {
+    snapshotEvents(): readonly SessionEvent[];
+}
+export declare function isPlanModeActive(session: SessionEventLog): boolean;

package/lib/types/prompt-override.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Prompt-surface override for the built-in plan mode's `plan:policy` section.
+ *
+ * The preset ships the section as static config text teaching the ORIGINAL
+ * delivery contract ("call exit_plan_mode with the complete plan markdown")
+ * while forbidding file writes — both directly contradict this plugin's
+ * file-first tool contract (`exit_plan_mode({ path })`). The section text is
+ * unreachable as config (isolated preset realm), so the correction runs on the
+ * assembled prompt instead: a `system-prompt/assemble` waterfall listener
+ * rewrites the offending sentences in place, leaving every other section —
+ * and any deployment-customized wording around them — untouched.
+ *
+ * The anchor sentence only appears in the assembly while plan mode is active
+ * (the built-in provider returns `''` otherwise), so the listener needs no
+ * plan-state tracking of its own. The mutation is visible to the session log
+ * through the per-request `request/header` event, which records the rendered
+ * system prompt after this waterfall.
+ *
+ * Registration is per-agent, on the agent's own scope: the loop assembles
+ * every prompt with the agent as the dispatch key (`assembleContextFor`), and
+ * scope-chain admission flows events UP the chain only — a listener on this
+ * plugin's own fiber is a sibling of the composition scopes and would never
+ * be admitted. This mirrors the tool shadow's per-agent registration.
+ *
+ * @module @huanlin/dsh-plugin-better-plan
+ */
+import type { Context as CordisContext } from '@deepseek-ai/cordis';
+/**
+ * The shipped preset's delivery sentence, verbatim across the standard, ptc,
+ * and cordis presets. Doubles as the plan-mode-active gate for the listener.
+ */
+export declare const PLAN_DELIVERY_ANCHOR = "When ready, call exit_plan_mode with the complete plan markdown, starting with a # title.";
+/**
+ * The shipped sentence right after the delivery anchor, verbatim across the
+ * standard, ptc, and cordis presets. With the file-first contract the write
+ * tool call necessarily precedes exit_plan_mode in the delivery turn, so this
+ * "only and final tool call" sentence reads as forbidding exactly that call —
+ * the observed write-then-stop failure — and must be rewritten too.
+ */
+export declare const FINAL_CALL_ANCHOR = "Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval.";
+/**
+ * Rewrite the shipped plan-mode guidance to the file-first delivery contract.
+ * Each replacement is independent: a sentence whose anchor is absent (an
+ * older or customized preset variant) is left as-is, and already-rewritten
+ * text passes through unchanged, so the function is idempotent.
+ * @param text - one assembled prompt section's text.
+ * @param planDir - the plugin config's suggested plan directory.
+ * @returns the corrected text, or the input untouched when no anchor matches.
+ */
+export declare function rewritePlanPolicySection(text: string, planDir: string): string;
+/**
+ * Register the assemble waterfall listener on one agent's scoped context.
+ * The agent is the loop's assemble dispatch key, so a listener tagged with
+ * that exact scope is admitted for every prompt this agent assembles.
+ * Sections without the plan-mode anchor pass through untouched, so non-plan
+ * requests pay one string scan per section.
+ * @param ctx - the agent's scoped context (`agent.ctx`); only event
+ *   registration is required, so the plain Cordis face suffices.
+ * @param planDir - the plugin config's suggested plan directory.
+ * @returns the listener disposer (for the caller's lifecycle effect).
+ */
+export declare function registerPlanPolicyOverride(ctx: CordisContext, planDir: string): () => void;

package/lib/types/resolve-cwd.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session working-directory resolution for relative plan paths.
+ *
+ * Chain (mirror of the sidebar's sessionCwdOf): the live session header wins;
+ * while that header carries no cwd (a stripped-down host or a session created
+ * without workspace metadata) the persistence index is consulted for cold
+ * sessions; the host process cwd is the final fallback. A persistence failure
+ * or a non-absolute persisted value also falls through to the process cwd —
+ * a delivery tool should not die because the index hiccups, and a wrong
+ * fallback surfaces as a clear "file does not exist" error from the caller's
+ * own stat.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/resolve-cwd
+ */
+/** The session-header slice this resolver reads. */
+export interface SessionCwdProbe {
+    readonly header?: {
+        readonly cwd?: string;
+    };
+}
+/**
+ * The session-persistence face this resolver consults (structural mirror).
+ * dsh 0.1.2-rc.1 rewrote the contract as handle-based snapshots: the old
+ * `inspect(id)` became `stat(id)` returning a `SessionPersistenceSnapshot`
+ * (the header lives under `snapshot.header`), or undefined when unknown.
+ */
+export interface PersistenceStat {
+    stat(sessionId: string): Promise<{
+        header: {
+            cwd?: string;
+        };
+    } | undefined>;
+}
+/**
+ * Resolve one session's working directory.
+ * @param session - the calling session (its header cwd is authoritative).
+ * @param sessionId - the session id, for the persistence lookup.
+ * @param persistence - the optional session-persistence service.
+ * @returns an absolute working directory (never empty).
+ */
+export declare function resolveSessionCwd(session: SessionCwdProbe | undefined, sessionId: string, persistence: PersistenceStat | undefined): Promise<string>;

package/lib/types/review-gate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The plan-review gate: the per-session record of a delivered plan that
+ * awaits the user's decision IN THE SIDEBAR (no chat popup).
+ *
+ * The shadowed `exit_plan_mode` returns immediately after a delivered push
+ * (the model ends its turn on the render's instruction — the conversation
+ * simply stops), and the user decides later in the plan panel. The gate
+ * holds that pending decision and its handlers; `decide()` (driven by the
+ * review HTTP route) settles the state, broadcasts it to the attached
+ * sidebar views, and fires the handlers that steer the decision back to the
+ * model. Handlers never throw into the route: they are defensive at their
+ * definition site.
+ *
+ * Every state change broadcasts a `{ kind: 'review', review }` frame, and
+ * `attach()` replays the latest state (including a pending review) so a page
+ * refresh restores the action bar.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/review-gate
+ */
+/** Lifecycle of one plan review (the wire status the plan panel renders). */
+export type ReviewStatus = 'pending' | 'approved' | 'delegated' | 'kept' | 'cancelled';
+/** The sidebar decision vocabulary: how the plan panel settles a review. */
+export type ReviewDecision = 'approve' | 'keep' | 'approve_new_session';
+/** One review's user-visible state (the wire face of a review frame). */
+export interface ReviewState {
+    /** The delivery id this review belongs to (stale-click guard). */
+    id: string;
+    /** Absolute path of the plan file under review. */
+    path: string;
+    /** The plan panel tab title. */
+    title: string;
+    status: ReviewStatus;
+}
+/** The server→view frame carrying review state (null = nothing to show). */
+export interface ReviewFrame {
+    kind: 'review';
+    review: ReviewState | null;
+}
+/** One attached sidebar view's review-frame sender. */
+export type ReviewSender = (frame: ReviewFrame) => void;
+/**
+ * The decision side effects, wired by the tool that delivered the plan:
+ * steer the outcome back to the model (approval also flips plan mode off;
+ * delegation flips it off too but hands execution to a new conversation).
+ */
+export interface ReviewHandlers {
+    onApprove(): void;
+    onKeep(feedback: string | undefined): void;
+    onDelegate(): void;
+}
+/**
+ * Per-session pending decision plus the attached view set. One pending
+ * review per session; a newer delivery supersedes the previous one (its
+ * handlers never fire — the newest plan is the one under review).
+ */
+export declare class PlanReviewGate {
+    private pending;
+    /** Latest known state per session — attach replay + stale-window reads. */
+    private latest;
+    private subscribers;
+    /**
+     * Record one pending review and broadcast it.
+     * @param sessionId - the session whose plan is under review.
+     * @param review - the delivery identity (id from the delivery push).
+     * @param handlers - the decision side effects (steer back to the model).
+     */
+    begin(sessionId: string, review: {
+        id: string;
+        path: string;
+        title: string;
+    }, handlers: ReviewHandlers): void;
+    /**
+     * Settle the session's pending review from the sidebar decision.
+     * @param sessionId - the session under review.
+     * @param decision - the user's choice (approve_new_session settles as
+     *   `delegated`: execution continues in a new conversation).
+     * @param feedback - optional keep-planning feedback (trimmed; forwarded to
+     *   the model verbatim in the steer message).
+     * @returns the settled review state, or undefined when nothing is pending.
+     */
+    decide(sessionId: string, decision: ReviewDecision, feedback?: string): ReviewState | undefined;
+    /**
+     * Read the session's pending review (stale-click guard + GET bootstrap).
+     * @param sessionId - the session to inspect.
+     * @returns the pending review, or null when nothing is parked.
+     */
+    peek(sessionId: string): ReviewState | null;
+    /**
+     * Attach one sidebar view; the latest known review state replays
+     * immediately (a `null` frame clears a stale bar), and later changes push.
+     * @param sessionId - the session the view displays.
+     * @param send - the review-frame sender.
+     * @returns the disposer detaching the view.
+     */
+    attach(sessionId: string, send: ReviewSender): () => void;
+    /**
+     * Settle every pending review as cancelled and drop the views (plugin
+     * teardown). Handlers do not fire: a reload discards the decision surface,
+     * and the user re-drives the session.
+     */
+    dispose(): void;
+    /**
+     * Record one state as latest and broadcast it to the session's views.
+     * @returns the recorded state.
+     */
+    private settle;
+}

package/lib/types/review-route.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The `POST /better-plan/api/review` route: the browser→host command channel
+ * that settles a parked plan review (the tab→host half of the sidebar
+ * approval flow the chat popup used to own).
+ *
+ * The plan panel posts `{ session, decision, feedback?, id? }` (decision:
+ * approve / keep / approve_new_session); the route settles the session's
+ * pending review through the {@link PlanReviewGate} and echoes the settled
+ * state back so the submitting view (and, over the delivery WebSocket,
+ * every other view) reflects the decision. `approve_new_session` settles
+ * as `delegated`: the planning session is closed out with a handoff steer
+ * and the panel itself launches the execution conversation.
+ *
+ * The same browser-trust fence as the delivery WebSocket guards the route:
+ * this is a DNS-rebinding / cross-site defense for a session-scoped command,
+ * not authentication.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/review-route
+ */
+import type { PlanReviewGate, ReviewDecision } from './review-gate.ts';
+import type { LocaleDirectory } from './locale.ts';
+import { type FenceRequest } from './trust-fence.ts';
+/** The exact pathname the route registers on the host webServer. */
+export declare const REVIEW_API_PATH = "/better-plan/api/review";
+/** Request-body cap: a decision is a handful of fields, not a plan. */
+export declare const REVIEW_BODY_LIMIT = 4096;
+/** The request face the handler consumes (node:http IncomingMessage subset). */
+export interface ReviewHttpRequest extends FenceRequest {
+    method?: string;
+    url?: string;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Uint8Array | string>;
+}
+/** The response face the handler writes (node:http ServerResponse subset). */
+export interface ReviewHttpResponse {
+    writeHead(status: number, headers?: Record<string, string>): unknown;
+    end(body?: string): unknown;
+}
+/** The exact HTTP route this plugin registers. */
+export interface ReviewApiRoute {
+    kind: 'exact';
+    path: string;
+    handler: (req: ReviewHttpRequest, res: ReviewHttpResponse) => void | Promise<void>;
+}
+/** One parsed review decision body. */
+export interface ReviewDecisionBody {
+    session: string;
+    decision: ReviewDecision;
+    feedback?: string;
+    id?: string;
+    /** The submitting view's active locale tag (BCP 47-style; optional). */
+    locale?: string;
+}
+/**
+ * Parse and validate one review decision body (wire-boundary validation).
+ * @param raw - the request body text.
+ * @returns the parsed decision, or an error message.
+ */
+export declare function parseReviewDecisionBody(raw: string): {
+    value: ReviewDecisionBody;
+    error?: undefined;
+} | {
+    value?: undefined;
+    error: string;
+};
+/**
+ * Serve one review request: GET bootstraps the plan panel's action bar with
+ * the current state (the WS attach replay remains the live channel); POST
+ * settles the pending decision. Both verbs record the submitting view's
+ * reported locale so the host's user-facing copy follows the browser.
+ *
+ * Error bodies carry a stable machine-readable `code` alongside the English
+ * `error` message: the plan panel maps known codes to localized copy and
+ * falls back to the raw message for unknown ones.
+ *
+ * @param gate - the review gate holding the pending review.
+ * @param req - the request (method/headers/body iterator).
+ * @param res - the response.
+ * @param trustedHosts - non-loopback authorities the deployment serves.
+ * @param directory - the locale directory view reports are recorded in.
+ */
+export declare function handleReviewRequest(gate: PlanReviewGate, req: ReviewHttpRequest, res: ReviewHttpResponse, trustedHosts: readonly string[], directory: LocaleDirectory): Promise<void>;
+/**
+ * Register the review decision route on the host webServer.
+ * @param register - the webServer's route registrar.
+ * @param gate - the review gate.
+ * @param trustedHosts - non-loopback authorities the deployment serves.
+ * @param directory - the locale directory view reports are recorded in.
+ * @returns the route disposer.
+ */
+export declare function registerReviewRoute(register: (route: ReviewApiRoute) => () => void, gate: PlanReviewGate, trustedHosts: readonly string[], directory: LocaleDirectory): () => void;

package/lib/types/shadow-tool.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The shadowed `exit_plan_mode` tool — better-plan's whole model-facing
+ * contract.
+ *
+ * The tool keeps the built-in plan mode's name (D1): every agent preset's
+ * planning group mounts `@deepseek-ai/dsh-plan-mode` inside an isolate realm,
+ * and preset mount lines cannot be patched, so a same-name per-agent
+ * registration through `agent.ctx` is the only replacement seam. Shadowing
+ * keeps the preset's `plan:policy` section verbatim (its statements about
+ * `exit_plan_mode` remain true) and leaves `/plan`, the projection, and the
+ * composer badge working unchanged.
+ *
+ * What changes is the delivery: the model must write the COMPLETE plan to a
+ * markdown file first (guided by this description — D2 verifies only that the
+ * file exists and is readable), then pass its path. When the push reaches a
+ * connected sidebar view, the tool RETURNS IMMEDIATELY with `decision:
+ * 'pending'` — the render instructs the model to end its turn, so the
+ * conversation simply stops with no approval popup — and the user reviews the
+ * plan and decides in the sidebar plan panel. The decision is steered back as
+ * the next turn's message (approval also flips plan mode off, see the review
+ * handlers below). When no view is attached, the built-in plan-review
+ * question renders in chat with the full plan text and blocks exactly like
+ * the original tool (no-sidebar environment ⇒ the original experience).
+ *
+ * Conventions (per plugin-development-guide.md §3):
+ *   C4 — `execute` returns one canonical JSON value; `render` is separate.
+ *   C6 — `exec.signal.throwIfAborted()` before any fs work.
+ *   C9 — presentCall/presentResult are pure functions of their arguments.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/shadow-tool
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { BetterPlanConfig } from './config.ts';
+import type { Context } from './context.ts';
+import type { PlanDeliveryRegistry } from './delivery-registry.ts';
+import { type PlanLocale } from './locale.ts';
+import type { PlanReviewGate } from './review-gate.ts';
+/** The review question's id, echoed in the answer this tool reads. */
+export declare const REVIEW_ID = "plan-review";
+/**
+ * The canonical tool value: `pending` = the plan reached the sidebar and the
+ * decision comes later (the model must end its turn); `approved` = the
+ * no-sidebar popup path answered in-turn. `delivered` distinguishes the
+ * push outcome for the render's context note.
+ */
+export interface ExitPlanValue {
+    delivered: boolean;
+    decision: 'pending' | 'approved';
+}
+/**
+ * The model-facing description. The model's only new knowledge: the
+ * file-first contract, the immediate-return + end-turn contract, and the
+ * decision arriving as the next message. `planDir` is interpolated into the
+ * example path.
+ * @param config - the plugin config (planDir suggestion).
+ * @returns the description string.
+ */
+export declare function exitPlanDescription(config: BetterPlanConfig): string;
+/**
+ * The review question's detail: the full plan text. Only the no-sidebar
+ * fallback reaches the question (a delivered plan is reviewed in the sidebar
+ * instead), so the user always sees the whole plan on the popup card.
+ * @param plan - the full plan markdown.
+ * @returns the detail string for the plan-review question.
+ */
+export declare function reviewDetail(plan: string): string;
+/** Dependencies the shadow tool closes over (all provided by the plugin entry). */
+export interface ShadowToolDeps {
+    /** The host plugin context (service reads at execute time). */
+    ctx: Context;
+    /** Resolved plugin config. */
+    config: BetterPlanConfig;
+    /** The delivery registry (per-session queue + views). */
+    registry: PlanDeliveryRegistry;
+    /** The sidebar review gate (records the pending decision + handlers). */
+    reviewGate: PlanReviewGate;
+    /**
+     * The session's resolved locale for user-facing copy (config override →
+     * sidebar-reported → en). Model-contract text never localizes.
+     */
+    localeOf: (sessionId: string | undefined) => PlanLocale;
+    /** Whether the plugin fiber was disposed while a review may be pending. */
+    isDisposed: () => boolean;
+    /** Queue the approved mode flip for the next accepted pre-step boundary. */
+    onApproved: (session: object) => void;
+}
+/**
+ * Build the shadowed tool definition. Registration is the caller's job
+ * (`agent.ctx.tools.register` from the session-start hook).
+ * @param deps - the plugin-provided collaborators.
+ * @returns a registry-ready tool definition.
+ */
+export declare function defineExitPlanTool(deps: ShadowToolDeps): ToolDefinition;

package/lib/types/trust-fence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser-trust fence for the delivery WebSocket, behaviorally identical to
+ * the sidebar's fence (and to the /api gateway's fence in
+ * @deepseek-ai/dsh-client-connection, from which both derive): Host-header
+ * loopback or a configured trusted authority passes; cross-site browser
+ * markers refuse. This is a DNS-rebinding / cross-site defense, not
+ * authentication — the push payload (plan path + title) is chat-adjacent
+ * data, so the fence keeps off-host pages from harvesting it.
+ *
+ * @module @huanlin/dsh-plugin-better-plan/trust-fence
+ */
+/** The request facts the fence reads. */
+export interface FenceRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+/** Whether a normalized URL hostname names the local loopback authority. */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Decide whether one request may reach the delivery WebSocket.
+ * @param request - the upgrade request's headers.
+ * @param trustedHosts - non-loopback authorities this deployment serves.
+ * @returns true when the Host is ours (loopback or trusted) and browser
+ *   markers are same-origin.
+ */
+export declare function isTrustedDeliveryRequest(request: FenceRequest, trustedHosts: readonly string[]): boolean;