@wfm-cn/dsh-storage 0.0.0-stage → 0.2.0

package/lib/notify.js

@@ -0,0 +1,56 @@
+/**
+ * 同步中断/恢复通知 (Task 6): the host side records toast notifications on
+ * HealthMonitor transitions; the browser client (src/client/toast.tsx) polls
+ * them through the status bridge and renders a React portal independent of
+ * the settings panel. The monitor already guarantees transitions only
+ * (same-state results never re-fire), so each record is a real state change.
+ */
+const MAX_TOASTS = 20;
+let nextId = 1;
+const toasts = [];
+/** 中断 toast: good → bad. */
+export function notifyGoodToBad(lastError) {
+    return push({
+        kind: 'interrupted',
+        // No "点击查看" suffix: the toast's click only dismisses — the DSH host
+        // exposes no navigation API reachable from the body-mounted portal, so
+        // the copy must not promise a click-through.
+        text: `⚠️ 会话同步中断：${lastError ?? '未知错误'}`,
+    });
+}
+/** 恢复 toast: bad → good, with a backfill hint for the gap. */
+export function notifyBadToGood() {
+    return push({
+        kind: 'recovered',
+        text: '✅ 会话同步已恢复',
+        hint: '如中断期间有新会话，可在设置面板点「补传」补齐',
+    });
+}
+function push(record) {
+    const toast = { ...record, id: nextId++, createdAt: Date.now() };
+    toasts.push(toast);
+    if (toasts.length > MAX_TOASTS)
+        toasts.splice(0, toasts.length - MAX_TOASTS);
+    return toast;
+}
+/** Records newer than `sinceId` (polling cursor for the client). */
+export function drainToasts(sinceId = 0) {
+    return toasts.filter((toast) => toast.id > sinceId);
+}
+/** Test/reset hook: drop all history. */
+export function clearToasts() {
+    toasts.length = 0;
+}
+/**
+ * Wire the toast records onto a monitor's transitions. Good→bad strictly
+ * means ok → down (a config error was never "good"); bad→good covers
+ * down → ok and config-error → ok.
+ */
+export function wireNotifications(monitor) {
+    return monitor.onTransition((to, from, status) => {
+        if (to === 'down' && from === 'ok')
+            notifyGoodToBad(status?.lastError);
+        else if (to === 'ok' && (from === 'down' || from === 'config-error'))
+            notifyBadToGood();
+    });
+}

package/lib/projector.js

