dsh-reference-anything 0.2.0

package/lib/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `ctx.references` — the registry of sources that can name and read material
+ * held outside this session.
+ *
+ * Unlike a seam that selects one configured backend per capability, this one
+ * dispatches per call: every reference carries the id of the source that owns
+ * it, so a single session can hold references into a browser chat, an exported
+ * file, and another agent's log at the same time.
+ *
+ * @module dsh-reference-anything
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ReferenceRef, ReferenceSnapshot, ReferenceSource, ReferenceSummary, ReferenceWindow } from './types.ts';
+export type * from './types.ts';
+export { ReferenceAnythingError, type ReferenceErrorCode } from './errors.ts';
+export { REFERENCE_SCHEME, decodeReferenceUri, encodeReferenceUri, formatReferenceMention, mayContainReference, parseReferenceText, type ParsedReferenceText, } from './uri.ts';
+/** Fan-out cap applied to discovery when a caller names no limit of its own. */
+export declare const DEFAULT_LIST_LIMIT = 20;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        references: ReferenceRuntime;
+    }
+}
+/** Deployment settings for reference discovery. */
+export interface Config {
+    /**
+     * Maximum items discovery returns across all sources combined. Varies by
+     * deployment: a browser host may have fifty open conversations where a
+     * directory of exports has three.
+     */
+    listLimit?: number;
+}
+/** Runtime schema for {@link Config}. */
+export declare const Config: z<Config>;
+/** Registry and dispatcher for {@link ReferenceSource} implementations. */
+export default class ReferenceRuntime extends Service {
+    static Config: z<Config>;
+    private readonly sources;
+    private readonly grants;
+    private readonly listLimit;
+    /**
+     * @param ctx - the mounting context.
+     * @param config - validated deployment settings.
+     */
+    constructor(ctx: Context, config?: Config);
+    /**
+     * Add one source to the registry.
+     * @param source - the implementation to register; its `id` must be unused.
+     * @returns a disposer that removes it again.
+     */
+    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. */
+    grant(sessionId: string, ref: ReferenceRef): void;
+    /** Enforce that a Web conversation URI originated in this task's mention/list surface. */
+    assertGranted(sessionId: string | undefined, ref: ReferenceRef): void;
+    /** Release task-local grants when a host knows the task is gone. */
+    revoke(sessionId: string): void;
+    /**
+     * Discover referenceable items across every available source.
+     *
+     * One source failing does not fail discovery — a broken browser attachment
+     * should not hide the exported files sitting on disk. Every available source
+     * failing does, because that is indistinguishable from a broken deployment
+     * and returning an empty list would present it as "you have no conversations".
+     * @param query - case-insensitive substring; empty means "the most relevant items".
+     * @param limit - maximum items overall; defaults to the configured `listLimit`.
+     * @param signal - cancellation from the caller.
+     * @returns matching items, capped at `limit`.
+     */
+    list(query?: string, limit?: number, signal?: AbortSignal): Promise<ReferenceSummary[]>;
+    /**
+     * Read one window of turns from a reference.
+     * @param ref - the reference to resolve; its `source` selects the owning implementation.
+     * @param window - which turns to return.
+     * @param signal - cancellation from the caller.
+     * @returns the requested turns and their position in the conversation.
+     */
+    read(ref: ReferenceRef, window: ReferenceWindow, signal?: AbortSignal): Promise<ReferenceSnapshot>;
+    private availableSources;
+}

package/lib/index.js

