@zhengjunyao/dsh-restart 0.1.0

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

@@ -0,0 +1,5 @@
+/** One panel render. */
+export declare function RestartPanel(props: {
+    variant?: 'settings' | 'floating';
+    onClose?: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,230 @@
+/**
+ * Browser-side API client for the /api/dsh-restart route family.
+ *
+ * Everything goes over same-origin fetch. The one endpoint that is *not* on the
+ * DSH server is the detached helper's recovery console (a different port,
+ * CORS-open) — that is the only thing still answering while DSH is down, so the
+ * panel uses it to show why a restart failed.
+ */
+/** Live helper state (mirrors the host contract; every field is optional). */
+export interface HelperStatus {
+    ok?: boolean;
+    /** Marker set by our own helper; absent on anything else listening on that port. */
+    helper?: string;
+    mode?: 'spawn' | 'observe';
+    phase?: string;
+    attempt?: number;
+    maxAttempts?: number;
+    port?: number;
+    url?: string;
+    fallbackPort?: number | null;
+    fallbackUrl?: string;
+    oldPid?: number | null;
+    childPid?: number | null;
+    childExit?: {
+        code: number | null;
+        signal: string | null;
+        at: string;
+    } | null;
+    startedAt?: string;
+    elapsedMs?: number;
+    readyAt?: string | null;
+    bootMs?: number | null;
+    failure?: {
+        kind: string;
+        message: string;
+        exitCode?: number | null;
+    } | null;
+    logFile?: string | null;
+    errorLines?: {
+        t: number;
+        text: string;
+    }[];
+    tail?: string[];
+    dshVersion?: string | null;
+    profile?: string | null;
+    argv?: string[];
+}
+/** Host identity. */
+export interface HostInfo {
+    pid: number;
+    ppid: number;
+    startedAt: string;
+    uptimeMs: number;
+    port: number;
+    host: string;
+    url: string;
+    cwd: string;
+    nodeVersion: string;
+    dshVersion: string;
+    profile: string;
+    command: string;
+    restarted: boolean;
+    platform: string;
+    logsDir: string;
+    statusFile: string;
+    helperFile: string;
+    helperExists: boolean;
+    launchd: {
+        managed: boolean;
+        label: string;
+        state: string;
+        pid: number | null;
+        plistPath: string;
+        logFile: string;
+        strategy: string;
+    };
+}
+/** One restart record. */
+export interface RestartRecord {
+    at: string;
+    source: string;
+    reason: string;
+    oldPid: number;
+    helperPid: number | null;
+    port: number;
+    logFile: string;
+    statusFile: string;
+    outcome?: string;
+}
+/** Effective plugin config (mirrors the host contract). */
+export interface RestartConfig {
+    enabled: boolean;
+    announceToAgent: boolean;
+    entry: 'sidebar' | 'ball' | 'both' | 'off';
+    restartMode: 'auto' | 'helper' | 'launchd';
+    fallbackPort: number;
+    bootTimeoutMs: number;
+    maxAttempts: number;
+    killGraceMs: number;
+    portFreeTimeoutMs: number;
+    lingerMs: number;
+    logLines: number;
+    autoReload: boolean;
+    showOverlay: boolean;
+    probeIntervalMs: number;
+    historyLimit: number;
+}
+/** GET /api/dsh-restart/status. */
+export interface StatusPayload {
+    ok: boolean;
+    host: HostInfo;
+    helper: HelperStatus | null;
+    helperAlive: boolean;
+    helperAgeMs: number | null;
+    launchd: {
+        managed: boolean;
+        label: string;
+        state: string;
+        logFile: string;
+        strategy: string;
+    } | null;
+    config: RestartConfig;
+    configFile: string;
+    configExists: boolean;
+    statusFile: string;
+    consoleUrl: string;
+    history: RestartRecord[];
+    logFiles: {
+        name: string;
+        file: string;
+        size: number;
+        mtime: string;
+    }[];
+}
+/** GET /api/dsh-restart/logs. */
+export interface LogPayload {
+    ok: boolean;
+    file: string;
+    exists: boolean;
+    mtime: string;
+    text: string;
+    lines: string[];
+    errorLines: string[];
+    logFiles: {
+        name: string;
+        file: string;
+        size: number;
+        mtime: string;
+    }[];
+}
+/** GET /api/dsh-restart/probe. */
+export interface ProbePayload {
+    ok: boolean;
+    pid: number;
+    startedAt: string;
+    uptimeMs: number;
+}
+/** POST /api/dsh-restart/restart. */
+export interface RestartAck {
+    ok: boolean;
+    helperPid: number | null;
+    logFile: string;
+    statusFile: string;
+    fallbackPort: number;
+    fallbackUrl: string;
+    exitInMs: number;
+    restartingAt: string;
+    oldPid: number;
+    mode?: 'helper' | 'launchd';
+    error?: string;
+}
+/** Error carrying the route's JSON error message. */
+export declare class RestartApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** The dsh-restart panel API. */
+export declare class RestartApi {
+    /** Host + helper + config + history. */
+    status(): Promise<StatusPayload>;
+    /** Liveness probe used while reconnecting (short timeout, tiny body). */
+    probe(timeoutMs?: number): Promise<ProbePayload>;
+    /** Ask for a restart; the host answers before it exits. */
+    restart(reason: string, source?: string): Promise<RestartAck>;
+    /** Boot-log tail; `which: 'latest'` = newest log file on disk. */
+    logs(which?: string, lines?: number): Promise<LogPayload>;
+    /** Restart history, newest first. */
+    history(limit?: number): Promise<{
+        ok: boolean;
+        history: RestartRecord[];
+    }>;
+    /** Patch (or reset) the plugin config. */
+    setConfig(patch: Partial<RestartConfig> & {
+        reset?: boolean;
+    }): Promise<{
+        ok: boolean;
+        config: RestartConfig;
+    }>;
+    /** Live helper state (through the host). */
+    helper(): Promise<{
+        ok: boolean;
+        alive: boolean;
+        ageMs: number | null;
+        consoleUrl: string;
+        status: HelperStatus | null;
+    }>;
+    /** Ask a failed helper to try again. */
+    helperRetry(): Promise<{
+        ok: boolean;
+        consoleUrl?: string;
+        error?: string;
+    }>;
+}
+/**
+ * Read the detached helper's live state straight from its console port.
+ *
+ * Used only while DSH itself is unreachable: the helper is a different origin
+ * (another port) but answers with `Access-Control-Allow-Origin: *`.
+ */
+export declare function fetchHelperDirect(consoleUrl: string, timeoutMs?: number): Promise<HelperStatus | null>;
+/**
+ * Fetch the helper's copy-ready failure report.
+ *
+ * Served by the recovery console (a different port, CORS-open), so it is
+ * reachable exactly when the main server is not — which is when a failure
+ * report matters.
+ */
+export declare function fetchHelperReport(consoleUrl: string, timeoutMs?: number): Promise<string>;
+/** Ask the helper (direct) to relaunch after a failure. */
+export declare function requestHelperRetry(consoleUrl: string, timeoutMs?: number): Promise<boolean>;

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

@@ -0,0 +1,2 @@
+/** Mount the sidebar entry (idempotent). */
+export declare function mountRestartEntry(): Promise<void>;

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

@@ -0,0 +1,8 @@
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** Required services. */
+export declare const inject: string[];
+/**
+ * Register the settings card, mount the sidebar entry and the overlay.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

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

@@ -0,0 +1,2 @@
+/** Mount the overlay root (called once by the client entry). */
+export declare function mountRestartOverlay(): void;

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

@@ -0,0 +1,79 @@
+/**
+ * dsh-restart — the browser-side restart state machine.
+ *
+ * One module-level store, subscribed to by every surface (settings card,
+ * sidebar popover, full-screen overlay). A restart is a process that outlives
+ * the page it started from, so the state is mirrored into sessionStorage: if
+ * the tab reloads mid-restart, the overlay picks the wait back up instead of
+ * leaving the user on a dead page with no explanation.
+ *
+ * The lifecycle:
+ *
+ *   requesting ──POST /api/dsh-restart/restart──▶ waiting
+ *   waiting ──probe /api/dsh-restart/probe every N ms──▶ ready ──▶ location.reload()
+ *   waiting ──helper reports failure──▶ failed (keeps probing; the helper can
+ *                                       be retried from the overlay)
+ */
+import { type HelperStatus, type RestartAck, type RestartConfig } from './api.ts';
+/** Restart phase. */
+export type Phase = 'idle' | 'requesting' | 'waiting' | 'ready' | 'failed';
+/** What every surface renders from. */
+export interface RestartState {
+    phase: Phase;
+    /** When this restart started (ms epoch). */
+    startedAt: number;
+    /** Wall-clock while waiting, refreshed by the ticker. */
+    elapsedMs: number;
+    /** Recovery console base URL ('' until the host answered). */
+    fallbackUrl: string;
+    /** Port DSH was serving on when the restart was requested. */
+    port: number;
+    /** Log file the new host writes to. */
+    logFile: string;
+    /** Human-readable failure text ('' when nothing failed). */
+    error: string;
+    /** Progress note for the overlay. */
+    note: string;
+    /** Live helper state (null when the helper is not reachable). */
+    helper: HelperStatus | null;
+    /** The host's acknowledgement of the restart request. */
+    ack: RestartAck | null;
+    /** Effective plugin config, once the status endpoint answered. */
+    config: RestartConfig | null;
+    /** Set when the page is about to reload itself. */
+    reloadAt: number | null;
+    /** Who asked for the restart. */
+    source: string;
+    /** Why (free text, recorded in the host's history). */
+    reason: string;
+    /** True while the helper is being asked to try again. */
+    retrying: boolean;
+}
+/** Current snapshot (stable identity between mutations). */
+export declare function getState(): RestartState;
+/** Subscribe to state changes. */
+export declare function subscribe(listener: () => void): () => void;
+/** Load the config once so the reconnect follows the user's preferences. */
+export declare function refreshConfig(): Promise<RestartConfig | null>;
+/**
+ * Start a restart and stay on top of it.
+ * @param reason - free-text reason recorded in the host's history.
+ * @param source - who asked (the panel passes 'web').
+ */
+export declare function startRestart(reason?: string, source?: string): Promise<void>;
+/** Probe right now (the overlay's "立即重试" button). */
+export declare function checkNow(): Promise<void>;
+/** Ask the helper to relaunch after a failed boot. */
+export declare function retryBoot(): Promise<void>;
+/** Dismiss the overlay without touching the server. */
+export declare function dismiss(): void;
+/** Forget a finished restart (keeps config). */
+export declare function reset(): void;
+/**
+ * Resume a restart that was in flight when the page went away.
+ *
+ * Called once at mount by the overlay; a no-op when nothing is pending.
+ */
+export declare function resumeIfPending(): void;
+/** React binding: re-renders the caller whenever the restart state changes. */
+export declare function useRestartState(): RestartState;

package/lib/types/config.d.ts

@@ -0,0 +1,125 @@
+/**
+ * dsh-restart — plugin config, on-disk layout, and restart history.
+ *
+ * Everything this plugin owns lives under one directory
+ * (`~/.dsh/dsh-restart` by default, override with `DSH_RESTART_HOME`):
+ *
+ *   config.json    plugin settings (0600)
+ *   history.json   one record per requested restart (newest first)
+ *   status.json    written by the detached helper — live restart state
+ *   pending-spec.json  handoff payload for the next helper run
+ *   logs/<stamp>.log   stdout+stderr of one restarted host
+ */
+/** Default plugin settings; every field is user-overridable. */
+export interface RestartConfig {
+    /** Master switch — when false the routes and tools stay unmounted. */
+    enabled: boolean;
+    /** Announce the plugin (tools + behaviour) in the agent system prompt. */
+    announceToAgent: boolean;
+    /** Where the panel entry lives in the GUI. */
+    entry: 'sidebar' | 'ball' | 'both' | 'off';
+    /**
+     * How the host is restarted: `auto` asks launchd when the host turns out to be
+     * launchd-managed (otherwise it relaunches itself), `helper` always relaunches,
+     * `launchd` forces the launchctl path.
+     */
+    restartMode: 'auto' | 'helper' | 'launchd';
+    /** Port for the detached recovery console (tries +9 further when busy). */
+    fallbackPort: number;
+    /** How long the new host may take to answer before the attempt fails. */
+    bootTimeoutMs: number;
+    /** Launch attempts per restart request (1 = no automatic retry). */
+    maxAttempts: number;
+    /** Grace period after SIGTERM before the helper SIGKILLs the old host. */
+    killGraceMs: number;
+    /** How long to wait for the old host to release its port. */
+    portFreeTimeoutMs: number;
+    /** How long the helper keeps its console up after success before exiting. */
+    lingerMs: number;
+    /** Lines of boot log kept for display. */
+    logLines: number;
+    /** Auto-reload the page once the new host answers. */
+    autoReload: boolean;
+    /** Show the full-screen restart overlay while waiting. */
+    showOverlay: boolean;
+    /** Reconnect probe interval (ms). */
+    probeIntervalMs: number;
+    /** Restart records kept in history.json. */
+    historyLimit: number;
+}
+/** Shipped defaults. */
+export declare const DEFAULT_CONFIG: RestartConfig;
+/** One completed restart request, as rendered in the panel history list. */
+export interface RestartRecord {
+    at: string;
+    /** Who asked: the web panel, an agent tool, or another caller. */
+    source: string;
+    reason: string;
+    oldPid: number;
+    helperPid: number | null;
+    port: number;
+    logFile: string;
+    statusFile: string;
+    /** Outcome, filled in by the panel/host once the new process is up. */
+    outcome?: string;
+}
+/**
+ * Plugin directory.
+ *
+ * Resolution order mirrors DSH's own: an explicit `DSH_RESTART_HOME` (used by
+ * the tests and by anyone running a throwaway instance), then DSH's own
+ * `DSH_HOME` when it is set — a launcher or a rescue capsule may relocate the
+ * whole home — and only then the conventional `~/.dsh`. Hardcoding `~/.dsh`
+ * would silently write a second, wrong home on such setups.
+ */
+export declare function restartHome(): string;
+/** Settings file (override with DSH_RESTART_CONFIG). */
+export declare function configPath(): string;
+/** Restart history file. */
+export declare function historyPath(): string;
+/** Live helper status file. */
+export declare function statusPath(): string;
+/** Handoff payload for the helper. */
+export declare function specPath(): string;
+/** Directory holding one log file per restarted host. */
+export declare function logsDir(): string;
+/**
+ * The detached helper shipped with this package. Resolved from the module URL
+ * so it works both from a local checkout and from an installed copy.
+ */
+export declare function helperPath(): string;
+/** Normalize a partial config against the defaults (never throws). */
+export declare function normalizeConfig(patch: Partial<RestartConfig> | undefined, base?: RestartConfig): RestartConfig;
+/** The effective config (defaults + file), plus where it came from. */
+export declare function loadConfig(): Promise<{
+    config: RestartConfig;
+    exists: boolean;
+    file: string;
+}>;
+/** Merge a patch into the stored config and return the fresh value. */
+export declare function saveConfig(patch: Partial<RestartConfig>): Promise<RestartConfig>;
+/** Delete the stored config (back to shipped defaults). */
+export declare function resetConfig(): Promise<RestartConfig>;
+/** Append one restart record (newest first, bounded by historyLimit). */
+export declare function appendHistory(record: RestartRecord, limit: number): Promise<void>;
+/** Read the restart history (newest first). */
+export declare function readHistory(limit?: number): Promise<RestartRecord[]>;
+/** Ensure the plugin directories exist (0600 where it matters). */
+export declare function ensureLayout(): Promise<void>;
+/**
+ * Synchronous config read, for the plugin's apply() path.
+ *
+ * Mounting must stay synchronous: cordis effects have to be created inside the
+ * plugin's own apply scope, so the roster cannot wait on a promise.
+ */
+export declare function loadConfigSync(): {
+    config: RestartConfig;
+    exists: boolean;
+    file: string;
+};
+/**
+ * Materialize the config file on first run so the settings become discoverable
+ * and editable; the composition row only seeds it, the file is authoritative.
+ * @param seed - values from the plugin row (enabled / announceToAgent / …).
+ */
+export declare function seedConfigSync(seed: Partial<RestartConfig>): boolean;

package/lib/types/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * dsh-restart — one-click restart for DeepSeek Harness. Host half.
+ *
+ * Installing or updating a plugin changes host-side code, and only a fresh
+ * `dsh web` process picks it up. This plugin makes that a button: the web
+ * panel (and the agent, through dsh_restart) hands the relaunch to a detached
+ * helper, the page reconnects by itself, and if the new host fails to boot the
+ * helper's recovery console shows the error instead of a dead tab.
+ *
+ * Mounts:
+ *   - /api/dsh-restart/* routes (status, probe, restart, logs, history, config)
+ *   - dsh_restart / dsh_restart_status agent tools
+ *   - one system-prompt section announcing the capability
+ *   - a browser half (lib/client.js): settings card, sidebar entry, overlay
+ *
+ * No DSH source changes: everything rides public plugin surfaces.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type RestartConfig } from './config.ts';
+/** Stable cordis plugin name. */
+export declare const name = "dsh-restart";
+/** Services required before the plugin surfaces can mount. */
+export declare const inject: string[];
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export declare const RESTART_GUIDANCE: string;
+/** Plugin config, read from the composition row (the JSON file wins once it exists). */
+export type Config = Partial<RestartConfig>;
+/**
+ * Mount the restart routes, tools and announcement.
+ * @param ctx - host plugin context carrying tools/systemPrompt/webServer.
+ * @param config - plugin config from the composition row (seeds the JSON file).
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+/** Re-exports for host consumers and the tests. */
+export { DEFAULT_CONFIG, appendHistory, configPath, ensureLayout, helperPath, historyPath, loadConfig, loadConfigSync, logsDir, normalizeConfig, readHistory, resetConfig, restartHome, saveConfig, seedConfigSync, specPath, statusPath, type RestartConfig, type RestartRecord, } from './config.ts';
+export { buildSpec, hostInfo, isAlive, launchSignature, launchdInfo, listLogs, newestLogFile, readHelperStatus, requestRestart, scheduleSelfExit, tailFile, type HelperStatus, type HostInfo, type LogTail, type RestartOutcome, type RestartSpec, } from './restart.ts';
+export { detectLaunchd, detectLaunchdFor, kickCommand, labelForPid, kickstart, readLaunchdLog, type LaunchdInfo, } from './launchd.ts';
+export { RESTART_API, makeRoutes, type RestartStatusPayload, type RouteContext } from './routes.ts';
+export { buildTools, restartStatusTool, restartTool, type ToolContext } from './tools.ts';

package/lib/types/launchd.d.ts

@@ -0,0 +1,80 @@
+/**
+ * dsh-restart — macOS launchd awareness.
+ *
+ * A DSH host is often managed by a launchd job (`com.dsh.web` with
+ * `KeepAlive: true` on this machine). That changes the correct restart from
+ * "relaunch it ourselves" to "ask launchd to restart it": a helper that spawns
+ * its own child would race the job for the listening port, and whichever loses
+ * dies with `EADDRINUSE`.
+ *
+ * So the plugin detects the situation and switches strategy:
+ *
+ *   launchd-managed → `launchctl kickstart -k gui/<uid>/<label>` (the job comes
+ *                     back with the plist's own cwd/env/argv) + the helper runs
+ *                     in observe mode, following the plist's stdout/stderr.
+ *   anything else   → the helper relaunches the exact same command itself.
+ *
+ * Detection is a pure read of `XPC_SERVICE_NAME` (set by launchd on every
+ * process it starts) confirmed by `launchctl print`, and every failure mode
+ * falls back to the self-relaunch path — a host that is not launchd-managed must
+ * never end up depending on launchctl.
+ */
+/** What we know about the managing launchd job. */
+export interface LaunchdInfo {
+    label: string;
+    uid: number;
+    domain: string;
+    plistPath: string;
+    /** Present when the plist could be parsed. */
+    stdoutPath: string;
+    stderrPath: string;
+    /** `launchctl print` state, e.g. "running". */
+    state: string;
+    pid: number | null;
+}
+/**
+ * Which launchd job owns a pid.
+ *
+ * `launchctl list` prints `PID  Status  Label`, so matching our own pid is the
+ * authoritative answer — and the only reliable one: **Node rewrites
+ * `XPC_SERVICE_NAME` to `0` in `process.env`**, so the environment variable
+ * launchd set (still visible in the kernel environment, e.g. `ps eww -p <pid>`)
+ * cannot be read from inside the process. The env var is kept only as a
+ * secondary signal for the case where `launchctl list` is unavailable.
+ *
+ * @param pid - the process to look up.
+ * @returns the job label, or null when the process is not a launchd job.
+ */
+export declare function labelForPid(pid: number): Promise<string | null>;
+/**
+ * Detect a managing launchd job for this process.
+ *
+ * Returns null on non-macOS, when the process is not launchd-managed, or when
+ * `launchctl print` cannot see the job — every one of those means the caller
+ * must fall back to the self-relaunch strategy.
+ */
+export declare function detectLaunchd(): Promise<LaunchdInfo | null>;
+/**
+ * Detect the launchd job owning an arbitrary pid.
+ *
+ * The plugin calls it for its own pid (the host is the job); tooling outside the
+ * host — a one-off handoff script, a test — needs it for a *different* pid, and
+ * in that case `process.env.XPC_SERVICE_NAME` says nothing useful.
+ *
+ * @param pid - the process to look up.
+ */
+export declare function detectLaunchdFor(pid: number): Promise<LaunchdInfo | null>;
+/**
+ * Ask launchd to restart the job (`kickstart -k`).
+ *
+ * @param info - the detected job.
+ * @returns ok plus launchctl's own output when it refused.
+ */
+export declare function kickstart(info: LaunchdInfo): Promise<{
+    ok: boolean;
+    error: string;
+}>;
+/** The command a retry should re-run for a managed host. */
+export declare function kickCommand(info: LaunchdInfo): string[];
+/** Read the tail of a launchd log file ('' when missing). */
+export declare function readLaunchdLog(file: string, lines: number): Promise<string>;