@massa-ai/core 1.2.1

package/dist/services/web/web-controller.js

@@ -0,0 +1,140 @@
+/**
+ * WebController — orchestration for `fetch_and_index`.
+ *
+ * Owns a single set of injected index deps (vector store + keyword search) and
+ * drives the parallel-fetch / serial-index pipeline:
+ *
+ *   1. Build a `PoolJob` per request URL.
+ *   2. runPool fetches them in parallel (concurrency from the caller, cpu-capped
+ *      for batch). Each job runs fetchAndConvertOne, whose internal index drain
+ *      is already SERIAL — so even when N fetches race, the per-URL indexing
+ *      never overlaps with itself. Cross-URL overlap is acceptable for
+ *      pgvector (row locks) but would contend on PostgreSQL WAL; the per-URL
+ *      serial drain keeps the worst case to N concurrent single-writers, which
+ *      PostgreSQL tolerates and pgvector handles trivially.
+ *   3. Drain the allSettled-shaped results in input order and return per-URL
+ *      status + chunk counts.
+ *
+ * The controller is the composition root that wires the real vector/keyword
+ * stores into the fetcher's `WebIndexDeps`. Tests construct it with a captured
+ * in-memory deps map instead.
+ */
+import { logger } from "@massa-ai/shared";
+import { runPool } from "../executor/run-pool.js";
+import { fetchAndConvertOne, } from "./fetcher.js";
+/**
+ * Maximum number of entries retained in the in-memory fetch cache. The cache is
+ * process-local and not durable; without a cap a long-running process fetching
+ * many distinct URLs grows memory without bound. Map preserves INSERTION order
+ * in JS, so the oldest entry is evicted first when the cap is hit. Re-touching
+ * an entry (re-mark) promotes it to most-recent via delete+set.
+ */
+const WEB_CACHE_MAX_ENTRIES = 512;
+export class WebController {
+    static instance = null;
+    deps;
+    cache = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    static getInstance() {
+        if (!WebController.instance) {
+            throw new Error("WebController.getInstance() requires explicit deps — call " +
+                "WebController.instantiate(deps) once at boot, or construct with deps directly.");
+        }
+        return WebController.instance;
+    }
+    /**
+     * Boot the singleton with real store deps. The Tools API route calls this lazily
+     * on first request (after resolving the async vector store). Idempotent.
+     */
+    static instantiate(deps) {
+        if (!WebController.instance) {
+            WebController.instance = new WebController(deps);
+        }
+        return WebController.instance;
+    }
+    /** For tests: reset the singleton + clear the cache. */
+    static resetInstance() {
+        WebController.instance = null;
+    }
+    /** Build the WebIndexDeps seam from the real stores + the in-memory cache. */
+    indexDeps(projectId) {
+        return {
+            indexChunk: async (chunk) => {
+                const doc = {
+                    id: chunk.id,
+                    content: chunk.content,
+                    metadata: chunk.metadata,
+                };
+                // Parallel within ONE chunk: vector add + keyword index. Both stores
+                // accept independent writes; a single chunk is the serial unit.
+                await Promise.all([
+                    this.deps.vectorStore.addDocuments([doc]),
+                    this.deps.keywordSearch.index(chunk.id, chunk.content, chunk.metadata),
+                ]);
+            },
+            getLastIndexedAt: (key) => {
+                const ts = this.cache.get(key);
+                if (ts === undefined)
+                    return null;
+                // LRU touch: promote this key to most-recently-used so frequently-fetched
+                // URLs survive eviction. Map preserves insertion order, so delete+set
+                // reorders it to the end (newest).
+                this.cache.delete(key);
+                this.cache.set(key, ts);
+                return ts;
+            },
+            markIndexed: (key, ts) => {
+                // Replace any existing entry so the key's insertion order is refreshed.
+                this.cache.delete(key);
+                this.cache.set(key, ts);
+                // Evict oldest (first-key) entries while over the cap.
+                while (this.cache.size > WEB_CACHE_MAX_ENTRIES) {
+                    const oldest = this.cache.keys().next().value;
+                    if (oldest === undefined)
+                        break;
+                    this.cache.delete(oldest);
+                }
+            },
+        };
+    }
+    async fetchAndIndex(params) {
+        const batch = params.requests
+            ? params.requests
+            : params.url
+                ? [{ url: params.url, source: params.source }]
+                : [];
+        if (batch.length === 0) {
+            return { success: false, results: [], concurrency: 0, capped: false };
+        }
+        const requestedConcurrency = Math.min(Math.max(1, params.concurrency ?? 1), 8);
+        const projectId = params.projectId ?? "web";
+        const jobs = batch.map((req) => ({
+            run: () => fetchAndConvertOne(req.url, this.indexDeps(projectId), {
+                source: req.source,
+                force: params.force,
+                ttl: params.ttl,
+                projectId,
+            }),
+        }));
+        const { settled, effectiveConcurrency, capped } = await runPool(jobs, {
+            concurrency: requestedConcurrency,
+            capByCpuCount: batch.length > 1 && requestedConcurrency > 1,
+        });
+        // Map settled[i] → FetchOneResult (preserve input order). runPool guarantees
+        // settled[i] corresponds to jobs[i]; rejected entries become error results.
+        const results = settled.map((s, i) => {
+            if (s.status === "fulfilled")
+                return s.value;
+            const msg = s.reason instanceof Error ? s.reason.message : String(s.reason);
+            logger.error("fetch_and_index job rejected", s.reason, {
+                url: batch[i].url,
+            });
+            return { kind: "error", url: batch[i].url, error: msg };
+        });
+        const success = results.every((r) => r.kind === "fetched" || r.kind === "cached");
+        return { success, results, concurrency: effectiveConcurrency, capped };
+    }
+}
+//# sourceMappingURL=web-controller.js.map

