@xiaoso/dsh-tool-plus 0.1.6 → 0.1.7-beta.1

package/lib/types/tools/omp/internal-urls/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Types for the internal URL routing system.
+ *
+ * Internal URLs (`agent://`, `artifact://`, `history://`, `issue://`, `local://`, `mcp://`, `memory://`, `omp://`, `pr://`, `rule://`, `security://`, `skill://`, `ssh://`, `vault://`, and `xd://`) are resolved by tools like read,
+ * providing access to agent outputs and server resources without exposing filesystem paths.
+ */
+import type { Skill } from "../extensibility/skills";
+import type { LocalProtocolOptions } from "./local-protocol";
+/**
+ * Raw resource payload returned by protocol handlers. The `immutable` flag is
+ * applied by the router from {@link ProtocolHandler.immutable}, so handlers do
+ * not need to set it themselves.
+ */
+export interface InternalResource {
+    /** Canonical URL that was resolved */
+    url: string;
+    /** Resolved text content */
+    content: string;
+    /** MIME type: text/markdown, application/json, or text/plain */
+    contentType: "text/markdown" | "application/json" | "text/plain";
+    /** Content size in bytes */
+    size?: number;
+    /** Underlying filesystem path (for debugging, not exposed to agent) */
+    sourcePath?: string;
+    /** Additional notes about resolution */
+    notes?: string[];
+    /**
+     * True when the resolved content cannot be edited by the agent (e.g. sealed
+     * artifacts, harness docs, machine-generated memory summaries). Hashline
+     * anchors and similar edit affordances are suppressed for immutable
+     * resources. Mutable resources (e.g. local://) behave like editable files.
+     */
+    immutable?: boolean;
+    /**
+     * True when the resource is a directory listing rather than file content.
+     * `search` refuses to grep such a resource when it has no `sourcePath` — a
+     * remote `ssh://` listing has no local path to recurse, so its listing text
+     * must never be mistaken for the directory's contents.
+     */
+    isDirectory?: boolean;
+}
+/**
+ * A single autocomplete candidate for the host/path portion of a `scheme://`
+ * URL, produced by {@link ProtocolHandler.complete}.
+ */
+export interface UrlCompletion {
+    /**
+     * The text that follows `scheme://` for this candidate (e.g. `humanizer`,
+     * `subdir/data.json`, `root`). The caller renders it as `scheme://<value>`.
+     */
+    value: string;
+    /** Human-facing label for the dropdown. Defaults to {@link value}. */
+    label?: string;
+    /** Optional one-line description shown beside the candidate. */
+    description?: string;
+}
+/**
+ * Parsed internal URL with preserved host casing.
+ */
+export interface InternalUrl extends URL {
+    /**
+     * Raw host segment extracted from input, preserving case.
+     */
+    rawHost: string;
+    /**
+     * Raw pathname extracted from input, preserving traversal markers before URL normalization.
+     */
+    rawPathname?: string;
+    /**
+     * Exact input string this URL was parsed from, before any normalization.
+     * Set by `parseInternalUrl`; used where byte-exact URI matching matters
+     * (e.g. MCP resource URIs compared by string equality).
+     */
+    rawHref?: string;
+}
+/**
+ * Caller-supplied context that the router threads into protocol handlers.
+ *
+ * Read tool calls `InternalUrlRouter.resolve(url, { cwd, settings, signal })`
+ * so handlers can resolve relative defaults (e.g. `issue://N` → which repo?)
+ * against the actual session that initiated the read, not whichever session
+ * happens to be registered first in the global `AgentRegistry`.
+ */
+export interface ResolveContext {
+    /** Working directory of the calling session. */
+    cwd?: string;
+    /** Settings of the calling session (used by `issue://`/`pr://` for cache TTLs). */
+    settings?: unknown;
+    /** Caller's abort signal. */
+    signal?: AbortSignal;
+    /**
+     * Calling session's `local://` root mapping. When present, the local-protocol
+     * handler resolves the URL against THIS session's artifacts dir instead of
+     * picking the first `main`-kind session from the global `AgentRegistry`.
+     *
+     * Required for correctness in multi-session hosts (cmux/ACP, embedded SDK
+     * consumers) where multiple sessions are registered as `main` and the
+     * "first one wins" lookup picks the wrong artifacts directory — see
+     * [#1608](https://github.com/can1357/oh-my-pi/issues/1608).
+     */
+    localProtocolOptions?: LocalProtocolOptions;
+    /** Calling session's loaded skills. Prefer this over process-global skill state. */
+    skills?: readonly Skill[];
+    /** Session-bound `xd://` documentation resolver. */
+    xd?: {
+        read(name: string | null): Promise<string>;
+    };
+    /**
+     * When set, handlers that would otherwise materialize an expensive directory
+     * listing (e.g. the ssh:// handler draining a full remote `ls`) instead return
+     * the directory shape (`isDirectory: true`) with empty content. `search`/`find`
+     * reject directory resources, so they never need the listing.
+     */
+    skipDirectoryListing?: boolean;
+    /**
+     * When set, handlers that would otherwise materialize expensive content
+     * (e.g. reading a multi-MiB artifact into memory just to expose its
+     * `sourcePath`) may return the resource shape without content. Callers
+     * that only need `sourcePath` — search/grep, bash URL expansion — pass
+     * this so a large `artifact://` still resolves to its backing file
+     * without OOM risk. Handlers that cannot separate path from content
+     * ignore the flag.
+     */
+    pathOnly?: boolean;
+}
+/**
+ * Caller context for write operations dispatched to host-owned URI handlers.
+ * Mirrors {@link ResolveContext} so handlers that share read/write state can
+ * accept the same shape.
+ */
+export interface WriteContext {
+    /** Working directory of the calling session. */
+    cwd?: string;
+    /** Caller's abort signal. */
+    signal?: AbortSignal;
+    /** Calling session's `local://` root mapping — see {@link ResolveContext.localProtocolOptions}. */
+    localProtocolOptions?: LocalProtocolOptions;
+    /** Session-bound `xd://` device dispatcher. */
+    xd?: {
+        write(name: string | null, content: string): Promise<void>;
+    };
+}
+/**
+ * Handler for a specific internal URL scheme (e.g., agent://, memory://, skill://, xd://).
+ */
+export interface ProtocolHandler {
+    /** The scheme this handler processes (without trailing ://) */
+    readonly scheme: string;
+    /**
+     * Whether resources produced by this handler are immutable (cannot be
+     * edited by the agent). When true, callers suppress hashline anchors and
+     * other edit affordances. When false, resources behave like editable files.
+     */
+    readonly immutable: boolean;
+    /**
+     * Resolve an internal URL to its content. The router stamps the
+     * {@link InternalResource.immutable} flag from {@link ProtocolHandler.immutable}.
+     *
+     * @param url Parsed URL object
+     * @param context Optional caller context. Handlers that depend on caller
+     *   identity (working directory, settings) **MUST** consume this in
+     *   preference to global state.
+     * @throws Error with user-friendly message if resolution fails
+     */
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    /**
+     * Optional write hook. When present, the write tool dispatches
+     * `write(url, content)` to this handler instead of writing to a filesystem
+     * path. The handler is responsible for any persistence and validation.
+     *
+     * Handlers that omit this method are treated as read-only; the write tool
+     * surfaces a clear "not writable" error when invoked against them.
+     */
+    write?(url: InternalUrl, content: string, context?: WriteContext): Promise<void>;
+    /**
+     * Optional autocomplete hook. Returns candidate completions for the
+     * host/path portion of a `scheme://` URL while the user composes a prompt.
+     *
+     * Implementations **MUST** be fast and local — this runs on every keystroke.
+     * Schemes backed by network or external CLIs (issue://, pr://, vault://,
+     * mcp://) omit it. The caller fuzzy-filters the returned set against the
+     * partially typed `query`, so handlers return their full (bounded) candidate
+     * list; `query` is provided only so handlers can scope expensive enumeration.
+     * `context.cwd`/`context.localProtocolOptions` carry the caller's working dir
+     * and session, for handlers whose candidates are project- or session-scoped
+     * (e.g. ssh:// hosts from a project `ssh.json`, local:// roots per session).
+     */
+    complete?(query?: string, context?: ResolveContext): Promise<UrlCompletion[]>;
+}