@@ -0,0 +1,153 @@
+/**
+ * `ctx.references` — the registry of sources that can name and read material
+ * held outside this session.
+ *
+ * Unlike a seam that selects one configured backend per capability, this one
+ * dispatches per call: every reference carries the id of the source that owns
+ * it, so a single session can hold references into a browser chat, an exported
+ * file, and another agent's log at the same time.
+ *
+ * @module dsh-reference-anything
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { ReferenceAnythingError } from "./errors.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. */
+export const DEFAULT_LIST_LIMIT = 20;
+/** Runtime schema for {@link Config}. */
+export const Config = z.object({
+    listLimit: z.number().step(1).min(1).default(DEFAULT_LIST_LIMIT),
+});
+/** Registry and dispatcher for {@link ReferenceSource} implementations. */
+export default class ReferenceRuntime extends Service {
+    static Config = Config;
+    sources = new Map();
+    grants = new Map();
+    listLimit;
+    /**
+     * @param ctx - the mounting context.
+     * @param config - validated deployment settings.
+     */
+    constructor(ctx, config = {}) {
+        super(ctx, 'references');
+        this.listLimit = config.listLimit ?? DEFAULT_LIST_LIMIT;
+        ctx.on('session/disposed', session => { this.revoke(String(session.id)); });
+    }
+    /**
+     * Add one source to the registry.
+     * @param source - the implementation to register; its `id` must be unused.
+     * @returns a disposer that removes it again.
+     */
+    registerSource(source) {
+        if (this.sources.has(source.id)) {
+            throw new ReferenceAnythingError(`a reference source with id ${JSON.stringify(source.id)} is already registered`, 'SOURCE_DUPLICATE');
+        }
+        const sources = this.sources;
+        const dispose = this.ctx.effect(function* () {
+            sources.set(source.id, source);
+            yield () => sources.delete(source.id);
+        }, 'references.registerSource()');
+        // ctx.effect's disposer resolves a promise; this API is synchronous
+        // fire-and-forget, so the settled promise is discarded.
+        return () => void dispose();
+    }
+    /** @returns the registered source ids, in registration order. */
+    sourceIds() {
+        return [...this.sources.keys()];
+    }
+    /** Authorize one task to read a Web conversation named by its user or discovery tool. */
+    grant(sessionId, ref) {
+        if (ref.source !== 'web-chat')
+            return;
+        const values = this.grants.get(sessionId) ?? new Set();
+        values.add(ref.id);
+        this.grants.set(sessionId, values);
+    }
+    /** Enforce that a Web conversation URI originated in this task's mention/list surface. */
+    assertGranted(sessionId, ref) {
+        if (ref.source !== 'web-chat')
+            return;
+        if (!sessionId || !this.grants.get(sessionId)?.has(ref.id)) {
+            throw new ReferenceAnythingError('this task has not been granted access to that conversation reference', 'CONVERSATION_REFERENCE_NOT_GRANTED');
+        }
+    }
+    /** Release task-local grants when a host knows the task is gone. */
+    revoke(sessionId) { this.grants.delete(sessionId); }
+    /**
+     * Discover referenceable items across every available source.
+     *
+     * One source failing does not fail discovery — a broken browser attachment
+     * should not hide the exported files sitting on disk. Every available source
+     * failing does, because that is indistinguishable from a broken deployment
+     * and returning an empty list would present it as "you have no conversations".
+     * @param query - case-insensitive substring; empty means "the most relevant items".
+     * @param limit - maximum items overall; defaults to the configured `listLimit`.
+     * @param signal - cancellation from the caller.
+     * @returns matching items, capped at `limit`.
+     */
+    async list(query = '', limit = this.listLimit, signal) {
+        throwIfCancelled(signal);
+        const available = await this.availableSources(signal);
+        if (available.length === 0)
+            return [];
+        const settled = await Promise.allSettled(available.map(source => source.list(query, limit, signal)));
+        throwIfCancelled(signal);
+        const failures = settled.filter(result => result.status === 'rejected');
+        if (failures.length === available.length) {
+            throw new ReferenceAnythingError(`every available reference source failed to list (${available.map(s => s.id).join(', ')})`, 'REFERENCE_READ_FAILED', { cause: failures[0]?.reason });
+        }
+        return settled
+            .flatMap(result => result.status === 'fulfilled' ? result.value : [])
+            .slice(0, limit);
+    }
+    /**
+     * Read one window of turns from a reference.
+     * @param ref - the reference to resolve; its `source` selects the owning implementation.
+     * @param window - which turns to return.
+     * @param signal - cancellation from the caller.
+     * @returns the requested turns and their position in the conversation.
+     */
+    async read(ref, window, signal) {
+        throwIfCancelled(signal);
+        const source = this.sources.get(ref.source);
+        if (source === undefined) {
+            throw new ReferenceAnythingError(`no reference source named ${JSON.stringify(ref.source)} is registered`, 'SOURCE_UNKNOWN');
+        }
+        if (!await source.available()) {
+            throw new ReferenceAnythingError(`reference source ${JSON.stringify(ref.source)} is not currently usable`, 'SOURCE_UNAVAILABLE');
+        }
+        throwIfCancelled(signal);
+        try {
+            return await source.read(ref, window, signal);
+        }
+        catch (error) {
+            if (error instanceof ReferenceAnythingError)
+                throw error;
+            throwIfCancelled(signal);
+            throw new ReferenceAnythingError(`reference source ${JSON.stringify(ref.source)} failed to read ${JSON.stringify(ref.id)}`, 'REFERENCE_READ_FAILED', { cause: error });
+        }
+    }
+    async availableSources(signal) {
+        const sources = [...this.sources.values()];
+        const checks = await Promise.all(sources.map(async (source) => {
+            try {
+                return await source.available();
+            }
+            catch {
+                // `available()` is documented as a cheap local check. One that throws
+                // is broken, not merely unusable, and treating it as unavailable keeps
+                // the rest of discovery working.
+                return false;
+            }
+        }));
+        throwIfCancelled(signal);
+        return sources.filter((_source, index) => checks[index] === true);
+    }
+}
+function throwIfCancelled(signal) {
+    if (signal?.aborted !== true)
+        return;
+    throw new ReferenceAnythingError('reference lookup was cancelled', 'REFERENCE_CANCELLED', { cause: signal.reason });
+}

