@squadrules/mcp 4.8.6

package/dist/utils/qdrant-vector-management.js

@@ -0,0 +1,284 @@
+import { logger } from './structured-logger.js';
+import { createQdrantCollection } from './qdrant-collection-utils.js';
+import { KAIROS_APP_SPACE_ID } from '../config.js';
+import { getSpaceContext } from '../utils/tenant-context.js';
+import { buildSpaceFilter } from '../utils/space-filter.js';
+/**
+ * Add named vectors to an existing collection by updating its config.
+ * This uses client.updateCollection and will fail if the server does not support the operation.
+ */
+export async function addVectorsToCollection(client, collectionName, vectors) {
+    logger.info(`addVectorsToCollection: Attempting to add vectors [${Object.keys(vectors).join(', ')}] to collection ${collectionName}`);
+    try {
+        const updateCtx = { vectors: {} };
+        Object.entries(vectors).forEach(([k, v]) => {
+            updateCtx.vectors[k] = { size: v.size, distance: v.distance || 'Cosine', on_disk: v.on_disk };
+        });
+        // Attempt to call Qdrant updateCollection if available
+        if (typeof client.updateCollection === 'function') {
+            await client.updateCollection(collectionName, { vectors: updateCtx.vectors });
+            logger.info(`addVectorsToCollection: updateCollection called successfully for ${collectionName} -> added ${Object.keys(updateCtx.vectors).join(',')}`);
+        }
+        else {
+            // Try fallback: for older JS client versions, may not support updateCollection
+            throw new Error('Qdrant client does not support updateCollection; please recreate collection with named vectors');
+        }
+    }
+    catch (err) {
+        // If updateCollection fails because server doesn't allow adding new vector names, we need a safer migration path
+        const msg = err?.data?.status?.error || err?.message || String(err);
+        logger.warn(`addVectorsToCollection: updateCollection failed: ${msg}`);
+        // Heuristic: detect "Not existing vector name" error and attempt safe recreate + restore
+        if (String(msg).includes('Not existing vector name') || String(msg).includes('Not existing named vector')) {
+            logger.info(`addVectorsToCollection: detected inability to add vector via updateCollection, starting recreation-based migration for ${collectionName} to add vectors [${Object.keys(vectors).join(', ')}]`);
+            // Step 1: Gather existing points via scroll in batches
+            const allPoints = [];
+            const filter = buildSpaceFilter(getSpaceContext().allowedSpaceIds);
+            let offset = undefined;
+            do {
+                const page = await client.scroll(collectionName, {
+                    filter,
+                    with_payload: true,
+                    with_vector: true,
+                    limit: 256,
+                    offset
+                });
+                if (!page?.points || page.points.length === 0)
+                    break;
+                for (const p of page.points) {
+                    allPoints.push({ id: p.id, payload: p.payload, vector: p.vector });
+                }
+                offset = page.next_page_offset;
+            } while (offset);
+            logger.info(`addVectorsToCollection: fetched ${allPoints.length} points from ${collectionName} for recreation`);
+            // Step 2: Recreate collection with merged vector set (existing vectors + requested)
+            // Gather existing vector descriptors so we can merge them
+            let mergedVectors = {};
+            try {
+                const existingCollectionInfo = await client.getCollection(collectionName);
+                const existingVectors = existingCollectionInfo.config?.params?.vectors;
+                if (existingVectors) {
+                    if (typeof existingVectors === 'object' && !existingVectors?.size) {
+                        Object.entries(existingVectors).forEach(([k, v]) => {
+                            mergedVectors[k] = { size: v.size, distance: v.distance || 'Cosine', on_disk: v.on_disk };
+                        });
+                    }
+                    else if (typeof existingVectors === 'object' && existingVectors.size) {
+                        // older single-vector layout
+                        const ev = existingVectors;
+                        mergedVectors[`vs${ev.size}`] = { size: ev.size, distance: ev.distance || 'Cosine', on_disk: ev.on_disk };
+                    }
+                }
+            }
+            catch (infoErr) {
+                // ignore; best-effort merge
+                logger.warn(`addVectorsToCollection: could not read existing collection info for ${collectionName}: ${String(infoErr)}`);
+            }
+            mergedVectors = { ...mergedVectors, ...vectors };
+            // We simply delete and recreate the collection with the desired vectors
+            try {
+                await client.deleteCollection(collectionName);
+                // small pause to ensure deletion is processed
+                await new Promise(resolve => setTimeout(resolve, 500));
+            }
+            catch (delErr) {
+                logger.warn(`addVectorsToCollection: failed to delete collection ${collectionName}: ${String(delErr)}; attempting to proceed`);
+            }
+            await createQdrantCollection(client, collectionName, mergedVectors);
+            logger.info(`addVectorsToCollection: recreated collection ${collectionName} with new vectors: ${Object.keys(mergedVectors).join(',')}`);
+            // Step 3: Re-insert points in batches to prevent memory pressure
+            const BATCH_SIZE = 256;
+            logger.info(`addVectorsToCollection: starting restore of ${allPoints.length} points to collection ${collectionName} (batchSize=${BATCH_SIZE})`);
+            let restored = 0;
+            for (let i = 0; i < allPoints.length; i += BATCH_SIZE) {
+                const batch = allPoints.slice(i, i + BATCH_SIZE).map(pt => ({
+                    id: pt.id,
+                    vector: pt.vector,
+                    payload: { ...pt.payload, space_id: pt.payload?.space_id ?? KAIROS_APP_SPACE_ID }
+                }));
+                try {
+                    await client.upsert(collectionName, { points: batch });
+                    restored += batch.length;
+                    logger.info(`addVectorsToCollection: upserted ${batch.length} restored points to ${collectionName} (restored total=${restored})`);
+                }
+                catch (upErr) {
+                    // If we fail here, try to continue and log
+                    logger.error(`addVectorsToCollection: failed upserting batch during recreation: ${String(upErr)}`);
+                }
+            }
+            logger.info(`addVectorsToCollection: restore complete, collection ${collectionName} now contains ${restored} points (attempted ${allPoints.length})`);
+            return;
+        }
+        throw err;
+    }
+}
+/**
+ * Migrate points from one named vector to another by re-embedding content.
+ * Assumes the new vector space is already added to the collection.
+ * @param client Qdrant client
+ * @param collectionName Collection name
+ * @param fromVectorName Source vector name (e.g., 'vs1024')
+ * @param toVectorName Target vector name (e.g., 'vs1536')
+ * @param embeddingService Service to generate new embeddings
+ * @param batchSize Batch size for migration (default 64)
+ */
+export async function migrateVectorSpace(client, collectionName, fromVectorName, toVectorName, embeddingService, // EmbeddingService
+batchSize = 64) {
+    let offset = undefined;
+    let migrated = 0;
+    let failed = 0;
+    logger.info(`migrateVectorSpace: Starting migration from ${fromVectorName} to ${toVectorName} in collection ${collectionName} - status=START`);
+    const filter = buildSpaceFilter(getSpaceContext().allowedSpaceIds);
+    do {
+        // Scroll points with the old vector
+        const page = await client.scroll(collectionName, {
+            filter,
+            with_payload: true,
+            with_vector: [fromVectorName], // Only fetch the old vector
+            limit: batchSize,
+            offset
+        });
+        if (!page.points || page.points.length === 0)
+            break;
+        const updates = [];
+        for (const point of page.points) {
+            const payload = point.payload;
+            // Re-embed the content to get new vector
+            const textToEmbed = [
+                payload.text || '',
+                payload.label || '',
+                payload.text || '',
+                `Tags: ${(payload.tags || []).join(', ')}`
+            ].filter(t => t.trim()).join('\n');
+            if (!textToEmbed.trim()) {
+                logger.warn(`Point ${point.id} has no embeddable content, skipping`);
+                continue;
+            }
+            let newVector = null;
+            try {
+                const embeddingResult = await embeddingService.generateEmbedding(textToEmbed);
+                newVector = embeddingResult.embedding;
+            }
+            catch (embedErr) {
+                failed += 1;
+                logger.warn(`migrateVectorSpace: failed to generate embedding for point ${point.id}; skipping; reason=${String(embedErr)}`);
+                continue;
+            }
+            // Prepare update: set new vector, keep payload
+            updates.push({
+                id: point.id,
+                vector: { [toVectorName]: newVector },
+                payload // Keep existing payload
+            });
+        }
+        if (updates.length > 0) {
+            try {
+                await client.upsert(collectionName, { points: updates });
+                migrated += updates.length;
+                logger.info(`migrateVectorSpace: Migrated ${updates.length} points in current batch, total migrated: ${migrated}`);
+            }
+            catch (upErr) {
+                // If upsert fails, log and attempt to continue
+                logger.error(`migrateVectorSpace: failed to upsert migrated vectors batch: ${String(upErr)}; migrated so far: ${migrated}`);
+            }
+        }
+        offset = page.next_page_offset;
+    } while (offset);
+    logger.info(`migrateVectorSpace: Migration complete for ${collectionName}: migrated=${migrated}, failed=${failed}, from=${fromVectorName}, to=${toVectorName} - status=COMPLETE`);
+}
+/**
+ * Remove a named vector from the collection after migration.
+ * Note: Qdrant may not support removing vectors once added; this is a placeholder.
+ */
+export async function removeVectorFromCollection(client, collectionName, vectorName) {
+    logger.info(`removeVectorFromCollection: Attempting to remove vector '${vectorName}' from collection '${collectionName}'`);
+    // Recreate the collection without the given vectorName by gathering all points, removing the vector field,
+    // and recreating the collection with a merged vector map that excludes the vectorName.
+    try {
+        const collectionInfo = await client.getCollection(collectionName);
+        const vectors = collectionInfo.config?.params?.vectors;
+        if (!vectors) {
+            logger.warn(`removeVectorFromCollection: No vector config found for ${collectionName}; nothing to remove`);
+            return;
+        }
+        // Convert to descriptor map
+        const existingVectors = {};
+        if (typeof vectors === 'object' && !vectors.size) {
+            Object.entries(vectors).forEach(([k, v]) => {
+                existingVectors[k] = { size: v.size, distance: v.distance || 'Cosine', on_disk: v.on_disk };
+            });
+        }
+        else if (typeof vectors === 'object' && vectors.size) {
+            // Single root vector; cannot remove unless recreating collection & leaving no vectors which is invalid
+            const ev = vectors;
+            existingVectors[`vs${ev.size}`] = { size: ev.size, distance: ev.distance || 'Cosine', on_disk: ev.on_disk };
+        }
+        if (!(vectorName in existingVectors)) {
+            logger.info(`removeVectorFromCollection: vector '${vectorName}' not present in collection '${collectionName}', nothing to remove`);
+            return;
+        }
+        // Build new vector map excluding the vectorName
+        const newVectors = {};
+        Object.entries(existingVectors).forEach(([k, v]) => {
+            if (k !== vectorName)
+                newVectors[k] = v;
+        });
+        if (Object.keys(newVectors).length === 0) {
+            logger.error(`removeVectorFromCollection: Cannot remove vector '${vectorName}' as it would leave collection '${collectionName}' without any vectors`);
+            return;
+        }
+        // Gather all points and strip the vectorName from all points
+        const filter = buildSpaceFilter(getSpaceContext().allowedSpaceIds);
+        const allPoints = [];
+        let offset = undefined;
+        do {
+            const page = await client.scroll(collectionName, { filter, with_payload: true, with_vector: true, limit: 256, offset });
+            if (!page?.points || page.points.length === 0)
+                break;
+            for (const p of page.points) {
+                const vec = p.vector || {};
+                // Copy all vector fields except the removed one
+                const newVectorFields = {};
+                Object.entries(vec).forEach(([vn, v]) => {
+                    if (vn !== vectorName)
+                        newVectorFields[vn] = v;
+                });
+                allPoints.push({ id: p.id, vector: newVectorFields, payload: p.payload });
+            }
+            offset = page.next_page_offset;
+        } while (offset);
+        logger.info(`removeVectorFromCollection: Fetched ${allPoints.length} points from ${collectionName} to recreate without ${vectorName}`);
+        // Delete, recreate with new vectors, and upsert points (without the removed vector)
+        try {
+            await client.deleteCollection(collectionName);
+            await new Promise(resolve => setTimeout(resolve, 500));
+        }
+        catch (delErr) {
+            logger.warn(`removeVectorFromCollection: failed to delete collection ${collectionName}: ${String(delErr)}; attempting to proceed`);
+        }
+        await createQdrantCollection(client, collectionName, newVectors);
+        logger.info(`removeVectorFromCollection: recreated collection ${collectionName} without vector ${vectorName}; new vectors: ${Object.keys(newVectors).join(',')}`);
+        const BATCH_SIZE = 256;
+        let restored = 0;
+        for (let i = 0; i < allPoints.length; i += BATCH_SIZE) {
+            const batch = allPoints.slice(i, i + BATCH_SIZE).map(p => ({
+                id: p.id,
+                vector: p.vector,
+                payload: { ...p.payload, space_id: p.payload?.space_id ?? KAIROS_APP_SPACE_ID }
+            }));
+            try {
+                await client.upsert(collectionName, { points: batch });
+                restored += batch.length;
+                logger.info(`removeVectorFromCollection: upserted ${batch.length} restored points into ${collectionName} (restored=${restored})`);
+            }
+            catch (upErr) {
+                logger.error(`removeVectorFromCollection: upsert failed during recreation: ${String(upErr)}`);
+            }
+        }
+        logger.info(`removeVectorFromCollection: Completed removal of ${vectorName} on ${collectionName} - restored points=${restored}`);
+    }
+    catch (err) {
+        logger.error(`removeVectorFromCollection: removal failed for ${vectorName} on ${collectionName}: ${String(err)}`);
+    }
+}
+//# sourceMappingURL=qdrant-vector-management.js.map

