@qvac/core 0.0.0 → 0.1.0

package/dist-lib/lib/fs-drive-bridge.js

@@ -0,0 +1,186 @@
+import fs from 'fs';
+import path from 'path';
+import { pipelinePromise, Readable } from 'streamx';
+import { STAGING_DIR as HARNESS_STAGING_DIR } from '@qvac/harness/lib/staging.ts';
+import { userTmpPath } from '@qvac/harness/lib/tmp-path.ts';
+import { MAX_DRIVE_BYTES } from '@qvac/harness/lib/tools/fs/remote.ts';
+export const DRIVE_OP_TIMEOUT_MS = 15_000;
+const STAGING_DIR = userTmpPath('qvac-fs-drive-host');
+const STAGING_MAX_AGE_MS = 60 * 60 * 1000;
+const noop = () => { };
+export async function sweepDriveStaging(now = Date.now()) {
+    const names = await fs.promises.readdir(STAGING_DIR).catch(() => []);
+    await Promise.all(names.map(async (name) => {
+        const file = path.join(STAGING_DIR, name);
+        const stat = await fs.promises.stat(file).catch(() => null);
+        if (stat && now - stat.mtimeMs > STAGING_MAX_AGE_MS) {
+            await fs.promises.unlink(file).catch(noop);
+        }
+    }));
+}
+function withDeadline(op, ms, task) {
+    const controller = new AbortController();
+    const { promise, resolve, reject } = Promise.withResolvers();
+    const timer = setTimeout(() => {
+        controller.abort();
+        reject(new Error(`drive ${op} timed out on the host`));
+    }, ms);
+    task(controller.signal).then((value) => {
+        clearTimeout(timer);
+        resolve(value);
+    }, (err) => {
+        clearTimeout(timer);
+        reject(err);
+    });
+    return promise;
+}
+async function stagedPath(prefix) {
+    await fs.promises.mkdir(STAGING_DIR, { recursive: true, mode: 0o700 });
+    const unique = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    return path.join(STAGING_DIR, `${prefix}-${unique}`);
+}
+function stripMetadata(entry) {
+    if (!entry)
+        return null;
+    return { ...entry, value: { ...entry.value, metadata: null } };
+}
+async function pipeCapped(source, target, cap, signal) {
+    const sink = fs.createWriteStream(target, { mode: 0o600 });
+    let sinkError = null;
+    sink.on('error', (err) => {
+        sinkError = err;
+    });
+    let written = 0;
+    let truncated = false;
+    try {
+        for await (const chunk of source) {
+            if (signal.aborted)
+                break;
+            if (sinkError)
+                throw sinkError;
+            if (written >= cap) {
+                truncated = true;
+                break;
+            }
+            const room = cap - written;
+            const slice = chunk.byteLength > room ? chunk.subarray(0, room) : chunk;
+            sink.write(slice);
+            written += slice.byteLength;
+            if (slice.byteLength < chunk.byteLength)
+                truncated = true;
+        }
+    }
+    finally {
+        await new Promise((resolve) => sink.end(resolve));
+    }
+    if (sinkError)
+        throw sinkError;
+    return truncated;
+}
+function folderRange(folder) {
+    const trimmed = folder === '/' ? '' : folder.replace(/\/+$/, '');
+    return { gt: `${trimmed}/`, lt: `${trimmed}0` };
+}
+async function handleRequest(acquired, request, signal) {
+    const drive = acquired.drive;
+    switch (request.op) {
+        case 'entry': {
+            const entry = await drive.entry(request.key, { timeout: DRIVE_OP_TIMEOUT_MS, wait: true });
+            return { entry: stripMetadata(entry) };
+        }
+        case 'get': {
+            const entry = await drive.entry(request.key, { timeout: DRIVE_OP_TIMEOUT_MS, wait: true });
+            if (!entry)
+                return { path: null };
+            if ((entry.value.blob?.byteLength ?? 0) > MAX_DRIVE_BYTES) {
+                return { error: `get exceeds ${MAX_DRIVE_BYTES} bytes: ${request.key}` };
+            }
+            const buffer = await drive.get(request.key, { timeout: DRIVE_OP_TIMEOUT_MS, wait: true });
+            if (!buffer)
+                return { path: null };
+            const target = await stagedPath('drive-get');
+            signal.addEventListener('abort', () => void fs.promises.unlink(target).catch(noop), {
+                once: true
+            });
+            await fs.promises.writeFile(target, buffer, { mode: 0o600 });
+            return { path: target };
+        }
+        case 'read': {
+            const target = await stagedPath('drive-read');
+            signal.addEventListener('abort', () => void fs.promises.unlink(target).catch(noop), {
+                once: true
+            });
+            const truncated = await pipeCapped(drive.createReadStream(request.key), target, MAX_DRIVE_BYTES, signal);
+            return { path: target, truncated };
+        }
+        case 'list': {
+            const skip = new Set(request.skip);
+            const entries = [];
+            let cursor = null;
+            const ignore = (key) => key.split('/').some((seg) => skip.has(seg));
+            const range = folderRange(request.folder);
+            const gt = request.cursor ?? range.gt;
+            for await (const raw of drive.entries({ gt, lt: range.lt }, { ignore })) {
+                entries.push(stripMetadata(raw));
+                if (entries.length >= request.limit) {
+                    cursor = raw.key;
+                    break;
+                }
+            }
+            return { entries, cursor };
+        }
+        case 'write': {
+            if (!acquired.writable)
+                return { error: `drive is read-only: cannot write ${request.key}` };
+            const resolvedPath = path.resolve(request.path);
+            if (path.relative(HARNESS_STAGING_DIR, resolvedPath).startsWith('..')) {
+                return { error: `write path is outside the staging directory: ${request.path}` };
+            }
+            const source = Readable.from(fs.createReadStream(resolvedPath));
+            const sink = drive.createWriteStream(request.key, request.executable ? { executable: true } : undefined);
+            signal.addEventListener('abort', () => {
+                source.destroy();
+                sink.destroy();
+            }, { once: true });
+            await pipelinePromise(source, sink);
+            await fs.promises.unlink(resolvedPath).catch(noop);
+            return {};
+        }
+    }
+}
+export function createDriveOp(drives) {
+    return async (request) => {
+        const acquired = drives.get(request.driveKey);
+        if (!acquired)
+            return { error: `drive not granted for this run: ${request.driveKey}` };
+        try {
+            return await withDeadline(request.op, DRIVE_OP_TIMEOUT_MS, (signal) => handleRequest(acquired, request, signal));
+        }
+        catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+        }
+    };
+}
+export async function resolveFsGrants(grants, driveHost, onDropped) {
+    const grantedDirs = grants
+        .filter((grant) => grant.kind === 'local')
+        .map((grant) => grant.path);
+    const hyperGrants = grants.filter((grant) => grant.kind === 'hyper');
+    if (!driveHost || hyperGrants.length === 0)
+        return { grantedDirs, grantedDrives: [] };
+    const drives = new Map();
+    const grantedDrives = [];
+    for (const grant of hyperGrants) {
+        try {
+            const acquired = await driveHost.acquire(grant.key);
+            drives.set(grant.key, acquired);
+            grantedDrives.push({ key: grant.key, writable: acquired.writable });
+        }
+        catch (err) {
+            onDropped?.(grant.key, err);
+        }
+    }
+    if (drives.size === 0)
+        return { grantedDirs, grantedDrives: [] };
+    return { grantedDirs, grantedDrives, driveOp: createDriveOp(drives) };
+}