@@ -0,0 +1,191 @@
+/**
+ * Projects dsh session events onto MessageRow / SessionRow.
+ *
+ * Event shapes verified against the dsh persistence catalog
+ * (https://deepseek-harness.github.io/deepseek-harness/reference/persistence-catalog)
+ * and the @deepseek-ai/dsh-llm message types:
+ * - envelope: `{ type, seq, time, data }` — payload lives under `data`.
+ * - `user/message` and `assistant/message` produce rows; `tool/result` updates
+ *   the matching assistant row's toolCalls instead of producing a tool row.
+ * - token usage (V3 log): `assistant/message.data.usage` is the settled
+ *   step's accounting; a failed/cancelled attempt commits `assistant/attempt`
+ *   instead, with the adapter's usage chunk preserved as a raw record in its
+ *   embedded compact stream (recovered in usageSampleOf). `turn/end` carries
+ *   none — it only serves as a rollup checkpoint.
+ * - compaction summaries enter the surface as a `user/message` with
+ *   `surfaceOp: replace`, so they flow through the user path unchanged.
+ */
+import { randomUUID } from 'node:crypto';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** Visible text of a message: its `text` blocks, unwrapping tool-result blocks. */
+function textOf(message) {
+    const blocks = Array.isArray(message?.content) ? message.content : [];
+    return blocks
+        .map((b) => {
+        if (b?.type === 'text')
+            return b.text ?? '';
+        if (b?.type === 'tool-result' && Array.isArray(b.content))
+            return textOf({ content: b.content });
+        return '';
+    })
+        .join('');
+}
+/** Reasoning blocks of an assistant message, in their original order. */
+function thoughtsOf(message) {
+    const blocks = Array.isArray(message?.content) ? message.content : [];
+    const replay = message?.source?.replayState?.blocks;
+    const thoughts = blocks
+        .map((b, index) => {
+        if (b?.type !== 'reasoning' || !b.text)
+            return null;
+        const metadata = Array.isArray(replay) ? replay[index] : undefined;
+        const signature = metadata?.type === 'reasoning'
+            ? (metadata.signature ?? metadata.thoughtSignature)
+            : undefined;
+        return {
+            content: b.text,
+            ...(typeof signature === 'string' ? { thoughtSignature: signature } : {}),
+        };
+    })
+        .filter((thought) => thought !== null);
+    return thoughts.length ? thoughts : undefined;
+}
+function toolPartsOf(message) {
+    const blocks = Array.isArray(message?.content) ? message.content : [];
+    const calls = blocks.filter((b) => b?.type === 'tool-call');
+    return calls.length > 0 ? calls : undefined;
+}
+/**
+ * Map one session event to zero or one message row. Returns null for events
+ * that should not be persisted as standalone rows (log-only events: chunks,
+ * turn/step lifecycle, approvals, ...).
+ */
+export function projectEvent(_session, event, sessionId) {
+    const data = event?.data ?? {};
+    const base = {
+        sessionId,
+        historyId: null,
+        agentId: 'main',
+        createdAt: new Date(event?.time ?? Date.now()),
+    };
+    switch (event?.type) {
+        case 'user/message': {
+            // data IS the UserMessage.
+            const message = data;
+            return {
+                ...base,
+                id: message.id ?? randomUUID(),
+                type: 'user',
+                content: textOf(message),
+                metadata: { event: event.type, seq: event.seq, message },
+            };
+        }
+        case 'assistant/message': {
+            const message = data.message;
+            return {
+                ...base,
+                id: message?.id ?? randomUUID(),
+                type: 'model',
+                content: textOf(message),
+                thoughts: thoughtsOf(message),
+                model: message?.source?.model ?? undefined,
+                tokens: data.usage ?? undefined,
+                toolCalls: toolPartsOf(message),
+                metadata: {
+                    event: event.type,
+                    seq: event.seq,
+                    ...(message?.source ? { source: message.source } : {}),
+                    ...(data.interrupted ? { interrupted: true } : {}),
+                },
+            };
+        }
+        default:
+            // Log-only events (assistant/attempt, turn/step lifecycle, approvals,
+            // compaction markers, ...) are not standalone rows; usage rolls up into
+            // SessionRow via usageSampleOf (assistant/message and assistant/attempt).
+            return null;
+    }
+}
+/** Identify the assistant tool call answered by either supported result shape. */
+export function toolResultCallId(event) {
+    const message = event?.data?.message;
+    const first = message?.content?.[0];
+    const callId = message?.toolCallId ??
+        message?.source?.callId ??
+        (first?.type === 'tool-result' ? first.toolCallId : undefined);
+    return typeof callId === 'string' ? callId : undefined;
+}
+/** Update the persisted assistant call identified by a tool result. */
+export function mergeToolResult(event, rows) {
+    const message = event?.data?.message;
+    const content = Array.isArray(message?.content) ? message.content : [];
+    const legacy = content.length === 1 && content[0]?.type === 'tool-result' ? content[0] : undefined;
+    const callId = toolResultCallId(event);
+    if (!callId)
+        return null;
+    const result = legacy ??
+        (message
+            ? {
+                type: 'tool-result',
+                toolCallId: callId,
+                content,
+                ...(typeof message.isError === 'boolean' ? { isError: message.isError } : {}),
+            }
+            : null);
+    const model = [...rows]
+        .reverse()
+        .find((row) => row.type === 'model' &&
+        Array.isArray(row.toolCalls) &&
+        row.toolCalls.some((call) => call?.id === callId));
+    if (!model)
+        return null;
+    return {
+        ...model,
+        toolCalls: model.toolCalls.map((call) => call?.id === callId
+            ? {
+                ...call,
+                result,
+                error: event.data.error
+                    ? { name: event.data.error.name, code: event.data.error.code }
+                    : undefined,
+            }
+            : call),
+    };
+}
+/**
+ * Extract one model call's usage, keyed by its durable event sequence.
+ *
+ * V3 session log (dsh-session@0.1.6-alpha.2):
+ * - `assistant/message.data.usage` — the settled call's accounting;
+ * - `assistant/attempt` — a failed/retried/cancelled call commits no surface
+ *   message; the adapter's usage chunk survives as a raw `chunk` record in the
+ *   embedded compact `stream` (deltas are packed, but usage is a raw type).
+ *
+ * Calls on one `(turn, step)` are additive: a retry is another billed model
+ * call, not a progressive snapshot. Only redelivery of the same event sequence
+ * is a duplicate. Totals include the cache buckets: cacheRead/cacheWrite are
+ * billed in their own buckets (observed cacheReadTokens ≫ inputTokens in dsh
+ * session logs — they are not subsets of inputTokens).
+ */
+export function usageSampleOf(event) {
+    const total = (u) => ({
+        input: (u?.inputTokens ?? 0) + (u?.cacheReadTokens ?? 0) + (u?.cacheWriteTokens ?? 0),
+        output: u?.outputTokens ?? 0,
+    });
+    let data;
+    let usage;
+    if (event?.type === 'assistant/message') {
+        data = event.data;
+        usage = data?.usage;
+    }
+    else if (event?.type === 'assistant/attempt') {
+        data = event.data;
+        usage = (Array.isArray(data?.stream) ? data.stream : []).find((r) => r?.type === 'chunk' && r.chunk?.type === 'usage')?.chunk?.usage;
+    }
+    else {
+        return null;
+    }
+    if (!usage || !Number.isSafeInteger(event?.seq))
+        return null;
+    return { key: String(event.seq), sample: total(usage) };
+}

