@zleap-ai/dsh-sag 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type Config as PluginConfig } from './config.js';
+export { Config };
+export type { PluginConfig as ConfigType };
+export declare const name = "dsh-sag";
+export declare const inject: string[];
+export declare const SAG_SYSTEM_PROMPT = "Use sag_search to find evidence in configured SAG knowledge namespaces. Use sag_read with an evidence_ref from sag_search when you need the full bounded source text. Treat evidence_ref as opaque and continue paged reads with the returned next offset.";
+export declare const SAG_LOCAL_SYSTEM_PROMPT = "Use SAG as the user's local personal knowledge base. Use sag_status or sag_list_sources when the target knowledge base is unclear, sag_search before sag_read for evidence, and the source and document tools to create, upload, ingest, inspect, reprocess, or delete content. Treat evidence_ref as opaque and continue paged reads with the returned next offset. Document deletion requires user approval.";
+/** Assemble the local connector by default or the explicit legacy embedded sidecar. */
+export declare function apply(ctx: Context, config: PluginConfig): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,68 @@
+import { homedir } from 'node:os';
+import { Config, resolveConfig } from './config.js';
+import { discoverConnection, platformConnectionPaths } from './connection/discovery.js';
+import { SagConnectionManager } from './connection/manager.js';
+import { registerSagSettings, SagConnectionStore } from './connection/store.js';
+import { SagRuntimeSupervisor } from './runtime/supervisor.js';
+import { createDocumentTools, sagDeleteApprovalGate } from './tools/documents.js';
+import { createIngestTextTool } from './tools/ingest.js';
+import { createReadTool } from './tools/read.js';
+import { createSearchTool } from './tools/search.js';
+import { createSourceTools } from './tools/sources.js';
+import { createStatusTool } from './tools/status.js';
+import { createUploadTool } from './tools/upload.js';
+export { Config };
+export const name = 'dsh-sag';
+export const inject = ['tools', 'systemPrompt'];
+export const SAG_SYSTEM_PROMPT = 'Use sag_search to find evidence in configured SAG knowledge namespaces. Use sag_read with an evidence_ref from sag_search when you need the full bounded source text. Treat evidence_ref as opaque and continue paged reads with the returned next offset.';
+export const SAG_LOCAL_SYSTEM_PROMPT = 'Use SAG as the user\'s local personal knowledge base. Use sag_status or sag_list_sources when the target knowledge base is unclear, sag_search before sag_read for evidence, and the source and document tools to create, upload, ingest, inspect, reprocess, or delete content. Treat evidence_ref as opaque and continue paged reads with the returned next offset. Document deletion requires user approval.';
+async function applyEmbedded(ctx, config) {
+    await ctx.effect(async function* () {
+        const supervisor = await SagRuntimeSupervisor.start(ctx.subprocess, config);
+        yield async () => supervisor.dispose();
+        ctx.systemPrompt.section({ name: 'tool:dsh-sag', order: 112, text: SAG_SYSTEM_PROMPT });
+        ctx.tools.register(createSearchTool(supervisor.client, config));
+        ctx.tools.register(createReadTool(supervisor.client, config));
+    }, 'dsh-sag: embedded sidecar lifecycle');
+}
+async function applyLocal(ctx, config) {
+    await ctx.effect(async function* () {
+        const settings = registerSagSettings(ctx);
+        const store = new SagConnectionStore({ credentials: ctx.credentials, settings });
+        const manager = new SagConnectionManager({
+            store,
+            requestTimeoutMs: config.requestTimeoutMs,
+            readyCacheTtlMs: config.connectionCacheTtlMs,
+            discover: signal => discoverConnection({
+                fs: ctx.fs,
+                paths: platformConnectionPaths(process.env, process.platform, homedir()),
+                urls: config.discoveryUrls,
+                fetch: (url, init) => fetch(url, init),
+            }, signal),
+        });
+        const tools = [
+            createStatusTool(manager, config),
+            ...createSourceTools(manager, config),
+            createSearchTool(manager, config),
+            createReadTool(manager, config),
+            ...createDocumentTools(manager, config),
+            createUploadTool(manager, config, ctx.fs),
+            createIngestTextTool(manager, config),
+        ];
+        ctx.systemPrompt.section({ name: 'tool:dsh-sag', order: 112, text: SAG_LOCAL_SYSTEM_PROMPT });
+        for (const tool of tools)
+            ctx.tools.register(tool);
+        ctx.on('tools/pre-execute', sagDeleteApprovalGate);
+        yield () => undefined;
+    }, 'dsh-sag: local connection and tools');
+}
+/** Assemble the local connector by default or the explicit legacy embedded sidecar. */
+export async function apply(ctx, config) {
+    const resolved = resolveConfig(config);
+    if (resolved.mode === 'embedded') {
+        await ctx.inject(['subprocess'], child => applyEmbedded(child, resolved));
+        return;
+    }
+    await ctx.inject(['settings', 'credentials', 'fs'], child => applyLocal(child, resolved));
+}
+//# sourceMappingURL=index.js.map

