@yejiming/dsh-data-agent 0.0.6 → 0.0.10

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

@@ -0,0 +1,26 @@
+/**
+ * Reusable chart container (task 3.3): owns one ECharts instance per mount,
+ * resizes it through a ResizeObserver, disposes it on unmount, and exposes an
+ * accessible image role + short text summary. Options arrive pre-built by
+ * chartOptionFor (token theme, non-HTML tooltips, reduced-motion included).
+ * @module @yejiming/dsh-data-agent/client/AnalysisChart
+ */
+import type { EChartsCoreOption } from 'echarts/core';
+/** Chart container props. */
+export interface AnalysisChartProps {
+    /** Safe pre-built option (pure mapping of the constrained report). */
+    option: EChartsCoreOption;
+    /** Accessible name of the chart image. */
+    ariaLabel: string;
+    /** Short plain-text summary announced to assistive tech. */
+    summary: string;
+    /** Chart canvas height in px (the container always spans full width). */
+    height?: number;
+}
+/**
+ * One chart instance: init on mount, setOption on every option change (theme
+ * switches rebuild the option), resize on container changes, dispose on
+ * unmount. Null data points render as gaps because numericOrNull never
+ * converts null to zero.
+ */
+export declare function AnalysisChart({ option, ariaLabel, summary, height }: AnalysisChartProps): import("react").JSX.Element;

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

@@ -0,0 +1,30 @@
+/**
+ * render-analysis tool result row + Dashboard Modal (tasks 3.4, 4.x).
+ *
+ * The row is registered for the keyed tool.call.toolview slot under
+ * key: render-analysis. It is a pure function of the frozen ToolCallBlock
+ * owner payload (decoded by analysis-view-model): running/error/interrupted
+ * statuses, a compact summary for complex reports, a bounded inline preview
+ * for the simple single-chart report, and a native "查看分析" button that
+ * opens THIS call's own Dashboard Modal (local state — one session may hold
+ * many independent reports).
+ *
+ * The Modal reuses the host primitives Modal (Escape/mask close) headless,
+ * keeps its own header fixed, scrolls the body independently, and returns
+ * focus to the trigger button on close. All interactive elements are native
+ * buttons; every chart carries an aria-label plus a plain-text summary; all
+ * cell/label/axis values render as text (React escaping + ECharts richText),
+ * so no report field can become executable DOM.
+ * @module @yejiming/dsh-data-agent/client/AnalysisDashboard
+ */
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client';
+import { type AnalysisViewV1, type AnalysisViewWidth } from '../analysis.ts';
+/** Full row props: the toolview runtime share + the data-agent locale seat. */
+export type RenderAnalysisRowProps = ToolCallViewProps & PropsLocale<'data-agent'>;
+/** Effective grid width per view id: tables and the first chart default full. */
+export declare function computeViewWidths(views: readonly AnalysisViewV1[]): Map<string, AnalysisViewWidth>;
+/** Format one metric value without ever inventing data. */
+export declare function formatMetricValue(value: string | null, format: 'number' | 'percent' | undefined, empty: string): string;
+/** The registered render-analysis tool result row. */
+export declare function RenderAnalysisRow({ toolName, block, t }: RenderAnalysisRowProps): import("react").JSX.Element;

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

@@ -16,7 +16,7 @@ export interface DataAgentWorkbenchInjected {
         };
     };
 }
-/** The workbench's full component props: the dock seat + the locale seat + the injected sessions hook. */
-export type DataAgentWorkbenchProps = PropsRuntime<'conversation.input.dock'> & PropsLocale<'data-agent'> & InjectFace<DataAgentWorkbenchInjected>;
+/** The workbench's full component props: the composer-right seat + locale + sessions hook. */
+export type DataAgentWorkbenchProps = PropsRuntime<'conversation.input.right'> & PropsLocale<'data-agent'> & InjectFace<DataAgentWorkbenchInjected>;
 /** The database workbench body. */
 export declare function DataAgentWorkbench({ sessionId, useSessions, t }: DataAgentWorkbenchProps): import("react").JSX.Element | null;