package/dist/services/web/web-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-controller.js","sourceRoot":"","sources":["../../../src/services/web/web-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAgB,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,kBAAkB,GAInB,MAAM,cAAc,CAAC;AAgCtB;;;;;;GAMG;AACH,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,MAAM,OAAO,aAAa;IAChB,MAAM,CAAC,QAAQ,GAAyB,IAAI,CAAC;IACpC,IAAI,CAAoB;IACxB,KAAK,GAAa,IAAI,GAAG,EAAE,CAAC;IAE7C,YAAY,IAAuB;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,4DAA4D;gBAC1D,gFAAgF,CACnF,CAAC;QACJ,CAAC;QACD,OAAO,aAAa,CAAC,QAAQ,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,IAAuB;QACxC,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;YAC5B,aAAa,CAAC,QAAQ,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,aAAa,CAAC,QAAQ,CAAC;IAChC,CAAC;IAED,wDAAwD;IACxD,MAAM,CAAC,aAAa;QAClB,aAAa,CAAC,QAAQ,GAAG,IAAI,CAAC;IAChC,CAAC;IAED,8EAA8E;IACtE,SAAS,CAAC,SAAiB;QACjC,OAAO;YACL,UAAU,EAAE,KAAK,EAAE,KAAmB,EAAE,EAAE;gBACxC,MAAM,GAAG,GAAmB;oBAC1B,EAAE,EAAE,KAAK,CAAC,EAAE;oBACZ,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;iBACzB,CAAC;gBACF,qEAAqE;gBACrE,gEAAgE;gBAChE,MAAM,OAAO,CAAC,GAAG,CAAC;oBAChB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC;oBACzC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;iBACvE,CAAC,CAAC;YACL,CAAC;YACD,gBAAgB,EAAE,CAAC,GAAG,EAAE,EAAE;gBACxB,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC/B,IAAI,EAAE,KAAK,SAAS;oBAAE,OAAO,IAAI,CAAC;gBAClC,0EAA0E;gBAC1E,sEAAsE;gBACtE,mCAAmC;gBACnC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACxB,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE;gBACvB,wEAAwE;gBACxE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACxB,uDAAuD;gBACvD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,qBAAqB,EAAE,CAAC;oBAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;oBAC9C,IAAI,MAAM,KAAK,SAAS;wBAAE,MAAM;oBAChC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,MAA2B;QAM7C,MAAM,KAAK,GAAmB,MAAM,CAAC,QAAQ;YAC3C,CAAC,CAAC,MAAM,CAAC,QAAQ;YACjB,CAAC,CAAC,MAAM,CAAC,GAAG;gBACV,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC9C,CAAC,CAAC,EAAE,CAAC;QAET,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACxE,CAAC;QAED,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CACnC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,EACpC,CAAC,CACF,CAAC;QACF,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC;QAE5C,MAAM,IAAI,GAA8B,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC1D,GAAG,EAAE,GAAG,EAAE,CACR,kBAAkB,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE;gBACrD,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,SAAS;aACV,CAAC;SACL,CAAC,CAAC,CAAC;QAEJ,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE;YACpE,WAAW,EAAE,oBAAoB;YACjC,aAAa,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,oBAAoB,GAAG,CAAC;SAC5D,CAAC,CAAC;QAEH,6EAA6E;QAC7E,4EAA4E;QAC5E,MAAM,OAAO,GAAqB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACrD,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW;gBAAE,OAAO,CAAC,CAAC,KAAK,CAAC;YAC7C,MAAM,GAAG,GACP,CAAC,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAClE,MAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE,CAAC,CAAC,MAAe,EAAE;gBAC9D,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG;aAClB,CAAC,CAAC;YACH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAC1D,CAAC,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAC3B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,CACnD,CAAC;QAEF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,EAAE,CAAC;IACzE,CAAC"}