package/lib/types/tools/omp/internal-urls/xd-protocol.d.ts

@@ -0,0 +1,19 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, WriteContext } from "./types";
+/** Canonical prefix for virtual tool-device URLs. */
+export declare const XD_URL_PREFIX = "xd://";
+/**
+ * Parse an `xd://` URL into its device target.
+ * Returns `null` for other or malformed URLs and `name: null` for the root.
+ */
+export declare function parseXdUrl(input: string): {
+    name: string | null;
+} | null;
+/** Whether a streaming path prefix could still become an `xd://` URL. */
+export declare function couldBecomeXdUrl(partialPath: string): boolean;
+/** Routes session-bound virtual tool devices through `xd://` URLs. */
+export declare class XdProtocolHandler implements ProtocolHandler {
+    readonly scheme = "xd";
+    readonly immutable = true;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    write(url: InternalUrl, content: string, context?: WriteContext): Promise<void>;
+}

package/lib/types/tools/omp/markit/converters/docx.d.ts

@@ -0,0 +1,6 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+export declare class DocxConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+}

package/lib/types/tools/omp/markit/converters/epub.d.ts

@@ -0,0 +1,15 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+/** A metadata value: a bare string, or a node carrying `#text` and/or array children. */
+type MetaValue = string | MetaNode;
+interface MetaNode {
+    "#text"?: string;
+    [index: number]: MetaValue;
+}
+export declare class EpubConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+    getText(node: MetaValue | undefined): string | undefined;
+    getTextArray(node: MetaValue | undefined): (string | undefined)[];
+}
+export {};