package/dist/utils/qdrant-vector-management.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrant-vector-management.js","sourceRoot":"","sources":["../../src/utils/qdrant-vector-management.ts"],"names":[],"mappings":"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"}

package/dist/utils/qdrant-vector-types.d.ts

@@ -0,0 +1,31 @@
+/** Vector size from resolved embedding dimension (set at startup probe). */
+export type VectorDescriptor = {
+    size: number;
+    distance?: 'Cosine' | 'Euclid' | 'Dot';
+    on_disk?: boolean;
+};
+export type VectorDescriptorMap = Record<string, VectorDescriptor>;
+export declare function getVectorSize(): number;
+export declare function getPrimaryVectorName(size?: number): string;
+export declare function getAdapterTitleVectorName(size?: number): string;
+export declare function getActivationPatternVectorName(size?: number): string;
+/**
+ * Build a named vector configuration object from resolved dimension.
+ * Uses "vs{DIMENSION}" naming to support migration between dimensions.
+ */
+export declare function getVectorDescriptors(): VectorDescriptorMap;
+/**
+ * Resolve a potential 'current' alias for Qdrant collection names.
+ *
+ * Usage:
+ * - If callers pass the literal alias 'current' (or an env var resolves to it),
+ *   this function returns the real collection name derived from:
+ *     1) process.env['QDRANT_COLLECTION_CURRENT']
+ *     2) process.env['QDRANT_COLLECTION'] (fallback)
+ *     3) the provided collection string (final fallback)
+ *
+ * This allows code to use the stable alias 'current' while the actual
+ * target collection can be changed via environment without touching code.
+ */
+export declare function resolveCollectionAlias(collectionName: string): string;
+//# sourceMappingURL=qdrant-vector-types.d.ts.map