package/dist/services/workspace/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Workspace Module Exports
+ */
+export { workspaceManager, WorkspaceManager } from "./workspace-manager.js";
+export type { WorkspaceRow, WorkspaceStatus } from "./workspace-manager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/workspace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/workspace/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/services/workspace/index.js

@@ -0,0 +1,5 @@
+/**
+ * Workspace Module Exports
+ */
+export { workspaceManager, WorkspaceManager } from "./workspace-manager.js";
+//# sourceMappingURL=index.js.map

package/dist/services/workspace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/workspace/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/services/workspace/workspace-manager.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace Manager
+ *
+ * Single source of truth for project registration and indexing status.
+ * Persists all state to the `workspaces` table in the symbol PostgreSQL DB
+ * (replacing the zero-embedding _metadata docs in the vector store).
+ *
+ * Subscribes to EventBus to auto-update status on indexing lifecycle events.
+ */
+import type { WorkspaceRow, WorkspaceStatus } from "../../data/symbol/symbol-repository-pg.js";
+export type { WorkspaceRow, WorkspaceStatus };
+export declare class WorkspaceManager {
+    private static instance;
+    private constructor();
+    static getInstance(): WorkspaceManager;
+    /**
+     * Register a workspace as "indexing" (called at the start of ETL).
+     * Creates the row if it doesn't exist yet.
+     */
+    markIndexing(projectId: string, projectPath: string): Promise<void>;
+    /**
+     * Called after a successful ETL run.
+     * Triggers centrality recomputation in the background.
+     */
+    markIndexed(projectId: string, stats: {
+        filesCount: number;
+        chunksCount: number;
+        symbolsCount: number;
+    }): Promise<void>;
+    /**
+     * Called on ETL failure.
+     */
+    markError(projectId: string, error: string): Promise<void>;
+    listWorkspaces(statusFilter?: WorkspaceStatus | "all"): Promise<WorkspaceRow[]>;
+    getWorkspace(projectId: string): Promise<WorkspaceRow | null>;
+    /**
+     * M25: Resolve a project by its unique name tail (the last segment of the
+     * project path or the projectId itself).
+     *
+     * - Unique match → return the WorkspaceRow
+     * - Ambiguous (2+ matches) → throw with candidate list
+     * - No match → return null (not-found)
+     *
+     * The "name tail" is the last path segment of `projectPath` (e.g.,
+     * `/home/user/my-project` → `my-project`) or the `projectId` itself if the
+     * path has no slashes. Case-sensitive.
+     */
+    resolveByNameTail(nameTail: string): Promise<WorkspaceRow | null>;
+    /**
+     * Remove a project: deletes workspace row + all symbol data (CASCADE).
+     * Does NOT clear the vector store — caller is responsible for that.
+     */
+    removeWorkspace(projectId: string): Promise<void>;
+    private subscribeToEvents;
+}
+export declare const workspaceManager: WorkspaceManager;
+//# sourceMappingURL=workspace-manager.d.ts.map

