dsh-ntr 0.2.0 → 0.3.0

package/lib/types/protocol.d.ts

@@ -229,6 +229,50 @@ export interface AcpPluginConfig {
      * up and reports the `cancelled` stop as-is. Default 2.
      */
     staleCancelMaxRetries?: number;
+    /**
+     * Inactivity watchdog for a turn the agent owes an answer: how long the turn
+     * may stay SILENT before the host finalizes it as stalled.
+     *
+     * The clock is `LiveSession.lastAgentActivityAt`, refreshed by ANY
+     * `session/update`, at every turn start, at each segment start (the host
+     * handing the turn back after a card), and when a permission ask arrives or
+     * is resolved. The watchdog only READS it while the turn is watched: an OPEN
+     * agent segment (always true on the `/acp`-RPC path, which has no driver
+     * stream) and no pending approval. The host-card execution phase and an
+     * unanswered ask are exempt by that gate, not because the clock is frozen —
+     * they legitimately move it too.
+     *
+     * Firing finalizes the TURN only (an `agent/notice` plus the usual turn
+     * end); it does NOT kill the agent process. The wedged `session/prompt` is
+     * abandoned, and the next message reclaims the session: parked with
+     * `releaseAll` and resumed with `session/load`, or reset outright when the
+     * agent declares no `loadSession` (the context is gone and the user is
+     * told).
+     *
+     * Default 600000 ms (10 minutes); `0` disables the WHOLE watchdog, the tool
+     * window included.
+     */
+    turnStallMs?: number;
+    /**
+     * The longer silence window applied while ANY ACP tool call is still active
+     * by `toolCallId` — parallel calls are tracked as a set, so the window lasts
+     * until the LAST of them finishes. The agent is working on its own clock in
+     * there, so the plain turn window would call a healthy long-running tool
+     * stalled.
+     *
+     * Default 1800000 ms (30 minutes); `0` falls back to
+     * {@link AcpPluginConfig.turnStallMs}. It matches
+     * `TOOL_OUTPUT_WAIT_MS = 30 * 60 * 1000` in `presets/acp/acp-guard.mjs`, so
+     * the two halves of one turn agree on how long a tool may take.
+     */
+    turnStallToolMs?: number;
+    /**
+     * How often the watchdog scans for silent turns, in milliseconds. A tuning /
+     * test knob only: NO settings-page control exists for it — and none for the
+     * two windows above either; the whole watchdog is configured in the patch
+     * file. Default 30000 ms.
+     */
+    turnStallTickMs?: number;
 }
 export type AgentProcessState = 'stopped' | 'starting' | 'ready' | 'error';
 /** Agent facts the browser may render (never includes env/argv secrets beyond argv itself, which is config-visible). */