package/lib/status-route.js

@@ -0,0 +1,172 @@
+/**
+ * Host→browser bridge for the settings panel: exposes the dshStorageStatus
+ * service over the DSH connection generic-RPC channel `/dsh-storage`.
+ *
+ * Pattern verified against the installed reference plugins (ds-harness-remote
+ * `registerControlRoute`, dsh-video-skin settings.section client): the browser
+ * client calls `ctx.connection.rpc.call('/dsh-storage', endpoint, payload)`,
+ * which POSTs `{type:'client-request', rpcId, method, payload}` to
+ * `/<channel>/<endpoint>` and expects `{type:'server-response', rpcId,
+ * result:{ok:true,value}|{ok:false,error:{code,message,details}}}`. When the
+ * webServer service is available we serve that path with a prefix route
+ * (guarded by `connection.requestRejection` for authentication); otherwise we
+ * fall back to `connection.rpc.handle` for in-process carriers. Both halves
+ * stay optional (`ctx.get`), so profiles without a web carrier simply skip
+ * the bridge.
+ */
+import { syncConfigProblem } from './config.js';
+export const STATUS_CHANNEL = '/dsh-storage';
+const ENDPOINT_SEGMENT = /^[A-Za-z0-9_$.-]+$/;
+function badRequest(message) {
+    return { ok: false, error: { code: 'gateway/bad-request', message, details: {} } };
+}
+/**
+ * Guard for cfg-taking endpoints. Rejections name the offending field (via
+ * syncConfigProblem) so a cleared/NaN port surfaces as 'cfg.port must be…',
+ * not a misleading generic 'requires a cfg object'.
+ */
+function cfgGuard(endpoint, cfg) {
+    const problem = syncConfigProblem(cfg);
+    return problem === undefined
+        ? { cfg: cfg }
+        : { error: { code: 'gateway/bad-request', message: `${endpoint}: ${problem}`, details: {} } };
+}
+/** Dispatch one endpoint; never throws — failures become ok:false results. */
+async function dispatch(service, endpoint, payload) {
+    const body = (typeof payload === 'object' && payload !== null ? payload : {});
+    try {
+        switch (endpoint) {
+            case 'snapshot':
+                return { ok: true, value: service.snapshot() };
+            case 'testConnection': {
+                const guarded = cfgGuard('testConnection', body.cfg);
+                if ('error' in guarded)
+                    return { ok: false, error: guarded.error };
+                return { ok: true, value: await service.testConnection(guarded.cfg) };
+            }
+            case 'createTables': {
+                const guarded = cfgGuard('createTables', body.cfg);
+                if ('error' in guarded)
+                    return { ok: false, error: guarded.error };
+                return { ok: true, value: await service.createTables(guarded.cfg) };
+            }
+            case 'getConfig':
+                return { ok: true, value: service.getConfig() };
+            case 'saveConfig': {
+                const guarded = cfgGuard('saveConfig', body.cfg);
+                if ('error' in guarded)
+                    return { ok: false, error: guarded.error };
+                return { ok: true, value: service.saveConfig(guarded.cfg) };
+            }
+            case 'backfill':
+                return { ok: true, value: await service.backfill() };
+            case 'toasts':
+                if (body.sinceId !== undefined && typeof body.sinceId !== 'number')
+                    return badRequest('toasts sinceId must be a number');
+                return { ok: true, value: service.toasts({ sinceId: body.sinceId }) };
+            default:
+                return badRequest(`unknown endpoint ${JSON.stringify(endpoint)}`);
+        }
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: {
+                code: 'gateway/internal',
+                message: error instanceof Error ? error.message : String(error),
+                details: {},
+            },
+        };
+    }
+}
+function endpointFromPath(pathname) {
+    if (!pathname.startsWith(`${STATUS_CHANNEL}/`))
+        return undefined;
+    const endpoint = pathname.slice(STATUS_CHANNEL.length + 1);
+    if (!ENDPOINT_SEGMENT.test(endpoint))
+        return undefined;
+    return endpoint;
+}
+function parseClientRequest(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const v = value;
+    if (v.type !== 'client-request' || typeof v.rpcId !== 'string' || typeof v.method !== 'string')
+        return undefined;
+    return { type: 'client-request', rpcId: v.rpcId, method: v.method, payload: v.payload };
+}
+function writeJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function fullResponse(rpcId, result) {
+    return { type: 'server-response', rpcId, result };
+}
+/**
+ * Register the /dsh-storage channel. Wire order mirrors ds-harness-remote's
+ * control route: an authenticated webServer prefix route when both services
+ * allow it, otherwise connection.rpc.handle for logical carriers.
+ */
+export function registerStatusRoute(ctx, service) {
+    const connection = ctx.get('connection');
+    if (!connection)
+        return undefined;
+    const handler = (endpoint, payload) => dispatch(service, endpoint, payload);
+    const webServer = ctx.get('webServer');
+    if (webServer !== undefined && connection.requestRejection !== undefined) {
+        const dispose = webServer.register({
+            kind: 'prefix',
+            path: STATUS_CHANNEL,
+            handler: async (req, res) => {
+                const rejection = connection.requestRejection?.(req);
+                if (rejection !== undefined) {
+                    res.writeHead(rejection);
+                    res.end(rejection === 401 ? 'unauthorized' : 'forbidden');
+                    return;
+                }
+                const endpoint = endpointFromPath(new URL(req.url ?? '/', 'http://dsh.internal').pathname);
+                if (req.method !== 'POST' || endpoint === undefined) {
+                    writeJson(res, 404, 'not found');
+                    return;
+                }
+                const contentType = Array.isArray(req.headers?.['content-type'])
+                    ? req.headers['content-type'][0]
+                    : req.headers?.['content-type'];
+                if ((contentType ?? '').split(';', 1)[0]?.trim().toLowerCase() !== 'application/json') {
+                    writeJson(res, 415, 'content type must be application/json');
+                    return;
+                }
+                let body;
+                try {
+                    const chunks = [];
+                    for await (const chunk of req) {
+                        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                    }
+                    body = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+                }
+                catch {
+                    writeJson(res, 400, 'body is not JSON');
+                    return;
+                }
+                const message = parseClientRequest(body);
+                if (message === undefined || message.method !== endpoint) {
+                    writeJson(res, 200, fullResponse('invalid-request', badRequest('invalid client-request message')));
+                    return;
+                }
+                try {
+                    writeJson(res, 200, fullResponse(message.rpcId, await handler(endpoint, message.payload)));
+                }
+                catch (error) {
+                    res.writeHead(500);
+                    res.end(`handler failure: ${String(error)}`);
+                }
+            },
+        });
+        return () => void dispose();
+    }
+    const rpcHandle = connection.rpc?.handle;
+    if (rpcHandle === undefined)
+        return undefined;
+    const dispose = rpcHandle(STATUS_CHANNEL, handler, { authority: 'loopback' });
+    return () => void dispose();
+}