package/dist/utils/qdrant-vector-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrant-vector-types.d.ts","sourceRoot":"","sources":["../../src/utils/qdrant-vector-types.ts"],"names":[],"mappings":"AAGA,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAC3G,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAEnE,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,MAAgC,GAAG,MAAM,CAEnF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,MAAgC,GAAG,MAAM,CAExF;AAED,wBAAgB,8BAA8B,CAAC,IAAI,GAAE,MAAgC,GAAG,MAAM,CAE7F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,mBAAmB,CAO1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAOrE"}

package/dist/utils/qdrant-vector-types.js

@@ -0,0 +1,49 @@
+import { QDRANT_COLLECTION_CURRENT, getQdrantCollection } from '../config.js';
+import { getEmbeddingDimension } from '../services/embedding/config.js';
+export function getVectorSize() {
+    return getEmbeddingDimension();
+}
+export function getPrimaryVectorName(size = getEmbeddingDimension()) {
+    return `vs${size}`;
+}
+export function getAdapterTitleVectorName(size = getEmbeddingDimension()) {
+    return `adapter_title_vs${size}`;
+}
+export function getActivationPatternVectorName(size = getEmbeddingDimension()) {
+    return `activation_pattern_vs${size}`;
+}
+/**
+ * Build a named vector configuration object from resolved dimension.
+ * Uses "vs{DIMENSION}" naming to support migration between dimensions.
+ */
+export function getVectorDescriptors() {
+    const dim = getEmbeddingDimension();
+    return {
+        [getPrimaryVectorName(dim)]: { size: dim, distance: 'Cosine', on_disk: true },
+        [getAdapterTitleVectorName(dim)]: { size: dim, distance: 'Cosine', on_disk: true },
+        [getActivationPatternVectorName(dim)]: { size: dim, distance: 'Cosine', on_disk: true }
+    };
+}
+/**
+ * Resolve a potential 'current' alias for Qdrant collection names.
+ *
+ * Usage:
+ * - If callers pass the literal alias 'current' (or an env var resolves to it),
+ *   this function returns the real collection name derived from:
+ *     1) process.env['QDRANT_COLLECTION_CURRENT']
+ *     2) process.env['QDRANT_COLLECTION'] (fallback)
+ *     3) the provided collection string (final fallback)
+ *
+ * This allows code to use the stable alias 'current' while the actual
+ * target collection can be changed via environment without touching code.
+ */
+export function resolveCollectionAlias(collectionName) {
+    if (!collectionName)
+        return collectionName;
+    if (collectionName === 'current') {
+        // Priority: explicit current mapping, then older QDRANT_COLLECTION, then alias itself
+        return QDRANT_COLLECTION_CURRENT || getQdrantCollection();
+    }
+    return collectionName;
+}
+//# sourceMappingURL=qdrant-vector-types.js.map