package/lib/types/client/analysis-charts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Safe ECharts mapping for the analysis dashboard (tasks 3.2/3.3). Only the
+ * four first-version chart types and their required components are registered
+ * from echarts/core — line/bar/pie/scatter + grid/tooltip/legend/aria with
+ * the SVG renderer — so the client bundle stays tree-shaken per chart type.
+ *
+ * Every option is a PURE mapping of the constrained AnalysisReportV1 (the
+ * client never aggregates, sorts, or null→0 converts), tooltips use the
+ * non-HTML richText render mode, all labels/values stay text, and the series
+ * palette is finite, colorblind-safe, and stable by series NAME (the same
+ * series name gets the same color across every view of one report).
+ * @module @yejiming/dsh-data-agent/client/analysis-charts
+ */
+import type { EChartsCoreOption } from 'echarts/core';
+import { type AnalysisDatasetResultV1, type AnalysisViewV1 } from '../analysis.ts';
+/** Colorblind-safe, finite series palette (Tableau 10 order). */
+export declare const ANALYSIS_PALETTE: readonly ["#4e79a7", "#f28e2b", "#59a14f", "#e15759", "#76b7b2", "#edc948", "#b07aa1", "#9c755f"];
+/** Stable color per series NAME: same name → same color in every view. */
+export declare function seriesColor(name: string): string;
+/** DSH token values the charts need (fallback constants for non-DOM tests). */
+export interface ChartThemeTokens {
+    fontFamily: string;
+    text: string;
+    textSecondary: string;
+    border: string;
+    background: string;
+    tooltipBorder: string;
+    grid: string;
+}
+/** Read the host's DSH tokens once per render (falls back off-DOM). */
+export declare function readChartThemeTokens(): ChartThemeTokens;
+/** Whether the environment asks for reduced motion. */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Map one constrained view + dataset pair to a safe ECharts option. Returns an
+ * empty option for metric/table views (they never reach the chart component).
+ */
+export declare function chartOptionFor(view: AnalysisViewV1, dataset: AnalysisDatasetResultV1, tokens: ChartThemeTokens, ariaLabel: string): EChartsCoreOption;
+/** Short plain-text summary of one chart (the accessible text description). */
+export declare function chartTextSummary(view: AnalysisViewV1, dataset: AnalysisDatasetResultV1, kindLabel: string): string;