package/dist/services/workspace/workspace-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-manager.d.ts","sourceRoot":"","sources":["../../../src/services/workspace/workspace-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAI/F,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC;AAE9C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IAExD,OAAO;IAIP,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAStC;;;OAGG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzE;;;OAGG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GACvE,OAAO,CAAC,IAAI,CAAC;IA0BhB;;OAEG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1D,cAAc,CAAC,YAAY,CAAC,EAAE,eAAe,GAAG,KAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAM/E,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAInE;;;;;;;;;;;OAWG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAiBvE;;;OAGG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,OAAO,CAAC,iBAAiB;CAuB1B;AAED,eAAO,MAAM,gBAAgB,kBAAiC,CAAC"}

package/dist/services/workspace/workspace-manager.js

@@ -0,0 +1,144 @@
+/**
+ * Workspace Manager
+ *
+ * Single source of truth for project registration and indexing status.
+ * Persists all state to the `workspaces` table in the symbol PostgreSQL DB
+ * (replacing the zero-embedding _metadata docs in the vector store).
+ *
+ * Subscribes to EventBus to auto-update status on indexing lifecycle events.
+ */
+import { logger } from "@massa-ai/shared";
+import { getSymbolRepository } from "../../data/symbol/symbol-repository-factory.js";
+import { eventBus } from "../events/event-bus.js";
+import { symbolGraphService } from "../symbol/symbol-graph.service.js";
+export class WorkspaceManager {
+    static instance = null;
+    constructor() {
+        this.subscribeToEvents();
+    }
+    static getInstance() {
+        if (!WorkspaceManager.instance) {
+            WorkspaceManager.instance = new WorkspaceManager();
+        }
+        return WorkspaceManager.instance;
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────────────
+    /**
+     * Register a workspace as "indexing" (called at the start of ETL).
+     * Creates the row if it doesn't exist yet.
+     */
+    async markIndexing(projectId, projectPath) {
+        const repo = getSymbolRepository();
+        const existing = await repo.getWorkspace(projectId);
+        await repo.upsertWorkspace({
+            project_id: projectId,
+            project_path: projectPath,
+            display_name: projectPath.split("/").pop(),
+            status: "indexing",
+            files_count: existing?.files_count ?? 0,
+            chunks_count: existing?.chunks_count ?? 0,
+            symbols_count: existing?.symbols_count ?? 0,
+            created_at: existing?.created_at,
+        });
+        eventBus.publish("workspace:updated", { projectId, status: "indexing" });
+        logger.info("WorkspaceManager: marked as indexing", { projectId });
+    }
+    /**
+     * Called after a successful ETL run.
+     * Triggers centrality recomputation in the background.
+     */
+    async markIndexed(projectId, stats) {
+        await getSymbolRepository().updateWorkspaceStatus(projectId, "indexed", {
+            lastIndexedAt: Date.now(),
+            lastError: null,
+            filesCount: stats.filesCount,
+            chunksCount: stats.chunksCount,
+            symbolsCount: stats.symbolsCount,
+        });
+        eventBus.publish("workspace:updated", {
+            projectId,
+            status: "indexed",
+            filesCount: stats.filesCount,
+            symbolsCount: stats.symbolsCount,
+        });
+        // Background centrality recomputation (non-blocking)
+        symbolGraphService
+            .recomputeCentrality(projectId)
+            .catch((err) => logger.error("WorkspaceManager: centrality recomputation failed", err, { projectId }));
+        logger.info("WorkspaceManager: marked as indexed", { projectId, ...stats });
+    }
+    /**
+     * Called on ETL failure.
+     */
+    async markError(projectId, error) {
+        await getSymbolRepository().updateWorkspaceStatus(projectId, "error", {
+            lastError: error,
+        });
+        eventBus.publish("workspace:updated", { projectId, status: "error" });
+        logger.warn("WorkspaceManager: marked as error", { projectId, error });
+    }
+    // ── Queries ────────────────────────────────────────────────────────────────
+    async listWorkspaces(statusFilter) {
+        const all = await getSymbolRepository().listWorkspaces();
+        if (!statusFilter || statusFilter === "all")
+            return all;
+        return all.filter((w) => w.status === statusFilter);
+    }
+    async getWorkspace(projectId) {
+        return getSymbolRepository().getWorkspace(projectId);
+    }
+    /**
+     * M25: Resolve a project by its unique name tail (the last segment of the
+     * project path or the projectId itself).
+     *
+     * - Unique match → return the WorkspaceRow
+     * - Ambiguous (2+ matches) → throw with candidate list
+     * - No match → return null (not-found)
+     *
+     * The "name tail" is the last path segment of `projectPath` (e.g.,
+     * `/home/user/my-project` → `my-project`) or the `projectId` itself if the
+     * path has no slashes. Case-sensitive.
+     */
+    async resolveByNameTail(nameTail) {
+        if (!nameTail)
+            return null;
+        const all = await getSymbolRepository().listWorkspaces();
+        const matches = all.filter((w) => {
+            const pathTail = w.project_path.split("/").pop() ?? w.project_path;
+            return pathTail === nameTail || w.project_id === nameTail;
+        });
+        if (matches.length === 0)
+            return null;
+        if (matches.length > 1) {
+            const candidates = matches.map((w) => w.project_id).join(", ");
+            throw new Error(`Ambiguous project name tail "${nameTail}": matches ${matches.length} projects [${candidates}]. Use the full projectId instead.`);
+        }
+        return matches[0];
+    }
+    /**
+     * Remove a project: deletes workspace row + all symbol data (CASCADE).
+     * Does NOT clear the vector store — caller is responsible for that.
+     */
+    async removeWorkspace(projectId) {
+        await getSymbolRepository().clearProject(projectId);
+        logger.info("WorkspaceManager: workspace removed", { projectId });
+    }
+    // ── EventBus integration ──────────────────────────────────────────────────
+    subscribeToEvents() {
+        eventBus.subscribe("indexing:started", ({ projectId, projectPath }) => {
+            this.markIndexing(projectId, projectPath).catch((err) => logger.error("WorkspaceManager: failed to mark indexing", err, { projectId }));
+        });
+        eventBus.subscribe("indexing:completed", ({ projectId, filesIndexed, chunksIndexed, symbolsIndexed }) => {
+            this.markIndexed(projectId, {
+                filesCount: filesIndexed,
+                chunksCount: chunksIndexed,
+                symbolsCount: symbolsIndexed,
+            }).catch((err) => logger.error("WorkspaceManager: failed to mark indexed", err, { projectId }));
+        });
+        eventBus.subscribe("indexing:failed", ({ projectId, error }) => {
+            this.markError(projectId, error).catch((err) => logger.error("WorkspaceManager: failed to mark error", err, { projectId }));
+        });
+    }
+}
+export const workspaceManager = WorkspaceManager.getInstance();
+//# sourceMappingURL=workspace-manager.js.map

package/dist/services/workspace/workspace-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-manager.js","sourceRoot":"","sources":["../../../src/services/workspace/workspace-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAErF,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAIvE,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAC,QAAQ,GAA4B,IAAI,CAAC;IAExD;QACE,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC;YAC/B,gBAAgB,CAAC,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACrD,CAAC;QACD,OAAO,gBAAgB,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,8EAA8E;IAE9E;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,SAAiB,EAAE,WAAmB;QACvD,MAAM,IAAI,GAAG,mBAAmB,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QACpD,MAAM,IAAI,CAAC,eAAe,CAAC;YACzB,UAAU,EAAE,SAAS;YACrB,YAAY,EAAE,WAAW;YACzB,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE;YAC1C,MAAM,EAAE,UAAU;YAClB,WAAW,EAAE,QAAQ,EAAE,WAAW,IAAI,CAAC;YACvC,YAAY,EAAE,QAAQ,EAAE,YAAY,IAAI,CAAC;YACzC,aAAa,EAAE,QAAQ,EAAE,aAAa,IAAI,CAAC;YAC3C,UAAU,EAAE,QAAQ,EAAE,UAAU;SACjC,CAAC,CAAC;QAEH,QAAQ,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;QACzE,MAAM,CAAC,IAAI,CAAC,sCAAsC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,CACf,SAAiB,EACjB,KAAwE;QAExE,MAAM,mBAAmB,EAAE,CAAC,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE;YACtE,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE;YACzB,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;SACjC,CAAC,CAAC;QAEH,QAAQ,CAAC,OAAO,CAAC,mBAAmB,EAAE;YACpC,SAAS;YACT,MAAM,EAAE,SAAS;YACjB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,YAAY,EAAE,KAAK,CAAC,YAAY;SACjC,CAAC,CAAC;QAEH,qDAAqD;QACrD,kBAAkB;aACf,mBAAmB,CAAC,SAAS,CAAC;aAC9B,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACb,MAAM,CAAC,KAAK,CAAC,mDAAmD,EAAE,GAAY,EAAE,EAAE,SAAS,EAAE,CAAC,CAC/F,CAAC;QAEJ,MAAM,CAAC,IAAI,CAAC,qCAAqC,EAAE,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,SAAiB,EAAE,KAAa;QAC9C,MAAM,mBAAmB,EAAE,CAAC,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE;YACpE,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;QAEH,QAAQ,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QACtE,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,8EAA8E;IAE9E,KAAK,CAAC,cAAc,CAAC,YAAsC;QACzD,MAAM,GAAG,GAAG,MAAM,mBAAmB,EAAE,CAAC,cAAc,EAAE,CAAC;QACzD,IAAI,CAAC,YAAY,IAAI,YAAY,KAAK,KAAK;YAAE,OAAO,GAAG,CAAC;QACxD,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,SAAiB;QAClC,OAAO,mBAAmB,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,iBAAiB,CAAC,QAAgB;QACtC,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3B,MAAM,GAAG,GAAG,MAAM,mBAAmB,EAAE,CAAC,cAAc,EAAE,CAAC;QACzD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YAC/B,MAAM,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,YAAY,CAAC;YACnE,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC;QAC5D,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/D,MAAM,IAAI,KAAK,CACb,gCAAgC,QAAQ,cAAc,OAAO,CAAC,MAAM,cAAc,UAAU,oCAAoC,CACjI,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,SAAiB;QACrC,MAAM,mBAAmB,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,qCAAqC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,6EAA6E;IAErE,iBAAiB;QACvB,QAAQ,CAAC,SAAS,CAAC,kBAAkB,EAAE,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,EAAE;YACpE,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACtD,MAAM,CAAC,KAAK,CAAC,2CAA2C,EAAE,GAAY,EAAE,EAAE,SAAS,EAAE,CAAC,CACvF,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,QAAQ,CAAC,SAAS,CAAC,oBAAoB,EAAE,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,EAAE,EAAE;YACtG,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE;gBAC1B,UAAU,EAAE,YAAY;gBACxB,WAAW,EAAE,aAAa;gBAC1B,YAAY,EAAE,cAAc;aAC7B,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACf,MAAM,CAAC,KAAK,CAAC,0CAA0C,EAAE,GAAY,EAAE,EAAE,SAAS,EAAE,CAAC,CACtF,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,QAAQ,CAAC,SAAS,CAAC,iBAAiB,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE;YAC7D,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAC7C,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE,GAAY,EAAE,EAAE,SAAS,EAAE,CAAC,CACpF,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;;AAGH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,WAAW,EAAE,CAAC"}

package/dist/tools/batch_execute.d.ts

@@ -0,0 +1,64 @@
+/**
+ * batch_execute tool (ctx_batch_execute) — run N shell commands via run-pool.
+ *
+ * Order-preserving (results[i] ↔ commands[i]) and concurrency-capped. The
+ * controller delegates to runPool with the requested concurrency (default
+ * clamped by cpu count). Auto-indexing of outputs is optional and currently
+ * a no-op stub — the core value is parallel gather.
+ */
+import type { ToolResponse, IToolHandler } from "@massa-ai/shared";
+export interface BatchCommand {
+    command: string;
+}
+export interface BatchExecuteParams {
+    commands: string[];
+    queries?: string[];
+    timeout?: number;
+    concurrency?: number;
+    cwd?: string;
+    query_scope?: string;
+}
+export declare class BatchExecuteTool implements IToolHandler {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            commands: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            queries: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            timeout: {
+                type: string;
+                description: string;
+            };
+            concurrency: {
+                type: string;
+                description: string;
+            };
+            cwd: {
+                type: string;
+                description: string;
+            };
+            query_scope: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private run;
+    constructor(run: (params: BatchExecuteParams) => Promise<ToolResponse>);
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=batch_execute.d.ts.map

package/dist/tools/batch_execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch_execute.d.ts","sourceRoot":"","sources":["../../src/tools/batch_execute.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,gBAAiB,YAAW,YAAY;IACnD,IAAI,SAAmB;IACvB,WAAW,SAGiE;IAE5E,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiCT;IAEF,OAAO,CAAC,GAAG,CAAwD;gBAEvD,GAAG,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC,YAAY,CAAC;IAIhE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CAGrD"}

package/dist/tools/batch_execute.js

@@ -0,0 +1,55 @@
+/**
+ * batch_execute tool (ctx_batch_execute) — run N shell commands via run-pool.
+ *
+ * Order-preserving (results[i] ↔ commands[i]) and concurrency-capped. The
+ * controller delegates to runPool with the requested concurrency (default
+ * clamped by cpu count). Auto-indexing of outputs is optional and currently
+ * a no-op stub — the core value is parallel gather.
+ */
+export class BatchExecuteTool {
+    name = "batch_execute";
+    description = "Run N shell commands in parallel via run-pool (order-preserving, " +
+        "concurrency-capped). Returns per-command stdout/stderr/exitCode in input " +
+        "order. Default concurrency = cpu count; failures do not abort siblings.";
+    inputSchema = {
+        type: "object",
+        properties: {
+            commands: {
+                type: "array",
+                items: { type: "string" },
+                description: "Shell commands to run (order is preserved in results).",
+            },
+            queries: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional queries to scope auto-indexing of outputs (reserved; " +
+                    "currently a no-op stub).",
+            },
+            timeout: {
+                type: "number",
+                description: "Per-command timeout in ms (default 30000).",
+            },
+            concurrency: {
+                type: "number",
+                description: "Max in-flight commands (default = host cpu count).",
+            },
+            cwd: {
+                type: "string",
+                description: "Working directory (defaults to project root).",
+            },
+            query_scope: {
+                type: "string",
+                description: "Optional scope label for the batch (diagnostics only).",
+            },
+        },
+        required: ["commands"],
+    };
+    run;
+    constructor(run) {
+        this.run = run;
+    }
+    async handle(params) {
+        return this.run(params);
+    }
+}
+//# sourceMappingURL=batch_execute.js.map

package/dist/tools/batch_execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch_execute.js","sourceRoot":"","sources":["../../src/tools/batch_execute.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,MAAM,OAAO,gBAAgB;IAC3B,IAAI,GAAG,eAAe,CAAC;IACvB,WAAW,GACT,mEAAmE;QACnE,2EAA2E;QAC3E,yEAAyE,CAAC;IAE5E,WAAW,GAAG;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,QAAQ,EAAE;gBACR,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,wDAAwD;aACtE;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EACT,gEAAgE;oBAChE,0BAA0B;aAC7B;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,4CAA4C;aAC1D;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,oDAAoD;aAClE;YACD,GAAG,EAAE;gBACH,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,+CAA+C;aAC7D;YACD,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,wDAAwD;aACtE;SACF;QACD,QAAQ,EAAE,CAAC,UAAU,CAAC;KACvB,CAAC;IAEM,GAAG,CAAwD;IAEnE,YAAY,GAA0D;QACpE,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAe;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,MAA4B,CAAC,CAAC;IAChD,CAAC;CACF"}

package/dist/tools/compact_snapshot.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Compact Snapshot Tool
+ *
+ * MCP tool for building a reference-based compaction snapshot of the current
+ * session's observations. The snapshot is a bounded (<~2KB) table-of-contents
+ * with runnable search/recall calls — NOT inlined data. Zero information loss:
+ * raw events stay in the observation store; the snapshot just points to them.
+ *
+ * SESSION continuity, NOT task state. This is distinct from `create_checkpoint`
+ * (which versions TASK progress/decisions/files in PostgreSQL memories table). See
+ * `packages/core/src/services/SESSION-STATE.md` for the full reconciliation.
+ *
+ * Optionally persists the snapshot itself as an observation of category
+ * `compaction-snapshots` so it is available for future sessions.
+ */
+import { IToolHandler, ToolResponse } from "@massa-ai/shared";
+import { type ObservationStore } from "../data/memory/observation-repository.js";
+import { type AttributionResolverLike } from "../services/hooks/attribution-resolver.js";
+export interface CompactSnapshotToolOptions {
+    /** Injectable store (tests); defaults to the shared observation store. */
+    store?: ObservationStore;
+    /** Injectable attribution resolver (tests); defaults to the shared resolver. */
+    resolver?: AttributionResolverLike;
+}
+export declare class CompactSnapshotTool implements IToolHandler {
+    name: string;
+    private readonly storeOverride?;
+    private readonly resolverOverride?;
+    constructor(options?: CompactSnapshotToolOptions);
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            sessionId: {
+                type: string;
+                description: string;
+            };
+            projectId: {
+                type: string;
+                description: string;
+            };
+            persist: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            cwd: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handle(params: unknown): Promise<ToolResponse>;
+}
+//# sourceMappingURL=compact_snapshot.d.ts.map

package/dist/tools/compact_snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact_snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/compact_snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAU,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,0CAA0C,CAAC;AAElD,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,2CAA2C,CAAC;AASnD,MAAM,WAAW,0BAA0B;IACzC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC;AAED,qBAAa,mBAAoB,YAAW,YAAY;IACtD,IAAI,SAAsB;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAmB;IAClD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAA0B;gBAEhD,OAAO,GAAE,0BAA+B;IAIpD,WAAW,SAMgF;IAC3F,WAAW;;;;;;;;;;;;;;;;;;;;;;MAwBT;IAEI,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;CA0FrD"}