package/dist/utils/qdrant-vector-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrant-vector-types.js","sourceRoot":"","sources":["../../src/utils/qdrant-vector-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAMxE,MAAM,UAAU,aAAa;IAC3B,OAAO,qBAAqB,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe,qBAAqB,EAAE;IACzE,OAAO,KAAK,IAAI,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,OAAe,qBAAqB,EAAE;IAC9E,OAAO,mBAAmB,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,OAAe,qBAAqB,EAAE;IACnF,OAAO,wBAAwB,IAAI,EAAE,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,GAAG,qBAAqB,EAAE,CAAC;IACpC,OAAO;QACL,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE;QAC7E,CAAC,yBAAyB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE;QAClF,CAAC,8BAA8B,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE;KACxF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,cAAsB;IAC3D,IAAI,CAAC,cAAc;QAAE,OAAO,cAAc,CAAC;IAC3C,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,sFAAsF;QACtF,OAAO,yBAAyB,IAAI,mBAAmB,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/utils/resolve-space-param.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve human-oriented space input (train / activate / tune) to a canonical space_id.
+ * Matches the train tool: "personal", group names, optional "Group: " prefix, or raw allowed IDs.
+ */
+import type { SpaceContext } from './tenant-context.js';
+export type ResolveSpaceParamResult = {
+    ok: true;
+    spaceId: string;
+} | {
+    ok: false;
+    code: 'SPACE_NOT_FOUND' | 'SPACE_READ_ONLY';
+    message: string;
+};
+export type ResolveSpaceParamOptions = {
+    /**
+     * When true, the Kairos app space (built-in adapters) may be resolved for activate/search scoping only.
+     * Train/tune omit this so the app space stays a read-only target for writes.
+     */
+    allowReadOnlyAppSearchScope?: boolean;
+};
+/**
+ * Resolve optional space string from tool input into an allowed space id.
+ * Empty / undefined / "personal" → default write space (typically personal).
+ */
+export declare function resolveSpaceParamForContext(ctx: SpaceContext, raw: string | undefined, options?: ResolveSpaceParamOptions): ResolveSpaceParamResult;
+/** Writable display names for spaces available in the current context. */
+export declare function listWritableSpaceDisplayNames(ctx: SpaceContext): string[];
+//# sourceMappingURL=resolve-space-param.d.ts.map