package/lib/opencli.d.ts

@@ -0,0 +1,116 @@
+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.0";
+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 declare class OpenCliError extends Error {
+    readonly code: OpenCliErrorCode;
+    constructor(message: string, code: OpenCliErrorCode, options?: ErrorOptions);
+}
+export interface OpenCliRunnerOptions {
+    executable?: string;
+    /** Fixed argv placed before OpenCLI arguments; useful for a Node-hosted wrapper or tests. */
+    prefixArgs?: readonly string[];
+    profile?: string;
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+/** Connection state of the Browser Bridge browser extension, mirroring `opencli daemon status`. */
+export type ExtensionState = 'connected' | 'disconnected' | 'profile-required' | 'profile-disconnected' | 'daemon-offline';
+export interface OpenCliHealth {
+    version: string;
+    /** Raw `opencli daemon status` output, kept for display and debugging. */
+    daemon: string;
+    pluginInstalled: boolean;
+    daemonRunning: boolean;
+    extensionConnected: boolean;
+    extensionState: ExtensionState;
+    extensionVersion?: string;
+    profileCount?: number;
+    opencliCompatible: boolean;
+    daemonVersion?: string;
+    daemonStale: boolean;
+    connectivityOk: boolean;
+    pluginVersion?: string;
+    adapterCommandsReady: boolean;
+    adapterCompatible: boolean;
+    versionError?: string;
+    daemonError?: string;
+    pluginError?: string;
+    doctorError?: string;
+}
+/** Result returned to the settings page after searching for an executable. */
+export interface OpenCliDiscovery {
+    found: boolean;
+    executable: string;
+    version: string;
+    error?: string;
+}
+export interface DaemonStatus {
+    daemonRunning: boolean;
+    extensionState: ExtensionState;
+    extensionConnected: boolean;
+    extensionVersion?: string;
+    profileCount?: number;
+}
+/**
+ * Parse the human-readable `opencli daemon status` output into structured
+ * bridge state. Empty output — including a probe failure — degrades to
+ * `daemon-offline` rather than throwing, so one broken probe never hides the
+ * rest of the viability panel.
+ */
+export declare function parseDaemonStatus(output: string): DaemonStatus;
+export interface BrowserProfile {
+    id: string;
+    alias?: string;
+    connected: boolean;
+    isDefault: boolean;
+}
+export interface ProviderIndex {
+    accountScope: string;
+    sinceApplied: string;
+    rows: ProviderConversationRow[];
+}
+export declare class OpenCliRunner {
+    readonly executable: string;
+    readonly profile: string;
+    readonly prefixArgs: readonly string[];
+    readonly timeoutMs: number;
+    readonly maxStdoutBytes: number;
+    constructor(options?: OpenCliRunnerOptions);
+    whoami(provider: ChatProvider, signal?: AbortSignal): Promise<string>;
+    /**
+     * List a provider's conversations.
+     * @param provider - which provider to list.
+     * @param signal - cancellation from the caller.
+     * @param since - ISO instant the adapter may stop paging at. Best-effort:
+     * adapters that page in an order they cannot vouch for ignore it, and one
+     * installed before the flag existed is retried without it rather than
+     * failing the pass.
+     * @returns the listed conversations.
+     */
+    history(provider: ChatProvider, signal?: AbortSignal, since?: string): Promise<ProviderConversationRow[]>;
+    /** 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>>;
+    health(signal?: AbortSignal): Promise<OpenCliHealth>;
+    /** Lightweight executable validation used by automatic path discovery. */
+    version(signal?: AbortSignal): Promise<string>;
+    /** Confirm the executable also exposes OpenCLI's plugin command, not merely a semver-looking --version. */
+    verifyInstallation(signal?: AbortSignal): Promise<void>;
+    profiles(signal?: AbortSignal): Promise<BrowserProfile[]>;
+    installPlugin(pluginUrl: string, signal?: AbortSignal): Promise<void>;
+    restartDaemon(signal?: AbortSignal): Promise<void>;
+    private probe;
+    private historyRows;
+    private json;
+    private raw;
+}
+/** Locate a working OpenCLI without asking a command-line newcomer for PATH details. */
+export declare function discoverOpenCli(configured?: string, signal?: AbortSignal): Promise<OpenCliDiscovery>;
+/** Install or upgrade the supported OpenCLI package through this Node runtime's npm. */
+export declare function installOpenCli(signal?: AbortSignal): Promise<OpenCliDiscovery>;
+/** Numeric semver comparison for the stable x.y.z versions OpenCLI publishes. */
+export declare function versionAtLeast(value: string, minimum: string): boolean;