@avantf/dsh-mission 0.3.0

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

@@ -0,0 +1,247 @@
+/**
+ * The "任务" view: one session's mission trees, driven by the `useSnapshot` hook so the
+ * component knows nothing about the transport; one mission's detail is read on demand and
+ * shown in a modal panel (left: section nav, right: the section, scrolled), the same shape
+ * as the shell's 设置 dialog. There is no toolbar (the engine pushes changes), deletion is a
+ * TREE-level gesture in the tree header (removing a node from a live tree leaves one that
+ * cannot converge), and a row's CHILDREN are open by default while its mission is in play and
+ * folded once it has finished — that folding is the tree, not the detail.
+ * @module @avantf/dsh-mission/client/MissionTreeView
+ */
+import { type ReactNode } from 'react';
+import type { ExecutorSessionLookup, MissionNodeDetail, MissionViewProps, WorkerSessionTarget } from './contract.js';
+/**
+ * The one dialog's data, as this view tracks it (not part of the contract): which node it is
+ * for, and how far that read has got. One at a time, because the dialog is modal — the
+ * per-node cache the inline panel kept existed only to survive rows scrolling past.
+ */
+interface DialogState {
+    readonly nodeId: string;
+    readonly status: 'loading' | 'ready' | 'error';
+    readonly detail?: MissionNodeDetail;
+    readonly error?: string;
+}
+/** How one on-demand full-result read is going, or `undefined` before it has been asked for. */
+export interface FullResultState {
+    readonly status: 'loading' | 'ready' | 'error';
+    readonly text?: string;
+    readonly error?: string;
+}
+/**
+ * The result pane for ONE read state, rendered as a pure function so every rule that matters —
+ * expanded replaces the head, a failed read keeps the locator, no reader means no button — is
+ * testable without a DOM to click in.
+ */
+export declare function ResultPane({ text, pointer, full, canLoad, onToggle }: {
+    text: string | null;
+    pointer: string | null;
+    full: FullResultState | undefined;
+    /** Whether a full read is even possible (a `result` face on the host). */
+    canLoad: boolean;
+    onToggle: () => void;
+}): ReactNode;
+/** One section of the detail dialog: its nav cell and the pane the cell shows. */
+export interface DetailTab {
+    readonly id: string;
+    readonly label: string;
+    /** How many entries the section holds; rendered after the label when present. */
+    readonly count?: number;
+    readonly body: ReactNode;
+}
+/**
+ * The detail's sections, derived from ONE detail read.
+ *
+ * Exported and pure so the mapping is testable without a DOM: the spec renders to static
+ * markup and cannot click a nav cell, so "what does the 纠偏 section hold" has to be
+ * askable of a function rather than of a rendered, clicked dialog.
+ *
+ * A section with nothing to show is ABSENT rather than empty: a 「纠偏」 tab reading
+ * 「（无）」 on a mission that was never steered is a section that exists only to say it does
+ * not. 内容 / 结果 always exist — every mission has a body to achieve, and "no result yet" is
+ * itself a fact about one.
+ *
+ * 标题 is NOT a section: it heads the dialog (see `MissionDetailDialog`), because it answers
+ * "which mission am I looking at" — a question asked before any section is chosen, and one a
+ * reader must be able to answer while reading every one of them. What used to share that tab
+ * (id / dispatch count / depth) rides the same header as its meta line.
+ *
+ * Order is the order a reader asks the questions: what it must achieve (内容) → why it exists
+ * (上下文) → how the executor reasoned about splitting it (拆解信息) → how the direction
+ * changed (纠偏) → what came out (结果) → what the parts reported (子任务).
+ */
+export declare function detailTabs(detail: MissionNodeDetail, options?: {
+    readonly loadResult?: (nodeId: string) => Promise<string>;
+}): readonly DetailTab[];
+/**
+ * Take everything that is NOT on the path from `overlay` up to `<body>` out of the tab order, and
+ * return the undo.
+ *
+ * `inert` is the platform's own "not tabbable, not clickable, hidden from assistive tech" flag, and
+ * the shell's overlays use it for the same reason. Only elements that were not ALREADY inert are
+ * touched, so an overlay opened over another one restores exactly what it changed. The walk goes all
+ * the way up, not just to the panel's own root: the composer and the sidebars are behind the mask
+ * too, and a dialog that lets Tab reach them is modal only in appearance.
+ */
+export declare function inertBackground(overlay: HTMLElement): () => void;
+/**
+ * The address of one worker session, exactly as the host's `uiWorkspace.openSession` takes it: the
+ * durable parent/child address of a *continuable* subagent — what the main UI sends when a child is
+ * picked from the "N 个子智能" dropdown. The PARENT is the owner session this panel belongs to.
+ *
+ * Exported, with `workerSessionOpen`/`createWorkerSessionClick`/`NodeIdEntry`, because this suite
+ * has no DOM: a spec cannot press a rendered button, so it asks these functions (the very ones the
+ * entry is wired to) what a click sends. That keeps "点击发出的 target 形状" pinned without adding a
+ * browser environment.
+ */
+export declare function workerSessionTarget(parentSessionId: string, workerSessionId: string): WorkerSessionTarget;
+/**
+ * What a node-id entry says, in BOTH cases — W18: the id is an entry whether or not the record
+ * already names an executor. The wording names the DESTINATION (the session that executed this
+ * mission) and its state, because the thing rendered is the MISSION's id and a reader must not
+ * mistake the click for "open the task".
+ *
+ * Without a handle the label stays honest rather than promising a session that may not exist: the
+ * click TRIES, and a miss is explained by {@link workerFailureText} instead of being a dead link.
+ * That is also why the two forms are not the same sentence — a reader can tell whether a lookup is
+ * about to happen.
+ */
+export declare function nodeIdLinkLabel(workerSessionId: string | null | undefined, workerLive: boolean | undefined): string;
+/** Why one click could not open a session. Four kinds, four sentences (see {@link workerFailureText}). */
+export type WorkerSessionFailureReason = 'never-dispatched' | 'not-found' | 'unsupported' | 'open';
+/**
+ * The sentence a failed click leaves behind, per reason. Exported and pure so each of the four is
+ * pinned by a test (this suite has no DOM) and so no caller has to invent wording:
+ *
+ * - 「从未派发过」 is a FACT about the record, not a failure to find something;
+ * - 「找不到」 is the case the spec names: a node that WAS dispatched, whose session is gone;
+ * - 「无法打开」 is the host's own limitation — no `uiWorkspace` to navigate with, no session service
+ *   to look one up in, or an older host whose Remote face predates the lookup — and the detail says
+ *   which one, since the three have different remedies;
+ * - 「打开失败」 is the one case where a session WAS named and navigation refused it.
+ */
+export declare function workerFailureText(reason: WorkerSessionFailureReason, detail?: string): string;
+/** What a busy button shows instead of the id — a separate export because there is no DOM here to
+ *  re-render, so the affordance itself is what a test can pin. */
+export declare function workerSessionBusyText(busy: boolean, nodeId: string): string;
+/** What one click did, as data: a test pins the address that was opened, and the panel renders this
+ *  failure instead of the click having "done nothing". */
+export type WorkerSessionOpenOutcome = {
+    readonly opened: true;
+    readonly workerSessionId: string;
+} | {
+    readonly opened: false;
+    readonly reason: WorkerSessionFailureReason;
+    readonly message: string;
+};
+/**
+ * The panel's one click handler, W18: the node id is ALWAYS an entry, and the session is resolved
+ * lazily when the record does not already name one.
+ *
+ * Order: ① a handle on the record opens immediately (zero I/O); ② otherwise `resolveSession` asks the
+ * host, and ONLY a `resolved` answer is opened; ③ a miss becomes a sentence about WHY — never a throw,
+ * never a blank panel. `onLookupStart` fires before the first await, which is what lets the button
+ * say 查找中… instead of looking like it ignored the click.
+ *
+ * `open` may throw or answer with a rejected promise (the session really was cleaned up): both become
+ * the `open` failure. The panel must never blank — or lose its place — because a link went stale,
+ * which is the one failure a link invited by us can cause.
+ */
+export declare function workerSessionOpen(input: {
+    readonly nodeId: string;
+    readonly parentSessionId: string;
+    /** The handle already on the record, when there is one. */
+    readonly workerSessionId?: string | null;
+    readonly open?: (target: WorkerSessionTarget) => unknown;
+    readonly resolveSession?: (nodeId: string) => Promise<ExecutorSessionLookup>;
+    readonly onLookupStart?: () => void;
+}): Promise<WorkerSessionOpenOutcome>;
+/**
+ * The click handler the entry is wired to, as a function of the entry's own state setters.
+ *
+ * Split out for the same reason `workerSessionTarget` is: this suite has no DOM, so "what a click
+ * does" has to be askable of a function rather than of a rendered, clicked button. It is also where
+ * the 查找中… bookkeeping lives — `onLookupStart` fires only when a lookup is really needed, so a
+ * click that already has a handle does not flash a wait state it never had.
+ */
+export declare function createWorkerSessionClick(input: {
+    readonly nodeId: string;
+    readonly parentSessionId: string;
+    readonly workerSessionId?: string | null;
+    readonly open?: (target: WorkerSessionTarget) => unknown;
+    readonly resolveSession?: (nodeId: string) => Promise<ExecutorSessionLookup>;
+    /** Whether a click is already in flight; a second one is ignored rather than queued. */
+    readonly busy: boolean;
+    readonly setBusy: (busy: boolean) => void;
+    readonly setFailed: (failed: boolean) => void;
+    readonly onFailure: (message: string) => void;
+}): () => Promise<void>;
+/**
+ * One node id as an ENTRY. W18: the id is clickable on EVERY node — an existing handle opens its
+ * session directly, and a historical record without one is looked up at CLICK time (the lookup reads
+ * session logs, so it must never happen while rendering). Both places that show a node id (the tree
+ * header's root id and the detail dialog's heading) render this, so the same thing never becomes two
+ * links — W8 put a second, separate link on the worker session id, and that link is what this
+ * replaces.
+ *
+ * Two degradation paths, both deliberate:
+ * ① the host cannot complete the jump — no `uiWorkspace` service, no session service, or an older
+ *    host whose Remote face predates the lookup → the click SAYS which
+ *    ({@link workerFailureText}); the id stays an entry rather than a dead-looking one, so the
+ *    explanation is one click away instead of a tooltip a reader has to go looking for;
+ * ② `open` throws or rejects (the session really was cleaned up) → `onFailure` turns it into the
+ *    caller's message; the panel never blanks and never loses its place.
+ */
+export declare function NodeIdEntry({ nodeId, workerSessionId, workerLive, sessionId, open, onFailure, resolveSession, className, }: {
+    /** The MISSION's id — what is rendered; the session is only the destination. */
+    nodeId: string;
+    workerSessionId: string | null | undefined;
+    workerLive?: boolean;
+    /** The owner session the worker hangs under — the parent half of the address. */
+    sessionId: string;
+    open?: (target: WorkerSessionTarget) => void;
+    onFailure: (message: string) => void;
+    /** The click-time lookup; absent on a host whose Remote face predates it (see `MissionViewProps`). */
+    resolveSession?: (nodeId: string) => Promise<ExecutorSessionLookup>;
+    /** The caller's own monospace slot class, applied to both the link and the plain-text form. */
+    className: string;
+}): ReactNode;
+/**
+ * The inline message a failed open leaves behind. Split out as a pure component, like `ResultPane`,
+ * so its markup is testable without a DOM to click in; the dialog owns the state that shows it.
+ */
+export declare function WorkerSessionHint({ message }: {
+    message: string;
+}): ReactNode;
+/**
+ * One mission's detail as a MODAL panel: a section rail on the left, the chosen section in a
+ * scrollable column on the right — the shell's 设置 dialog, sized for reading (1040×880, capped
+ * by the viewport) rather than the settings' 800×800.
+ *
+ * The heading is the mission's own TITLE, not a 「标题」 section: "which mission is this" is asked
+ * before a section is chosen and must stay answerable while reading every one of them.
+ *
+ * Why a dialog instead of an expanding row: the detail exists to be READ and it runs long —
+ * a description, every correction, every child's conclusion. Inline, it pushed the tree down
+ * by however much the text happened to be, so comparing two missions meant scrolling one of
+ * them out of sight. A fixed panel with its own scroll keeps the tree where it was.
+ */
+export declare function MissionDetailDialog({ nodeId, state, onClose, loadResult, sessionId, openWorkerSession, resolveWorkerSession }: {
+    nodeId: string;
+    /** `undefined` until this node's first read lands; a loading state once it has been asked for. */
+    state: DialogState | undefined;
+    onClose: () => void;
+    /** Read a spilled result back in full. Absent in a host that has no `result` face, and then the
+     *  pane shows the locator without offering a read it cannot perform. */
+    loadResult?: (nodeId: string) => Promise<string>;
+    /** The owner session the shown mission's worker hangs under — the parent half of the address. */
+    sessionId: string;
+    /** Open the executor's session; absent on a host with no `uiWorkspace` service, and then the id
+     *  is rendered as plain text instead of a dead link (see `MissionViewProps.openWorkerSession`). */
+    openWorkerSession?: (target: WorkerSessionTarget) => void;
+    /** The click-time lookup for a record with no handle (see `MissionViewProps.resolveWorkerSession`). */
+    resolveWorkerSession?: (nodeId: string) => Promise<ExecutorSessionLookup>;
+}): ReactNode;
+/** Render the session's mission trees. */
+export declare function MissionTreeView({ useSnapshot, onDeleteTree, onCleanFinished, loadDetail, loadResult, sessionId, openWorkerSession, resolveWorkerSession, }: MissionViewProps): ReactNode;
+export {};
+//# sourceMappingURL=MissionTreeView.d.ts.map