package/dist/utils/resolve-space-param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-space-param.d.ts","sourceRoot":"","sources":["../../src/utils/resolve-space-param.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,CAAC,EAAE,wBAAwB,GACjC,uBAAuB,CAyEzB;AAED,0EAA0E;AAC1E,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,EAAE,CAUzE"}

package/dist/utils/resolve-space-param.js

@@ -0,0 +1,97 @@
+/**
+ * Resolve human-oriented space input (train / activate / tune) to a canonical space_id.
+ * Matches the train tool: "personal", group names, optional "Group: " prefix, or raw allowed IDs.
+ */
+import { KAIROS_APP_SPACE_DISPLAY_NAME, spaceIdToDisplayName } from './space-display.js';
+import { KAIROS_APP_SPACE_ID } from '../config.js';
+/**
+ * Resolve optional space string from tool input into an allowed space id.
+ * Empty / undefined / "personal" → default write space (typically personal).
+ */
+export function resolveSpaceParamForContext(ctx, raw, options) {
+    if (raw === undefined || typeof raw !== 'string') {
+        return { ok: false, code: 'SPACE_NOT_FOUND', message: 'Space parameter is required.' };
+    }
+    const trimmed = raw.trim();
+    if (trimmed === '') {
+        const spaceId = ctx.defaultWriteSpaceId || ctx.allowedSpaceIds[0] || '';
+        if (!spaceId) {
+            return { ok: false, code: 'SPACE_NOT_FOUND', message: 'No default space in context.' };
+        }
+        return { ok: true, spaceId };
+    }
+    const spaceParam = trimmed.toLowerCase();
+    if (spaceParam === 'personal') {
+        const fromJwt = typeof ctx.personalSpaceId === 'string' && ctx.personalSpaceId.trim().length > 0
+            ? ctx.personalSpaceId.trim()
+            : '';
+        const spaceId = fromJwt || ctx.defaultWriteSpaceId || ctx.allowedSpaceIds[0] || '';
+        if (!spaceId) {
+            return { ok: false, code: 'SPACE_NOT_FOUND', message: 'No personal or default space in context.' };
+        }
+        return { ok: true, spaceId };
+    }
+    const isKairosAppLabel = trimmed.toLowerCase() === KAIROS_APP_SPACE_DISPLAY_NAME.toLowerCase();
+    const isKairosAppRaw = trimmed === KAIROS_APP_SPACE_ID;
+    if (isKairosAppLabel || isKairosAppRaw) {
+        if (options?.allowReadOnlyAppSearchScope) {
+            return { ok: true, spaceId: KAIROS_APP_SPACE_ID };
+        }
+        return {
+            ok: false,
+            code: 'SPACE_READ_ONLY',
+            message: `Cannot use "${KAIROS_APP_SPACE_DISPLAY_NAME}" as a writable target; it is read-only. Use "personal" or a group name.`
+        };
+    }
+    const idsForDisplayMatch = [
+        ...ctx.allowedSpaceIds,
+        ...(options?.allowReadOnlyAppSearchScope ? [KAIROS_APP_SPACE_ID] : [])
+    ];
+    const tl = trimmed.toLowerCase();
+    for (const id of idsForDisplayMatch) {
+        if (spaceIdToDisplayName(id, ctx.spaceNamesById).toLowerCase() === tl) {
+            return { ok: true, spaceId: id };
+        }
+    }
+    const groupName = trimmed.startsWith('Group: ') ? trimmed.slice(7).trim() : trimmed;
+    const groupPathForm = groupName.startsWith('/') ? groupName : `/${groupName}`;
+    const groupNameLower = groupName.toLowerCase();
+    const groupPathLower = groupPathForm.toLowerCase();
+    const match = ctx.allowedSpaceIds.find((id) => {
+        if (id === groupName || id === trimmed)
+            return true;
+        if (id.startsWith('group:')) {
+            const canonical = (ctx.spaceNamesById?.[id] ?? '').trim();
+            if (!canonical)
+                return false;
+            const canonicalLower = canonical.toLowerCase();
+            if (canonicalLower === groupNameLower)
+                return true;
+            if (canonicalLower === groupPathLower)
+                return true;
+        }
+        return false;
+    });
+    if (!match) {
+        return {
+            ok: false,
+            code: 'SPACE_NOT_FOUND',
+            message: `Group or space "${groupName}" not found in your allowed spaces.`
+        };
+    }
+    return { ok: true, spaceId: match };
+}
+/** Writable display names for spaces available in the current context. */
+export function listWritableSpaceDisplayNames(ctx) {
+    const seen = new Set();
+    const names = [];
+    for (const spaceId of ctx.allowedSpaceIds) {
+        const name = spaceIdToDisplayName(spaceId, ctx.spaceNamesById);
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        names.push(name);
+    }
+    return names;
+}
+//# sourceMappingURL=resolve-space-param.js.map