package/lib/types/tools/omp/markit/converters/pdf/index.d.ts

@@ -0,0 +1,7 @@
+import type { ConversionResult, Converter, StreamInfo } from "../../types";
+/** Converts PDF buffers to Markdown through the native `pdf-inspector` bridge. */
+export declare class PdfConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+}

package/lib/types/tools/omp/markit/converters/pptx.d.ts

@@ -0,0 +1,57 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+/** A text value: bare string/number, or a `{ "#text" }` node when the element carries attributes. */
+type XmlText = string | number | {
+    "#text"?: string;
+};
+interface TextRun {
+    "a:t"?: XmlText;
+}
+interface Paragraph {
+    "a:r"?: TextRun | TextRun[];
+}
+interface TextBody {
+    "a:p"?: Paragraph | Paragraph[];
+}
+interface CNvPr {
+    "@_name": string;
+}
+interface Placeholder {
+    "@_type": string;
+}
+interface NvPr {
+    "p:ph"?: Placeholder;
+}
+interface NvSpPr {
+    "p:cNvPr"?: CNvPr;
+    "p:nvPr"?: NvPr;
+}
+interface Shape {
+    "p:txBody"?: TextBody;
+    "p:nvSpPr"?: NvSpPr;
+}
+interface TableCell {
+    "a:txBody"?: TextBody;
+}
+interface TableRow {
+    "a:tc"?: TableCell | TableCell[];
+}
+interface Table {
+    "a:tr"?: TableRow | TableRow[];
+}
+interface GraphicData {
+    "a:tbl"?: Table;
+}
+interface Graphic {
+    "a:graphicData"?: GraphicData;
+}
+interface GraphicFrame {
+    "a:graphic"?: Graphic;
+}
+export declare class PptxConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+    extractText(shape: Shape): string;
+    extractTable(gf: GraphicFrame): string | null;
+}
+export {};

