dsh-reference-anything 0.3.1 → 0.3.2

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>;