@qvac/core 0.0.0 → 0.1.0

package/dist-lib/lib/core/tool-activity.js

@@ -0,0 +1,39 @@
+import { capToolActivityArguments } from "../../schema/qvac.js";
+import { randomId } from "./id.js";
+const TOOL_ACTIVITY_BY_AGENT = '@qvac/tool-activity-by-agent';
+export async function recordToolActivity(store, input) {
+    const activity = {
+        id: randomId(),
+        agentId: input.agentId,
+        originDeviceId: input.originDeviceId,
+        chatId: input.chatId,
+        runId: input.runId,
+        toolName: input.toolName,
+        arguments: capToolActivityArguments(input.arguments),
+        resource: input.resource ?? undefined,
+        effect: input.effect,
+        decision: input.decision,
+        at: input.at,
+        seq: 0
+    };
+    await store.dispatch('append-tool-activity', { activity });
+    return { id: activity.id };
+}
+export async function listToolActivity(store, agentId, { limit, beforeSeq } = {}) {
+    if (beforeSeq !== undefined && beforeSeq <= 0)
+        return [];
+    const snap = store.view.snapshot();
+    try {
+        return await snap
+            .find(TOOL_ACTIVITY_BY_AGENT, {
+            gte: { agentId },
+            lte: beforeSeq === undefined ? { agentId } : { agentId, seq: beforeSeq - 1 },
+            reverse: true,
+            limit: limit || undefined
+        })
+            .toArray();
+    }
+    finally {
+        await snap.close();
+    }
+}

package/dist-lib/lib/core/tool-configs.d.ts

@@ -0,0 +1,13 @@
+import type { QvacToolConfigs } from '../../spec/mesh/hyperschema/types.d.ts';
+import type { Mesh } from './mesh.ts';
+export interface ToolConfigInput {
+    readonly agentId: string;
+    readonly toolName: string;
+    readonly settings: Readonly<Record<string, unknown>>;
+}
+export declare function toolConfigsCarrySecret(settings: unknown): boolean;
+export declare function getToolConfigs(store: Mesh, agentId: string, toolName: string): Promise<QvacToolConfigs | null>;
+export declare function listToolConfigs(store: Mesh, agentId: string): Promise<QvacToolConfigs[]>;
+export declare function setToolConfigs(store: Mesh, input: ToolConfigInput): Promise<QvacToolConfigs>;
+export declare function deleteToolConfigs(store: Mesh, agentId: string, toolName: string): Promise<QvacToolConfigs>;
+export declare function softDeleteToolConfigsForAgent(store: Mesh, agentId: string): Promise<void>;

package/dist-lib/lib/core/tool-configs.js

