dsh-reference-anything 0.3.0 → 0.3.2

package/lib/host.js

@@ -1,7 +1,65 @@
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import { switchReferenceUiMode as switchProfileReferenceUiMode } from "./profile-mode.js";
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { validateDownloadDirectory } from "./download-directory.js";
 export class ReferenceAnythingRemote extends TypertRemoteService {
     constructor(ctx) { super(ctx, 'referenceAnything'); }
+    /**
+     * Discovery for the `@` menu's local-agent group.
+     *
+     * Resolved optionally rather than injected: `reference-anything-web` must
+     * still load in a profile where the local-agent plugin is switched off, and an
+     * absent service means an empty group, not a broken composer. Workspace
+     * scoping takes the session's own cwd, so a Web server serving projects from
+     * anywhere still scopes to the project the user is in.
+     */
+    async agentSearch(agent, input, signal) {
+        const agents = this.ctx.get('referenceLocalAgents');
+        if (agents === undefined)
+            return [];
+        // A session with no cwd of its own is rare and has no workspace to scope
+        // to; falling back to the process's directory is the same guess the
+        // `ReferenceSource.list` seam makes, rather than an empty group.
+        const rows = await agents.listForWorkspace(input.query, input.limit, agent.session.header.cwd ?? process.cwd(), signal);
+        return rows.map(row => ({
+            id: row.ref.id,
+            kind: row.ref.id.slice(0, row.ref.id.indexOf(':')),
+            label: row.label,
+            provider: row.provider ?? '',
+            ...row.updatedAt === undefined ? {} : { updatedAt: row.updatedAt },
+            ...row.searchIncomplete === true ? { searchIncomplete: true } : {},
+        }));
+    }
+    async agentStats(signal) {
+        signal.throwIfAborted();
+        const agents = this.ctx.get('referenceLocalAgents');
+        if (agents === undefined)
+            return [];
+        agents.setAgentDirectories(this.ctx.referenceChatHistory.getSettings().agentDirectories ?? {});
+        return (await agents.stats(signal)).map(row => ({ agent: row.kind, conversations: row.conversations }));
+    }
+    /**
+     * Discovery for the `@` menu's cloud-drive group.
+     *
+     * Optional for the same reason as `agentSearch` above. It takes no session:
+     * a drive is not scoped to a workspace, so there is nothing a cwd could
+     * narrow. `list` already refuses to name a download URL, so what comes back
+     * here is a label and a display path.
+     */
+    async driveSearch(input, signal) {
+        const drives = this.ctx.get('referenceCloudDrive');
+        if (drives === undefined)
+            return [];
+        const rows = await drives.pickerList(input.query, input.limit, signal);
+        return rows.map(row => ({
+            id: row.ref.id,
+            label: row.label,
+            provider: row.provider ?? '',
+            ...row.origin === undefined ? {} : { origin: row.origin },
+            ...row.updatedAt === undefined ? {} : { updatedAt: row.updatedAt },
+            ...row.isDirectory === true ? { isDirectory: true } : {},
+        }));
+    }
     search(input, signal) {
         signal.throwIfAborted();
         return this.ctx.referenceChatHistory.search(input.query, input.provider, input.limit, signal);
@@ -16,19 +74,6 @@ export class ReferenceAnythingRemote extends TypertRemoteService {
     updateStatus(signal) { return this.ctx.referenceChatHistory.updateStatus(signal); }
     checkUpdate(signal) { return this.ctx.referenceChatHistory.checkUpdate(signal); }
     installUpdate(signal) { return this.ctx.referenceChatHistory.installUpdate(signal); }
-    async switchReferenceUiMode(input, signal) {
-        const settings = this.ctx.referenceChatHistory.getSettings();
-        const previousMode = settings.referenceUiMode ?? 'plugin';
-        const result = await switchProfileReferenceUiMode({ mode: input.mode, signal });
-        try {
-            await this.ctx.referenceChatHistory.updateSettings({ ...settings, referenceUiMode: input.mode });
-        }
-        catch (error) {
-            await switchProfileReferenceUiMode({ mode: previousMode }).catch(() => undefined);
-            throw error;
-        }
-        return result;
-    }
     stats() { return this.ctx.referenceChatHistory.stats(); }
     syncStart(input) {
         return this.ctx.referenceChatHistory.sync.start(input.providers, input.mode);
@@ -36,7 +81,24 @@ export class ReferenceAnythingRemote extends TypertRemoteService {
     syncStatus(input) { return this.ctx.referenceChatHistory.sync.status(input.jobId); }
     syncCancel(input) { return this.ctx.referenceChatHistory.sync.cancel(input.jobId); }
     settingsGet() { return this.ctx.referenceChatHistory.getSettings(); }
-    settingsUpdate(settings) { return this.ctx.referenceChatHistory.updateSettings(settings); }
+    async settingsUpdate(settings) {
+        const value = await this.ctx.referenceChatHistory.updateSettings(settings);
+        this.ctx.get('referenceLocalAgents')?.setAgentDirectories(value.agentDirectories ?? {});
+        return value;
+    }
+    async openDownloadDirectory(signal) {
+        signal.throwIfAborted();
+        const configured = this.ctx.referenceChatHistory.getSettings().cloudDriveDownloadDirectory;
+        const path = configured || tmpdir();
+        await validateDownloadDirectory(path);
+        const child = process.platform === 'win32'
+            ? spawn('explorer.exe', [path], { detached: true, stdio: 'ignore' })
+            : process.platform === 'darwin'
+                ? spawn('open', [path], { detached: true, stdio: 'ignore' })
+                : spawn('xdg-open', [path], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return true;
+    }
     browse(input, signal) {
         signal.throwIfAborted();
         return this.ctx.referenceChatHistory.browse(input.query, input.provider, input.limit, input.offset);
@@ -50,10 +112,6 @@ export class ReferenceAnythingRemote extends TypertRemoteService {
         signal.throwIfAborted();
         return this.ctx.referenceChatHistory.removeProvider(input.provider);
     }
-    clearOlder(input, signal) {
-        signal.throwIfAborted();
-        return this.ctx.referenceChatHistory.removeOlderThan(input.days);
-    }
     clearRemoteMissing(signal) {
         signal.throwIfAborted();
         return this.ctx.referenceChatHistory.removeRemoteMissing();
@@ -63,4 +121,15 @@ export class ReferenceAnythingRemote extends TypertRemoteService {
         return this.ctx.referenceChatHistory.removeOldAccounts();
     }
     syncStates() { return this.ctx.referenceChatHistory.syncStates(); }
+    openListStatus(signal) { return this.ctx.openListManager.status(signal); }
+    openListInstall(signal) { return this.ctx.openListManager.install(signal); }
+    openListUpgrade(input, signal) { return this.ctx.openListManager.upgrade(input, signal); }
+    openListConnectExternal(input, signal) { return this.ctx.openListManager.connectExternal(input, signal); }
+    openListDisconnect(signal) { return this.ctx.openListManager.disconnect(signal); }
+    openListDrivers(signal) { return this.ctx.openListManager.drivers(signal); }
+    openListMounts(signal) { return this.ctx.openListManager.mounts(signal); }
+    openListCreateMount(input, signal) { return this.ctx.openListManager.createMount(input, signal); }
+    async openListDisableMount(input, signal) { await this.ctx.openListManager.disableMount(input.id, input.disabled ?? true, signal); return true; }
+    async openListRemoveMount(input, signal) { await this.ctx.openListManager.removeMount(input.id, signal); return true; }
+    openListReindex(input, signal) { return this.ctx.openListManager.reindexMount(input.id, signal); }
 }

package/lib/index.d.ts

@@ -10,6 +10,7 @@
  * @module dsh-reference-anything
  */
 import { Context, Service } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
 import z from '@deepseek-ai/schemastery';
 import type { ReferenceRef, ReferenceSnapshot, ReferenceSource, ReferenceSummary, ReferenceWindow } from './types.ts';
 export type * from './types.ts';
@@ -52,10 +53,29 @@ export default class ReferenceRuntime extends Service {
     registerSource(source: ReferenceSource): () => void;
     /** @returns the registered source ids, in registration order. */
     sourceIds(): string[];
-    /** Authorize one task to read a Web conversation named by its user or discovery tool. */
+    /**
+     * Whether a source's items may only be read after an explicit grant.
+     *
+     * An unregistered source fails closed: registration order must never decide
+     * authorization, and `read()` would reject it as `SOURCE_UNKNOWN` a moment
+     * later anyway.
+     */
+    private gated;
+    /**
+     * Qualify the grant by source.
+     *
+     * Two sources can mint the same opaque id, and an unqualified key would let
+     * a grant for one silently authorize the other. NUL cannot occur in either
+     * half, so the join is unambiguous.
+     */
+    private static grantKey;
+    private static contentMentions;
+    /** Authorize one task to read a gated reference named by its user or discovery tool. */
     grant(sessionId: string, ref: ReferenceRef): void;
-    /** Enforce that a Web conversation URI originated in this task's mention/list surface. */
+    /** Enforce that a gated URI originated in this task's mention/list surface. */
     assertGranted(sessionId: string | undefined, ref: ReferenceRef): void;
+    /** Allow a gated URI granted live or named in this task's durable user/tool-result history. */
+    assertSessionGranted(session: Session | undefined, ref: ReferenceRef): void;
     /** Release task-local grants when a host knows the task is gone. */
     revoke(sessionId: string): void;
     /**

package/lib/index.js

@@ -12,6 +12,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { ReferenceAnythingError } from "./errors.js";
+import { mayContainReference, parseReferenceText } from "./uri.js";
 export { ReferenceAnythingError } from "./errors.js";
 export { REFERENCE_SCHEME, decodeReferenceUri, encodeReferenceUri, formatReferenceMention, mayContainReference, parseReferenceText, } from "./uri.js";
 /** Fan-out cap applied to discovery when a caller names no limit of its own. */
@@ -57,22 +58,71 @@ export default class ReferenceRuntime extends Service {
     sourceIds() {
         return [...this.sources.keys()];
     }
-    /** Authorize one task to read a Web conversation named by its user or discovery tool. */
+    /**
+     * Whether a source's items may only be read after an explicit grant.
+     *
+     * An unregistered source fails closed: registration order must never decide
+     * authorization, and `read()` would reject it as `SOURCE_UNKNOWN` a moment
+     * later anyway.
+     */
+    gated(source) {
+        const registered = this.sources.get(source);
+        return registered === undefined || registered.requiresGrant === true;
+    }
+    /**
+     * Qualify the grant by source.
+     *
+     * Two sources can mint the same opaque id, and an unqualified key would let
+     * a grant for one silently authorize the other. NUL cannot occur in either
+     * half, so the join is unambiguous.
+     */
+    static grantKey(ref) { return `${ref.source}\u0000${ref.id}`; }
+    static contentMentions(blocks, key) {
+        return blocks.some(block => {
+            if (block.type === 'tool-result')
+                return ReferenceRuntime.contentMentions(block.content, key);
+            if (block.type !== 'text' || !mayContainReference(block.text))
+                return false;
+            try {
+                return parseReferenceText(block.text).references.some(input => ReferenceRuntime.grantKey(input.ref) === key);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    /** Authorize one task to read a gated reference named by its user or discovery tool. */
     grant(sessionId, ref) {
-        if (ref.source !== 'web-chat')
-            return;
+        // Recorded unconditionally: a source may register after the mention that
+        // named it, and a grant for an ungated source is merely inert.
         const values = this.grants.get(sessionId) ?? new Set();
-        values.add(ref.id);
+        values.add(ReferenceRuntime.grantKey(ref));
         this.grants.set(sessionId, values);
     }
-    /** Enforce that a Web conversation URI originated in this task's mention/list surface. */
+    /** Enforce that a gated URI originated in this task's mention/list surface. */
     assertGranted(sessionId, ref) {
-        if (ref.source !== 'web-chat')
+        if (!this.gated(ref.source))
             return;
-        if (!sessionId || !this.grants.get(sessionId)?.has(ref.id)) {
+        if (!sessionId || !this.grants.get(sessionId)?.has(ReferenceRuntime.grantKey(ref))) {
             throw new ReferenceAnythingError('this task has not been granted access to that conversation reference', 'CONVERSATION_REFERENCE_NOT_GRANTED');
         }
     }
+    /** Allow a gated URI granted live or named in this task's durable user/tool-result history. */
+    assertSessionGranted(session, ref) {
+        const key = ReferenceRuntime.grantKey(ref);
+        if (session && !this.grants.get(String(session.id))?.has(key)) {
+            const mentioned = session.events.some(event => {
+                if (event.type === 'user/message')
+                    return ReferenceRuntime.contentMentions(event.data.content, key);
+                if (event.type === 'tool/result')
+                    return ReferenceRuntime.contentMentions(event.data.message.content, key);
+                return false;
+            });
+            if (mentioned)
+                this.grant(String(session.id), ref);
+        }
+        this.assertGranted(session && String(session.id), ref);
+    }
     /** Release task-local grants when a host knows the task is gone. */
     revoke(sessionId) { this.grants.delete(sessionId); }
     /**

package/lib/opencli.d.ts

@@ -1,9 +1,11 @@
 import type { ChatProvider } from './store/spec.ts';
 import type { ProviderConversationRow, ProviderTurnRow } from './store/store.ts';
 export declare const MIN_OPENCLI_VERSION = "1.8.6";
-export declare const MIN_ADAPTER_VERSION = "0.2.2";
+export declare const MIN_ADAPTER_VERSION = "0.2.3";
+/** Allows a 25 MiB attachment to cross JSON/base64 stdout with bounded headroom. */
+export declare const DEFAULT_OPENCLI_MAX_STDOUT_BYTES: number;
 export declare const OPENCLI_NPM_PACKAGE = "@jackwener/opencli";
-export type OpenCliErrorCode = 'EXTENSION_NOT_CONNECTED' | 'PROVIDER_TIMEOUT' | 'PROVIDER_NOT_LOGGED_IN' | 'PROVIDER_ACCOUNT_MISMATCH' | 'OPENCLI_CONFIGURATION' | 'OPENCLI_OUTPUT_TOO_LARGE' | 'OPENCLI_FAILED' | 'OPENCLI_INSTALL_FAILED';
+export type OpenCliErrorCode = 'EXTENSION_NOT_CONNECTED' | 'PROVIDER_TIMEOUT' | 'PROVIDER_NOT_LOGGED_IN' | 'PROVIDER_ACCOUNT_MISMATCH' | 'PROVIDER_RATE_LIMIT' | 'OPENCLI_CONFIGURATION' | 'OPENCLI_OUTPUT_TOO_LARGE' | 'OPENCLI_FAILED' | 'OPENCLI_INSTALL_FAILED' | 'ATTACHMENT_TOO_LARGE';
 export declare class OpenCliError extends Error {
     readonly code: OpenCliErrorCode;
     constructor(message: string, code: OpenCliErrorCode, options?: ErrorOptions);
@@ -95,7 +97,7 @@ export declare class OpenCliRunner {
     /** Resolve account identity and history through one OpenCLI browser command. */
     syncIndex(provider: ChatProvider, signal?: AbortSignal, since?: string, accountScope?: string): Promise<ProviderIndex>;
     detail(provider: ChatProvider, id: string, signal?: AbortSignal, accountScope?: string): Promise<ProviderTurnRow[]>;
-    attachment(provider: ChatProvider, locator: string, output: string, maxBytes: number, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    attachment(provider: ChatProvider, locator: string, output: string, maxBytes: number, signal?: AbortSignal, accountScope?: string): Promise<Record<string, unknown>>;
     health(signal?: AbortSignal): Promise<OpenCliHealth>;
     /** Inspect local OpenCLI, daemon, extension and plugin state without an active connectivity probe. */
     quickHealth(signal?: AbortSignal): Promise<OpenCliHealth>;

package/lib/opencli.js

@@ -5,7 +5,9 @@ import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
 const execFile = promisify(nodeExecFile);
 export const MIN_OPENCLI_VERSION = '1.8.6';
-export const MIN_ADAPTER_VERSION = '0.2.2';
+export const MIN_ADAPTER_VERSION = '0.2.3';
+/** Allows a 25 MiB attachment to cross JSON/base64 stdout with bounded headroom. */
+export const DEFAULT_OPENCLI_MAX_STDOUT_BYTES = 40 * 1024 * 1024;
 export const OPENCLI_NPM_PACKAGE = '@jackwener/opencli';
 const SITE = {
     chatgpt: 'dsh-chatgpt', claude: 'dsh-claude', gemini: 'dsh-gemini',
@@ -55,7 +57,7 @@ export class OpenCliRunner {
         this.profile = options.profile || '';
         this.prefixArgs = options.prefixArgs ?? [];
         this.timeoutMs = options.timeoutMs ?? 60_000;
-        this.maxStdoutBytes = options.maxStdoutBytes ?? 32 * 1024 * 1024;
+        this.maxStdoutBytes = options.maxStdoutBytes ?? DEFAULT_OPENCLI_MAX_STDOUT_BYTES;
     }
     async whoami(provider, signal) {
         const rows = await this.json(SITE[provider], 'whoami', [], signal);
@@ -107,8 +109,11 @@ export class OpenCliRunner {
             };
         });
     }
-    async attachment(provider, locator, output, maxBytes, signal) {
-        const rows = await this.json(SITE[provider], 'attachment', [locator, '--output', output, '--maxBytes', String(maxBytes)], signal);
+    async attachment(provider, locator, output, maxBytes, signal, accountScope = '') {
+        const rows = await this.json(SITE[provider], 'attachment', [
+            locator, '--output', output, '--maxBytes', String(maxBytes),
+            ...(accountScope ? ['--accountScope', accountScope] : []),
+        ], signal);
         return rows[0] ?? {};
     }
     async health(signal) {
@@ -246,8 +251,10 @@ export class OpenCliRunner {
             const stderr = String(detail.stderr || detail.stdout || '').trim().slice(0, 2_000);
             const exit = typeof detail.code === 'number' ? detail.code : undefined;
             const code = stderr.includes('DSH_ACCOUNT_SCOPE_MISMATCH') ? 'PROVIDER_ACCOUNT_MISMATCH'
-                : exit === 69 ? 'EXTENSION_NOT_CONNECTED' : exit === 75 ? 'PROVIDER_TIMEOUT'
-                    : exit === 77 ? 'PROVIDER_NOT_LOGGED_IN' : exit === 78 ? 'OPENCLI_CONFIGURATION' : 'OPENCLI_FAILED';
+                : stderr.includes('DSH_PROVIDER_RATE_LIMIT') ? 'PROVIDER_RATE_LIMIT'
+                    : stderr.includes('DSH_ATTACHMENT_TOO_LARGE') ? 'ATTACHMENT_TOO_LARGE'
+                        : exit === 69 ? 'EXTENSION_NOT_CONNECTED' : exit === 75 ? 'PROVIDER_TIMEOUT'
+                            : exit === 77 ? 'PROVIDER_NOT_LOGGED_IN' : exit === 78 ? 'OPENCLI_CONFIGURATION' : 'OPENCLI_FAILED';
             throw new OpenCliError(stderr || `OpenCLI exited with ${String(detail.code)}`, code, { cause: error });
         }
     }

package/lib/openlist/host.d.ts

@@ -0,0 +1,157 @@
+import { chmod, copyFile, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { spawn as nodeSpawn } from 'node:child_process';
+/** Deliberately fixed; upgrades are a conscious manifest change. */
+export declare const OPENLIST_FIXED_VERSION = "v4.2.2";
+export declare const OPENLIST_CREDENTIAL_DIRECTORY: string;
+export declare const OPENLIST_CREDENTIAL_FILE: string;
+export interface OpenListAsset {
+    readonly platform: string;
+    readonly arch: string;
+    readonly url: string;
+    readonly sha256: string;
+    readonly archive: 'tar.gz' | 'zip';
+    readonly binary: string;
+}
+export interface OpenListReleaseManifest {
+    readonly version: string;
+    readonly assets: readonly OpenListAsset[];
+}
+/** SHA-256 values were computed from the six named GitHub v4.2.2 release assets. */
+export declare const OPENLIST_RELEASE: OpenListReleaseManifest;
+export interface OpenListCredentials {
+    readonly endpoint: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly token?: string;
+    readonly mode?: 'managed' | 'external';
+    readonly version?: string; /** Host-only cache revision. */
+    readonly generation?: number;
+}
+export type OpenListAdminMutationState = 'not-started' | 'committed' | 'unknown';
+/** Safe administration facts.  No storage addition, credentials, or raw URLs cross this boundary. */
+export interface OpenListMount {
+    readonly id: string;
+    readonly name: string;
+    readonly driver: string;
+    readonly enabled: boolean;
+    readonly status?: 'ready' | 'disabled' | 'error';
+    readonly error?: string;
+    readonly capacityUsed?: number;
+    readonly capacityTotal?: number;
+    readonly indexStatus?: 'idle' | 'running' | 'complete' | 'failed';
+    readonly indexProgress?: number;
+    readonly indexCount?: number;
+}
+export interface OpenListDriverField {
+    readonly name: string;
+    readonly label: string;
+    readonly type: 'text' | 'password' | 'number' | 'boolean' | 'select';
+    readonly secret: boolean;
+    readonly required: boolean;
+    readonly hasDefault?: boolean;
+    readonly default?: string | number | boolean;
+    readonly options?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+export interface OpenListDriver {
+    readonly name: string;
+    readonly description?: string;
+    readonly quickAuth: boolean;
+    readonly fields: readonly OpenListDriverField[];
+}
+/** Host-only mount creation values. `addition` is serialized only on the Host. */
+export interface OpenListMountInput {
+    readonly mountPath: string;
+    readonly driver: string;
+    readonly addition: Record<string, unknown>;
+    readonly order?: number;
+    readonly remark?: string;
+}
+export interface OpenListSeams {
+    readonly fetch?: typeof fetch;
+    readonly spawn?: typeof nodeSpawn;
+    readonly readFile?: typeof readFile;
+    readonly writeFile?: typeof writeFile;
+    readonly mkdir?: typeof mkdir;
+    readonly chmod?: typeof chmod;
+    readonly rename?: typeof rename;
+    readonly copyFile?: typeof copyFile;
+    readonly unlink?: typeof unlink;
+    readonly fsyncFile?: (path: string) => Promise<void>;
+    /** Required on Windows to apply a restrictive ACL (for example via icacls). */
+    readonly securePermissions?: (path: string, directory: boolean) => Promise<void>;
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Test/integration seam for the executable replacement transaction. */
+    readonly install?: typeof installOpenList;
+}
+/** Exchange external username/password for the raw OpenList token. */
+export declare function authenticateOpenList(endpoint: string, username: string, password: string, fetchImpl?: (input: string, init?: RequestInit) => Promise<Response>, signal?: AbortSignal): Promise<string>;
+/** Download only a manifest-pinned binary after validating its SHA-256. */
+export declare function installOpenList(dataRoot: string, manifest?: OpenListReleaseManifest, seams?: OpenListSeams, os?: NodeJS.Platform, cpu?: string, signal?: AbortSignal, retainBackup?: boolean): Promise<{
+    version: string;
+    path: string;
+    finish: (success: boolean) => Promise<void>;
+}>;
+/** Extract only the expected executable; archive paths never reach the filesystem. */
+export declare function unpackOpenListBinary(archive: Uint8Array, asset: OpenListAsset): Uint8Array;
+/** Select exactly the release asset for this OS and CPU architecture. */
+export declare function selectOpenListAsset(manifest: OpenListReleaseManifest, os?: NodeJS.Platform, cpu?: string): OpenListAsset;
+export declare function sha256(bytes: Uint8Array): string;
+export declare function verifyOpenListAsset(bytes: Uint8Array, expected: string): boolean;
+/** Validate an endpoint without leaking its full value in a diagnostic. */
+export declare function validateOpenListEndpoint(value: string, managed?: boolean): string;
+export declare function isLoopback(host: string): boolean;
+/** Ask the kernel for a loopback port. Start immediately afterwards to minimize the normal port race. */
+export declare function chooseOpenListPort(): Promise<number>;
+export declare function readOpenListCredentials(path?: string, seams?: OpenListSeams): Promise<OpenListCredentials | undefined>;
+export declare function writeOpenListCredentials(credentials: OpenListCredentials, path?: string, seams?: OpenListSeams, signal?: AbortSignal): Promise<void>;
+/** A Host-private authenticated API wrapper with redacted errors and safe mount shapes. */
+export declare class OpenListHostClient {
+    private credentials;
+    private readonly refreshToken?;
+    private readonly managed;
+    private readonly fetchImpl;
+    private readonly secretDefaults;
+    constructor(credentials: OpenListCredentials, seams?: OpenListSeams, refreshToken?: ((signal?: AbortSignal) => Promise<OpenListCredentials>) | undefined, managed?: boolean);
+    connect(signal?: AbortSignal): Promise<void>;
+    drivers(signal?: AbortSignal): Promise<string[]>;
+    driverInfo(signal?: AbortSignal): Promise<OpenListDriver[]>;
+    fillSecretDefaults(driver: string, supplied: Record<string, unknown>): Record<string, unknown>;
+    mounts(signal?: AbortSignal): Promise<OpenListMount[]>;
+    createMount(input: OpenListMountInput, signal?: AbortSignal): Promise<OpenListMount>;
+    updateMount(id: string, input: OpenListMountInput, signal?: AbortSignal): Promise<OpenListMount>;
+    /** Reauthentication patches only credential fields onto the full host-side row. */
+    updateMountPatch(id: string, additionPatch: Record<string, unknown>, signal?: AbortSignal): Promise<OpenListMount>;
+    removeMount(id: string, signal?: AbortSignal): Promise<void>;
+    disableMount(id: string, disabled?: boolean, signal?: AbortSignal): Promise<void>;
+    configureManagedIndex(signal?: AbortSignal): Promise<void>;
+    updateIndex(mountPath: string, signal?: AbortSignal): Promise<void>;
+    reindexMount(_id?: string, signal?: AbortSignal): Promise<{
+        supported: true;
+    }>;
+    indexProgress(signal?: AbortSignal): Promise<Pick<OpenListMount, 'indexStatus' | 'indexProgress' | 'indexCount'> | undefined>;
+    private request;
+    private mountRows;
+    private storageRow;
+    private mountRow;
+}
+/** Owns only a process it launched; it never kills a user-managed OpenList. */
+export declare class ManagedOpenListRuntime {
+    private readonly seams;
+    private child;
+    constructor(seams?: OpenListSeams);
+    get running(): boolean;
+    start(binary: string, dataDirectory: string, port?: number, signal?: AbortSignal): Promise<string>;
+    /** Generate an administrator password without exposing it in argv. */
+    setAdminPassword(binary: string, dataDirectory: string, _password?: string, signal?: AbortSignal, mutationState?: (state: OpenListAdminMutationState) => void): Promise<string>;
+    stop(): Promise<void>;
+}
+/** v4.2.2 reads `scheme.address` and `scheme.http_port` from data/config.json. */
+export declare function writeManagedOpenListConfig(dataDirectory: string, port: number, seams?: OpenListSeams, signal?: AbortSignal): Promise<void>;
+export declare function parseRandomAdminPassword(output: string): string | undefined;
+export declare function isSensitiveDriverField(name: string): boolean;
+export declare function isApiPagesQuickDriver(name: string): boolean;
+/** Recover the only crash window in Windows' two-rename executable replacement. */
+export declare function recoverInterruptedReplacement(target: string, backup: string, marker: string, seams?: OpenListSeams, windows?: boolean, owner?: symbol): Promise<void>;