package/lib/types/backends/database.d.ts

@@ -0,0 +1,78 @@
+/**
+ * MySQL/PostgreSQL/SQLite/SQL Server backend via Prisma 7. The clients are
+ * pre-generated at package build time (`pnpm generate`, see
+ * scripts/prisma-generate.mjs) from the schema variants in prisma/ and
+ * shipped compiled in lib/generated — consumers never run `prisma generate`.
+ *
+ * Prisma 7 requires a driver adapter per database; `@prisma/client` and the
+ * adapter for your provider are optional peer dependencies (sqlite uses
+ * `@prisma/adapter-libsql` — no native build scripts, unlike
+ * `@prisma/adapter-better-sqlite3`). Table creation
+ * (`prisma db push` / migrations) uses the shipped schema variant with the
+ * connection URL in the user's prisma.config.ts.
+ */
+import type { MessageRow, SessionRow, StorageBackend } from '../types.js';
+export type DatabaseProvider = 'mysql' | 'postgresql' | 'sqlite' | 'sqlserver';
+export interface DatabaseBackendConfig {
+    provider: DatabaseProvider;
+    /** Full connection URL, e.g. mysql://user:pass@host:3306/dbname, file:/data/dsh.db */
+    url: string;
+    /**
+     * IANA-named offset for the mariadb driver's `timezone` option (e.g.
+     * '+08:00'), applied when writing DATETIME columns. Only used by mysql.
+     */
+    timezone?: string;
+    /**
+     * Device identifier stamped on every ai_messages / ai_chat_histories row
+     * this backend writes, so several machines can share one database.
+     * Falls back to the OS hostname when unset.
+     */
+    device?: string;
+}
+/**
+ * Parse mysql://user:password@host[:port]/database into discrete connection
+ * options for the mariadb driver adapter. Passing the URI string itself
+ * pool-times-out in production (verified against a real MySQL 8.4);
+ * discrete host/port/user/password/database options work. Components are
+ * percent-decoded — credentials with @ : / arrive encoded in the URL.
+ */
+export declare function parseMysqlUrl(url: string): {
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    database: string;
+};
+export declare function createAdapter(config: DatabaseBackendConfig): Promise<unknown>;
+export declare class DatabaseBackend implements StorageBackend {
+    private config;
+    readonly name = "database";
+    private prisma;
+    constructor(config: DatabaseBackendConfig);
+    /** Device identifier stamped on rows written through this backend. */
+    private get device();
+    private client;
+    /** Load the pre-generated client for the configured provider (seam for tests). */
+    protected loadClient(): Promise<any>;
+    init(): Promise<void>;
+    /** JSON column value, text-serialized on SQL Server (no Prisma Json type). */
+    private jsonField;
+    private toDbData;
+    private writeMessage;
+    upsertMessage(row: MessageRow): Promise<void>;
+    readMessages(sessionId: string, messageId: string): Promise<MessageRow[]>;
+    readToolCallMessages(sessionId: string, callId: string): Promise<MessageRow[]>;
+    private readRows;
+    readSession(sessionId: string): Promise<SessionRow | null>;
+    /**
+     * Max created_at per session over active message rows — the database-side
+     * watermark for backfill gap detection (sessions with newer local logs
+     * have missing events).
+     */
+    latestPerSession(): Promise<Map<string, Date>>;
+    private writeSession;
+    upsertSession(row: SessionRow): Promise<void>;
+    upsertEvent(message: MessageRow | null, session: SessionRow): Promise<void>;
+    archiveSession(sessionId: string): Promise<string | null>;
+    close(): Promise<void>;
+}