@@ -0,0 +1,141 @@
+import { MAX_TOOL_CONFIGS_BYTES, toolConfigsWithinBounds } from "../../schema/qvac.js";
+import { mustGetAgent } from "./agent.js";
+const TOOL_CONFIGS = '@qvac/tool-configs';
+const ACTIVE_TOOL_CONFIGS_BY_AGENT = '@qvac/active-tool-configs-by-agent';
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+const SECRET_KEY_HINTS = [
+    'authorization',
+    'apikey',
+    'password',
+    'passwd',
+    'passphrase',
+    'secret',
+    'privatekey',
+    'accesskey',
+    'accesstoken',
+    'refreshtoken',
+    'sessiontoken',
+    'authtoken',
+    'bearer',
+    'credential'
+];
+const SECRET_KEY_PATTERNS = [/token$/];
+const SECRET_REFERENCE_SUFFIXES = ['ref', 'refid', 'reference', 'id', 'name', 'handle', 'alias'];
+function looksLikeSecretKey(key) {
+    const normalized = key.toLowerCase().replace(/[-_\s]/g, '');
+    const secretish = SECRET_KEY_HINTS.some((hint) => normalized.includes(hint)) ||
+        SECRET_KEY_PATTERNS.some((pattern) => pattern.test(normalized));
+    if (!secretish)
+        return false;
+    return !SECRET_REFERENCE_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+function findReplicatedSecret(value, path) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const hit = findReplicatedSecret(item, path);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }
+    if (!isPlainObject(value))
+        return null;
+    for (const key of Object.keys(value)) {
+        if (looksLikeSecretKey(key))
+            return `${path}.${key}`;
+        const hit = findReplicatedSecret(value[key], `${path}.${key}`);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+function assertNoReplicatedSecrets(value, path) {
+    const hit = findReplicatedSecret(value, path);
+    if (hit) {
+        throw new Error(`tool configs must not carry secrets (${hit}); ` +
+            'keep the secret device-local and store a mesh-safe reference instead');
+    }
+}
+export function toolConfigsCarrySecret(settings) {
+    return findReplicatedSecret(settings, 'settings') !== null;
+}
+export async function getToolConfigs(store, agentId, toolName) {
+    return store.view.get(TOOL_CONFIGS, { agentId, toolName });
+}
+export async function listToolConfigs(store, agentId) {
+    const snap = store.view.snapshot();
+    try {
+        const rows = [];
+        for await (const row of snap.find(ACTIVE_TOOL_CONFIGS_BY_AGENT, {
+            gte: { agentId },
+            lte: { agentId }
+        })) {
+            rows.push(row);
+        }
+        return rows;
+    }
+    finally {
+        await snap.close();
+    }
+}
+export async function setToolConfigs(store, input) {
+    const agent = await mustGetAgent(store, input.agentId);
+    if (agent.deletedAt) {
+        throw new Error(`agent is deleted: ${input.agentId}`);
+    }
+    if (!isPlainObject(input.settings)) {
+        throw new Error('tool configs must be a plain object');
+    }
+    assertNoReplicatedSecrets(input.settings, 'settings');
+    const normalized = { ...input.settings };
+    if (!toolConfigsWithinBounds(normalized)) {
+        throw new Error(`tool configs exceed the ${MAX_TOOL_CONFIGS_BYTES} byte wire cap`);
+    }
+    const now = Date.now();
+    const current = await getToolConfigs(store, input.agentId, input.toolName);
+    const settings = {
+        agentId: input.agentId,
+        toolName: input.toolName,
+        settings: normalized,
+        createdAt: current?.createdAt ?? now,
+        updatedAt: now,
+        deletedAt: undefined
+    };
+    await store.dispatch('put-tool-configs', { settings });
+    return settings;
+}
+export async function deleteToolConfigs(store, agentId, toolName) {
+    await mustGetAgent(store, agentId);
+    const current = await getToolConfigs(store, agentId, toolName);
+    if (!current || current.deletedAt) {
+        throw new Error(`tool configs not found: ${agentId}/${toolName}`);
+    }
+    const now = Date.now();
+    const settings = { ...current, deletedAt: now, updatedAt: now };
+    await store.dispatch('put-tool-configs', { settings });
+    return settings;
+}
+export async function softDeleteToolConfigsForAgent(store, agentId) {
+    const snap = store.view.snapshot();
+    try {
+        for await (const row of snap.find(ACTIVE_TOOL_CONFIGS_BY_AGENT, {
+            gte: { agentId },
+            lte: { agentId }
+        })) {
+            if (store.closing)
+                return;
+            const now = Date.now();
+            await store.dispatch('put-tool-configs', {
+                settings: { ...row, deletedAt: now, updatedAt: now }
+            });
+        }
+    }
+    finally {
+        await snap.close();
+    }
+}

package/dist-lib/lib/core.d.ts

@@ -0,0 +1,291 @@
+import Corestore from 'corestore';
+import CorestoreStorage from 'hypercore-storage';
+import type { BootstrapNode } from 'hyperswarm';
+import ReadyGuard from 'ready-guard';
+import ReadyResource from 'ready-resource';
+import type { Logger } from '../index.ts';
+import type { AssistantCompactChatResponse, AssistantCopySkillResponse, AssistantDeleteModelRequest, AssistantDeleteModelResponse, AssistantDeleteSkillResponse, AssistantKvCacheDeletionResponse, AssistantListModelsRequest, AssistantManagedSkillsResponse, AssistantModelCatalogRevision, AssistantModelInfoList, AssistantOkResponse, AssistantSkillCatalogResponse, AssistantSkillFileResponse, AssistantSpeakRequest, AssistantSpeakResponse, AssistantToolCatalogResponse, AssistantTranscribeRequest, AssistantTranscribeResponse } from '../spec/index.d.ts';
+import { type BlindPeeringOpts } from './core/blind-peers.ts';
+import { type IndexingEmbedder, type RagExtractors, type VectorIndex } from './core/files/index.ts';
+import { type DriveHost } from './core/fs-drives.ts';
+import { type MeshInvite } from './core/invite.ts';
+import { openLocalStore } from './core/local/index.ts';
+import { type SecretRequest } from './core/secret-handoff.ts';
+import type { AppBuildMetadata } from './core/app-build.ts';
+import { Mesh, type DeviceMetadata } from './core/mesh.ts';
+import { type Stream, type Transport } from '@qvac/harness/rpc';
+import { type CoreSpec } from './spec-loader.ts';
+import { type LocalQvacState } from '../spec/index.js';
+export interface CoreOptions {
+    storagePath: string;
+    logger?: Logger | null;
+    spec?: () => Promise<CoreSpec>;
+    bootstrapNodes?: ReadonlyArray<BootstrapNode>;
+    device?: DeviceMetadata;
+    app?: AppBuildMetadata;
+    minSupportedVersion?: string;
+    otaConfigCore?: {
+        readonly key: string;
+        readonly minLength: number;
+    };
+    blindPeerKeys?: ReadonlyArray<Buffer>;
+    blindPeeringOpts?: BlindPeeringOpts;
+    meshSeed?: Buffer;
+    meshKey?: Buffer;
+    additionalNodes?: ReadonlyArray<{
+        readonly host: string;
+        readonly port: number;
+    }>;
+    listModels?: (options: AssistantListModelsRequest) => Promise<AssistantModelInfoList>;
+    deleteModel?: (options: AssistantDeleteModelRequest) => Promise<AssistantDeleteModelResponse>;
+    clearKvCache?: () => Promise<AssistantKvCacheDeletionResponse>;
+    deleteChatKvCache?: (chatId: string) => Promise<AssistantKvCacheDeletionResponse>;
+    compactChat?: (chatId: string) => Promise<AssistantCompactChatResponse>;
+    modelCatalogWatch?: () => AsyncIterable<AssistantModelCatalogRevision>;
+    retryModelDownload?: (name: string) => Promise<void>;
+    transcribe?: (request: AssistantTranscribeRequest) => Promise<AssistantTranscribeResponse>;
+    speak?: (request: AssistantSpeakRequest) => Promise<AssistantSpeakResponse>;
+    speakStream?: (text: AsyncIterable<string>) => AsyncIterable<AssistantSpeakResponse>;
+    embedder?: IndexingEmbedder;
+    extractors?: RagExtractors;
+    skills?: (agentId?: string | null, modelName?: string | null, options?: {
+        readonly refresh?: boolean;
+    }) => Promise<unknown>;
+    skillCatalog?: (agentId?: string | null, modelName?: string | null, options?: {
+        readonly refresh?: boolean;
+    }) => Promise<AssistantSkillCatalogResponse>;
+    tools?: () => Promise<AssistantToolCatalogResponse>;
+    hostsModelSource?: boolean;
+    vectorIndex?: VectorIndex;
+    apiLifecycle?: {
+        readonly suspend: () => Promise<void>;
+        readonly resume: () => Promise<void>;
+    };
+}
+export interface SkillManagementHooks {
+    listManagedSkills(): Promise<AssistantManagedSkillsResponse>;
+    readSkillFile(name: string): Promise<AssistantSkillFileResponse>;
+    writeSkillFile(name: string, content: string): Promise<AssistantOkResponse>;
+    copySkillForEdit(name: string): Promise<AssistantCopySkillResponse>;
+    deleteOverlaySkill(name: string): Promise<AssistantDeleteSkillResponse>;
+}
+export declare class Core extends ReadyResource {
+    private readonly _storagePath;
+    store: Corestore;
+    rootCorestore: Corestore;
+    storage: CorestoreStorage;
+    local: ReturnType<typeof openLocalStore>;
+    state: LocalQvacState;
+    private readonly _transport;
+    private readonly _apiLifecycle;
+    private readonly _log;
+    private readonly _spec;
+    private readonly _bootstrapNodes;
+    private readonly _device;
+    private readonly _app;
+    private _minSupportedVersion;
+    private readonly _otaConfigCore;
+    private _otaConfig;
+    private _configPeering;
+    private _localDevice;
+    private readonly _blindPeerKeys;
+    private readonly _blindPeeringOpts;
+    private readonly _meshSeed;
+    private readonly _meshKey;
+    private readonly _additionalNodes;
+    private _listModels;
+    private _deleteModel;
+    private _clearKvCache;
+    private _deleteChatKvCache;
+    private _compactChat;
+    private _modelCatalogWatch;
+    private _modelCatalogWatchSource;
+    private _retryModelDownload;
+    private _transcribe;
+    private _speak;
+    private _speakStream;
+    private _embedder;
+    private _ragExtractors;
+    private _indexedEmbedder;
+    private readonly _indexingLock;
+    private readonly _meshTransitionLock;
+    private _processingFiles;
+    private _skills;
+    private _skillCatalog;
+    private _skillManagement;
+    private readonly _catalogHooks;
+    private _tools;
+    private readonly _hostsModelSource;
+    private _vectorIndex;
+    private readonly _closeSignal;
+    private _signalClose;
+    private readonly _closeListeners;
+    private _closeSignaled;
+    private _mesh;
+    private readonly _offlineBoot;
+    readonly onlineBoot: ReadyGuard;
+    private _candidateMesh;
+    private _cancelCandidateJoin;
+    private _joinCancellation;
+    private _meshSecretSeed;
+    private readonly _rpcs;
+    private _stream;
+    private _api;
+    private readonly _clients;
+    private _deviceKeyPair;
+    private readonly _memberLock;
+    private _identityPhrase;
+    private _identityPublicKey;
+    private _swarm;
+    private _departures;
+    private _fsDrives;
+    private _blobServer;
+    private readonly _attachmentUrl;
+    private readonly _wakeup;
+    private readonly _secretHandoff;
+    private readonly _skillOverlayHandoff;
+    private _hostedAgents;
+    private _minting;
+    private _leaving;
+    private _kicked;
+    private _kickedPending;
+    private readonly _peers;
+    private readonly _statusListeners;
+    private readonly _diagnosticsProviders;
+    private _systemInfo;
+    private readonly _onMeshWritable;
+    private readonly _onMeshDead;
+    private readonly _onMeshStalled;
+    private _statusError;
+    private _upgradeRequired;
+    constructor(transport: Transport, { storagePath, logger, spec, bootstrapNodes, device, app, minSupportedVersion, otaConfigCore, blindPeerKeys, blindPeeringOpts, meshSeed, meshKey, additionalNodes, listModels, deleteModel, clearKvCache, deleteChatKvCache, compactChat, modelCatalogWatch, retryModelDownload, transcribe, speak, speakStream, embedder, extractors, skills, skillCatalog, tools, hostsModelSource, vectorIndex, apiLifecycle }: CoreOptions);
+    get devicePublicKey(): Buffer | null;
+    get fsDrives(): DriveHost | null;
+    get suspended(): boolean;
+    get mesh(): Pick<Mesh, 'view' | 'discoveryKey' | 'publicKey' | 'key' | 'localWriterKey' | 'writable' | 'localLength' | 'blindPeerKeys'> | null;
+    meshReady(): Promise<void>;
+    get peerCount(): number;
+    get peerDeviceIds(): ReadonlyArray<string>;
+    _open(): Promise<void>;
+    private _runBootOffline;
+    private _openBootMesh;
+    private _runBootOnline;
+    private _reopenMesh;
+    get otaConfigCore(): {
+        readonly key: string;
+        readonly minLength: number;
+    } | null;
+    private _openOtaConfig;
+    private _logFloor;
+    private _peerConfigCore;
+    private _closeConfigPeering;
+    private _closeOtaConfig;
+    private _blockedByMinVersion;
+    private _setUpgradeRequired;
+    setMinSupportedVersion(required: string | null | undefined): void;
+    connect(stream: Stream): Promise<void>;
+    wakeup(): Promise<void>;
+    presuspend(): Promise<void>;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    private _refreshTopics;
+    _close(): Promise<void>;
+    private _openSwarm;
+    private _resolveBlindPeerKeys;
+    private _startMesh;
+    private _openMesh;
+    private _mintBirthMember;
+    private _holdIdentityPhrase;
+    private _pushIdentityPhrase;
+    private _offerIdentityPhrase;
+    private _bringMeshOnline;
+    private _advertiseDeviceProfile;
+    private _advertiseAppVersion;
+    private _settleMembership;
+    private _migrationContext;
+    private _recordMembership;
+    private _ensureNotRevoked;
+    private _retireMesh;
+    private _withdrawFromMesh;
+    private _onKicked;
+    private _requestFreshMesh;
+    private _onClose;
+    private _waitForMeshChange;
+    joinMesh(rawInvite: string): Promise<void>;
+    cancelMeshJoin(): void;
+    private _throwIfJoinCanceled;
+    private _joinMesh;
+    private _runJoinMesh;
+    private _joinParkedMesh;
+    private _openCandidateMesh;
+    private _waitForCandidateWritable;
+    private _activateMesh;
+    private _currentMesh;
+    private _awaitMesh;
+    private _startMeshServices;
+    private _stopHostedAgents;
+    private _discardCandidateMesh;
+    private _departureHasAudience;
+    private _announceDeparture;
+    leaveMesh(): Promise<void>;
+    removeDeviceWriter(writerKey: Buffer, deviceId: Buffer): Promise<void>;
+    renameLocalDevice(name: string): Promise<void>;
+    saveDeviceProfileLocal(capabilityProfile: DeviceMetadata['capabilityProfile'], recommendedModelName: string, platform?: string): Promise<void>;
+    waitForWritable(): Promise<void>;
+    getMeshInvite(): Promise<MeshInvite | null>;
+    private _closeSwarm;
+    pushSkillSecret(request: SecretRequest): Promise<void>;
+    private _storeHandedOffSecret;
+    private _skillOverlayOp;
+    private _resolveSkillOverlayHost;
+    private _serveSkillOverlayOp;
+    private _runLocalSkillOverlayOp;
+    private _setupFields;
+    private _hostSkills;
+    private _onConnection;
+    private _trackPeerConnection;
+    private _onPeerChange;
+    private _meshStatusSource;
+    private _networkStatusSource;
+    private _networkSnapshot;
+    private _networkState;
+    private _logSource;
+    compact(force?: boolean): Promise<void>;
+    registerDiagnostics(provider: () => object): () => void;
+    registerListModels(hook: (options: AssistantListModelsRequest) => Promise<AssistantModelInfoList>): () => void;
+    registerDeleteModel(hook: (options: AssistantDeleteModelRequest) => Promise<AssistantDeleteModelResponse>): () => void;
+    registerClearKvCache(hook: () => Promise<AssistantKvCacheDeletionResponse>): () => void;
+    registerDeleteChatKvCache(hook: (chatId: string) => Promise<AssistantKvCacheDeletionResponse>): () => void;
+    registerCompactChat(hook: (chatId: string) => Promise<AssistantCompactChatResponse>): () => void;
+    registerModelCatalogWatch(hook: () => AsyncIterable<AssistantModelCatalogRevision>): () => void;
+    private _watchModelCatalog;
+    private _openModelCatalogWatchSource;
+    private _resetModelCatalogWatchSource;
+    registerRetryModelDownload(hook: (name: string) => Promise<void>): () => void;
+    registerSkills(hook: (agentId?: string | null, modelName?: string | null, options?: {
+        readonly refresh?: boolean;
+    }) => Promise<unknown>): () => void;
+    registerSkillCatalog(hook: (agentId?: string | null, modelName?: string | null, options?: {
+        readonly refresh?: boolean;
+        readonly skipCredentialProbe?: boolean;
+    }) => Promise<AssistantSkillCatalogResponse>): () => void;
+    registerSkillManagement(hooks: SkillManagementHooks): () => void;
+    private _waitForCatalogHooks;
+    private _catalogHooksReady;
+    private _openCatalogHooks;
+    registerTools(hook: () => Promise<AssistantToolCatalogResponse>): () => void;
+    registerEmbedder(embedder: IndexingEmbedder, extractors?: RagExtractors): () => Promise<void>;
+    private _reconcileIndexing;
+    private _startIndexing;
+    private _stopIndexing;
+    registerTranscribe(hook: (request: AssistantTranscribeRequest) => Promise<AssistantTranscribeResponse>): () => void;
+    registerSpeak(hook: (request: AssistantSpeakRequest) => Promise<AssistantSpeakResponse>): () => void;
+    registerSpeakStream(hook: (text: AsyncIterable<string>) => AsyncIterable<AssistantSpeakResponse>): () => void;
+    private _diagnosticsSource;
+    private _memberDiagnostics;
+    private _diagnostics;
+    private _statusSnapshot;
+    acknowledgeKicked(): void;
+    private _statusState;
+    private _notifyStatus;
+}