package/dist/utils/resolve-space-param.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-space-param.js","sourceRoot":"","sources":["../../src/utils/resolve-space-param.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,6BAA6B,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAcnD;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,GAAiB,EACjB,GAAuB,EACvB,OAAkC;IAElC,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC;IACzF,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC;QACzF,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACzC,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;QAC9B,MAAM,OAAO,GACX,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ,IAAI,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAC9E,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE;YAC5B,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,OAAO,GAAG,OAAO,IAAI,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,0CAA0C,EAAE,CAAC;QACrG,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,KAAK,6BAA6B,CAAC,WAAW,EAAE,CAAC;IAC/F,MAAM,cAAc,GAAG,OAAO,KAAK,mBAAmB,CAAC;IACvD,IAAI,gBAAgB,IAAI,cAAc,EAAE,CAAC;QACvC,IAAI,OAAO,EAAE,2BAA2B,EAAE,CAAC;YACzC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;QACpD,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,eAAe,6BAA6B,0EAA0E;SAChI,CAAC;IACJ,CAAC;IAED,MAAM,kBAAkB,GAAG;QACzB,GAAG,GAAG,CAAC,eAAe;QACtB,GAAG,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;IACF,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACjC,KAAK,MAAM,EAAE,IAAI,kBAAkB,EAAE,CAAC;QACpC,IAAI,oBAAoB,CAAC,EAAE,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC;YACtE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IACpF,MAAM,aAAa,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC;IAC9E,MAAM,cAAc,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IAC/C,MAAM,cAAc,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC;IACnD,MAAM,KAAK,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE;QAC5C,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QACpD,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC1D,IAAI,CAAC,SAAS;gBAAE,OAAO,KAAK,CAAC;YAC7B,MAAM,cAAc,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;YAC/C,IAAI,cAAc,KAAK,cAAc;gBAAE,OAAO,IAAI,CAAC;YACnD,IAAI,cAAc,KAAK,cAAc;gBAAE,OAAO,IAAI,CAAC;QACrD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,mBAAmB,SAAS,qCAAqC;SAC3E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACtC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,6BAA6B,CAAC,GAAiB;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,oBAAoB,CAAC,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;QAC/D,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC7B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/space-display.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Human-readable names for space IDs. Frontend (tools, responses) uses names; backend uses ids.
+ */
+/** Display label for the app space (embedded mem docs). */
+export declare const KAIROS_APP_SPACE_DISPLAY_NAME = "Kairos app";
+/**
+ * Map a space_id to a human-readable name for tool outputs and agent-facing responses.
+ * user:*:* → "Personal"; group:*:* → "Group: /full/path"; space:kairos-app → "Kairos app".
+ */
+export declare function spaceKindFromSpaceId(spaceId: string): 'personal' | 'group' | 'app' | 'other';
+export declare function spaceIdToDisplayName(spaceId: string, namesById?: Record<string, string>): string;
+//# sourceMappingURL=space-display.d.ts.map