package/lib/types/backfill.d.ts

@@ -0,0 +1,67 @@
+import type { StorageBackend } from './types.js';
+/** Exactly the event types the live tap mirrors (see index.ts session/event). */
+export declare const MIRROR_EVENT_TYPES: readonly ["user/message", "assistant/message", "assistant/attempt", "tool/result", "turn/end", "session/title", "compaction/end"];
+interface MirrorEvent {
+    type: string;
+    seq?: number;
+    time?: number;
+    data?: Record<string, unknown>;
+}
+/** Metadata key for the usage high-water mark — shared with the live tap. */
+export declare const LAST_USAGE_KEY = "dsh-storage:lastUsage";
+/** One session with missing events: replay starts at `fromSeq` (inclusive). */
+export interface BackfillGap {
+    sessionId: string;
+    fromSeq: number;
+}
+export interface BackfillSummary {
+    /** Sessions whose events were replayed (excludes reported errors). */
+    sessions: number;
+    /** Message rows written by this run. */
+    replayed: number;
+    /** Events already present in the database (idempotent skips). */
+    skipped: number;
+    /** Per-session failures — one entry per session that could not be replayed. */
+    errors: string[];
+}
+interface LogFile {
+    file: string;
+    mtime: Date;
+}
+interface SessionLog extends LogFile {
+    sessionId: string;
+}
+/**
+ * Read one session log as text. Plain files are read directly; `.zstd` files
+ * are decompressed through the first available system binary.
+ */
+export declare function readSessionLogText(file: string, binaries?: readonly string[]): Promise<string>;
+/** Parse JSONL lines into event objects; malformed lines are skipped. */
+export declare function parseSessionEvents(text: string): MirrorEvent[];
+/**
+ * Enumerate session logs. Real DSH layout is
+ * `<sessionsDir>/<workspace-dir>/<session-id>/session.v4.jsonl[.zstd]`
+ * (two levels); a log directly under a child directory is also accepted so
+ * a flattened sessions dir keeps working.
+ */
+export declare function listSessionLogs(sessionsDir: string): Promise<SessionLog[]>;
+/**
+ * Select sessions whose latest local activity (log mtime) is newer than the
+ * database's last mirrored activity. Sessions absent from the database are
+ * selected for a full replay (fromSeq 0) — but only when their log holds at
+ * least one row-producing event; a log-only session mirrors no rows and its
+ * "gap" would never converge. For known sessions `fromSeq` is the sequence
+ * of the first row-producing event newer than the DB watermark.
+ */
+export declare function computeGap(sessionsDir: string, dbLatestPerSession: Map<string, Date>): Promise<BackfillGap[]>;
+/** computeGap + replayEvents in one call, for the panel button. */
+export declare function backfillAll(sessionsDir: string, backend: StorageBackend & {
+    latestPerSession?(): Promise<Map<string, Date>>;
+}): Promise<BackfillSummary>;
+/**
+ * Replay the missing events of each gap through the projector into the
+ * backend. Idempotent: message rows whose deterministic id already exists
+ * are skipped without error, and the session rollup is never double-counted.
+ */
+export declare function replayEvents(gaps: BackfillGap[], sessionsDir: string, backend: StorageBackend): Promise<BackfillSummary>;
+export {};

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