package/lib/types/client/analysis-view-model.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Frozen-session decoder for render-analysis tool results (task 3.1). The
+ * component owns NO database state: everything derives from the frozen
+ * ToolCallBlock the slot owner supplies, so history replay is a pure function
+ * of the persisted meta and never touches the database, HTTP routes, or any
+ * storage domain.
+ *
+ * States:
+ * - running: tool/call seen, tool/result not yet;
+ * - error / interrupted: settled with an error outcome (interrupted carries
+ *   the host's interrupted error code);
+ * - report: settled with a valid AnalysisReportV1 meta;
+ * - fallback: missing, malformed, string-encoded or unknown-version meta —
+ *   degrade to the safe model content text, never guess or re-query.
+ * @module @yejiming/dsh-data-agent/client/analysis-view-model
+ */
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client';
+import { type AnalysisReportV1 } from '../analysis.ts';
+/** The five display states of one render-analysis call. */
+export type AnalysisBlockState = 'running' | 'error' | 'interrupted' | 'report' | 'fallback';
+/** Decoded view model for one frozen block. */
+export interface AnalysisViewModel {
+    state: AnalysisBlockState;
+    /** Valid version-1 report (state=report only). */
+    report?: AnalysisReportV1;
+    /** Safe error text (state=error/interrupted). */
+    errorText?: string;
+    /** Safe model content text (state=fallback). */
+    fallbackText?: string;
+}
+/** Join the text blocks of a settled result into one safe plain string. */
+export declare function contentText(content: readonly unknown[]): string;
+/**
+ * Decode one frozen ToolCallBlock into the display view model. The block is
+ * treated as immutable input; no lookups, no queries, no throws.
+ */
+export declare function decodeAnalysisBlock(block: ToolCallBlock): AnalysisViewModel;
+/** Whether a report is the simple single-chart case deserving an inline preview. */
+export declare function isSimpleChartReport(report: AnalysisReportV1): boolean;
+/** Human-facing dataset/view counts for the summary line. */
+export declare function reportCounts(report: AnalysisReportV1): {
+    datasets: number;
+    views: number;
+};

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

@@ -1,8 +1,7 @@
 /**
  * Data Agent browser half, plugin entry: registers the database workbench
- * into the composer input dock (the strip ABOVE the input bar) for
- * data-agent sessions, and the `data-agent` dictionaries. The old
- * conversation-view tab is gone — the workbench lives inside the session.
+ * as a compact context-row control for data-agent sessions, and the
+ * `data-agent` dictionaries. The workbench itself opens in one Modal.
  * Connection state lives in the server-side connection store, so layout and
  * session switches never lose it — the view only mirrors what
  * `/plugins/data-agent/status` reports.
@@ -20,7 +19,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 export declare const inject: string[];
 /**
  * Client plugin body: register the data-agent dictionaries and the database
- * workbench into the composer input dock. The registration rides the slot
+ * workbench trigger into the composer card's right control region. The registration rides the slot
  * service's effect wrapper, so plugin unload removes it.
  * @param ctx - client root context.
  */

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

@@ -17,6 +17,13 @@ export declare const zh: {
     'form.port': string;
     'form.user': string;
     'form.password': string;
+    'form.credentialMode': string;
+    'form.credentialMode.password': string;
+    'form.credentialMode.reference': string;
+    'form.passwordRef': string;
+    'form.passwordRef.hint': string;
+    'credential.configured': string;
+    'credential.unconfigured': string;
     'form.rememberPassword': string;
     'form.rememberPassword.hint': string;
     'form.readonly': string;
@@ -33,6 +40,15 @@ export declare const zh: {
     'state.disconnected': string;
     'state.checking': string;
     'state.reconnecting': string;
+    'workbench.open.connected': string;
+    'workbench.open.disconnected': string;
+    'workbench.open.checking': string;
+    'workbench.open.error': string;
+    'composer.placeholder.disconnected': string;
+    'composer.placeholder.connected': string;
+    'wb.workbench.title': string;
+    'wb.workbench.description': string;
+    'wb.workbench.tabs': string;
     'wb.schemas': string;
     'wb.tables': string;
     'wb.columns': string;
@@ -50,6 +66,23 @@ export declare const zh: {
     'action.browse': string;
     'action.close': string;
     'error.title': string;
+    'analysis.running': string;
+    'analysis.failed': string;
+    'analysis.interrupted': string;
+    'analysis.fallback': string;
+    'analysis.view': string;
+    'analysis.close': string;
+    'analysis.summary': string;
+    'analysis.empty': string;
+    'analysis.kind.metric': string;
+    'analysis.kind.line': string;
+    'analysis.kind.bar': string;
+    'analysis.kind.pie': string;
+    'analysis.kind.scatter': string;
+    'analysis.kind.table': string;
+    'analysis.chart.summary': string;
+    'analysis.metric.null': string;
+    'analysis.row.title': string;
 };
 /** The data-agent namespace key union. */
 export type DataAgentKey = keyof typeof zh;
@@ -69,6 +102,13 @@ export declare const en: {
     'form.port': string;
     'form.user': string;
     'form.password': string;
+    'form.credentialMode': string;
+    'form.credentialMode.password': string;
+    'form.credentialMode.reference': string;
+    'form.passwordRef': string;
+    'form.passwordRef.hint': string;
+    'credential.configured': string;
+    'credential.unconfigured': string;
     'form.rememberPassword': string;
     'form.rememberPassword.hint': string;
     'form.readonly': string;
@@ -85,6 +125,15 @@ export declare const en: {
     'state.disconnected': string;
     'state.checking': string;
     'state.reconnecting': string;
+    'workbench.open.connected': string;
+    'workbench.open.disconnected': string;
+    'workbench.open.checking': string;
+    'workbench.open.error': string;
+    'composer.placeholder.disconnected': string;
+    'composer.placeholder.connected': string;
+    'wb.workbench.title': string;
+    'wb.workbench.description': string;
+    'wb.workbench.tabs': string;
     'wb.schemas': string;
     'wb.tables': string;
     'wb.columns': string;
@@ -102,4 +151,21 @@ export declare const en: {
     'action.browse': string;
     'action.close': string;
     'error.title': string;
+    'analysis.running': string;
+    'analysis.failed': string;
+    'analysis.interrupted': string;
+    'analysis.fallback': string;
+    'analysis.view': string;
+    'analysis.close': string;
+    'analysis.summary': string;
+    'analysis.empty': string;
+    'analysis.kind.metric': string;
+    'analysis.kind.line': string;
+    'analysis.kind.bar': string;
+    'analysis.kind.pie': string;
+    'analysis.kind.scatter': string;
+    'analysis.kind.table': string;
+    'analysis.chart.summary': string;
+    'analysis.metric.null': string;
+    'analysis.row.title': string;
 };

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

@@ -2,7 +2,7 @@
  * Connection-config persistence for the database workbench. The most recent
  * successful connection (type/host/port/user/database/password) is kept in
  * localStorage under one key so remounts and restarts can restore the form
- * and auto-reconnect (the server-side connection store stays in-memory).
+ * and auto-reconnect (the server persists only non-secret profiles/bindings).
  *
  * Security note: the password is persisted in PLAIN TEXT by explicit user
  * decision (local single-user scenario) — see README 安全说明. The storage
@@ -21,8 +21,13 @@ export interface SavedConnection {
     database: string;
     /** Present only when the user explicitly opted in to persist the password. */
     password?: string;
+    /** Non-secret credential reference; mutually exclusive with `password`. */
+    passwordRef?: string;
+    /** Explicit form mode; absent legacy records infer it from passwordRef. */
+    credentialMode?: 'password' | 'reference';
     /** Opt-in flag; when true, {@link saveConnection} may write `password`. */
     persistPassword?: boolean;
+    readonly?: boolean;
     /** Diagnostic timestamp of the save. */
     savedAt: string;
 }

package/lib/types/client-discovery.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cross-platform database CLI discovery.
+ *
+ * The subprocess provider remains the authority for executable validation.
+ * This module only builds a bounded, platform-aware PATH fallback when the
+ * provider cannot resolve the configured/default bare command from its
+ * current execution environment. No shell, registry, or recursive scan is
+ * involved, and the exact discovery environment is returned for spawn.
+ * @module @yejiming/dsh-data-agent/client-discovery
+ */
+import type { ClientConfig } from './clients.ts';
+import type { DatabaseType } from './connections.ts';
+/** Host facts are injectable so all supported platforms can be tested on one CI host. */
+export interface ClientDiscoverySystem {
+    platform: NodeJS.Platform;
+    env: Readonly<Record<string, string | undefined>>;
+    homeDir: string;
+    cwd: string;
+    readDirectory(directory: string): Promise<readonly string[]>;
+}
+/** DSH subprocess executable resolver face. */
+export type ExecutableResolver = (command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<string>;
+/** A resolved executable plus the environment that must also be used for spawn. */
+export interface ClientExecutableResolution {
+    executable: string;
+    env: Readonly<Record<string, string>>;
+    searchedDirectories: readonly string[];
+}
+/** Input for one database client resolution attempt. */
+export interface ResolveClientExecutableOptions {
+    type: DatabaseType;
+    command: string;
+    config?: ClientConfig;
+    env: Readonly<Record<string, string>>;
+    signal: AbortSignal;
+    resolveExecutable: ExecutableResolver;
+    system?: ClientDiscoverySystem;
+}
+/** Build ordered fallback directories without recursively scanning the host. */
+export declare function buildClientSearchDirectories(type: DatabaseType, config: ClientConfig | undefined, signal: AbortSignal, system?: ClientDiscoverySystem): Promise<string[]>;
+/**
+ * Resolve one configured/default client. Current PATH (or an explicit path)
+ * always wins. Only a missing bare command activates bounded PATH discovery.
+ */
+export declare function resolveClientExecutable(options: ResolveClientExecutableOptions): Promise<ClientExecutableResolution>;

package/lib/types/clients.d.ts

@@ -12,6 +12,7 @@
  * @module @yejiming/dsh-data-agent/clients
  */
 import type { DatabaseConnection, DatabaseType } from './connections.ts';
+import z from 'schemastery';
 import { assertSingleStatement, hasTopLevelKeyword, stripTrailingTerminator } from './sql.ts';
 export { assertSingleStatement, hasTopLevelKeyword, stripTrailingTerminator };
 /**
@@ -44,25 +45,31 @@ export declare function sanitizeIdentifier(type: DatabaseType, identifier: strin
 /** One deployment override for a database type's CLI client. */
 export interface ClientConfig {
     /** Executable name (resolved through PATH) or absolute path. */
-    command: string;
+    command?: string;
     /** Extra flag arguments prepended before the built-in flags. */
     args?: readonly string[];
+    /** Absolute directories searched after the current subprocess PATH. */
+    searchPaths?: readonly string[];
 }
 /** Loader schema for one client override (all fields optional at input). */
-export declare const clientConfigSchema: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
-    command: import("@deepseek-ai/schemastery").default<string, string>;
-    args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+export declare const clientConfigSchema: z<Schemastery.ObjectS<{
+    command: z<string, string>;
+    args: z<string[], string[]>;
+    searchPaths: z<string[], string[]>;
 }>, Schemastery.ObjectT<{
-    command: import("@deepseek-ai/schemastery").default<string, string>;
-    args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+    command: z<string, string>;
+    args: z<string[], string[]>;
+    searchPaths: z<string[], string[]>;
 }>>;
 /** Loader schema for the whole `clients` config object (any type key). */
-export declare const clientsSchema: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/cosmokit").Dict<{
+export declare const clientsSchema: z<import("cosmokit").Dict<{
     command?: string | null | undefined;
     args?: string[] | null | undefined;
-} & import("cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-    command: import("@deepseek-ai/schemastery").default<string, string>;
-    args: import("@deepseek-ai/schemastery").default<string[], string[]>;
+    searchPaths?: string[] | null | undefined;
+} & import("@deepseek-ai/cosmokit").Dict, string>, import("cosmokit").Dict<Schemastery.ObjectT<{
+    command: z<string, string>;
+    args: z<string[], string[]>;
+    searchPaths: z<string[], string[]>;
 }>, string>>;
 /**
  * A fully constructed client invocation: argv (command + flags, no SQL),

package/lib/types/command.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Agent-scoped `/database` human command. The preset mounts this entry below
+ * the agent context, so the command registry scopes it to data-agent without
+ * importing dsh-tui, React, or Ink.
+ * @module @yejiming/dsh-data-agent/command
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import { type ConnectionFormDraft, type ConnectionSummary, type DatabaseConnectionInput } from './connections.ts';
+export declare const name = "data-agent-database-command";
+export declare const inject: string[];
+export declare const DATABASE_COMMAND_USAGE: string;
+type DatabaseAction = {
+    kind: 'status';
+} | {
+    kind: 'connect';
+    input?: DatabaseConnectionInput;
+} | {
+    kind: 'test';
+} | {
+    kind: 'disconnect';
+};
+export declare const DATA_AGENT_TOOL_NAMES: readonly ["str_replace_editor", "sql-query", "sql-write", "sql-cmd"];
+export interface DatabaseCommandInteraction {
+    isTuiFormAvailable(): boolean;
+    collectTuiConnection(signal: AbortSignal, options: {
+        initialDraft?: ConnectionFormDraft;
+        persistDraft(draft: ConnectionFormDraft): Promise<void>;
+    }): Promise<DatabaseConnectionInput | undefined>;
+}
+/** Register the command in the calling preset/agent scope. */
+export declare function apply(ctx: Context): void;
+/** Public for focused command tests and alternate command adapters. */
+export declare function executeDatabaseCommand(ctx: Context, invocation: CommandInvocation, interaction?: DatabaseCommandInteraction): Promise<CommandResult>;
+/** Parse one command's raw input without ever accepting a plaintext password. */
+export declare function parseDatabaseAction(rawInput: string): DatabaseAction;
+/** Non-interactive `connect` argument grammar. */
+export declare function parseConnectArguments(tokens: readonly string[]): DatabaseConnectionInput;
+/** Render a public summary; no password-bearing field exists in the type. */
+export declare function formatConnectionStatus(summary: ConnectionSummary | undefined): string;
+export {};

package/lib/types/connections.d.ts

@@ -1,74 +1,149 @@
 /**
- * The `dataAgentConnections` connection store: one in-memory connection per
- * session id, host-plane provided by the server half (`src/index.ts`) and
- * consumed by the sqlcmd tool half (`src/tool.ts`) inside the data-agent
- * preset.
+ * Surface-independent database connection service shared by Web routes,
+ * agent tools, and human commands.
  *
- * Security contract:
- * - passwords live in memory only — never written to session logs, settings,
- *   config, or disk;
- * - `get()` returns a password-stripped COPY, so UI/status consumers never
- *   see the secret;
- * - `getWithSecret()` is the process-internal read used ONLY by the sqlcmd
- *   tool half (same package), which forwards the password to the database
- *   client through an environment variable.
- *
- * Wildcard: a connection stored under the key `'*'` acts as the fallback for
- * every session without its own entry (a deployment seeding a default
- * database, or a headless/keyless run). Config-seeded entries cannot carry
- * passwords, so the wildcard is always password-free.
+ * Runtime records may contain one temporary Web password. Durable records
+ * never do: they contain a non-secret profile plus an optional credential
+ * reference that is resolved again at the start of every database operation.
  * @module @yejiming/dsh-data-agent/connections
  */
-/** Key of the wildcard (default) connection applied to any session without its own. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ClientConfig, type ColumnInfo } from './clients.ts';
+import { type QueryResult } from './query.ts';
+/** Key of the wildcard connection applied to sessions without an exact entry. */
 export declare const WILDCARD_SESSION = "*";
 /** Supported database client kinds. */
 export type DatabaseType = 'mysql' | 'postgres' | 'sqlite' | 'oracle' | 'hive' | 'impala';
-/**
- * One session's database connection. `host`/`port`/`user` are empty for
- * SQLite, whose `database` is a file path (resolved to absolute at connect).
- * `tables` is the connectivity check's table listing, retained so the
- * browser half can restore it after a tab switch without re-querying.
- */
-export interface DatabaseConnection {
+/** Safe credential facts returned to UI/command surfaces. */
+export interface CredentialSummary {
+    configured: boolean;
+    source?: string;
+}
+/** One connect request accepted by every surface. */
+export interface DatabaseConnectionInput {
     type: DatabaseType;
     host?: string;
     port?: number;
     user?: string;
     database: string;
-    /** In-memory only; never exposed through {@link DataAgentConnections.get}. */
+    /** Temporary Web-only secret, retained in this process only. */
     password?: string;
-    /** Optional per-session read-only guard (defaults to the plugin's `readonly`). */
+    /** Non-secret DSH credential reference, mutually exclusive with password. */
+    passwordRef?: string;
     readonly?: boolean;
+    /** Optional stable durable profile id. */
+    profileId?: string;
+    /** Optional human-readable profile label. */
+    name?: string;
+}
+/** Runtime connection. `tables` and temporary `password` are never durable. */
+export interface DatabaseConnection extends DatabaseConnectionInput {
     tables?: string[];
 }
-/** Password-free view of one connection (the wire/UI face). */
+/** Password-free public connection view. */
 export interface ConnectionSummary {
     type: DatabaseType;
     host?: string;
     port?: number;
     user?: string;
     database: string;
-    /** Present only when the connection explicitly set it. */
+    passwordRef?: string;
     readonly?: boolean;
+    profileId?: string;
+    name?: string;
     tables?: string[];
+    credential?: CredentialSummary;
+}
+/** Value stored in the `profiles` domain table. Never add secrets here. */
+export interface PersistedConnectionProfile {
+    name?: string;
+    type: DatabaseType;
+    host?: string;
+    port?: number;
+    user?: string;
+    database: string;
+    readonly?: boolean;
+    passwordRef?: string;
+    updatedAt: string;
+}
+/** Value stored in the `bindings` domain table. */
+export interface SessionConnectionBinding {
+    profileId: string;
+    updatedAt: string;
+}
+/** Non-secret values restored when a session reopens an interactive form. */
+export interface ConnectionFormDraft {
+    type: DatabaseType;
+    host: string;
+    port: string;
+    user: string;
+    database: string;
+    readonly: boolean;
+}
+/** Durable draft record. Passwords and credential references are forbidden. */
+export interface PersistedConnectionFormDraft extends ConnectionFormDraft {
+    updatedAt: string;
+}
+/** Minimal durable seam; backed by a DSH storage domain in production. */
+export interface ConnectionPersistence {
+    getProfile(profileId: string): PersistedConnectionProfile | undefined;
+    putProfile(profileId: string, profile: PersistedConnectionProfile): Promise<void>;
+    deleteProfile(profileId: string): Promise<boolean>;
+    getBinding(sessionId: string): SessionConnectionBinding | undefined;
+    putBinding(sessionId: string, binding: SessionConnectionBinding): Promise<void>;
+    deleteBinding(sessionId: string): Promise<boolean>;
+    getDraft?(sessionId: string): PersistedConnectionFormDraft | undefined;
+    putDraft?(sessionId: string, draft: PersistedConnectionFormDraft): Promise<void>;
+}
+/** Shared service configuration supplied by the host plugin. */
+export interface ConnectionServiceOptions {
+    connectTimeoutMs: number;
+    queryTimeoutMs: number;
+    maxResultChars: number;
+    maxQueryChars?: number;
+    introspectMaxTables: number;
+    readonly: boolean;
+    clients: Partial<Record<string, ClientConfig>>;
+    cwd?: string;
+}
+export interface ConnectResult {
+    tables: string[];
+    summary: ConnectionSummary;
 }
-/** The host-plane connection store service (`ctx.dataAgentConnections`). */
+/** Host-plane service (`ctx.dataAgentConnections`). */
 export interface DataAgentConnections {
-    /** Save (replace) one session's connection, password included. */
+    /** Compatibility setter for config seeds/tests; does not persist. */
     set(sessionId: string, connection: DatabaseConnection): void;
-    /** Read one session's connection WITHOUT the password (a fresh copy). */
+    /** Password-free synchronous status (runtime/binding/wildcard resolution). */
     get(sessionId: string): ConnectionSummary | undefined;
-    /**
-     * Read one session's connection INCLUDING the password. Process-internal
-     * only (the sqlcmd tool half); never hand this to a wire/UI consumer.
-     */
+    /** Compatibility internal read; credential references remain unresolved. */
     getWithSecret(sessionId: string): DatabaseConnection | undefined;
-    /** Whether a session currently has a connection. */
     has(sessionId: string): boolean;
-    /** Drop one session's connection. */
+    /** Compatibility runtime-only clear. Use disconnect() for durable bindings. */
     clear(sessionId: string): void;
+    /** Restore the latest non-secret interactive form values for this session. */
+    getFormDraft(sessionId: string): ConnectionFormDraft | undefined;
+    /** Save non-secret form values; the implementation never accepts a password. */
+    saveFormDraft(sessionId: string, draft: ConnectionFormDraft): Promise<void>;
+    status(sessionId: string): Promise<ConnectionSummary | undefined>;
+    connect(sessionId: string, input: DatabaseConnectionInput, signal: AbortSignal): Promise<ConnectResult>;
+    disconnect(sessionId: string): Promise<void>;
+    test(sessionId: string, signal: AbortSignal): Promise<ConnectResult>;
+    resolveForExecution(sessionId: string): Promise<DatabaseConnection>;
+    listSchemas(sessionId: string, signal: AbortSignal): Promise<string[]>;
+    listTables(sessionId: string, schema: string | undefined, signal: AbortSignal): Promise<string[]>;
+    describe(sessionId: string, schema: string | undefined, table: string, signal: AbortSignal): Promise<ColumnInfo[]>;
+    query(sessionId: string, sql: string, signal: AbortSignal): Promise<QueryResult>;
 }
-/** Build the password-stripped copy of one connection. */
+/** Build a password-stripped copy of one connection. */
 export declare function summarize(connection: DatabaseConnection): ConnectionSummary;
-/** Create a fresh connection store (per-process singleton, one per plugin instance). */
+/** Replace every occurrence of a resolved secret before crossing a public seam. */
+export declare function redactSecretText(text: string, secrets: readonly (string | undefined)[]): string;
+/** Redact a client result without mutating the runner-owned object. */
+export declare function redactQueryResult(result: QueryResult, connection: DatabaseConnection): QueryResult;
+/** Validate/normalize a shared connect input before any I/O. */
+export declare function normalizeConnectionInput(input: DatabaseConnectionInput, cwd?: string): DatabaseConnection;
+/** Create the surface-independent service. */
+export declare function createConnectionService(ctx?: Context, options?: ConnectionServiceOptions, persistence?: ConnectionPersistence): DataAgentConnections;
+/** Backward-compatible in-memory store factory used by embedders/tests. */
 export declare function createConnectionStore(): DataAgentConnections;

package/lib/types/defaults.d.ts

@@ -14,6 +14,8 @@ export declare const DEFAULT_INTROSPECT_MAX_TABLES = 500;
 export declare const DEFAULT_QUERY_TIMEOUT_MS = 30000;
 /** In-memory cap on database-tool captured output (stdout and stderr each). */
 export declare const DEFAULT_MAX_RESULT_CHARS = 20000;
+/** Maximum structured rows returned by one database read tool call. */
+export declare const DEFAULT_MAX_ROWS = 100;
 /** Cap on one /query SQL text length (abuse guard; the wire body stays small). */
 export declare const DEFAULT_MAX_QUERY_CHARS = 65536;
 /** Grace period for the subprocess terminate escalation. */