@@ -669,6 +713,35 @@ export interface DefaultAgentSetPayload {
 export type DefaultAgentResult = {
     agentId?: string;
 };
+/** `plugin/version`: the installed host package's version, for the settings badge. */
+export type PluginVersionResult = {
+    version?: string;
+};
+/**
+ * Where the plugin's own update check stands. The host half only ever reports
+ * facts it can read from the harness plugin manager and the npm registry — it
+ * never downloads, swaps files, or restarts itself.
+ */
+export type PluginUpdateStatus = 'unsupported' | 'not-installed' | 'source-install' | 'managed' | 'current' | 'available' | 'applying' | 'busy' | 'applied' | 'restart-required' | 'failed';
+/**
+ * One update-check answer, shared by `plugin/update-check` and
+ * `plugin/update-apply`.
+ */
+export interface PluginUpdateState {
+    status: PluginUpdateStatus;
+    /** 运行中（内存里）的插件版本 */
+    current: string;
+    /** 磁盘上装着的版本（listBundles().version），可读时才有 */
+    installed?: string;
+    /** profile registry 链上最新的稳定版 */
+    latest?: string;
+    /** latest 的 npm 发布时间 ISO */
+    publishedAt?: string;
+    /** 实际按顺序问过的 registry */
+    registries?: string[];
+    /** 失败/额外说明（英文技术信息，UI 自己负责本地化） */
+    message?: string;
+}
 /**
  * How the composer-edge agent tag shows liveness (the blue halo). `breath`
  * pulses the halo at the speed below; `steady` shows a constant glow.

package/lib/types/update.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Host-side built-in update for dsh-ntr.
+ *
+ * The plugin NEVER downloads a package, swaps files, or restarts itself. The
+ * harness plugin manager owns installation (profile bookkeeping, npm, the
+ * restart contract); this module only asks it what is installed, asks an npm
+ * registry what is published, and delegates the install back to the manager.
+ * Every method therefore reports a {@link PluginUpdateState} instead of
+ * throwing; version syntax is validated at the RPC boundary (`impl.ts`).
+ */
+import type { PluginUpdateState } from './protocol.ts';
+/** The npm package this plugin is published as, and the bundle name to look for. */
+export declare const UPDATE_PACKAGE = "dsh-ntr";
+/** npm's public registry; the only base a private `resolved` may be widened to. */
+export declare const NPM_PUBLIC_REGISTRY = "https://registry.npmjs.org";
+/**
+ * Structural view of one row from the harness plugin manager's
+ * `listBundles()`. Deliberately local: importing the host package would tie
+ * this module to a runtime version it must merely probe structurally.
+ */
+export interface UpdateBundleInfo {
+    name: string;
+    installed: boolean;
+    removable?: boolean;
+    enabled?: boolean;
+    version?: string;
+    source?: string;
+    readOnlyReason?: string;
+    error?: {
+        code?: string;
+        message?: string;
+        diagnostic?: string;
+    };
+}
+/** Structural view of `pluginManager.registries()`. */
+export interface UpdateRegistryPlan {
+    registry?: string | null;
+    fallbackRegistries?: readonly string[];
+    resolved?: string | null;
+}
+/** Structural view of the manager's `installBundle()` / `removeBundle()` result (a ChangeResult). */
+export interface UpdateInstallResult {
+    application?: string;
+    version?: string;
+    error?: {
+        code?: string;
+        message?: string;
+        diagnostic?: string;
+    };
+}
+/** The plugin-manager face this service needs. Every member is probed, never assumed. */
+export interface UpdateManagerLike {
+    listBundles?(): Promise<readonly UpdateBundleInfo[]>;
+    registries?(): Promise<UpdateRegistryPlan>;
+    installBundle?(spec: string, options?: {
+        enabled?: boolean;
+        registry?: string;
+    }): Promise<UpdateInstallResult | undefined>;
+    /**
+     * Native-update half of the harness: `installBundle` refuses to replace an
+     * already-installed bundle while HMR holds it, so the host removes first.
+     * Optional — older hosts cannot install at all and answer `already-installed`.
+     */
+    removeBundle?(name: string): Promise<UpdateInstallResult | undefined>;
+}
+/**
+ * The shared eligibility verdict. `ok` carries the disk version (when the host
+ * reports one); the failure arm is already a full state, so check/apply can
+ * return it verbatim.
+ */
+export type BundleEligibility = {
+    ok: true;
+    installed?: string;
+} | {
+    ok: false;
+    state: PluginUpdateState;
+};
+/**
+ * Whether a `listBundles().source` value names a registry-resolvable version
+ * spec — the only install shape this updater may replace. The test is positive
+ * on purpose: link/file/git/workspace/URL/tarball/relative forms all carry a
+ * `:` / `/` / `\` or start with `.`, so they fall out without an ever-growing
+ * blacklist (a new source scheme must not become silently updatable).
+ */
+export declare function isRegistrySpec(source: string): boolean;
+/**
+ * Compare two semver strings (build metadata ignored, prerelease precedence per
+ * semver §11). Malformed segments count as `0`, so the function never throws on
+ * a value read off a registry.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Turn the manager's registry plan into the ordered list this service will
+ * actually query, following the host's privacy rule: a *private* `resolved`
+ * registry must not be widened with the shared fallback chain.
+ *
+ * - No configured registry: query `resolved`; append fallbacks only when it is
+ *   npm's public registry or one of the fallbacks themselves.
+ * - Configured registry: query it first, then `resolved` under the same
+ *   condition, then the fallbacks.
+ *
+ * http(s) only (a private http registry is legitimate), trailing slashes
+ * normalized, duplicates dropped. A base that carries credentials in its URL is
+ * skipped: a bare GET cannot replay `.npmrc` auth, so it could only fail with a
+ * 401 that reads as "unreachable".
+ */
+export declare function registryPlan(plan: UpdateRegistryPlan): string[];
+/**
+ * Pick the version an update should offer.
+ *
+ * `dist-tags.latest` leads when it is a stable release newer than `current`
+ * (that is the line npm itself blesses). Otherwise the highest stable,
+ * non-deprecated published version wins — a lagging `latest` tag must not hide
+ * a newer release. When nothing is newer, the stable `latest` tag is still
+ * returned so the UI can say "you are on the latest release".
+ */
+export declare function pickUpdateTarget(packument: unknown, current: string): {
+    version?: string;
+    publishedAt?: string;
+};
+/**
+ * Pure eligibility matrix, shared by check and apply.
+ *
+ * `undefined` means the manager (or one of its methods) is unavailable; an
+ * empty list means the manager answered but does not carry this plugin.
+ */
+export declare function bundleEligibility(bundles: readonly UpdateBundleInfo[] | undefined, currentVersion: string): BundleEligibility;
+export interface UpdateServiceOptions {
+    resolveManager(): UpdateManagerLike | undefined;
+    currentVersion: string;
+    isBusy(): boolean;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * Update checks and installs, memoized per registry base.
+ *
+ * Caching exists because the settings page polls: a 10-minute window keeps the
+ * check honest without turning every mount into a registry round trip. Apply
+ * clears the cache so the next check sees the freshly installed version.
+ */
+export declare class UpdateService {
+    private readonly resolveManager;
+    private readonly currentVersion;
+    private readonly isBusy;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly cache;
+    private applying;
+    /** Registry that answered the last `available` check, passed through to apply. */
+    private lastTarget?;
+    constructor(options: UpdateServiceOptions);
+    /** The manager surface plus the disk-version verdict, or a ready-to-return failure state. */
+    private eligibility;
+    private fetchTarget;
+    /** One registry's packument, via the 10-minute cache. Throws when unreachable. */
+    private targetFor;
+    /**
+     * Ask the manager's registry chain what is published; never installs.
+     *
+     * A mirror may lag behind the rest of the chain, so a base that only knows
+     * the running (or an older) release does not end the walk — the next base
+     * gets its turn. `busy` is deliberately not checked here: reading a registry
+     * costs no ACP work, and the settings card should still be able to say what
+     * is out there while a turn runs.
+     */
+    check(): Promise<PluginUpdateState>;
+    /**
+     * Install one exact version through the harness plugin manager.
+     *
+     * Re-entry while an install is running answers `applying` instead of
+     * stacking a second npm operation; the install itself is the host's job.
+     *
+     * With HMR alive the manager refuses to replace a bundle already in the
+     * profile (`already-installed`), so the host's own update semantics are
+     * remove-then-install. That is NOT self-replacement: a human gesture started
+     * it, the manager still performs every file operation, and it unloads the
+     * live module first — exactly what the host does for any bundle update. If
+     * the reinstall fails, the previous version is put back through the same
+     * `installBundle` path.
+     */
+    apply(version: string): Promise<PluginUpdateState>;
+}