package/dist-lib/lib/fs-grant-keys.d.ts

@@ -0,0 +1,2 @@
+export declare function fsGrantKey(agentId: string): string;
+export declare function fsWriteGrantKey(agentId: string): string;

package/dist-lib/lib/fs-grant-keys.js

@@ -0,0 +1,6 @@
+export function fsGrantKey(agentId) {
+    return `fs.${agentId}.roots`;
+}
+export function fsWriteGrantKey(agentId) {
+    return `fs.${agentId}.writable`;
+}

package/dist-lib/lib/fs-grants.d.ts

@@ -0,0 +1,10 @@
+export type FsGrant = {
+    readonly kind: 'local';
+    readonly path: string;
+} | HyperGrant;
+export interface HyperGrant {
+    readonly kind: 'hyper';
+    readonly key: string;
+}
+export declare function fsGrantsFrom(value: unknown): FsGrant[];
+export declare function grantedDirsFrom(value: unknown): string[];

package/dist-lib/lib/fs-grants.js

@@ -0,0 +1,44 @@
+import path from 'path';
+import HypercoreId from 'hypercore-id-encoding';
+function parseHyperKey(value) {
+    if (typeof value !== 'string')
+        return null;
+    try {
+        HypercoreId.decode(value);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export function fsGrantsFrom(value) {
+    if (!Array.isArray(value))
+        return [];
+    const grants = [];
+    for (const item of value) {
+        if (typeof item === 'string') {
+            if (path.isAbsolute(item))
+                grants.push({ kind: 'local', path: item });
+            continue;
+        }
+        if (!item || typeof item !== 'object')
+            continue;
+        const kind = item.kind;
+        if (kind === 'local') {
+            const dir = item.path;
+            if (typeof dir === 'string' && path.isAbsolute(dir))
+                grants.push({ kind: 'local', path: dir });
+        }
+        else if (kind === 'hyper') {
+            const key = parseHyperKey(item.key);
+            if (key)
+                grants.push({ kind: 'hyper', key });
+        }
+    }
+    return grants;
+}
+export function grantedDirsFrom(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((dir) => typeof dir === 'string' && path.isAbsolute(dir));
+}

package/dist-lib/lib/image-cache-dir.d.ts

@@ -0,0 +1 @@
+export declare function defaultImageCacheDir(): string;

package/dist-lib/lib/image-cache-dir.js

@@ -0,0 +1,5 @@
+import { persistent } from 'bare-storage';
+import { join } from 'path';
+export function defaultImageCacheDir() {
+    return join(persistent(), 'qvac', 'image-cache');
+}

package/dist-lib/lib/integrations/index.d.ts

@@ -0,0 +1,4 @@
+export type { SkillSetup, SkillSetupField, SkillSetupRoute } from '../skill-types.ts';
+export { isMcpTokenProvider, MCP_TOKEN_PROVIDERS, type McpProviderConfig, type McpTokenProvider, resolveMcpProvider } from './mcp-providers.ts';
+export { OAUTH_PROVIDERS, type OAuthIntegrationConfig, resolveOAuthProviderByCredentialKey } from './oauth-providers.ts';
+export { deriveSetupRoutes, SETUP_ROUTE_KIND } from './setup-routes.ts';

package/dist-lib/lib/integrations/index.js

@@ -0,0 +1,3 @@
+export { isMcpTokenProvider, MCP_TOKEN_PROVIDERS, resolveMcpProvider } from "./mcp-providers.js";
+export { OAUTH_PROVIDERS, resolveOAuthProviderByCredentialKey } from "./oauth-providers.js";
+export { deriveSetupRoutes, SETUP_ROUTE_KIND } from "./setup-routes.js";

package/dist-lib/lib/integrations/mcp-providers.d.ts

@@ -0,0 +1,12 @@
+export type McpTokenProvider = 'github';
+export type McpProviderConfig = {
+    readonly provider: McpTokenProvider;
+    readonly credentialKey: string;
+    readonly label: string;
+    readonly description: string;
+    readonly tokenHelpUrl: string;
+    readonly guide?: ReadonlyArray<string> | undefined;
+};
+export declare const MCP_TOKEN_PROVIDERS: ReadonlyArray<McpProviderConfig>;
+export declare function isMcpTokenProvider(value: unknown): value is McpTokenProvider;
+export declare function resolveMcpProvider(provider: McpTokenProvider): McpProviderConfig;

package/dist-lib/lib/integrations/mcp-providers.js

@@ -0,0 +1,22 @@
+const GITHUB_CONFIG = {
+    provider: 'github',
+    credentialKey: 'github_access_token',
+    label: 'GitHub',
+    description: 'Repos, pull requests, issues, and workflow runs — Personal Access Token',
+    tokenHelpUrl: 'https://github.com/settings/tokens',
+    guide: [
+        'Create a personal access token (classic) at https://github.com/settings/tokens — scopes: repo and read:org. Classic tokens work everywhere; fine-grained ones need per-org enablement.',
+        'Paste it above and click Save.',
+        'For organizations enforcing SAML SSO, authorize the token for the org after creating it.'
+    ]
+};
+const REGISTRY = {
+    github: GITHUB_CONFIG
+};
+export const MCP_TOKEN_PROVIDERS = Object.values(REGISTRY);
+export function isMcpTokenProvider(value) {
+    return typeof value === 'string' && Object.hasOwn(REGISTRY, value);
+}
+export function resolveMcpProvider(provider) {
+    return REGISTRY[provider];
+}

package/dist-lib/lib/integrations/oauth-providers.d.ts

@@ -0,0 +1,14 @@
+import type { OAuthProvider } from '../oauth/types.ts';
+import type { SkillSetupField } from '../skill-types.ts';
+export type OAuthIntegrationConfig = {
+    readonly provider: OAuthProvider;
+    readonly credentialKey: string;
+    readonly label: string;
+    readonly description: string;
+    readonly helpUrl?: string | undefined;
+    readonly fields?: ReadonlyArray<SkillSetupField> | undefined;
+    readonly guide?: ReadonlyArray<string> | undefined;
+    readonly configGuide?: ReadonlyArray<string> | undefined;
+};
+export declare const OAUTH_PROVIDERS: ReadonlyArray<OAuthIntegrationConfig>;
+export declare function resolveOAuthProviderByCredentialKey(credentialKey: string): OAuthIntegrationConfig | null;

package/dist-lib/lib/integrations/oauth-providers.js

@@ -0,0 +1,116 @@
+import { ASANA_MCP_CREDENTIAL_KEY, GMAIL_CREDENTIAL_KEY, GOOGLE_CALENDAR_CREDENTIAL_KEY, GOOGLE_DOCS_CREDENTIAL_KEY, GOOGLE_DRIVE_CREDENTIAL_KEY, GOOGLE_SHEETS_CREDENTIAL_KEY, NOTION_MCP_CREDENTIAL_KEY, SPOTIFY_CREDENTIAL_KEY } from "../oauth/keys.js";
+const OAUTH_CLIENT_FIELDS = [
+    {
+        key: 'clientId',
+        label: 'Client ID',
+        placeholder: 'OAuth client ID from your app'
+    },
+    { key: 'clientSecret', label: 'Client Secret', secret: true }
+];
+function googleConfig(input) {
+    return {
+        provider: 'google',
+        credentialKey: input.credentialKey,
+        label: input.label,
+        description: input.description,
+        fields: OAUTH_CLIENT_FIELDS,
+        guide: [
+            `Click Connect and approve access in the browser. Approving grants ${input.grants} only.`,
+            'Each Google skill is connected separately, with its own app and its own approval.'
+        ],
+        configGuide: [
+            `[Open Google Cloud Console](https://console.cloud.google.com/flows/enableapi?apiid=${input.api}) to enable the ${input.label} API`,
+            '[Open OAuth clients](https://console.cloud.google.com/auth/clients) to create an OAuth client — choose "Desktop app" as the type',
+            '[Open OAuth audience](https://console.cloud.google.com/auth/audience) and add your Google account as a test user'
+        ]
+    };
+}
+const GOOGLE_CONFIGS = [
+    googleConfig({
+        credentialKey: GMAIL_CREDENTIAL_KEY,
+        label: 'Gmail',
+        description: 'Read, search, send, and manage Gmail messages and labels',
+        api: 'gmail.googleapis.com',
+        grants: 'access to your Gmail'
+    }),
+    googleConfig({
+        credentialKey: GOOGLE_CALENDAR_CREDENTIAL_KEY,
+        label: 'Google Calendar',
+        description: 'List, create, update, and delete Google Calendar events',
+        api: 'calendar-json.googleapis.com',
+        grants: 'access to your calendars'
+    }),
+    googleConfig({
+        credentialKey: GOOGLE_DOCS_CREDENTIAL_KEY,
+        label: 'Google Docs',
+        description: 'Create, read, and edit Google Docs documents',
+        api: 'docs.googleapis.com,drive.googleapis.com',
+        grants: 'access to your documents and Drive files'
+    }),
+    googleConfig({
+        credentialKey: GOOGLE_DRIVE_CREDENTIAL_KEY,
+        label: 'Google Drive',
+        description: 'Search, list, and manage Google Drive files and folders',
+        api: 'drive.googleapis.com',
+        grants: 'access to your Drive files'
+    }),
+    googleConfig({
+        credentialKey: GOOGLE_SHEETS_CREDENTIAL_KEY,
+        label: 'Google Sheets',
+        description: 'Create, read, and update Google Sheets spreadsheets',
+        api: 'sheets.googleapis.com,drive.googleapis.com',
+        grants: 'access to your spreadsheets and Drive files'
+    })
+];
+const SPOTIFY_FIELDS = [
+    {
+        key: 'clientId',
+        label: 'Client ID',
+        placeholder: 'From your app at developer.spotify.com'
+    }
+];
+const SPOTIFY_CONFIG = {
+    provider: 'spotify',
+    credentialKey: SPOTIFY_CREDENTIAL_KEY,
+    label: 'Spotify',
+    description: 'Search, library, and playback control — playback requires Spotify Premium',
+    helpUrl: 'https://developer.spotify.com/dashboard',
+    fields: SPOTIFY_FIELDS,
+    guide: [
+        'Search and library browsing work with any Spotify account; controlling playback (play, pause, skip) requires Spotify Premium and an open Spotify app on a device.',
+        'Create your own app at https://developer.spotify.com/dashboard (Spotify requires the app owner to hold a Premium subscription).',
+        'In the app settings, add these exact Redirect URIs: http://127.0.0.1:18974/callback (desktop) and, for mobile, the Redirect URI shown in this connect form (the scheme varies per build, e.g. qvac://oauth-callback or qvac-dev://oauth-callback).',
+        'Paste the Client ID above and click Connect, then approve access in the browser. No Client Secret is needed — Workbench uses PKCE.'
+    ]
+};
+const ASANA_CONFIG = {
+    provider: 'asana',
+    credentialKey: ASANA_MCP_CREDENTIAL_KEY,
+    label: 'Asana',
+    description: 'Tasks, projects, and comments',
+    helpUrl: 'https://app.asana.com/0/my-apps',
+    fields: OAUTH_CLIENT_FIELDS,
+    configGuide: [
+        '[Open the Asana developer console](https://app.asana.com/0/my-apps) and create an MCP app',
+        'In OAuth settings, add the exact redirect URI shown below',
+        'In "Manage distribution", allow the workspace you want this connection to access'
+    ]
+};
+const NOTION_CONFIG = {
+    provider: 'notion',
+    credentialKey: NOTION_MCP_CREDENTIAL_KEY,
+    label: 'Notion',
+    description: 'Pages, databases, and blocks',
+    guide: [
+        "Click Connect and approve access in the browser — Workbench uses Notion's hosted MCP OAuth, so no app credentials are needed."
+    ]
+};
+export const OAUTH_PROVIDERS = [
+    ...GOOGLE_CONFIGS,
+    SPOTIFY_CONFIG,
+    ASANA_CONFIG,
+    NOTION_CONFIG
+];
+export function resolveOAuthProviderByCredentialKey(credentialKey) {
+    return OAUTH_PROVIDERS.find((config) => config.credentialKey === credentialKey) ?? null;
+}

package/dist-lib/lib/integrations/setup-routes.d.ts

@@ -0,0 +1,12 @@
+import type { SkillEntry, SkillSetup } from '../skill-types.ts';
+export declare const SETUP_ROUTE_KIND: {
+    readonly oauth: "oauth";
+    readonly token: "token";
+    readonly install: "install";
+    readonly picker: "picker";
+    readonly instructions: "instructions";
+};
+export type DeriveSetupOptions = {
+    readonly sandboxed?: boolean;
+};
+export declare function deriveSetupRoutes(entry: SkillEntry, options?: DeriveSetupOptions): SkillSetup;

package/dist-lib/lib/integrations/setup-routes.js

@@ -0,0 +1,114 @@
+import { OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY } from "../obsidian-key.js";
+import { MCP_TOKEN_PROVIDERS } from "./mcp-providers.js";
+import { resolveOAuthProviderByCredentialKey } from "./oauth-providers.js";
+const UNSUPPORTED_STATE = 'unsupported';
+export const SETUP_ROUTE_KIND = {
+    oauth: 'oauth',
+    token: 'token',
+    install: 'install',
+    picker: 'picker',
+    instructions: 'instructions'
+};
+const OBSIDIAN_SKILL_NAME = 'obsidian';
+const OBSIDIAN_VAULT_PICKER = {
+    kind: SETUP_ROUTE_KIND.picker,
+    label: 'Select a vault folder',
+    provider: OBSIDIAN_SKILL_NAME,
+    credentialKey: OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY,
+    description: "Pick the vault's top-level folder — the one containing its `.obsidian` settings folder, which marks it a valid Obsidian vault. Workbench then reads and writes that folder's Markdown files directly instead of using the Obsidian CLI; app-only actions (open, plugins, sync) still need the CLI and are unavailable while a folder is set. Disconnect to restore CLI mode."
+};
+export function deriveSetupRoutes(entry, options = {}) {
+    const base = entry.metadata.setup ?? { routes: derivedRoutes(entry) };
+    if (entry.metadata.name === OBSIDIAN_SKILL_NAME) {
+        return appendVaultPicker(base, options.sandboxed === true);
+    }
+    return base;
+}
+function appendVaultPicker(setup, preferPicker) {
+    const routes = setup.routes ?? [];
+    if (routes.some((route) => route.kind === SETUP_ROUTE_KIND.picker)) {
+        return preferPicker ? prioritizeVaultPicker(setup) : setup;
+    }
+    const next = preferPicker
+        ? [OBSIDIAN_VAULT_PICKER, ...routes]
+        : [...routes, OBSIDIAN_VAULT_PICKER];
+    return { ...setup, routes: next };
+}
+function prioritizeVaultPicker(setup) {
+    const routes = setup.routes ?? [];
+    const picker = routes.find((route) => route.kind === SETUP_ROUTE_KIND.picker);
+    if (!picker || routes[0]?.kind === SETUP_ROUTE_KIND.picker) {
+        return setup;
+    }
+    return {
+        ...setup,
+        routes: [picker, ...routes.filter((route) => route.kind !== SETUP_ROUTE_KIND.picker)]
+    };
+}
+function derivedRoutes(entry) {
+    const routes = [];
+    for (const key of credentialKeysFor(entry)) {
+        const route = credentialRoute(key);
+        if (route) {
+            routes.push(route);
+        }
+    }
+    const install = installRoute(entry);
+    if (install) {
+        routes.push(install);
+    }
+    return routes;
+}
+function credentialKeysFor(entry) {
+    const transports = entry.metadata.transports ?? [];
+    if (transports.length > 0) {
+        return transports.map((transport) => transport.credentialKey);
+    }
+    return entry.metadata.requires?.credentials ?? [];
+}
+function credentialRoute(credentialKey) {
+    const oauth = resolveOAuthProviderByCredentialKey(credentialKey);
+    if (oauth) {
+        return {
+            kind: SETUP_ROUTE_KIND.oauth,
+            label: `Connect ${oauth.label}`,
+            provider: oauth.provider,
+            credentialKey,
+            description: oauth.description,
+            helpUrl: oauth.helpUrl,
+            fields: oauth.fields,
+            steps: oauth.guide,
+            configSteps: oauth.configGuide
+        };
+    }
+    const token = MCP_TOKEN_PROVIDERS.find((config) => config.credentialKey === credentialKey);
+    if (token) {
+        return {
+            kind: SETUP_ROUTE_KIND.token,
+            label: `Connect ${token.label}`,
+            provider: token.provider,
+            credentialKey,
+            description: token.description,
+            helpUrl: token.tokenHelpUrl,
+            steps: token.guide,
+            fields: [{ key: credentialKey, label: token.label, secret: true, required: true }]
+        };
+    }
+    return null;
+}
+function installRoute(entry) {
+    const steps = entry.metadata.install ?? [];
+    if (steps.length === 0 || entry.state === UNSUPPORTED_STATE) {
+        return null;
+    }
+    const step = steps[0];
+    if (!step) {
+        return null;
+    }
+    return {
+        kind: SETUP_ROUTE_KIND.install,
+        label: step.label,
+        description: step.formula ? `Installs \`${step.formula}\`.` : undefined,
+        satisfied: entry.available
+    };
+}

package/dist-lib/lib/knowledge-search.d.ts

@@ -0,0 +1,7 @@
+import type { AbortSignal } from 'bare-abort-controller';
+import type { Capabilities } from './api/index.ts';
+import type { AssistantRagSearchRequest } from '../spec/hyperschema/types.d.ts';
+export declare function searchKnowledge(engine: Pick<Capabilities, 'ragSearch' | 'fileStatusWatch'>, request: AssistantRagSearchRequest, options: {
+    signal: AbortSignal;
+    preparing: (active: boolean) => void;
+}): Promise<import("../spec/index").AssistantRagSearchResponse>;

package/dist-lib/lib/knowledge-search.js

@@ -0,0 +1,53 @@
+import { isWholeDocumentQuery, referencedDocuments } from "./core/files/index.js";
+import { raceAbort } from '@qvac/harness/race-abort';
+export async function searchKnowledge(engine, request, options) {
+    const { signal, preparing } = options;
+    const search = await raceAbort(engine.ragSearch(request), signal);
+    if (!search.enabled || !search.hasKnowledge || !search.pendingFiles?.length)
+        return search;
+    const watch = engine.fileStatusWatch({ chatId: request.chatId });
+    const iterator = watch[Symbol.asyncIterator]();
+    let wanted = null;
+    let waiting = false;
+    try {
+        while (true) {
+            const next = await raceAbort(iterator.next(), signal);
+            if (next.done)
+                throw new Error('file status closed while preparing documents');
+            const files = next.value.files;
+            if (!wanted) {
+                const named = referencedDocuments(request.query, files.map((file) => ({ ...file, title: file.fileName })));
+                const requested = request.attachmentIds?.length
+                    ? files.filter((file) => request.attachmentIds.includes(file.fileId))
+                    : named.length
+                        ? named
+                        : isWholeDocumentQuery(request.query)
+                            ? files
+                            : [];
+                wanted = new Set(requested
+                    .filter((file) => search.pendingFiles.includes(file.fileName))
+                    .map((file) => file.fileId));
+                if (wanted.size === 0)
+                    return search;
+            }
+            if (!files.some((file) => wanted.has(file.fileId) && pending(file))) {
+                return await raceAbort(engine.ragSearch(request), signal);
+            }
+            if (!waiting) {
+                waiting = true;
+                preparing(true);
+            }
+        }
+    }
+    finally {
+        watch.destroy();
+        if (waiting)
+            preparing(false);
+    }
+}
+function pending(file) {
+    const rag = file.processors.find((processor) => processor.processorId === 'rag');
+    return (!file.readyForChat &&
+        ['pending', 'running', 'uploading'].includes(file.state) &&
+        rag?.state !== 'not-applicable');
+}

package/dist-lib/lib/kv-cache-reclaim.d.ts

@@ -0,0 +1,5 @@
+import type { AssistantAgent } from '../spec/hyperschema/types.d.ts';
+export declare function chatKvCacheKey(chatId: string): string;
+export declare function chatRepairKvCacheKey(chatId: string, acceptedRepairs: number): string;
+export declare function disappearedChatIds(known: ReadonlySet<string>, current: ReadonlyArray<string>): string[];
+export declare function agentRekeyFingerprint(agent: AssistantAgent): string;

package/dist-lib/lib/kv-cache-reclaim.js

@@ -0,0 +1,29 @@
+export function chatKvCacheKey(chatId) {
+    return `chat-${chatId}`;
+}
+export function chatRepairKvCacheKey(chatId, acceptedRepairs) {
+    const base = chatKvCacheKey(chatId);
+    return acceptedRepairs > 0 ? `${base}/r${acceptedRepairs}` : base;
+}
+export function disappearedChatIds(known, current) {
+    const live = new Set(current);
+    const gone = [];
+    for (const id of known)
+        if (!live.has(id))
+            gone.push(id);
+    return gone;
+}
+export function agentRekeyFingerprint(agent) {
+    return JSON.stringify([
+        agent.bio,
+        agent.modelName,
+        agent.ctxSize ?? 0,
+        agent.kvCacheK ?? '',
+        agent.kvCacheV ?? '',
+        agent.enabledTools ?? null,
+        agent.enabledSkills ?? null,
+        agent.toolsScope ?? '',
+        agent.skillsScope ?? '',
+        agent.disabledToolsets ?? null
+    ]);
+}