@zhengjunyao/dsh-restart 0.1.0

package/lib/types/restart.d.ts

@@ -0,0 +1,236 @@
+/**
+ * dsh-restart — the restart engine (host half).
+ *
+ * A host cannot restart itself in place: the moment it exits, the browser has
+ * nothing to talk to, and any failure would be invisible. So the handoff goes
+ * through a detached helper process that survives the host:
+ *
+ *   panel / tool ──POST /api/dsh-restart/restart──▶ host
+ *   host ──writes pending-spec.json, spawns helper──▶ helper (detached)
+ *   host ──SIGTERM after a short delay──▶ exit
+ *   helper ──waits for the port to free, relaunches the same command──▶ new host
+ *   helper ──status.json + fallback console──▶ the page shows progress / errors
+ *
+ * The relaunch reuses the exact invocation the running host was started with
+ * (`process.execArgv` + `argv[1:]`), so `dsh web --port 3080`, a `node` path
+ * override, a custom port and a custom cwd all survive a restart unchanged.
+ */
+import { type LaunchdInfo } from './launchd.ts';
+import { type RestartConfig, type RestartRecord } from './config.ts';
+/** Everything the panel needs to describe the running host. */
+export interface HostInfo {
+    pid: number;
+    ppid: number;
+    startedAt: string;
+    uptimeMs: number;
+    /** Port the host is actually listening on. */
+    port: number;
+    host: string;
+    url: string;
+    cwd: string;
+    nodeVersion: string;
+    dshVersion: string;
+    profile: string;
+    /** Full relaunch command, for display. */
+    command: string;
+    /** True when this host was itself started by a restart helper. */
+    restarted: boolean;
+    platform: string;
+    logsDir: string;
+    statusFile: string;
+    helperFile: string;
+    helperExists: boolean;
+    /** macOS launchd job managing this host, when there is one. */
+    launchd: {
+        managed: boolean;
+        label: string;
+        state: string;
+        pid: number | null;
+        plistPath: string;
+        /** Log file the job's stdout/stderr land in ('' when the plist is silent). */
+        logFile: string;
+        /** Which strategy a restart will use right now. */
+        strategy: 'helper' | 'launchd';
+    };
+}
+/** Live state written by the detached helper (all fields optional). */
+export interface HelperStatus {
+    ok?: boolean;
+    /** Marker set by our own helper; absent on anything else bound to 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;
+    statusFile?: string | null;
+    errorLines?: {
+        t: number;
+        text: string;
+    }[];
+    tail?: string[];
+    dshVersion?: string | null;
+    profile?: string | null;
+    argv?: string[];
+}
+/** Launch specification handed to the helper. */
+export interface RestartSpec {
+    port: number;
+    host: string;
+    url: string;
+    file: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    oldPid: number;
+    logFile: string;
+    statusFile: string;
+    fallbackPort: number;
+    bootTimeoutMs: number;
+    maxAttempts: number;
+    killGraceMs: number;
+    portFreeTimeoutMs: number;
+    lingerMs: number;
+    ringLines: number;
+    dshVersion: string;
+    profile: string;
+    /**
+     * `spawn` — the helper relaunches the host itself.
+     * `observe` — something else owns the relaunch (launchd); the helper kicks it
+     *   and then only watches, so two processes never race for the port.
+     */
+    mode: 'spawn' | 'observe';
+    owner: string;
+    kickCommand: string[];
+    kickDelayMs: number;
+    observeLog: string;
+    /** Single self-contained report the helper writes when a boot fails. */
+    failureReport: string;
+}
+/** True when a pid is alive (signal 0 probe). */
+export declare function isAlive(pid: number): boolean;
+/** Detect (and cache) the launchd job managing this host. */
+export declare function launchdInfo(force?: boolean): Promise<LaunchdInfo | null>;
+/** The relaunch command, exactly as this host was started. */
+export declare function launchSignature(): {
+    file: string;
+    args: string[];
+    cwd: string;
+};
+/** Describe the running host. */
+export declare function hostInfo(options: {
+    port: number;
+    host: string;
+    url: string;
+}): Promise<HostInfo>;
+/** Build the helper spec for a restart of the current host. */
+export declare function buildSpec(options: {
+    config: RestartConfig;
+    port: number;
+    host: string;
+    url: string;
+    /** Managing launchd job, when the restart will be delegated to it. */
+    launchd?: LaunchdInfo | null;
+}): Promise<RestartSpec>;
+/** Outcome of one restart request. */
+export interface RestartOutcome {
+    ok: boolean;
+    error: string;
+    helperPid: number | null;
+    logFile: string;
+    statusFile: string;
+    specFile: string;
+    fallbackPort: number;
+    fallbackUrl: string;
+    /** Milliseconds after which this host stops serving (helper mode). */
+    exitInMs: number;
+    /** Which strategy actually ran. */
+    mode: 'helper' | 'launchd';
+    record: RestartRecord;
+    /**
+     * Perform the handover. MUST be called after the HTTP reply is on the wire:
+     * in launchd mode the helper kickstart terminates this process.
+     */
+    commit: () => Promise<void>;
+}
+/**
+ * Hand the restart over to a detached helper.
+ *
+ * Returns as soon as the helper is running; the caller is responsible for
+ * answering the HTTP request first and only then ending this process (see
+ * {@link scheduleSelfExit}), so the browser always gets a definite reply.
+ *
+ * @param options - config, listen address, and who asked.
+ */
+export declare function requestRestart(options: {
+    config: RestartConfig;
+    port: number;
+    host: string;
+    url: string;
+    source: string;
+    reason: string;
+    exitDelayMs?: number;
+}): Promise<RestartOutcome>;
+/**
+ * End this host so the helper can take over.
+ *
+ * SIGTERM first (lets DSH close sessions and release the port), then a hard
+ * exit as a backstop — the helper SIGKILLs anything still holding the port
+ * after its own grace period.
+ * @param delayMs - how long to wait before signalling (the HTTP reply needs to flush).
+ */
+export declare function scheduleSelfExit(delayMs: number): void;
+/** Read the live helper status, if any. */
+export declare function readHelperStatus(): Promise<{
+    status: HelperStatus | null;
+    alive: boolean;
+    ageMs: number | null;
+}>;
+/** A log tail plus the lines that look like errors. */
+export interface LogTail {
+    file: string;
+    exists: boolean;
+    mtime: string;
+    text: string;
+    lines: string[];
+    errorLines: string[];
+}
+/** Tail a log file (missing files come back as an empty tail, not an error). */
+export declare function tailFile(file: string, limit: number): Promise<LogTail>;
+/** Where the helper drops the copy-ready failure report. */
+export declare function failureReportPath(): string;
+/** Read the last failure report ('' when the last restart did not fail). */
+export declare function readFailureReport(): Promise<{
+    text: string;
+    file: string;
+    exists: boolean;
+}>;
+/** The newest log file in the logs directory (null when none exist). */
+export declare function newestLogFile(): Promise<string | null>;
+/** List recent log files (newest first). */
+export declare function listLogs(limit?: number): Promise<{
+    name: string;
+    file: string;
+    size: number;
+    mtime: string;
+}[]>;

package/lib/types/routes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * dsh-restart — loopback HTTP routes for the web panel.
+ *
+ * Route family: /api/dsh-restart/*. Every route is loopback-only (127.0.0.1 /
+ * ::1, same-origin), matching the other dsh-* panels.
+ *
+ *   GET  /status          host + live helper + config, plus the last restarts
+ *   GET  /probe           tiny liveness probe the page polls while reconnecting
+ *   POST /restart         hand the restart to the detached helper, then exit
+ *   GET  /logs            boot-log tail (and the lines that look like errors)
+ *   GET  /history         one record per requested restart
+ *   POST /config          patch / reset the plugin config
+ *   GET  /helper          the helper's live status through the host (proxy)
+ *   POST /helper/retry    ask a failed helper to try again
+ */
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import { type RestartConfig } from './config.ts';
+import { type HelperStatus, type HostInfo } from './restart.ts';
+/** Route paths. */
+export declare const RESTART_API: {
+    readonly status: "/api/dsh-restart/status";
+    readonly probe: "/api/dsh-restart/probe";
+    readonly restart: "/api/dsh-restart/restart";
+    readonly logs: "/api/dsh-restart/logs";
+    readonly history: "/api/dsh-restart/history";
+    readonly config: "/api/dsh-restart/config";
+    readonly helper: "/api/dsh-restart/helper";
+    readonly helperRetry: "/api/dsh-restart/helper/retry";
+};
+/** Where this host is reachable (filled in by the plugin at mount time). */
+export interface RouteContext {
+    /** Listening port of the host's web server. */
+    port: number;
+    /** Bind host. */
+    host: string;
+    /** Base URL used in links and the helper spec. */
+    url: string;
+}
+/** Status payload returned to the panel. */
+export interface RestartStatusPayload {
+    ok: true;
+    host: HostInfo;
+    helper: HelperStatus | null;
+    helperAlive: boolean;
+    helperAgeMs: number | null;
+    config: RestartConfig;
+    configFile: string;
+    configExists: boolean;
+    statusFile: string;
+    /** Where the detached recovery console is reachable (after a restart). */
+    consoleUrl: string;
+    /** launchd job managing this host, when there is one. */
+    launchd: {
+        managed: boolean;
+        label: string;
+        state: string;
+        logFile: string;
+        strategy: string;
+    } | null;
+    /** Restarts requested through this plugin, newest first. */
+    history: unknown[];
+    logFiles: unknown[];
+    endpoints: typeof RESTART_API;
+}
+/** Build the route list for ctx.webServer.register. */
+export declare function makeRoutes(deps: RouteContext): WebRoute[];

package/lib/types/tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh-restart — model-facing tools.
+ *
+ *   dsh_restart_status  read-only: host identity, live helper state, and the
+ *                       lines of the last boot log that look like errors.
+ *   dsh_restart         restart the host through the detached helper.
+ *
+ * The write tool demands `confirm: true`, because restarting DSH ends the
+ * current turn and the current session's connection: an agent must have asked
+ * the user first (the local standing rule is that DSH is never restarted
+ * without explicit consent).
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { RouteContext } from './routes.ts';
+/** Shared tool dependencies. */
+export interface ToolContext {
+    /** Where this host listens. */
+    endpoint: RouteContext;
+}
+/** Tool: restart status, live helper state, last boot errors. */
+export declare function restartStatusTool(ctx: ToolContext): ToolDefinition;
+/** Tool: restart the host. */
+export declare function restartTool(ctx: ToolContext): ToolDefinition;
+/** Build the tool roster. */
+export declare function buildTools(ctx: ToolContext): ToolDefinition[];

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@zhengjunyao/dsh-restart",
+  "version": "0.1.0",
+  "description": "One-click restart for DeepSeek Harness: a web button (plus a dsh_restart agent tool) hands the relaunch to a detached helper that waits for the port to free, relaunches the exact same command, streams the new host's output, auto-reconnects the page — and shows the boot errors in a recovery console when the new host dies",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    },
+    "engines": {
+      "dsh": ">=0.1.5-rc.1"
+    }
+  },
+  "files": [
+    "lib",
+    "helper",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "restart",
+    "reload",
+    "supervisor",
+    "重启",
+    "panel"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsdown",
+    "bundle": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "node tests/smoke.mjs && node tests/helper.mjs && node tests/routes.mjs && node tests/handoff.mjs && node tests/launchd.mjs",
+    "verify": "node scripts/portability.mjs --health /api/dsh-restart/probe --restart-route /api/dsh-restart/restart",
+    "verify:quick": "node scripts/portability.mjs --skip-audit --health /api/dsh-restart/probe",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-connection": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.5",
+    "lightningcss": "1.32.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsdown": "0.22.2",
+    "typescript": "~5.7.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhengjy01/dsh-restart"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}