@@ -0,0 +1,12 @@
+/**
+ * Browser half of dsh-storage: registers the settings panel into the DSH
+ * settings page (`settings.section` slot) and reaches the host plugin's
+ * dshStorageStatus service through the connection generic-RPC channel
+ * /dsh-storage (registered host-side in src/status-route.ts).
+ *
+ * Module shape follows the reference client plugins (dsh-pet, dsh-video-skin,
+ * ds-harness-remote): a `window.__ModuleLoader__.load({ id, factory })` call
+ * whose factory receives the page's `require` — React comes from the host
+ * page, never bundled. Built by esbuild into the single-file lib/client.js.
+ */
+export {};

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

@@ -0,0 +1,79 @@
+/**
+ * Settings-panel component for dsh-storage (会话存储镜像).
+ *
+ * Authored against the reference client plugins (dsh-pet / dsh-video-skin):
+ * the browser half receives React from the host module loader inside the
+ * __ModuleLoader__ factory, so the component is built through a factory that
+ * takes the React module — no module-scope React import survives into the
+ * bundle. All RPC goes through the injected `client` (connection rpc; see
+ * src/client/index.ts), which keeps this file render-pure and testable with
+ * a fake client.
+ */
+import type { SyncConfig } from '../config.js';
+import type { BackfillSummary } from '../backfill.js';
+/** Shapes mirrored from the host (type-only imports — erased in the bundle). */
+export interface HealthStatus {
+    state: 'ok' | 'down' | 'disabled' | 'config-error';
+    lastOkAt?: number;
+    lastError?: string;
+    retryCount: number;
+    mirroredTotal?: number;
+}
+export type TestResult = 'ok' | 'no-tables' | `fail:${string}`;
+/** Promise-based panel API; the client entry implements it over connection rpc. */
+export interface StorageClient {
+    snapshot(): Promise<HealthStatus>;
+    testConnection(cfg: SyncConfig): Promise<TestResult>;
+    createTables(cfg: SyncConfig): Promise<'ok' | `fail:${string}`>;
+    getConfig(): Promise<{
+        config: SyncConfig;
+        error?: 'parse' | 'missing-field';
+    }>;
+    saveConfig(cfg: SyncConfig): Promise<unknown>;
+    backfill(): Promise<BackfillSummary>;
+}
+export declare const DEFAULT_TIMEZONES: string[];
+/** Mirrors config.ts isValidPort — kept local so no node builtins enter the browser bundle. */
+export declare function isValidPort(value: unknown): value is number;
+/**
+ * The cfg object to persist: the port is sent only when it is a valid
+ * integer — a cleared/garbage port field is omitted so the RPC rejects it
+ * with an honest per-field error instead of building a host:NaN URL.
+ */
+export declare function buildSaveConfig(cfg: SyncConfig): SyncConfig;
+/** Structural React surface the factory needs (satisfied by react 18). */
+export interface ReactLike {
+    createElement: any;
+    useState: <S>(initial: S) => [S, (value: S | ((prev: S) => S)) => void];
+    useEffect: (effect: () => void | (() => void), deps?: unknown[]) => void;
+}
+export type Tone = 'ok' | 'warn' | 'bad' | 'idle';
+/** Status-light copy per HealthStatus.state. */
+export declare function statusView(status: HealthStatus): {
+    tone: Tone;
+    label: string;
+    details: string[];
+};
+/** Three-state connection-test copy: green ok / yellow no-tables / red fail. */
+export declare function testResultView(result: TestResult): {
+    tone: Tone;
+    label: string;
+};
+export declare function createResultView(result: 'ok' | `fail:${string}`): {
+    tone: Tone;
+    label: string;
+};
+/** 补传 summary copy: green when clean, yellow when some sessions failed. */
+export declare function backfillResultView(summary: BackfillSummary): {
+    tone: Tone;
+    label: string;
+};
+export interface PanelProps {
+    client: StorageClient;
+    /** Status poll interval; default 30s per the task brief. */
+    pollMs?: number;
+}
+export declare function makeStoragePanel(React: ReactLike): {
+    (props: PanelProps): any;
+    displayName: string;
+};