package/lib/types/tools/omp/markit/converters/xlsx.d.ts

@@ -0,0 +1,25 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+/** A text value: bare string/number, or a `{ "#text" }` node when the element carries attributes. */
+type XmlText = string | number | {
+    "#text"?: string;
+};
+interface RichTextRun {
+    t?: XmlText;
+}
+interface StringItem {
+    t?: XmlText;
+    r?: RichTextRun | RichTextRun[];
+}
+interface Cell {
+    "@_t"?: string;
+    v?: string | number;
+    is?: StringItem;
+}
+export declare class XlsxConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+    getCellValue(cell: Cell, shared: StringItem[]): string;
+    getSharedString(shared: StringItem[], idx: number): string;
+}
+export {};

package/lib/types/tools/omp/markit/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./registry";
+export * from "./types";

package/lib/types/tools/omp/markit/registry.d.ts

@@ -0,0 +1,16 @@
+import type { ConversionResult, MarkitOptions, StreamInfo } from "./types";
+/**
+ * In-house document → markdown engine (replaces the `markit-ai` package).
+ *
+ * Only the document converters omp routes are registered (pdf, docx, pptx,
+ * xlsx, epub). The first converter whose `accepts()` returns true and whose
+ * `convert()` succeeds wins.
+ */
+export declare class Markit {
+    #private;
+    constructor(options?: MarkitOptions);
+    convertFile(filePath: string, extra?: {
+        imageDir?: string;
+    }): Promise<ConversionResult>;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+}

package/lib/types/tools/omp/markit/types.d.ts

@@ -0,0 +1,30 @@
+export interface StreamInfo {
+    mimetype?: string;
+    extension?: string;
+    charset?: string;
+    filename?: string;
+    localPath?: string;
+    url?: string;
+    /** Directory to write extracted images/diagrams. */
+    imageDir?: string;
+}
+export interface ConversionResult {
+    markdown: string;
+    title?: string;
+}
+export interface MarkitOptions {
+    /** Describe an image, return markdown. Receives raw bytes and mimetype. */
+    describe?: (image: Buffer, mimetype: string) => Promise<string>;
+    /** Transcribe audio, return text. Receives raw bytes and mimetype. */
+    transcribe?: (audio: Buffer, mimetype: string) => Promise<string>;
+    /** Extra instructions appended to the image description prompt. */
+    prompt?: string;
+}
+export interface Converter {
+    /** Human-readable name for error messages. */
+    name: string;
+    /** Quick check: can this converter handle the given stream? */
+    accepts(streamInfo: StreamInfo): boolean;
+    /** Convert the source to markdown. */
+    convert(input: Buffer, streamInfo: StreamInfo, options?: MarkitOptions): Promise<ConversionResult>;
+}

package/lib/types/tools/omp/sdk.d.ts