package/dist/utils/space-display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-display.d.ts","sourceRoot":"","sources":["../../src/utils/space-display.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,2DAA2D;AAC3D,eAAO,MAAM,6BAA6B,eAAe,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAQ5F;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAahG"}

package/dist/utils/space-display.js

@@ -0,0 +1,45 @@
+/**
+ * Human-readable names for space IDs. Frontend (tools, responses) uses names; backend uses ids.
+ */
+import { KAIROS_APP_SPACE_ID } from '../config.js';
+/** Display label for the app space (embedded mem docs). */
+export const KAIROS_APP_SPACE_DISPLAY_NAME = 'Kairos app';
+/**
+ * Map a space_id to a human-readable name for tool outputs and agent-facing responses.
+ * user:*:* → "Personal"; group:*:* → "Group: /full/path"; space:kairos-app → "Kairos app".
+ */
+export function spaceKindFromSpaceId(spaceId) {
+    if (!spaceId || typeof spaceId !== 'string')
+        return 'other';
+    if (spaceId === KAIROS_APP_SPACE_ID)
+        return 'app';
+    const parts = spaceId.split(':');
+    if (parts[0] === 'user')
+        return 'personal';
+    if (parts[0] === 'group')
+        return 'group';
+    if (parts[0] === 'space')
+        return 'other';
+    return 'other';
+}
+export function spaceIdToDisplayName(spaceId, namesById) {
+    if (!spaceId || typeof spaceId !== 'string')
+        return 'Unknown';
+    if (spaceId === KAIROS_APP_SPACE_ID)
+        return KAIROS_APP_SPACE_DISPLAY_NAME;
+    const mapped = namesById?.[spaceId];
+    if (mapped && mapped.trim().length > 0) {
+        if (spaceId.startsWith('group:'))
+            return `Group: ${mapped}`;
+        return mapped;
+    }
+    const parts = spaceId.split(':');
+    if (parts[0] === 'user')
+        return 'Personal';
+    if (parts[0] === 'group')
+        return 'Group';
+    if (parts[0] === 'space' && parts.length >= 2)
+        return parts.slice(1).join(':') || spaceId;
+    return spaceId;
+}
+//# sourceMappingURL=space-display.js.map

