@zleap-ai/dsh-sag 0.1.0

package/lib/connection/manager.js

@@ -0,0 +1,273 @@
+import { SagApiClient, SagApiError } from '../local/api-client.js';
+import { createSagGateway } from '../local/gateway.js';
+import { McpProbeIncompatibleError, probeMcp, } from '../local/mcp-probe.js';
+function errorMessage(error, descriptor) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.split(descriptor.accessToken).join('<redacted>');
+}
+/** Run health, readiness, capabilities, source count, and MCP compatibility checks without mutations. */
+export async function inspectSagConnection(descriptor, signal, gateway = createSagGateway(new SagApiClient(descriptor)), mcpProbe = (candidate, candidateSignal, capabilities) => probeMcp(candidate, candidateSignal, undefined, capabilities)) {
+    const errors = [];
+    let health = false;
+    try {
+        await gateway.health(signal);
+        health = true;
+    }
+    catch (error) {
+        errors.push(errorMessage(error, descriptor));
+        return { status: 'unreachable', health, ready: false, sourceCount: 0, errors };
+    }
+    const [readyResult, capabilitiesResult] = await Promise.allSettled([
+        gateway.ready(signal),
+        gateway.capabilities(signal),
+    ]);
+    if (signal.aborted)
+        throw signal.reason;
+    const supportsSourceList = capabilitiesResult.status === 'fulfilled'
+        && capabilitiesResult.value.capabilities.includes('sources.list');
+    const sourcesResult = supportsSourceList
+        ? await gateway.listSources(signal).then(value => ({ status: 'fulfilled', value }), reason => ({ status: 'rejected', reason }))
+        : { status: 'fulfilled', value: [] };
+    if (signal.aborted)
+        throw signal.reason;
+    const mcpResult = capabilitiesResult.status === 'fulfilled'
+        ? await mcpProbe(descriptor, signal, capabilitiesResult.value.capabilities).then(value => ({ status: 'fulfilled', value }), reason => ({ status: 'rejected', reason }))
+        : { status: 'rejected', reason: capabilitiesResult.reason };
+    if (signal.aborted)
+        throw signal.reason;
+    const ready = readyResult.status === 'fulfilled';
+    const capabilities = capabilitiesResult.status === 'fulfilled' ? capabilitiesResult.value : undefined;
+    const sourceCount = sourcesResult.status === 'fulfilled' ? sourcesResult.value.length : 0;
+    const mcp = mcpResult.status === 'fulfilled' ? mcpResult.value : undefined;
+    for (const result of [readyResult, capabilitiesResult, ...(supportsSourceList ? [sourcesResult] : []), ...(capabilitiesResult.status === 'fulfilled' ? [mcpResult] : [])]) {
+        if (result.status === 'rejected')
+            errors.push(errorMessage(result.reason, descriptor));
+    }
+    let status;
+    if (!ready || (supportsSourceList && sourcesResult.status === 'rejected')) {
+        status = 'unreachable';
+    }
+    else if (capabilitiesResult.status === 'rejected') {
+        status = capabilitiesResult.reason instanceof SagApiError ? 'unreachable' : 'incompatible';
+    }
+    else if (mcpResult.status === 'rejected') {
+        status = mcpResult.reason instanceof McpProbeIncompatibleError ? 'incompatible' : 'unreachable';
+    }
+    else {
+        status = 'ready';
+    }
+    return {
+        status,
+        health,
+        ready,
+        sourceCount,
+        ...(capabilities === undefined ? {} : { capabilities }),
+        ...(mcp === undefined ? {} : { mcp }),
+        ...(errors.length === 0 ? {} : { errors }),
+    };
+}
+function waitForCaller(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort)).catch(() => undefined);
+    });
+}
+/** Lazy, single-flight manager for saved and automatically discovered local SAG connections. */
+export class SagConnectionManager {
+    deps;
+    flight;
+    connected;
+    gateway;
+    requestTimeoutMs;
+    readyCacheTtlMs;
+    connectedAt = 0;
+    generation = 0;
+    requestSequence = 0;
+    latestAdmittedRequest = 0;
+    /** @param deps - saved-connection reader, discovery, and optional testable network seams. */
+    constructor(deps) {
+        this.deps = deps;
+        this.gateway = deps.gateway ?? (descriptor => createSagGateway(new SagApiClient(descriptor)));
+        this.requestTimeoutMs = deps.requestTimeoutMs ?? 30_000;
+        this.readyCacheTtlMs = deps.readyCacheTtlMs ?? 5_000;
+    }
+    report(descriptor, gateway, inspection, discovery) {
+        return {
+            ...inspection,
+            descriptor,
+            gateway,
+            ...(discovery === undefined ? {} : { discovery }),
+        };
+    }
+    async inspectCandidate(descriptor, signal, assertOwned) {
+        const gateway = this.gateway(descriptor);
+        try {
+            const inspection = this.deps.inspect === undefined
+                ? await inspectSagConnection(descriptor, signal, gateway)
+                : await this.deps.inspect(descriptor, signal);
+            assertOwned();
+            return { inspection, gateway };
+        }
+        catch (error) {
+            this.closeDetached(gateway);
+            throw error;
+        }
+    }
+    async connect(saved, signal, assertOwned) {
+        let savedInspection;
+        if (saved !== undefined) {
+            const candidate = await this.inspectCandidate(saved, signal, assertOwned);
+            savedInspection = candidate.inspection;
+            if (savedInspection.status === 'ready')
+                return this.report(saved, candidate.gateway, savedInspection);
+            this.closeDetached(candidate.gateway);
+        }
+        const discovery = await this.deps.discover(signal);
+        assertOwned();
+        if (discovery.descriptor === undefined) {
+            if (saved !== undefined && savedInspection !== undefined)
+                return { ...savedInspection, descriptor: saved, discovery };
+            return { status: 'not-found', health: false, ready: false, sourceCount: 0, discovery };
+        }
+        const candidate = await this.inspectCandidate(discovery.descriptor, signal, assertOwned);
+        const report = this.report(discovery.descriptor, candidate.gateway, candidate.inspection, discovery);
+        return report;
+    }
+    deadline(operation) {
+        const controller = new AbortController();
+        let timer;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                const error = new Error(`dsh-sag: SAG connection inspection timed out after ${this.requestTimeoutMs} ms`);
+                controller.abort(error);
+                reject(error);
+            }, this.requestTimeoutMs);
+        });
+        const running = operation(controller.signal);
+        running.catch(() => undefined);
+        return Promise.race([running, timeout]).finally(() => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        });
+    }
+    static fingerprint(descriptor) {
+        if (descriptor === undefined)
+            return 'discover';
+        return JSON.stringify([
+            descriptor.schemaVersion, descriptor.name, descriptor.apiUrl, descriptor.mcpUrl,
+            descriptor.accessToken, descriptor.defaultSourceId ?? null,
+        ]);
+    }
+    closeDetached(gateway) {
+        if (gateway?.close === undefined)
+            return;
+        try {
+            const closing = Promise.resolve(gateway.close());
+            const bounded = new Promise(resolve => {
+                const timer = setTimeout(resolve, Math.min(this.requestTimeoutMs, 1_000));
+                timer.unref?.();
+            });
+            void Promise.race([closing, bounded]).catch(() => undefined);
+        }
+        catch {
+            // Obsolete optional gateway cleanup cannot invalidate a new ready connection.
+        }
+    }
+    replaceConnected(report) {
+        const previous = this.connected;
+        this.connected = report.status === 'ready' ? report : undefined;
+        this.connectedAt = report.status === 'ready' ? Date.now() : 0;
+        if (previous?.gateway !== report.gateway)
+            this.closeDetached(previous?.gateway);
+        if (report.status !== 'ready')
+            this.closeDetached(report.gateway);
+    }
+    reusableConnected(saved) {
+        if (this.connected === undefined || Date.now() - this.connectedAt >= this.readyCacheTtlMs)
+            return undefined;
+        const matches = saved === undefined
+            ? this.connected.discovery?.descriptor !== undefined
+            : SagConnectionManager.fingerprint(this.connected.descriptor) === SagConnectionManager.fingerprint(saved);
+        return matches ? this.connected : undefined;
+    }
+    /** Load the caller's latest saved descriptor, then share only a matching connection flight. */
+    async ensureConnected(signal) {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        const request = ++this.requestSequence;
+        const admission = this.deadline(async (callerDeadlineSignal) => {
+            const assertCallerActive = () => {
+                if (signal.aborted)
+                    throw signal.reason;
+                if (callerDeadlineSignal.aborted)
+                    throw callerDeadlineSignal.reason;
+            };
+            const saved = await this.deps.store.load();
+            assertCallerActive();
+            const key = SagConnectionManager.fingerprint(saved);
+            if (request < this.latestAdmittedRequest) {
+                const reusable = this.reusableConnected(saved);
+                if (reusable !== undefined)
+                    return reusable;
+                if (this.flight?.key === key)
+                    return waitForCaller(this.flight.promise, callerDeadlineSignal);
+                throw new Error('dsh-sag: connection request was superseded');
+            }
+            this.latestAdmittedRequest = request;
+            if (this.flight !== undefined && this.flight.key !== key) {
+                ++this.generation;
+                this.flight = undefined;
+            }
+            const reusable = this.reusableConnected(saved);
+            if (reusable !== undefined)
+                return reusable;
+            if (this.flight?.key === key)
+                return waitForCaller(this.flight.promise, callerDeadlineSignal);
+            const generation = ++this.generation;
+            const promise = this.deadline(async (sharedSignal) => {
+                const assertOwned = () => {
+                    if (sharedSignal.aborted)
+                        throw sharedSignal.reason;
+                    if (generation !== this.generation)
+                        throw new Error('dsh-sag: connection flight was superseded');
+                };
+                let report;
+                try {
+                    report = await this.connect(saved, sharedSignal, assertOwned);
+                    assertOwned();
+                    this.replaceConnected(report);
+                    return report;
+                }
+                catch (error) {
+                    if (report?.gateway !== this.connected?.gateway)
+                        this.closeDetached(report?.gateway);
+                    throw error;
+                }
+            });
+            const flight = { key, promise };
+            this.flight = flight;
+            promise.finally(() => {
+                if (this.flight === flight)
+                    this.flight = undefined;
+            }).catch(() => undefined);
+            return waitForCaller(promise, callerDeadlineSignal);
+        });
+        return waitForCaller(admission, signal);
+    }
+    /** Re-run only non-mutating connection checks for setup and diagnostics. */
+    async doctor(signal) {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        return waitForCaller(this.deadline(async (sharedSignal) => {
+            const assertActive = () => { if (sharedSignal.aborted)
+                throw sharedSignal.reason; };
+            const saved = await this.deps.store.load();
+            assertActive();
+            return this.connect(saved, sharedSignal, assertActive);
+        }), signal);
+    }
+}
+//# sourceMappingURL=manager.js.map