@@ -0,0 +1,103 @@
+/**
+ * DSH adapter for OMP `sdk.ts` — the `ToolSession` interface consumed by the
+ * tool-plus engines (read/write/grep/glob/edit).
+ *
+ * Shared superset: read/write/grep/glob adapter copies declared the members
+ * their engine touches; this shared copy keeps the union (read's
+ * conflict-history, grep/glob's `getSessionSpawns`, the native edit store).
+ * DSH provides a session adapter implementing this interface.
+ */
+import type { Settings } from './config/settings.ts';
+import type { Skill } from './extensibility/skills.ts';
+import type { ConflictHistory } from './tools/conflict-detect.ts';
+import type { Model } from '@oh-my-pi/pi-ai';
+declare module '@oh-my-pi/pi-agent-core' {
+    interface AgentToolContext {
+        hasUI?: boolean;
+        toolNames?: string[];
+        /** Session settings (cross-module nominal Settings — typed loosely). */
+        settings?: any;
+        /** Session manager (DSH: none). */
+        sessionManager?: {
+            saveArtifact: (text: string, toolName: string) => Promise<string | undefined>;
+        };
+    }
+}
+/**
+ * Minimal ToolSession surface used by the OMP engines (verbatim member
+ * shapes, shared superset). DSH provides a session adapter implementing
+ * this interface.
+ */
+export interface ToolSession {
+    /** Current working directory */
+    cwd: string;
+    /** Whether an edit-capable tool is available (controls hashline output) */
+    hasEditTool?: boolean;
+    /** Session settings (read.* keys; DSH maps them onto tool-plus config). */
+    settings: Settings;
+    /** Active model string for mode resolution (optional in DSH). */
+    getActiveModelString?: () => string | undefined;
+    /** Active model object (image-capability checks; optional in DSH). */
+    getActiveModel?: () => Model | undefined;
+    /**
+     * DSH image bridge (拍板#22): attachment store + route vision-capability
+     * probe handed to the read/fetch image paths. Optional — engines degrade to
+     * a model-facing metadata text when absent.
+     */
+    imageBridge?: () => import('../shared/image-bridge.ts').ImageBridge | undefined;
+    /**
+     * Native edit store (created lazily by the engine): the hashline snapshot
+     * ring, the `CUT`/`PUT` clipboard registers and the no-op loop guard. Shared
+     * by read / search / write / edit through `file-snapshot-store.ts`, and
+     * round-tripped across tool calls by `shared/session-state.ts`.
+     */
+    editStore?: import('../hashline/native/index.ts').EditStore;
+    /** Plan-mode state (DSH plan is a hint layer — never enabled). */
+    getPlanModeState?: () => {
+        enabled: boolean;
+        planFilePath: string;
+    } | undefined;
+    /** Plan reference path (DSH: none). */
+    getPlanReferencePath?: () => string | null;
+    /** Local protocol options (DSH has no local:// sandbox — optional). */
+    localProtocolOptions?: import('./internal-urls/index.ts').LocalProtocolOptions;
+    getArtifactsDir?: () => string | null;
+    /** Allocate a new artifact path (DSH: none). */
+    allocateOutputArtifact?: (toolType: string) => Promise<{
+        id?: string;
+        path?: string;
+    }>;
+    getSessionId?: () => string | null;
+    /** Session spawn policy (DSH: none — engines fall back to `"*"`). */
+    getSessionSpawns?: () => string | boolean | null | undefined;
+    /** Fetch implementation for URL reads (DSH: global fetch). */
+    fetch?: typeof globalThis.fetch;
+    /** Tool-choice queue (resolution devices; DSH: none). */
+    getToolChoiceQueue?: () => ToolChoiceQueueLike | undefined;
+    /** Plan-proposal handler (resolution devices; DSH: none). */
+    peekPlanProposalHandler?: () => PlanProposalHandler | undefined;
+    /** Queued/pending invocation peek (resolution devices; DSH: none). */
+    peekQueueInvoker?: () => ResolveInvoker | undefined;
+    peekPendingInvoker?: () => ResolveInvoker | undefined;
+    /** Clear pending invokers (resolution devices; DSH: none). */
+    clearPendingInvokers?: () => void;
+    /** Whether a built-in tool is active in this turn's tool set. */
+    isToolActive?: (name: string) => boolean;
+    /** Pre-loaded skills (DSH: none). */
+    skills?: readonly Skill[];
+    /** Auth storage for search providers (DSH: none). */
+    authStorage?: import('@oh-my-pi/pi-ai').AuthStorage;
+    /** Conflict history for conflict:// write-back (DSH: absent). */
+    conflictHistory?: ConflictHistory;
+}
+/** Tool-choice queue for staged resolution previews (DSH: never present). */
+export interface ToolChoiceQueueLike {
+    registerPendingInvoker: (id: string, toolName: string, invoker: ResolveInvoker) => void;
+    removePendingInvoker: (id: string) => void;
+}
+/** Plan-proposal approval handler (DSH: never present). */
+export type PlanProposalHandler = (title: string) => Promise<import('@oh-my-pi/pi-agent-core').AgentToolResult<unknown>>;
+/** Staged resolution invocation runner (DSH: never present). */
+export type ResolveInvoker = (invocation: unknown) => Promise<import('@oh-my-pi/pi-agent-core').AgentToolResult<unknown>>;
+/** DSH: no auth storage discovery — search providers have no credentials. */
+export declare function discoverAuthStorage(_agentDir?: string): Promise<import('@oh-my-pi/pi-ai').AuthStorage>;