package/dist/utils/space-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-display.js","sourceRoot":"","sources":["../../src/utils/space-display.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,6BAA6B,GAAG,YAAY,CAAC;AAE1D;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAC5D,IAAI,OAAO,KAAK,mBAAmB;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,UAAU,CAAC;IAC3C,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IACzC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IACzC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,SAAkC;IACtF,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9D,IAAI,OAAO,KAAK,mBAAmB;QAAE,OAAO,6BAA6B,CAAC;IAC1E,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvC,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,UAAU,MAAM,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,UAAU,CAAC;IAC3C,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IACzC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC;IAC1F,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/space-filter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Build Qdrant filter for space isolation. Merges space_id constraint with optional existing filter.
+ */
+/** Qdrant filter shape (must array of conditions). */
+export interface QdrantFilterMust {
+    must?: Array<Record<string, unknown>>;
+}
+/**
+ * Build a filter that restricts results to points whose space_id is in allowedSpaceIds.
+ * Merges with existingFilter.must so callers can add domain, adapter.id, etc.
+ */
+export declare function buildSpaceFilter(allowedSpaceIds: string[], existingFilter?: QdrantFilterMust): {
+    must: Array<Record<string, unknown>>;
+};
+/**
+ * Scroll filter for adapter siblings: same `adapter.id` and either `space_id` in the allowed set
+ * or older rows with no `space_id` payload (Qdrant `match any` does not match missing payload keys).
+ */
+export declare function buildAdapterSiblingScrollFilter(allowedSpaceIds: string[], adapterId: string): {
+    must: Array<Record<string, unknown>>;
+};
+//# sourceMappingURL=space-filter.d.ts.map

package/dist/utils/space-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-filter.d.ts","sourceRoot":"","sources":["../../src/utils/space-filter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EAAE,EACzB,cAAc,CAAC,EAAE,gBAAgB,GAChC;IAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,CAS1C;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,MAAM,EAAE,EACzB,SAAS,EAAE,MAAM,GAChB;IAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,CAY1C"}