package/lib/local/api-client.d.ts

@@ -0,0 +1,157 @@
+import type { SagCapabilityDescriptor, SagConnectionDescriptor } from '../connection/types.js';
+/** One SAG source projected through its public REST fields. */
+export interface SagSource {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly status?: string;
+    readonly documentCount?: number;
+    readonly chunkCount?: number;
+    readonly [field: string]: unknown;
+}
+/** Parameters accepted by SAG's source creation endpoint. */
+export interface CreateSourceRequest {
+    readonly name: string;
+    readonly description?: string;
+    readonly connectorKind?: string;
+    readonly config?: Readonly<Record<string, unknown>>;
+}
+/** Parameters for structured workspace search. */
+export interface SagSearchRequest {
+    readonly query: string;
+    readonly sourceIds?: readonly string[];
+    readonly topK?: number;
+    readonly strategy?: string;
+}
+/** One structured evidence section returned by SAG. */
+export interface SagSearchSection {
+    readonly sourceId: string;
+    readonly sourceName: string | null;
+    readonly chunkId: string;
+    readonly heading: string;
+    readonly content: string;
+    readonly score: number;
+    readonly rank: number;
+}
+/** Structured search response used by the local gateway. */
+export interface SagSearchResult {
+    readonly query: string;
+    readonly sections: readonly SagSearchSection[];
+    readonly summary: string;
+    readonly stats: Readonly<Record<string, unknown>>;
+}
+/** Bytes already admitted by dsh FS for one multipart upload. */
+export interface SagFileUpload {
+    readonly sourceId: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+}
+/** Text content to ingest into one source. */
+export interface SagTextIngest {
+    readonly sourceId: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly messages?: readonly Readonly<Record<string, unknown>>[];
+}
+/** A source-bound SAG document or processing job. */
+export interface SagDocument {
+    readonly id: string;
+    readonly sourceId?: string;
+    readonly filename?: string;
+    readonly status?: 'pending' | 'loading' | 'extracting' | 'pausing' | 'paused' | 'deleting' | 'delete_failed' | 'ready' | 'failed';
+    readonly progress?: number;
+    readonly chunkCount?: number;
+    readonly error?: string | null;
+    readonly errorLayer?: string | null;
+    readonly errorStage?: string | null;
+    readonly [field: string]: unknown;
+}
+/** One asynchronous SAG processing job returned by document mutations. */
+export interface SagJob {
+    readonly id: string;
+    readonly status: 'queued' | 'running' | 'paused' | 'succeeded' | 'failed';
+    readonly sourceId: string | null;
+    readonly documentId: string | null;
+    readonly type: 'process_document' | 'reprocess_document' | 'delete_document' | 'sync_source' | 'index_universe' | 'octx_preflight' | 'octx_import' | 'octx_export' | 'octx_gc_installation' | 'octx_gc_transfer';
+    readonly progress?: number;
+    readonly attempts?: number;
+    readonly error?: string | null;
+}
+/** Reprocess endpoint job with its operation-specific type. */
+export interface SagReprocessJob extends SagJob {
+    readonly type: 'reprocess_document';
+}
+/** Full content for one source chunk. */
+export interface SagChunk {
+    readonly sourceId: string;
+    readonly chunkId: string;
+    readonly content: string;
+    readonly [field: string]: unknown;
+}
+/** Versioned local reference emitted by search and accepted by read. */
+export interface LocalEvidenceRef {
+    readonly v: 1;
+    readonly sourceId: string;
+    readonly chunkId: string;
+}
+/** A non-success SAG response with its stable public error fields. */
+export declare class SagApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean | undefined;
+    readonly requestId: string | undefined;
+    readonly layer: string | undefined;
+    readonly stage: string | undefined;
+    /**
+     * @param status - HTTP status returned by SAG.
+     * @param code - stable SAG error code.
+     * @param message - redacted public error message.
+     * @param retryable - whether SAG considers a retry safe.
+     * @param requestId - optional SAG request identifier.
+     * @param layer - public SAG responsibility category.
+     * @param stage - public SAG processing stage.
+     */
+    constructor(status: number, code: string, message: string, retryable: boolean | undefined, requestId: string | undefined, layer: string | undefined, stage: string | undefined);
+}
+/** Encode a canonical local SAG evidence reference. */
+export declare function encodeLocalEvidenceRef(ref: LocalEvidenceRef): string;
+/** Decode and strictly validate a canonical local SAG evidence reference. */
+export declare function decodeLocalEvidenceRef(encoded: string): LocalEvidenceRef;
+/** REST client for the public SAG dsh, source, search, chunk, and document endpoints. */
+export declare class SagApiClient {
+    private readonly descriptor;
+    private readonly fetch;
+    /** @param descriptor - resolved local SAG connection. @param fetch - injectable HTTP implementation. */
+    constructor(descriptor: SagConnectionDescriptor, fetch?: typeof globalThis.fetch);
+    private requestJson;
+    private redact;
+    private json;
+    /** Check whether the SAG API process is alive. */
+    health(signal: AbortSignal): Promise<unknown>;
+    /** Check whether SAG storage and knowledge runtime are ready. */
+    ready(signal: AbortSignal): Promise<unknown>;
+    /** Read the versioned dsh integration capabilities. */
+    capabilities(signal: AbortSignal): Promise<SagCapabilityDescriptor>;
+    /** List all local knowledge sources. */
+    listSources(signal: AbortSignal): Promise<readonly SagSource[]>;
+    /** Create one file-upload or configured SAG source. */
+    createSource(request: CreateSourceRequest, signal: AbortSignal): Promise<SagSource>;
+    /** Search one or more sources using SAG's structured workspace response. */
+    search(request: SagSearchRequest, signal: AbortSignal): Promise<SagSearchResult>;
+    /** Read one complete chunk by its source-local identifiers. */
+    readChunk(sourceId: string, chunkId: string, signal: AbortSignal): Promise<SagChunk>;
+    /** List documents belonging to one source. */
+    listDocuments(sourceId: string, signal: AbortSignal): Promise<readonly SagDocument[]>;
+    /** Get one document and its current processing status. */
+    getDocument(sourceId: string, documentId: string, signal: AbortSignal): Promise<SagDocument>;
+    /** Upload bytes already read through dsh FS as one multipart document. */
+    uploadFile(upload: SagFileUpload, signal: AbortSignal): Promise<SagDocument>;
+    /** Ingest text or messages without waiting for background parsing. */
+    ingestText(ingest: SagTextIngest, signal: AbortSignal): Promise<SagDocument>;
+    /** Queue reprocessing for one document. */
+    reprocessDocument(sourceId: string, documentId: string, signal: AbortSignal): Promise<SagReprocessJob>;
+    /** Delete one document after the caller has obtained dsh approval. */
+    deleteDocument(sourceId: string, documentId: string, signal: AbortSignal): Promise<unknown>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/lib/local/api-client.js

@@ -0,0 +1,338 @@
+/** A non-success SAG response with its stable public error fields. */
+export class SagApiError extends Error {
+    status;
+    code;
+    retryable;
+    requestId;
+    layer;
+    stage;
+    /**
+     * @param status - HTTP status returned by SAG.
+     * @param code - stable SAG error code.
+     * @param message - redacted public error message.
+     * @param retryable - whether SAG considers a retry safe.
+     * @param requestId - optional SAG request identifier.
+     * @param layer - public SAG responsibility category.
+     * @param stage - public SAG processing stage.
+     */
+    constructor(status, code, message, retryable, requestId, layer, stage) {
+        super(`SAG API ${status} ${code}: ${message}`);
+        this.status = status;
+        this.code = code;
+        this.retryable = retryable;
+        this.requestId = requestId;
+        this.layer = layer;
+        this.stage = stage;
+        this.name = 'SagApiError';
+    }
+}
+function object(value, label) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error(`dsh-sag: ${label} must be an object`);
+    return value;
+}
+function string(value, label) {
+    if (typeof value !== 'string' || !value)
+        throw new Error(`dsh-sag: ${label} must be a non-empty string`);
+    return value;
+}
+function number(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error(`dsh-sag: ${label} must be a finite number`);
+    return value;
+}
+function recordWithCamelIds(value, label) {
+    const source = object(value, label);
+    const result = { ...source };
+    if (typeof source.source_id === 'string')
+        result.sourceId = source.source_id;
+    if (typeof source.chunk_id === 'string')
+        result.chunkId = source.chunk_id;
+    if (typeof source.document_count === 'number')
+        result.documentCount = source.document_count;
+    if (typeof source.chunk_count === 'number')
+        result.chunkCount = source.chunk_count;
+    if (source.error === null || typeof source.error === 'string')
+        result.error = source.error;
+    if (source.error_layer === null || typeof source.error_layer === 'string')
+        result.errorLayer = source.error_layer;
+    if (source.error_stage === null || typeof source.error_stage === 'string')
+        result.errorStage = source.error_stage;
+    return result;
+}
+function parseSource(value) {
+    const result = recordWithCamelIds(value, 'source');
+    return { ...result, id: string(result.id, 'source.id'), name: string(result.name, 'source.name') };
+}
+function parseDocument(value) {
+    const result = recordWithCamelIds(value, 'document');
+    if (result.progress !== undefined && !Number.isInteger(result.progress))
+        throw new Error('dsh-sag: document.progress must be an integer percentage');
+    return { ...result, id: string(result.id, 'document.id') };
+}
+function nullableString(value, label) {
+    if (value === null)
+        return null;
+    return string(value, label);
+}
+function parseJob(value) {
+    const source = object(value, 'job');
+    const jobTypes = ['process_document', 'reprocess_document', 'delete_document', 'sync_source', 'index_universe', 'octx_preflight', 'octx_import', 'octx_export', 'octx_gc_installation', 'octx_gc_transfer'];
+    const jobStatuses = ['queued', 'running', 'paused', 'succeeded', 'failed'];
+    const type = string(source.type, 'job.type');
+    const status = string(source.status, 'job.status');
+    if (!jobTypes.includes(type))
+        throw new Error('dsh-sag: job.type is unsupported');
+    if (!jobStatuses.includes(status))
+        throw new Error('dsh-sag: job.status is unsupported');
+    const optionalProgress = typeof source.progress === 'number' ? { progress: source.progress } : {};
+    const optionalAttempts = typeof source.attempts === 'number' ? { attempts: source.attempts } : {};
+    const optionalError = source.error === null || typeof source.error === 'string' ? { error: source.error } : {};
+    return {
+        id: string(source.id, 'job.id'),
+        type: type,
+        status: status,
+        sourceId: nullableString(source.source_id, 'job.source_id'),
+        documentId: nullableString(source.document_id, 'job.document_id'),
+        ...optionalProgress,
+        ...optionalAttempts,
+        ...optionalError,
+    };
+}
+function parseCapability(value) {
+    const root = object(value, 'capability response');
+    if (root.schemaVersion !== 1)
+        throw new Error('dsh-sag: capability response requires schemaVersion 1');
+    if (!Array.isArray(root.capabilities) || !root.capabilities.every(item => typeof item === 'string')) {
+        throw new Error('dsh-sag: capability response capabilities must be strings');
+    }
+    let upload;
+    if (root.upload !== undefined) {
+        const candidate = object(root.upload, 'capability response upload');
+        if (!Number.isInteger(candidate.maxMb) || candidate.maxMb <= 0) {
+            throw new Error('dsh-sag: capability response upload.maxMb must be a positive integer');
+        }
+        if (!Array.isArray(candidate.extensions) || !candidate.extensions.every(item => typeof item === 'string' && item.length > 0 && !item.startsWith('.'))) {
+            throw new Error('dsh-sag: capability response upload.extensions must omit leading dots');
+        }
+        upload = { maxMb: candidate.maxMb, extensions: candidate.extensions };
+    }
+    const defaultSourceId = root.defaultSourceId;
+    if (defaultSourceId !== undefined && defaultSourceId !== null && (typeof defaultSourceId !== 'string' || !defaultSourceId)) {
+        throw new Error('dsh-sag: capability response defaultSourceId must be a non-empty string or null');
+    }
+    return {
+        schemaVersion: 1,
+        capabilities: root.capabilities,
+        ...(upload === undefined ? {} : { upload }),
+        ...(defaultSourceId === undefined ? {} : { defaultSourceId }),
+    };
+}
+function encodePath(value) {
+    return encodeURIComponent(value);
+}
+/** Encode a canonical local SAG evidence reference. */
+export function encodeLocalEvidenceRef(ref) {
+    return Buffer.from(JSON.stringify({ v: 1, sourceId: ref.sourceId, chunkId: ref.chunkId }), 'utf8').toString('base64url');
+}
+/** Decode and strictly validate a canonical local SAG evidence reference. */
+export function decodeLocalEvidenceRef(encoded) {
+    try {
+        if (encoded.length > 4096)
+            throw new Error('evidence reference is too long');
+        if (!encoded || !/^[A-Za-z0-9_-]+$/.test(encoded))
+            throw new Error('invalid alphabet');
+        const decoded = Buffer.from(encoded, 'base64url').toString('utf8');
+        const value = object(JSON.parse(decoded), 'evidence reference');
+        if (Object.keys(value).sort().join(',') !== 'chunkId,sourceId,v')
+            throw new Error('unexpected fields');
+        if (value.v !== 1)
+            throw new Error('unsupported version');
+        const ref = { v: 1, sourceId: string(value.sourceId, 'evidence reference sourceId'), chunkId: string(value.chunkId, 'evidence reference chunkId') };
+        if (encodeLocalEvidenceRef(ref) !== encoded)
+            throw new Error('non-canonical encoding');
+        return ref;
+    }
+    catch (error) {
+        throw new Error(`dsh-sag: invalid local evidence reference: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function requestSignal(init, signal) {
+    if (init.signal === undefined || init.signal === null || init.signal === signal)
+        return signal;
+    return AbortSignal.any([init.signal, signal]);
+}
+/** REST client for the public SAG dsh, source, search, chunk, and document endpoints. */
+export class SagApiClient {
+    descriptor;
+    fetch;
+    /** @param descriptor - resolved local SAG connection. @param fetch - injectable HTTP implementation. */
+    constructor(descriptor, fetch = globalThis.fetch) {
+        this.descriptor = descriptor;
+        this.fetch = fetch;
+    }
+    async requestJson(path, init, signal) {
+        const headers = {};
+        if (init.headers instanceof Headers) {
+            for (const [name, value] of init.headers.entries())
+                headers[name] = value;
+        }
+        else if (Array.isArray(init.headers)) {
+            for (const [name, value] of init.headers)
+                headers[name] = value;
+        }
+        else if (init.headers !== undefined) {
+            Object.assign(headers, init.headers);
+        }
+        headers.Authorization = `Bearer ${this.descriptor.accessToken}`;
+        let response;
+        try {
+            response = await this.fetch(`${this.descriptor.apiUrl}${path}`, {
+                ...init,
+                headers,
+                signal: requestSignal(init, signal),
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw signal.reason;
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`dsh-sag: SAG API request failed: ${this.redact(message)}`);
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            if (!response.ok)
+                throw new SagApiError(response.status, 'http_error', this.redact(response.statusText || 'request failed'), undefined, undefined, undefined, undefined);
+            throw new Error(`dsh-sag: SAG API ${response.status} returned invalid JSON`);
+        }
+        if (!response.ok) {
+            const root = typeof payload === 'object' && payload !== null ? payload : {};
+            const candidate = typeof root.error === 'object' && root.error !== null ? root.error : {};
+            const parsed = {
+                code: typeof candidate.code === 'string' ? candidate.code : 'http_error',
+                message: typeof candidate.message === 'string' ? candidate.message : response.statusText || 'request failed',
+                ...(typeof candidate.retryable === 'boolean' ? { retryable: candidate.retryable } : {}),
+                ...(typeof candidate.request_id === 'string' ? { request_id: candidate.request_id } : {}),
+                ...(typeof candidate.layer === 'string' ? { layer: candidate.layer } : {}),
+                ...(typeof candidate.stage === 'string' ? { stage: candidate.stage } : {}),
+            };
+            throw new SagApiError(response.status, this.redact(parsed.code), this.redact(parsed.message), parsed.retryable, parsed.request_id === undefined ? undefined : this.redact(parsed.request_id), parsed.layer === undefined ? undefined : this.redact(parsed.layer), parsed.stage === undefined ? undefined : this.redact(parsed.stage));
+        }
+        return payload;
+    }
+    redact(message) {
+        return message.split(this.descriptor.accessToken).join('<redacted>');
+    }
+    json(method, body) {
+        return { method, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) };
+    }
+    /** Check whether the SAG API process is alive. */
+    health(signal) { return this.requestJson('/system/health', {}, signal); }
+    /** Check whether SAG storage and knowledge runtime are ready. */
+    ready(signal) { return this.requestJson('/system/ready', {}, signal); }
+    /** Read the versioned dsh integration capabilities. */
+    async capabilities(signal) {
+        return parseCapability(await this.requestJson('/system/dsh', {}, signal));
+    }
+    /** List all local knowledge sources. */
+    async listSources(signal) {
+        const value = await this.requestJson('/sources', {}, signal);
+        if (!Array.isArray(value))
+            throw new Error('dsh-sag: source list must be an array');
+        return value.map(parseSource);
+    }
+    /** Create one file-upload or configured SAG source. */
+    async createSource(request, signal) {
+        return parseSource(await this.requestJson('/sources', this.json('POST', {
+            name: request.name,
+            description: request.description ?? '',
+            connector_kind: request.connectorKind ?? 'file_upload',
+            config: request.config ?? {},
+        }), signal));
+    }
+    /** Search one or more sources using SAG's structured workspace response. */
+    async search(request, signal) {
+        const payload = await this.requestJson('/search', this.json('POST', {
+            query: request.query,
+            ...(request.sourceIds === undefined ? {} : { source_ids: request.sourceIds }),
+            ...(request.topK === undefined ? {} : { top_k: request.topK }),
+            ...(request.strategy === undefined ? {} : { strategy: request.strategy }),
+            save_exploration: false,
+        }), signal);
+        const root = object(payload, 'search response');
+        if (!Array.isArray(root.sections))
+            throw new Error('dsh-sag: search response sections must be an array');
+        const sections = root.sections.flatMap((item, index) => {
+            const section = object(item, `search response sections[${index}]`);
+            if (section.source_id === null || section.chunk_id === null)
+                return [];
+            return [{
+                    sourceId: string(section.source_id, `search section ${index} source_id`),
+                    sourceName: section.source_name === null || section.source_name === undefined ? null : string(section.source_name, `search section ${index} source_name`),
+                    chunkId: string(section.chunk_id, `search section ${index} chunk_id`),
+                    heading: typeof section.heading === 'string' ? section.heading : '',
+                    content: string(section.content, `search section ${index} content`),
+                    score: number(section.score, `search section ${index} score`),
+                    rank: number(section.rank, `search section ${index} rank`),
+                }];
+        });
+        return {
+            query: string(root.query, 'search response query'),
+            sections,
+            summary: typeof root.summary === 'string' ? root.summary : '',
+            stats: object(root.stats, 'search response stats'),
+        };
+    }
+    /** Read one complete chunk by its source-local identifiers. */
+    async readChunk(sourceId, chunkId, signal) {
+        const value = recordWithCamelIds(await this.requestJson(`/sources/${encodePath(sourceId)}/chunks/${encodePath(chunkId)}`, {}, signal), 'chunk');
+        const content = typeof value.content === 'string' ? value.content : typeof value.text === 'string' ? value.text : undefined;
+        return {
+            ...value,
+            sourceId: typeof value.sourceId === 'string' ? value.sourceId : sourceId,
+            chunkId: string(value.chunkId, 'chunk.chunk_id'),
+            content: string(content, 'chunk content'),
+        };
+    }
+    /** List documents belonging to one source. */
+    async listDocuments(sourceId, signal) {
+        const value = await this.requestJson(`/sources/${encodePath(sourceId)}/documents`, {}, signal);
+        if (!Array.isArray(value))
+            throw new Error('dsh-sag: document list must be an array');
+        return value.map(parseDocument);
+    }
+    /** Get one document and its current processing status. */
+    async getDocument(sourceId, documentId, signal) {
+        return parseDocument(await this.requestJson(`/sources/${encodePath(sourceId)}/documents/${encodePath(documentId)}`, {}, signal));
+    }
+    /** Upload bytes already read through dsh FS as one multipart document. */
+    async uploadFile(upload, signal) {
+        const form = new FormData();
+        const bytes = Uint8Array.from(upload.bytes);
+        form.set('file', new Blob([bytes.buffer], { type: upload.contentType }), upload.filename);
+        return parseDocument(await this.requestJson(`/sources/${encodePath(upload.sourceId)}/documents`, { method: 'POST', body: form }, signal));
+    }
+    /** Ingest text or messages without waiting for background parsing. */
+    async ingestText(ingest, signal) {
+        return parseDocument(await this.requestJson(`/sources/${encodePath(ingest.sourceId)}/documents/ingest`, this.json('POST', {
+            text: ingest.text,
+            ...(ingest.title === undefined ? {} : { title: ingest.title }),
+            ...(ingest.messages === undefined ? {} : { messages: ingest.messages }),
+        }), signal));
+    }
+    /** Queue reprocessing for one document. */
+    async reprocessDocument(sourceId, documentId, signal) {
+        const job = parseJob(await this.requestJson(`/sources/${encodePath(sourceId)}/documents/${encodePath(documentId)}/reprocess`, { method: 'POST' }, signal));
+        if (job.type !== 'reprocess_document')
+            throw new Error('dsh-sag: reprocess job.type must be reprocess_document');
+        return job;
+    }
+    /** Delete one document after the caller has obtained dsh approval. */
+    async deleteDocument(sourceId, documentId, signal) {
+        return this.requestJson(`/sources/${encodePath(sourceId)}/documents/${encodePath(documentId)}`, { method: 'DELETE' }, signal);
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/lib/local/gateway.d.ts

@@ -0,0 +1,43 @@
+import { type CreateSourceRequest, type SagApiClient, type SagChunk, type SagDocument, type SagFileUpload, type SagReprocessJob, type SagSearchRequest, type SagSource, type SagTextIngest } from './api-client.js';
+import type { SagCapabilityDescriptor } from '../connection/types.js';
+/** One search section with an opaque read reference for the model-facing tool. */
+export interface SagEvidence {
+    readonly evidenceRef: string;
+    readonly sourceId: string;
+    readonly sourceName: string | null;
+    readonly chunkId: string;
+    readonly heading: string;
+    readonly content: string;
+    readonly score: number;
+    readonly rank: number;
+}
+/** Stable local search output independent of SAG's wire field names. */
+export interface SagGatewaySearchResult {
+    readonly query: string;
+    readonly evidences: readonly SagEvidence[];
+    readonly summary: string;
+    readonly stats: Readonly<Record<string, unknown>>;
+}
+/** Stable operations consumed by local dsh-sag tools and diagnostics. */
+export interface SagGateway {
+    /** Release optional transport resources owned by a custom gateway. */
+    close?(): void | Promise<void>;
+    health(signal: AbortSignal): Promise<unknown>;
+    ready(signal: AbortSignal): Promise<unknown>;
+    capabilities(signal: AbortSignal): Promise<SagCapabilityDescriptor>;
+    listSources(signal: AbortSignal): Promise<readonly SagSource[]>;
+    createSource(request: CreateSourceRequest, signal: AbortSignal): Promise<SagSource>;
+    search(request: SagSearchRequest, signal: AbortSignal): Promise<SagGatewaySearchResult>;
+    read(request: {
+        readonly evidenceRef: string;
+    }, signal: AbortSignal): Promise<SagChunk>;
+    listDocuments(sourceId: string, signal: AbortSignal): Promise<readonly SagDocument[]>;
+    getDocument(sourceId: string, documentId: string, signal: AbortSignal): Promise<SagDocument>;
+    uploadFile(request: SagFileUpload, signal: AbortSignal): Promise<SagDocument>;
+    ingestText(request: SagTextIngest, signal: AbortSignal): Promise<SagDocument>;
+    reprocessDocument(sourceId: string, documentId: string, signal: AbortSignal): Promise<SagReprocessJob>;
+    deleteDocument(sourceId: string, documentId: string, signal: AbortSignal): Promise<unknown>;
+}
+/** Adapt the SAG REST client to stable camel-case domain operations. */
+export declare function createSagGateway(api: SagApiClient): SagGateway;
+//# sourceMappingURL=gateway.d.ts.map

package/lib/local/gateway.js

@@ -0,0 +1,34 @@
+import { decodeLocalEvidenceRef, encodeLocalEvidenceRef, } from './api-client.js';
+/** Adapt the SAG REST client to stable camel-case domain operations. */
+export function createSagGateway(api) {
+    return {
+        health: signal => api.health(signal),
+        ready: signal => api.ready(signal),
+        capabilities: signal => api.capabilities(signal),
+        listSources: signal => api.listSources(signal),
+        createSource: (request, signal) => api.createSource(request, signal),
+        async search(request, signal) {
+            const result = await api.search(request, signal);
+            return {
+                query: result.query,
+                summary: result.summary,
+                stats: result.stats,
+                evidences: result.sections.map(section => ({
+                    ...section,
+                    evidenceRef: encodeLocalEvidenceRef({ v: 1, sourceId: section.sourceId, chunkId: section.chunkId }),
+                })),
+            };
+        },
+        read(request, signal) {
+            const ref = decodeLocalEvidenceRef(request.evidenceRef);
+            return api.readChunk(ref.sourceId, ref.chunkId, signal);
+        },
+        listDocuments: (sourceId, signal) => api.listDocuments(sourceId, signal),
+        getDocument: (sourceId, documentId, signal) => api.getDocument(sourceId, documentId, signal),
+        uploadFile: (request, signal) => api.uploadFile(request, signal),
+        ingestText: (request, signal) => api.ingestText(request, signal),
+        reprocessDocument: (sourceId, documentId, signal) => api.reprocessDocument(sourceId, documentId, signal),
+        deleteDocument: (sourceId, documentId, signal) => api.deleteDocument(sourceId, documentId, signal),
+    };
+}
+//# sourceMappingURL=gateway.js.map