package/lib/types/tools/omp/session/agent-storage.d.ts

@@ -0,0 +1,154 @@
+import { type AuthCredential, type AuthCredentialStore, type StoredAuthCredential } from "@oh-my-pi/pi-ai";
+import type { RawSettings as Settings } from "../config/settings";
+/** One completed request's timing, folded into the per-model aggregates. */
+export interface ModelPerfSample {
+    /** Output tokens the provider reported for the turn. */
+    outputTokens: number;
+    /** Total request duration in milliseconds. */
+    durationMs: number;
+    /** Time to first token in milliseconds; omit when the provider did not report one. */
+    ttftMs?: number;
+}
+/** Recency-weighted per-model performance averages. */
+export interface ModelPerfStats {
+    /** Decayed sample count backing the averages. */
+    samples: number;
+    /** Average output tokens/sec over the total request duration. */
+    tps: number;
+    /** Average time-to-first-token in milliseconds; null when no sample reported one. */
+    ttftMs: number | null;
+}
+/** Current agent.db schema version; bump when schema changes require migration. */
+export declare const SCHEMA_VERSION = 6;
+/**
+ * Unified SQLite storage for agent settings, model usage, and auth credentials.
+ * Delegates auth credential operations to AuthCredentialStore from @oh-my-pi/pi-ai.
+ * Uses singleton pattern per database path; access via AgentStorage.open().
+ */
+export declare class AgentStorage {
+    #private;
+    private constructor();
+    /**
+     * Returns singleton instance for the given database path, creating if needed.
+     * Retries on the `SQLITE_BUSY` family (including `SQLITE_BUSY_RECOVERY`) with
+     * exponential backoff. See issue #2421.
+     * @param dbPath - Path to the SQLite database file (defaults to config path)
+     * @returns AgentStorage instance for the given path
+     */
+    static open(dbPath?: string): Promise<AgentStorage>;
+    /** @internal Reset all singletons and close their databases — test-only. */
+    static resetInstance(): void;
+    /**
+     * Reads legacy settings persisted in the agent.db `settings` table.
+     * The canonical settings store is `config.yml`; this accessor only
+     * exists so the config loader can migrate values from older installs.
+     * @returns Settings object, or null if no settings are stored
+     */
+    getSettings(): Settings | null;
+    /**
+     * Records model usage, updating the last-used timestamp.
+     * @param modelKey - Model key in "provider/modelId" format
+     */
+    recordModelUsage(modelKey: string): void;
+    /**
+     * Gets model keys ordered by most recently used.
+     * Results are cached until recordModelUsage is called.
+     * @returns Array of model keys ("provider/modelId") in MRU order
+     */
+    getModelUsageOrder(): string[];
+    /**
+     * Folds one completed request's timing into the model's perf aggregates.
+     * TPS is measured over the total request duration — not the post-TTFT
+     * decode window, which undercounts generation time (and so inflates the
+     * rate) when reasoning tokens are generated before the first visible
+     * token. Invalid samples (no tokens, no duration) are dropped.
+     *
+     * Deferred like prompt history: samples are batched and written in one
+     * transaction after {@link MODEL_PERF_FLUSH_DELAY_MS}, keeping SQLite off
+     * the turn-completion hot path. Fire-and-forget safe — flush failures are
+     * logged, never thrown; await the returned promise only to observe the flush.
+     * @param modelKey - Model key in "provider/modelId" format
+     */
+    recordModelPerf(modelKey: string, sample: ModelPerfSample): Promise<void>;
+    /**
+     * Returns recency-weighted TPS/TTFT averages for every model with recorded
+     * requests, keyed by "provider/modelId". Read by the /models browser.
+     * Also kicks the one-time background stats.db import; until it completes,
+     * models without live samples are simply absent.
+     */
+    getModelPerf(): Map<string, ModelPerfStats>;
+    /**
+     * Imports recent measurable request rows from an `omp stats` database
+     * (`messages` table) into the model_perf aggregates. Walks newest-first
+     * over the timestamp index in {@link MODEL_PERF_BACKFILL_CHUNK}-row chunks,
+     * yielding to the event loop between chunks, and keeps at most
+     * {@link MODEL_PERF_DECAY_AT} rows per model within the
+     * {@link MODEL_PERF_BACKFILL_MAX_AGE_MS} window — beyond either bound the
+     * live decay would erase the contribution anyway. Errored turns are
+     * excluded; aborted turns with reported usage count, matching live capture.
+     * Sums land in one additive transaction at the end, so concurrent live
+     * samples merge correctly regardless of order.
+     * @param statsDbPath - Path to a stats.db file; opened read-only
+     * @returns Number of rows folded in
+     * @throws When the stats db cannot be opened or queried
+     */
+    backfillModelPerfFromStats(statsDbPath: string): Promise<number>;
+    /**
+     * Checks if any auth credentials exist in storage.
+     * @returns True if at least one credential is stored
+     */
+    hasAuthCredentials(): boolean;
+    /**
+     * Returns the underlying {@link AuthCredentialStore} so callers that need
+     * the lower-level pi-ai abstraction (e.g. `findAnthropicAuth(store)`) can
+     * reuse this storage's open database connection instead of opening their
+     * own.
+     */
+    get authStore(): AuthCredentialStore;
+    /**
+     * Lists auth credentials, optionally filtered by provider.
+     * Only returns active (non-disabled) credentials by default.
+     * @param provider - Optional provider name to filter by
+     * @param includeDisabled - If true, includes disabled credentials
+     * @returns Array of stored credentials with their database IDs
+     */
+    listAuthCredentials(provider?: string, includeDisabled?: boolean): StoredAuthCredential[];
+    /**
+     * Atomically replaces all credentials for a provider.
+     * Useful for OAuth token refresh where old tokens should be discarded.
+     * @param provider - Provider name (e.g., "anthropic", "openai")
+     * @param credentials - New credentials to store
+     * @returns Array of newly stored credentials with their database IDs
+     */
+    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
+    /**
+     * Updates an existing auth credential by ID.
+     * @param id - Database row ID of the credential to update
+     * @param credential - New credential data
+     */
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    /**
+     * Disables an auth credential by ID with a persisted cause.
+     * @param id - Database row ID of the credential to disable
+     * @param disabledCause - Human-readable cause stored with the disabled row
+     */
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    /**
+     * Disables all auth credentials for a provider with a persisted cause.
+     * @param provider - Provider name whose credentials should be disabled
+     * @param disabledCause - Human-readable cause stored with the disabled rows
+     */
+    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    /**
+     * Gets a cached value by key. Returns null if not found or expired.
+     */
+    getCache(key: string): string | null;
+    /**
+     * Sets a cached value with expiry time (unix seconds).
+     */
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    /**
+     * Deletes expired cache entries. Call periodically for cleanup.
+     */
+    cleanExpiredCache(): void;
+}