package/lib/connection/store.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import { type SettingsScope } from '@deepseek-ai/dsh-settings';
+import type { SagConnectionDescriptor, SagLocalSettings } from './types.js';
+/** The fixed settings namespace for the locally managed SAG connection. */
+export declare const SAG_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** The only credential record owned by the local SAG connection. */
+export declare const SAG_CREDENTIAL_KEY: import("@deepseek-ai/dsh-credentials").CredentialKey;
+/** Machine-readable error for saved connection data that cannot be used safely. */
+export declare class SagConnectionConfigurationError extends Error {
+    /** Stable error code for interactive configuration surfaces. */
+    readonly code = "SAG_CONNECTION_CONFIG_INVALID";
+    /** Stored location that failed validation. */
+    readonly field: string;
+    /**
+     * @param field - stored location that failed validation.
+     * @param message - human-readable validation failure.
+     */
+    constructor(field: string, message: string);
+}
+/** The services the store uses; kept small so callers can provide real providers or focused in-memory fakes. */
+export interface SagConnectionStoreDeps {
+    readonly credentials: Pick<CredentialProvider, 'readRecord' | 'modifyRecord' | 'deleteRecord'>;
+    readonly settings: SettingsScope<SagLocalSettings>;
+}
+/** Register the non-secret local connection settings in the fixed plugin namespace. */
+export declare function registerSagSettings(ctx: Context): SettingsScope<SagLocalSettings>;
+/** Store one local connection with endpoints in Settings and its bearer token in Credentials. */
+export declare class SagConnectionStore {
+    private readonly deps;
+    /**
+     * @param deps - live settings and credential providers.
+     */
+    constructor(deps: SagConnectionStoreDeps);
+    /** Read the saved connection, resolving the credential record again for every call. */
+    load(): Promise<SagConnectionDescriptor | undefined>;
+    /** Persist a complete connection, deliberately keeping its token outside Settings. */
+    save(descriptor: SagConnectionDescriptor): Promise<void>;
+    /** Remove the saved local connection and its owned credential record. */
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/connection/store.js

@@ -0,0 +1,164 @@
+import { credentialKey } from '@deepseek-ai/dsh-credentials';
+import { settingsNamespace } from '@deepseek-ai/dsh-settings';
+import z from '@deepseek-ai/schemastery';
+import { parseConnectionDescriptor } from './descriptor.js';
+/** The fixed settings namespace for the locally managed SAG connection. */
+export const SAG_SETTINGS_NAMESPACE = settingsNamespace('dsh-sag');
+/** The only credential record owned by the local SAG connection. */
+export const SAG_CREDENTIAL_KEY = credentialKey('dsh-sag', 'local');
+/** Machine-readable error for saved connection data that cannot be used safely. */
+export class SagConnectionConfigurationError extends Error {
+    /** Stable error code for interactive configuration surfaces. */
+    code = 'SAG_CONNECTION_CONFIG_INVALID';
+    /** Stored location that failed validation. */
+    field;
+    /**
+     * @param field - stored location that failed validation.
+     * @param message - human-readable validation failure.
+     */
+    constructor(field, message) {
+        super(`dsh-sag: saved connection ${field} ${message}`);
+        this.name = 'SagConnectionConfigurationError';
+        this.field = field;
+    }
+}
+const LocalSettingsSchema = z.object({
+    schemaVersion: z.const(1).default(1),
+    mode: z.const('local').default('local'),
+    name: z.string().default(''),
+    apiUrl: z.string().default(''),
+    mcpUrl: z.string().default(''),
+    defaultSourceId: z.union([z.string(), z.const(null)]).default(null),
+    credentialId: z.const('local').default('local'),
+});
+/** Register the non-secret local connection settings in the fixed plugin namespace. */
+export function registerSagSettings(ctx) {
+    return ctx.settings.register(SAG_SETTINGS_NAMESPACE, LocalSettingsSchema);
+}
+function plainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function localSettings(value) {
+    if (!plainObject(value)) {
+        throw new SagConnectionConfigurationError('settings', 'must be an object');
+    }
+    const expected = new Set(['schemaVersion', 'mode', 'name', 'apiUrl', 'mcpUrl', 'defaultSourceId', 'credentialId']);
+    for (const key of Object.keys(value)) {
+        if (!expected.has(key)) {
+            throw new SagConnectionConfigurationError(`settings.${key}`, 'is not supported');
+        }
+    }
+    if (value.schemaVersion !== 1) {
+        throw new SagConnectionConfigurationError('settings.schemaVersion', 'must be 1');
+    }
+    if (value.mode !== 'local') {
+        throw new SagConnectionConfigurationError('settings.mode', 'must be local');
+    }
+    if (value.credentialId !== 'local') {
+        throw new SagConnectionConfigurationError('settings.credentialId', 'must be local');
+    }
+    for (const field of ['name', 'apiUrl', 'mcpUrl']) {
+        if (typeof value[field] !== 'string') {
+            throw new SagConnectionConfigurationError(`settings.${field}`, 'must be a string');
+        }
+    }
+    const defaultSourceId = value.defaultSourceId;
+    if (defaultSourceId !== null && (typeof defaultSourceId !== 'string' || !defaultSourceId.trim())) {
+        throw new SagConnectionConfigurationError('settings.defaultSourceId', 'must be a non-empty string or null');
+    }
+    return {
+        schemaVersion: 1,
+        mode: 'local',
+        name: value.name,
+        apiUrl: value.apiUrl,
+        mcpUrl: value.mcpUrl,
+        defaultSourceId,
+        credentialId: 'local',
+    };
+}
+function credentialPayload(record) {
+    if (record.kind !== 'grant') {
+        throw new SagConnectionConfigurationError('credential.kind', 'must be grant');
+    }
+    if (!plainObject(record.payload)) {
+        throw new SagConnectionConfigurationError('credential.payload', 'must be an object');
+    }
+    const expected = new Set(['schemaVersion', 'accessToken']);
+    for (const key of Object.keys(record.payload)) {
+        if (!expected.has(key)) {
+            throw new SagConnectionConfigurationError(`credential.payload.${key}`, 'is not supported');
+        }
+    }
+    if (record.payload.schemaVersion !== 1) {
+        throw new SagConnectionConfigurationError('credential.payload.schemaVersion', 'must be 1');
+    }
+    if (typeof record.payload.accessToken !== 'string' || !record.payload.accessToken.trim()) {
+        throw new SagConnectionConfigurationError('credential.payload.accessToken', 'must be a non-empty string');
+    }
+    return { schemaVersion: 1, accessToken: record.payload.accessToken };
+}
+function descriptorErrorField(error) {
+    const message = error instanceof Error ? error.message : '';
+    for (const field of ['name', 'apiUrl', 'mcpUrl', 'defaultSourceId']) {
+        if (message.startsWith(`dsh-sag: connection descriptor ${field} `)) {
+            return `settings.${field}`;
+        }
+    }
+    return 'settings';
+}
+/** Store one local connection with endpoints in Settings and its bearer token in Credentials. */
+export class SagConnectionStore {
+    deps;
+    /**
+     * @param deps - live settings and credential providers.
+     */
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Read the saved connection, resolving the credential record again for every call. */
+    async load() {
+        const record = await this.deps.credentials.readRecord(SAG_CREDENTIAL_KEY);
+        if (record === undefined)
+            return undefined;
+        const settings = localSettings(this.deps.settings.get());
+        const credential = credentialPayload(record);
+        try {
+            return parseConnectionDescriptor({
+                schemaVersion: settings.schemaVersion,
+                name: settings.name,
+                apiUrl: settings.apiUrl,
+                mcpUrl: settings.mcpUrl,
+                accessToken: credential.accessToken,
+                defaultSourceId: settings.defaultSourceId,
+            });
+        }
+        catch (error) {
+            throw new SagConnectionConfigurationError(descriptorErrorField(error), error instanceof Error ? error.message : 'is invalid');
+        }
+    }
+    /** Persist a complete connection, deliberately keeping its token outside Settings. */
+    async save(descriptor) {
+        await this.deps.credentials.modifyRecord(SAG_CREDENTIAL_KEY, async () => ({
+            kind: 'grant',
+            payload: { schemaVersion: 1, accessToken: descriptor.accessToken },
+        }));
+        await this.deps.settings.update({
+            schemaVersion: 1,
+            mode: 'local',
+            name: descriptor.name,
+            apiUrl: descriptor.apiUrl,
+            mcpUrl: descriptor.mcpUrl,
+            defaultSourceId: descriptor.defaultSourceId ?? null,
+            credentialId: 'local',
+        });
+    }
+    /** Remove the saved local connection and its owned credential record. */
+    async clear() {
+        await this.deps.credentials.deleteRecord(SAG_CREDENTIAL_KEY);
+        await this.deps.settings.replace({});
+    }
+}
+//# sourceMappingURL=store.js.map

package/lib/connection/types.d.ts

@@ -0,0 +1,35 @@
+/** A versioned local SAG connection, as exported by the SAG application. */
+export interface SagConnectionDescriptor {
+    readonly schemaVersion: 1;
+    readonly name: string;
+    readonly apiUrl: string;
+    readonly mcpUrl: string;
+    readonly accessToken: string;
+    readonly defaultSourceId?: string | null;
+}
+/** The non-sensitive portion of a saved local SAG connection. */
+export interface SagLocalSettings {
+    readonly schemaVersion: 1;
+    readonly mode: 'local';
+    readonly name: string;
+    readonly apiUrl: string;
+    readonly mcpUrl: string;
+    readonly defaultSourceId?: string | null;
+    readonly credentialId: 'local';
+}
+/** The credential payload kept separately from local settings. */
+export interface SagCredentialPayload {
+    readonly schemaVersion: 1;
+    readonly accessToken: string;
+}
+/** The versioned dsh integration capabilities advertised by SAG. */
+export interface SagCapabilityDescriptor {
+    readonly schemaVersion: 1;
+    readonly capabilities: readonly string[];
+    readonly upload?: {
+        readonly maxMb: number;
+        readonly extensions: readonly string[];
+    };
+    readonly defaultSourceId?: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/connection/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map