package/lib/types/client/MissionTreeView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MissionTreeView.d.ts","sourceRoot":"","sources":["../../../src/client/MissionTreeView.tsx"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,184 @@
+import type { ExecutorSessionLookup, MissionNodeDetail, MissionSnapshot } from './contract.js';
+/** Safety-net re-read interval; slow on purpose, since the session itself is the primary trigger. */
+export declare const POLL_INTERVAL_MS = 5000;
+/**
+ * Coalescing window: one turn's burst of session revisions becomes a single read.
+ */
+export declare const REFRESH_COALESCE_MS = 400;
+/**
+ * How often the panel re-reads even while the engine's change stream is up. The stream is the update
+ * channel, but a stream that is silently dead (open, delivering nothing) is not detectable from this
+ * side, and the panel must not be able to go stale forever — this bounds the staleness. It is not a
+ * "poll": at 30 s it is a backstop, and a healthy stream still gives sub-second freshness.
+ */
+export declare const STREAM_KEEPALIVE_MS = 30000;
+/**
+ * The cheap session-side value that changes when the mission tree may have. It deliberately does NOT
+ * include the chat node count: the mission tree is not a function of how many messages the
+ * conversation holds, and folding that in made every chat activity re-read and re-render the whole
+ * tree (the stream is what carries actual mission changes; `queued`/`running` are the session-side
+ * facts that matter).
+ */
+export declare function sessionRevision(input: {
+    readonly queued: number;
+    readonly running: boolean;
+}): string;
+/** The Remote namespace surface this plugin consumes. */
+export interface MissionRemote {
+    snapshot: (args: {
+        sessionId: string;
+    }) => Promise<unknown>;
+    detail: (args: {
+        sessionId: string;
+        nodeId: string;
+    }) => Promise<unknown>;
+    delete: (args: {
+        sessionId: string;
+        rootId: string;
+    }) => Promise<unknown>;
+    /** Delete EVERY closed tree this session owns (the panel's "清理已完成"). Optional for the same
+     *  reason as `result`: an older host has no such method, and the panel refuses to send the call
+     *  rather than reading the gateway's 404 as "the missions are gone". */
+    cleanFinished?: (args: {
+        sessionId: string;
+    }) => Promise<unknown>;
+    /** The FULL text behind a spilled result. Optional for the same reason `watch` is: an older host
+     *  simply does not have it, and the pane falls back to showing the locator. */
+    result?: (args: {
+        sessionId: string;
+        nodeId: string;
+    }) => Promise<unknown>;
+    /** The click-time executor lookup (W18). Optional for the same reason as `result`: an older host
+     *  has no such method, and the panel says "the two halves are out of step" instead of guessing. */
+    resolveExecutorSession?: (args: {
+        sessionId: string;
+        nodeId: string;
+    }) => Promise<unknown>;
+    /** The engine's change stream, called with the transport's cancellation signal.
+     *  Optional: an older host may not expose it, so the caller keeps its timer fallback. */
+    watch?: (args: {
+        sessionId: string;
+    }, signal: AbortSignal) => AsyncIterable<unknown>;
+}
+/** A timer as the client platform publishes it (`interval` returns its disposer). */
+export interface IntervalTimer {
+    interval: (callback: () => void, delay: number) => () => void;
+}
+/**
+ * The human half of a failure. `Error#message` is NOT an own enumerable property, so a plain
+ * `JSON.stringify(error)` drops exactly the sentence a reader needs and leaves `{"code":…}` — the
+ * `RemoteError` this boundary carries is an `Error` subclass with `code`/`details` as the own ones.
+ * So: the message first, the JSON only when there is no message to show.
+ */
+export declare function errorText(error: unknown): string;
+/**
+ * Collapse a burst of triggers into ONE call after `delayMs` of quiet.
+ *
+ * The mission tree has three refresh triggers (the session revision, the engine's change stream, and the
+ * stream's reopen) and the engine pushes a frame per state change, so without this a burst of changes
+ * costs one snapshot RPC per frame. `cancel` releases a pending call — the disposer of the effect that
+ * owns the coalescer, so leaving the tab cannot fire a read into an unmounted panel.
+ */
+export declare function coalesce(run: () => void, delayMs: number): {
+    request: () => void;
+    cancel: () => void;
+};
+/** Peel the transport envelope (`{ ok, value }` / `{ ok, error }`, or a bare value) so a
+ *  wiring mistake surfaces as a message rather than an empty view. */
+export declare function unwrap(response: unknown): {
+    value?: unknown;
+    error?: string;
+};
+/**
+ * The version-skew note for one `snapshot` payload, or `undefined` when the two halves agree.
+ *
+ * WHY A NOTE AND NOT A THROW. The host half is loaded ONCE when `dsh web` starts; this bundle is
+ * re-read on every page load. So a rebuilt client routinely talks to an older host, and the ONE thing
+ * the marker must never do is blank the panel: `snapshot` is the entry point every other read hangs
+ * off, and an unrecognised revision usually still carries the fields the panel renders. So an absent
+ * marker ("host predates it") and an unknown one ("host is newer") both come back as a note beside the
+ * tree, never as a failed read.
+ *
+ * `wire` is read off the RAW payload rather than a validated field: the schema accepts any number, and
+ * a payload whose `wire` is missing must not be reported as a shape failure.
+ */
+export declare function snapshotSkew(value: unknown): string | undefined;
+/** Read one session's trees; throws with the reason when the read cannot be trusted. */
+export declare function fetchSnapshot(remote: MissionRemote, sessionId: string): Promise<MissionSnapshot>;
+/**
+ * Delete one whole finished mission tree by root — the unit is the TREE; a refusal travels in
+ * the result envelope and becomes an exception here.
+ */
+export declare function deleteWork(remote: MissionRemote, sessionId: string, rootId: string): Promise<readonly string[]>;
+/**
+ * Delete EVERY closed tree this session owns — the batch entry behind the panel's "清理已完成".
+ *
+ * The first half is the version-skew gate, exactly as {@link fetchExecutorSession}'s: against a host
+ * whose `wire` predates the method, sending the call can only produce a gateway 404 that reads like
+ * "the missions are gone". The call is not sent, and the sentence names the remedy (restart dsh).
+ *
+ * Returns the two id lists the host reported — the roots removed and the roots kept because they were
+ * never retired — so the caller can render "N removed / M skipped" without parsing prose.
+ */
+export declare function cleanFinishedWork(remote: MissionRemote, sessionId: string, hostWire?: number): Promise<{
+    deleted: readonly string[];
+    skipped: readonly string[];
+}>;
+export declare function asDetail(value: unknown): Partial<MissionNodeDetail> & {
+    error?: string;
+};
+/** Read one mission's full detail on demand — results run to 2 KB each, and the snapshot re-reads on change. */
+export declare function fetchDetail(remote: MissionRemote, sessionId: string, nodeId: string): Promise<MissionNodeDetail>;
+/**
+ * Name a transport failure that is really a VERSION SKEW.
+ *
+ * The two halves of this plugin do not update together: the browser bundle is re-read on every page
+ * load, the host half is loaded once when `dsh web` starts. So a rebuilt plugin routinely talks to an
+ * older host, and the gateway answers a method that host never published with an HTTP 404 — which
+ * reads exactly like "the mission or the file is gone", the two things it does NOT mean. The sentence
+ * therefore names the missing REGISTRATION (an older host, or one that was never restarted) rather
+ * than only repeating the transport text.
+ */
+export declare function transportHint(cause: unknown): string;
+/**
+ * Read the FULL text behind a spilled result. On demand only: the pane offering it is answering a
+ * question ("show me all of it"), and the host reads a file to answer — so nothing prefetches it.
+ * A host that cannot resolve the locator answers with a reason instead, which the pane shows beside
+ * the locator rather than as a failed read.
+ */
+export declare function fetchFullResult(remote: MissionRemote, sessionId: string, nodeId: string): Promise<string>;
+/**
+ * Ask the host to find the session that ran one node (W18). CALLED ONLY FROM A CLICK: the server
+ * side lists the session corpus and reads a few logs, which is exactly the cost the panel must not
+ * pay while rendering.
+ *
+ * Four failure shapes, kept apart on purpose:
+ * - the host reports a `wire` older than the method (an older host, or one never restarted) → the call
+ *   is NOT SENT at all, and the sentence names the remedy (restart dsh);
+ * - the host has no such method despite a current `wire` → the same version-skew sentence;
+ * - the call itself failed (transport) → `transportHint`'s reading of it;
+ * - the host ANSWERED "never dispatched" / "not found" / "cannot look up" → returned as an answer,
+ *   because those are outcomes a reader must be told about, not failures of the panel.
+ *
+ * `hostWire` is the revision the host reported on its last `snapshot` (carried on the snapshot the
+ * panel renders from). Checked FIRST and before the remote is even touched: against a host that never
+ * registered the method, sending the call can only produce a gateway 404 that reads like a deleted
+ * mission (see `transportHint`).
+ */
+export declare function fetchExecutorSession(remote: MissionRemote, sessionId: string, nodeId: string, hostWire?: number): Promise<ExecutorSessionLookup>;
+/**
+ * Follow the engine's change stream, calling `onChange` per frame; the frame carries a
+ * revision and nothing else. The CALLER decides what a normal end means.
+ */ export declare function watchChanges(remote: MissionRemote, sessionId: string, signal: AbortSignal, onChange: () => void): Promise<void>;
+export declare const STREAM_REOPEN_MS = 1000;
+/**
+ * Start re-reading on a timer — a poll, not a subscription, because the tree lives in a
+ * host-side KV domain with no event feed. Two rungs because the platform `timer` service is
+ * NOT reliably mounted: the service is preferred, the browser's own timers are the fallback.
+ */
+export declare function startPolling(refresh: () => void, intervalMs: number, service: Partial<IntervalTimer> | undefined, host?: HostTimers): () => void;
+export interface HostTimers {
+    setInterval?: (callback: () => void, delay: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+}
+//# sourceMappingURL=api.d.ts.map

package/lib/types/client/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/client/api.ts"],"names":[],"mappings":"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"}