@deepseek-harness-tui/dsh-tui 0.12.0 → 0.14.0

package/lib/types/adapter/upstream/panels-driver.js

@@ -0,0 +1,159 @@
+/**
+ * Upstream driver for the TUI side-panel capability (ctx.tuiPanels).
+ *
+ * Panels are a register-class capability. The driver performs a real
+ * reversible probe through the host-only panels facade: register a uniquely
+ * named temporary panel, list it, dispose it, then prove the same id can be
+ * registered again (no residue). It never opens the panel during the probe,
+ * so no visible UI mutation is caused.
+ *
+ * Publication is feature-level: register/list are live only after the
+ * reversible no-residue probe; open/close/badge/subscribe are not safely
+ * auto-verifiable and stay degraded.
+ */
+import { randomUUID } from 'node:crypto';
+import { lifecycleFromDetection } from '../kernel/lifecycle.js';
+import { getHostPanelRuntime } from '../../dsh-adapter/panels.js';
+const CAPABILITY = 'host.panels';
+const PANEL_FEATURES = Object.freeze([
+    'host.panels.register',
+    'host.panels.list',
+    'host.panels.open',
+    'host.panels.close',
+    'host.panels.badge',
+    'host.panels.subscribe',
+]);
+function serviceEvidence(id) {
+    return { kind: 'service', id };
+}
+function methodEvidence(service, method) {
+    return { kind: 'method', id: service + ':' + method };
+}
+function probeEvidence(id, detail) {
+    return { kind: 'probe', id, detail };
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function panelHost(ctx) {
+    const service = ctx?.get?.('tuiPanels');
+    if (service === undefined)
+        return undefined;
+    try {
+        return getHostPanelRuntime(service);
+    }
+    catch {
+        return undefined;
+    }
+}
+function degradedFeature(capability, evidence, missing) {
+    return lifecycleFromDetection(capability, {
+        state: 'degraded',
+        missing: [missing],
+        evidence,
+    });
+}
+function liveFeature(capability, evidence) {
+    return lifecycleFromDetection(capability, {
+        state: 'supported',
+        evidence,
+    });
+}
+export function detectPanelsCapability(ctx) {
+    const service = ctx?.get?.('tuiPanels');
+    if (service === undefined) {
+        return { state: 'unsupported', reason: 'tuiPanels service is not mounted' };
+    }
+    const evidence = [serviceEvidence('tuiPanels')];
+    const host = panelHost(ctx);
+    if (host === undefined) {
+        return { state: 'degraded', missing: ['tuiPanels host facade'], evidence };
+    }
+    const methods = ['register', 'list', 'open', 'close', 'subscribe'];
+    for (const method of methods) {
+        if (typeof host[method] === 'function') {
+            evidence.push(methodEvidence('tuiPanels', method));
+        }
+        else {
+            return { state: 'degraded', missing: ['tuiPanels.' + method + '()'], evidence };
+        }
+    }
+    return { state: 'supported', evidence };
+}
+async function verifyPanelsLive(ctx) {
+    const host = panelHost(ctx);
+    const baseEvidence = [serviceEvidence('tuiPanels')];
+    if (host === undefined) {
+        return PANEL_FEATURES.map(feature => degradedFeature(feature, baseEvidence, feature + '.live-probe'));
+    }
+    const evidence = [serviceEvidence('tuiPanels')];
+    const id = 'dsh_tui_probe:' + randomUUID().replace(/-/g, '').slice(0, 12);
+    let dispose;
+    let registerLive = false;
+    try {
+        dispose = host.register({ id, title: 'dsh-tui reversible panel probe' });
+        const listed = host.list();
+        if (!Array.isArray(listed) || !listed.some(panel => panel.id === id)) {
+            throw new Error('temporary panel was not visible through list()');
+        }
+        evidence.push(probeEvidence('tuiPanels.register+dispose(' + id + ')', 'temporary panel registered and listed'));
+        dispose();
+        dispose = undefined;
+        // No-residue proof: the same id must be registrable again.
+        const second = host.register({ id, title: 'dsh-tui reversible panel probe' });
+        second();
+        evidence.push(probeEvidence('tuiPanels.dispose(' + id + ')', 'temporary panel removed; same id re-register succeeded'));
+        registerLive = true;
+    }
+    catch (error) {
+        evidence.push(probeEvidence('tuiPanels.reversible-live-probe', errorText(error)));
+    }
+    finally {
+        try {
+            dispose?.();
+        }
+        catch {
+            // Best-effort cleanup.
+        }
+    }
+    const out = [];
+    out.push(registerLive
+        ? liveFeature('host.panels.register', evidence)
+        : degradedFeature('host.panels.register', evidence, 'tuiPanels.reversible-live-probe'));
+    if (registerLive) {
+        out.push(liveFeature('host.panels.list', [
+            serviceEvidence('tuiPanels'),
+            methodEvidence('tuiPanels', 'list'),
+            probeEvidence('tuiPanels.list()', 'temporary panel visible through list()'),
+        ]));
+    }
+    else {
+        out.push(degradedFeature('host.panels.list', [serviceEvidence('tuiPanels'), methodEvidence('tuiPanels', 'list')], 'tuiPanels.list() live-probe'));
+    }
+    for (const feature of ['host.panels.open', 'host.panels.close', 'host.panels.badge', 'host.panels.subscribe']) {
+        out.push(degradedFeature(feature, [serviceEvidence('tuiPanels')], feature + '.live-probe'));
+    }
+    return out;
+}
+function createPanelsPort(host) {
+    return Object.freeze({
+        register: descriptor => host.register(descriptor),
+        list: () => host.list(),
+        open: id => host.open(id),
+        close: id => host.close(id),
+        subscribe: listener => host.subscribe(listener),
+    });
+}
+export const panelsDriver = {
+    id: 'dsh-tui-panels',
+    upstreamFamily: 'dsh-tui',
+    capability: 'host.panels',
+    mountEffectClass: 'register',
+    detect: detectPanelsCapability,
+    verifyLive: verifyPanelsLive,
+    async mount(context) {
+        const host = panelHost(context);
+        const ports = host === undefined ? undefined : { panels: createPanelsPort(host) };
+        return { disposer: () => undefined, ...(ports === undefined ? {} : { ports }) };
+    },
+};

package/lib/types/agent/backend.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Backend registry contract: how a backend is detected, how a session is
+ * opened, and its offline catalog.
+ */
+import type { PreviewEntry, SessionSummary } from '../adapter/ports/channel-session.js';
+import type { AgentSession } from './session.js';
+/** What `detect()` found. Detection never throws: failures land here. */
+export interface BackendDetection {
+    readonly installed: boolean;
+    /**
+     * Whether a credential the backend can use was found without a network
+     * call: `unknown` when the backend cannot tell (a platform keychain).
+     */
+    readonly auth?: 'ok' | 'missing' | 'unknown';
+    readonly version?: string;
+    /** A version outside the validated range (warn, never block). */
+    readonly drift?: string;
+    /** How to install or sign in when unavailable. */
+    readonly hint?: string;
+    /**
+     * A missing credential can be supplied after the session opened (the
+     * backend's own `/login`): the kernel picker keeps the row selectable and
+     * says to sign in after start, instead of dimming it.
+     */
+    readonly loginInSession?: true;
+}
+/**
+ * One-click install surface for an optional backend's SDK peer (the Claude
+ * backend's wizard is the first consumer). These types live here so the UI
+ * layer can read them without importing a backend package; the install
+ * implementation itself stays inside the backend.
+ */
+export type SdkInstallTarget = {
+    readonly kind: 'profile';
+    readonly dir: string;
+} | {
+    readonly kind: 'standalone';
+} | {
+    readonly kind: 'no-profile';
+};
+/** How `pnpm add` ended; `tail` carries the captured output's last lines. */
+export type SdkInstallResult = {
+    readonly kind: 'ok';
+} | {
+    readonly kind: 'cancelled';
+} | {
+    readonly kind: 'pnpm-missing';
+} | {
+    readonly kind: 'failed';
+    readonly exitCode: number;
+    readonly tail: readonly string[];
+};
+/** A running install: `result` settles once, `cancel` kills the child. */
+export interface SdkInstaller {
+    readonly result: Promise<SdkInstallResult>;
+    readonly cancel: () => void;
+}
+/** Which session to open. */
+export type OpenTarget = {
+    readonly kind: 'create';
+    readonly cwd: string;
+}
+/** A persisted session of this backend. `cwd` narrows where the backend
+ *  looks for it (absent = the session's own recorded directory, else
+ *  every project the backend knows). */
+ | {
+    readonly kind: 'resume';
+    readonly sessionId: string;
+    readonly cwd?: string;
+};
+/** A usable OAuth access token and its expiry (epoch ms). Token material:
+ *  only ever handed to the backend's child process, never logged. */
+export interface OAuthAccess {
+    readonly access: string;
+    readonly expires: number;
+}
+/** The host's stored OAuth login for one provider (dsh-auth on DSH hosts). */
+export interface OAuthCredentialSource {
+    /**
+     * The stored credential, refreshed first when it is about to expire;
+     * undefined when none is stored. Rejects when a needed refresh fails.
+     *
+     * `rejected` is the access token the backend just refused: it is refreshed
+     * only while the store still holds that very token (compare-and-swap). A
+     * credential rotated meanwhile (a fresh `/login`, another process's
+     * refresh) is returned as is, never force-refreshed.
+     */
+    fresh(options?: {
+        readonly rejected?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<OAuthAccess | undefined>;
+    /** Whether a credential is stored, without touching the network. */
+    stored(): Promise<boolean>;
+}
+/** Host-owned credential refs; token material never enters events or logs. */
+export interface BackendTokenStore {
+    read(ref: string): string | undefined;
+    write(ref: string, value: string): void;
+    erase(ref: string): void;
+    declared(ref: string): boolean;
+}
+/** Host services a backend may use while detecting or opening. */
+export interface BackendHost {
+    readonly cwd: string;
+    /** Stored channel tokens, when the host provides its credential service. */
+    readonly tokenStore?: BackendTokenStore;
+    /** Opt-in diagnostics; never stdout while the TUI renders. */
+    debug(message: string): void;
+    /** User-visible warning (localized by the caller). */
+    warn(message: string): void;
+    /** One line a backend child process wrote to stderr (never the terminal:
+     *  the host logs it and folds repeats into notices). */
+    stderr?(line: string): void;
+    /** The host's stored OAuth login for a provider id (`anthropic`), when the
+     *  host keeps one. */
+    oauthCredential?(provider: string): OAuthCredentialSource | undefined;
+}
+/** Where an offline listing looks. */
+export interface SessionListScope {
+    /** The project directory (and its worktrees, where the backend groups
+     *  them); absent = the host's working directory. */
+    readonly cwd?: string;
+    /** Every project the backend knows (`cwd` is then ignored). */
+    readonly allProjects?: boolean;
+}
+/**
+ * A backend's offline session catalog: no session needs to be open. Rows
+ * are the browser's own `SessionSummary` shape with `backendId` set. The
+ * backend's own store stays authoritative; the TUI indexes nothing beyond
+ * what the catalog itself caches.
+ */
+export interface SessionCatalog {
+    list(scope?: SessionListScope): Promise<readonly SessionSummary[]>;
+    /** One session's row, or undefined when the backend has no such session. */
+    info?(sessionId: string, cwd?: string): Promise<SessionSummary | undefined>;
+    /** The trailing exchanges of a session (browser preview), newest last. */
+    preview?(sessionId: string, options?: {
+        readonly cwd?: string;
+        readonly limit?: number;
+    }): Promise<readonly PreviewEntry[]>;
+    rename?(sessionId: string, title: string, cwd?: string): Promise<void>;
+    delete?(sessionId: string, cwd?: string): Promise<void>;
+    /** Omitted means deletion; archive keeps the backend's durable transcript. */
+    readonly deleteAction?: 'archive';
+}
+/** Backend-scoped launcher marker and session browser usage notes. */
+export interface BackendSessionPrefs {
+    lastSession(): string | undefined;
+    setLastSession(sessionId: string): void;
+    touch(sessionId: string): void;
+    forget(sessionId: string): void;
+}
+/** One agent backend. */
+export interface AgentBackend {
+    /** `dsh` | `claude` | `acp:<agent>`. */
+    readonly id: string;
+    readonly descriptor: {
+        readonly label: string;
+    };
+    detect(host: BackendHost): Promise<BackendDetection>;
+    open(target: OpenTarget, host: BackendHost): Promise<AgentSession>;
+    readonly catalog?: SessionCatalog;
+    readonly launch?: {
+        sessionPrefs(debug: (message: string) => void): BackendSessionPrefs;
+        resumeCommand(sessionId: string): string;
+    };
+}
+//# sourceMappingURL=backend.d.ts.map

package/lib/types/agent/backend.d.ts.map

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

package/lib/types/agent/backend.js

@@ -0,0 +1 @@
+export {};