@evandu/super-pi 0.1.146 → 0.1.148

package/dist/server/application/session-watchdog.js

@@ -0,0 +1,244 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** The file name the state lives under, inside the workspace's `.super-pi` directory. */
+export const WATCHDOG_STATE_FILE = "watchdogs.json";
+/** The longest silence a parent may declare: a day. Beyond that it is not a watchdog, it is a plan. */
+export const WATCHDOG_MAX_TIMEOUT_SECONDS = 86_400;
+/** The shortest silence a parent may declare. One second is a test's value, not a parent's. */
+export const WATCHDOG_MIN_TIMEOUT_SECONDS = 1;
+/**
+ * The watchdog manager: the timers, the state, and the state file.
+ *
+ * ONE WATCHDOG PER CHILD. The parent declares a duration for a child, and the duration belongs to that
+ * child - not to the pair of sessions in general - because "how long may this child be quiet" is a
+ * property of that child, and the parent may well declare different expectations for different children.
+ */
+export class SessionWatchdog {
+    host;
+    entries = new Map();
+    timers = new Map();
+    /** One write chain per workspace, so two watchdogs in one workspace cannot interleave a write. */
+    writes = new Map();
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Declares (or re-declares) the watchdog for a child.
+     *
+     * `timeoutSeconds` of 0 CANCELS the watchdog: "I am no longer waiting for a report from this one".
+     * That is the only way a parent takes the expectation back, and it is deliberately explicit - a
+     * watchdog that quietly switched itself off would leave the parent believing it was still watched.
+     */
+    async arm(input) {
+        const { childConversationId } = input;
+        if (!childConversationId.trim())
+            return;
+        this.clearTimer(childConversationId);
+        if (!Number.isFinite(input.timeoutSeconds) || input.timeoutSeconds <= 0) {
+            // CANCEL. The entry is removed and the file rewritten, so a cancelled watchdog stays cancelled
+            // across a restart.
+            if (this.entries.delete(childConversationId))
+                await this.persist(input.workspaceId);
+            return;
+        }
+        const timeoutSeconds = Math.min(WATCHDOG_MAX_TIMEOUT_SECONDS, Math.max(WATCHDOG_MIN_TIMEOUT_SECONDS, Math.floor(input.timeoutSeconds)));
+        const entry = {
+            childConversationId,
+            parentConversationId: input.parentConversationId,
+            workspaceId: input.workspaceId,
+            timeoutSeconds,
+            lastSignalAt: Date.now(),
+            endedReminded: false,
+        };
+        this.entries.set(childConversationId, entry);
+        await this.persist(input.workspaceId);
+        this.schedule(entry);
+    }
+    /**
+     * Records a sign of life: the child reported, so the clock starts again.
+     *
+     * A REPORT RESETS THE CLOCK, IT DOES NOT CANCEL THE WATCHDOG. The parent asked to hear from this
+     * child while the child was working; a report that says "the first stage is done, I am continuing"
+     * must not be read as "the work is over". Cancelling on the first report would turn the watchdog into
+     * a one-shot device, and the whole point of the parent's declaration is that it holds for as long as
+     * the child is out of sight.
+     */
+    async noteSignal(childConversationId) {
+        const entry = this.entries.get(childConversationId);
+        if (!entry)
+            return;
+        entry.lastSignalAt = Date.now();
+        entry.endedReminded = false;
+        this.clearTimer(childConversationId);
+        this.schedule(entry);
+        await this.persist(entry.workspaceId);
+    }
+    /** Takes the watchdog away. The parent is no longer waiting. */
+    async cancel(childConversationId) {
+        const entry = this.entries.get(childConversationId);
+        this.clearTimer(childConversationId);
+        if (!entry)
+            return;
+        this.entries.delete(childConversationId);
+        await this.persist(entry.workspaceId);
+    }
+    /** The watchdogs that are currently armed. */
+    list() {
+        return [...this.entries.values()].map((entry) => ({ ...entry }));
+    }
+    /** The watchdog on one child, if there is one. */
+    get(childConversationId) {
+        const entry = this.entries.get(childConversationId);
+        return entry ? { ...entry } : undefined;
+    }
+    /**
+     * Re-arms the watchdogs that were on disk when the server stopped.
+     *
+     * A watchdog whose silence had ALREADY run out while the server was down fires as soon as it comes
+     * back: the parent asked to be told after N minutes of silence, and the silence did happen. The
+     * remaining time is measured from the last sign of life, not from the restart.
+     */
+    async restore() {
+        for (const workspaceId of this.host.workspaceIds()) {
+            const path = this.statePath(workspaceId);
+            if (!path)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(await readFile(path, "utf8"));
+            }
+            catch {
+                // A missing file is the normal case (no watchdog was ever declared). A corrupt one is not
+                // fatal either: the worst case of losing it is that the parent stops being reminded, which
+                // is the state it was in before this feature existed.
+                continue;
+            }
+            const records = parsed?.watchdogs;
+            if (!records || typeof records !== "object")
+                continue;
+            for (const [childConversationId, record] of Object.entries(records)) {
+                if (!record || typeof record.timeoutSeconds !== "number" || !record.parentConversationId)
+                    continue;
+                const entry = {
+                    childConversationId,
+                    parentConversationId: record.parentConversationId,
+                    workspaceId: record.workspaceId ?? workspaceId,
+                    timeoutSeconds: record.timeoutSeconds,
+                    lastSignalAt: typeof record.lastSignalAt === "number" ? record.lastSignalAt : Date.now(),
+                    endedReminded: Boolean(record.endedReminded),
+                };
+                this.entries.set(childConversationId, entry);
+                this.schedule(entry);
+            }
+        }
+    }
+    /** Stops every timer. The process is going away; the state stays on disk. */
+    dispose() {
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+    }
+    /**
+     * Arms the timer for one entry.
+     *
+     * THE TIMER IS UNREF'D. A pending reminder must not keep the Node process alive: the server is
+     * allowed to shut down with a watchdog in flight, and the state is on disk anyway.
+     */
+    schedule(entry) {
+        this.clearTimer(entry.childConversationId);
+        const elapsed = Date.now() - entry.lastSignalAt;
+        const remaining = Math.max(0, entry.timeoutSeconds * 1000 - elapsed);
+        const timer = setTimeout(() => {
+            void this.fire(entry.childConversationId);
+        }, remaining);
+        timer.unref?.();
+        this.timers.set(entry.childConversationId, timer);
+    }
+    clearTimer(childConversationId) {
+        const timer = this.timers.get(childConversationId);
+        if (timer)
+            clearTimeout(timer);
+        this.timers.delete(childConversationId);
+    }
+    /**
+     * The clock ran out.
+     *
+     * THE CHILD'S STATE DECIDES WHETHER THIS IS A REPEAT, AND THE REPEAT IS NOT LOUDER - IT IS THE
+     * SAME. Every interval the parent gets the same reminder, because the parent's need is the same:
+     * "I still have no news". An interval that grew would make the watchdog quietest exactly when the
+     * child has been silent longest, which is backwards.
+     *
+     * THE ONE EXCEPTION IS A CHILD THAT IS NO LONGER WORKING. A child whose turn ended without reporting
+     * is not going to report: the turn is over. The parent is told once that the child has gone quiet
+     * AND stopped, and the watchdog then takes itself off - a reminder that repeats for a child that
+     * cannot speak any more is noise, not information.
+     */
+    async fire(childConversationId) {
+        const entry = this.entries.get(childConversationId);
+        if (!entry)
+            return;
+        const childWorking = this.host.isChildWorking(childConversationId);
+        if (!childWorking && entry.endedReminded) {
+            await this.cancel(childConversationId);
+            return;
+        }
+        const elapsedSeconds = Math.max(0, Math.round((Date.now() - entry.lastSignalAt) / 1000));
+        try {
+            await this.host.onTimeout({
+                childConversationId,
+                parentConversationId: entry.parentConversationId,
+                timeoutSeconds: entry.timeoutSeconds,
+                elapsedSeconds,
+                childWorking,
+            });
+        }
+        catch (error) {
+            this.host.warn?.(`Super Pi: watchdog reminder for ${childConversationId} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        entry.endedReminded = !childWorking;
+        entry.lastSignalAt = Date.now();
+        await this.persist(entry.workspaceId);
+        this.schedule(entry);
+    }
+    /** The path of one workspace's state file, or undefined when the workspace is unknown. */
+    statePath(workspaceId) {
+        const workspacePath = this.host.workspacePath(workspaceId);
+        if (!workspacePath)
+            return undefined;
+        return join(workspacePath, ".super-pi", WATCHDOG_STATE_FILE);
+    }
+    /**
+     * Writes one workspace's state file.
+     *
+     * THE WRITES ARE SERIALIZED PER WORKSPACE. Two watchdogs in one workspace each rewrite the same
+     * file, and an interleaved pair of writes would leave a file that describes one watchdog twice and
+     * loses the other.
+     */
+    async persist(workspaceId) {
+        const path = this.statePath(workspaceId);
+        if (!path)
+            return;
+        const previous = this.writes.get(workspaceId) ?? Promise.resolve();
+        const next = previous.then(() => this.writeStateFile(path, workspaceId)).catch((error) => {
+            this.host.warn?.(`Super Pi: watchdog state could not be written: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        this.writes.set(workspaceId, next);
+        await next;
+    }
+    async writeStateFile(path, workspaceId) {
+        const watchdogs = {};
+        for (const entry of this.entries.values()) {
+            if (entry.workspaceId !== workspaceId)
+                continue;
+            watchdogs[entry.childConversationId] = {
+                parentConversationId: entry.parentConversationId,
+                workspaceId: entry.workspaceId,
+                timeoutSeconds: entry.timeoutSeconds,
+                lastSignalAt: entry.lastSignalAt,
+                endedReminded: entry.endedReminded,
+            };
+        }
+        await mkdir(join(path, ".."), { recursive: true });
+        await writeFile(path, `${JSON.stringify({ version: 1, watchdogs }, null, 2)}\n`, "utf8");
+    }
+}

package/dist/server/http-server.js

@@ -25,6 +25,7 @@ import { packageUpdateArgs } from "./update.js";
 import { FileIndex } from "./file-index.js";
 import { ensureNameIndex, recordWorkspacePath } from "./file-name-index.js";
 import { resolveSessionCwd, sessionScopeKey, workspacePathFromSession } from "./session-cwd.js";
+import { verifyDirectChildScope, verifyListParentScope, verifyReportTargetScope, verifySpawnParentScope } from "./session-tree-scope.js";
 import { MAX_CONTENT_DEPTH, MAX_CONTENT_FILE_BYTES, MAX_CONTENT_RESULTS, searchByContent } from "./content-search.js";
 import { getAvailableSkills, readSkill } from "./skills.js";
 /**
@@ -1501,11 +1502,26 @@ export function createHttpServer(options) {
                             });
                             return;
                         }
+                        // THE PARENT EDGE IS NOT THE CALLER'S TO CHOOSE. `parentConversationId` is written onto the
+                        // new conversation at birth, and the child's result callback follows that edge home. A
+                        // caller that named somebody ELSE as the parent would rewrite that session's reporting
+                        // line - the victim's result would land in the caller's inbox - so the parent must be the
+                        // caller. An empty parent means a top-level session, which is what the user's own "+"
+                        // creates and what a session with no owner legitimately is.
+                        const parentScope = verifySpawnParentScope({
+                            store: context.store,
+                            callerConversationId,
+                            requestedParentId: body.parentConversationId,
+                        });
+                        if (!parentScope.ok) {
+                            json(parentScope.status, { error: parentScope.error });
+                            return;
+                        }
                         if (!body.task)
                             throw new Error("spawn requires task");
                         const result = await service.spawn({
                             task: body.task,
-                            parentConversationId: body.parentConversationId,
+                            parentConversationId: body.parentConversationId?.trim() || undefined,
                             workspaceId: requestedWorkspaceId,
                             title: body.title,
                             agentId: body.agentId,
@@ -1514,38 +1530,39 @@ export function createHttpServer(options) {
                             initialPrompt: body.initialPrompt,
                             wait: body.wait,
                             cwd: body.cwd,
+                            watchdogTimeoutSeconds: body.watchdogTimeoutSeconds ?? body.watchdog_timeout_seconds ?? body.watchdogSeconds,
                         });
                         json(200, { ok: true, ...result });
                         return;
                     }
-                    const verifyTargetScope = (targetConversationId) => {
-                        const store = context.store;
-                        const callerWorkspaceId = store && callerConversationId
-                            ? store.conversation(callerConversationId)?.workspaceId
-                            : undefined;
-                        if (!callerWorkspaceId) {
-                            return {
-                                ok: false,
-                                error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。`,
-                            };
-                        }
-                        const target = store?.conversation(targetConversationId);
-                        if (target && target.workspaceId !== callerWorkspaceId) {
-                            return {
-                                ok: false,
-                                error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，目标会话 ${targetConversationId} 所在工作区为 ${target.workspaceId}，拒绝跨工作区操作。目标会话必须属于调用方工作区。`,
-                            };
-                        }
-                        return { ok: true };
-                    };
+                    // THE SCOPE RULE, IN ONE PLACE, FOR EVERY ACTION THAT TOUCHES ANOTHER SESSION.
+                    //
+                    // A session may only manage its DIRECT children: the target's `parentConversationId` must be
+                    // the caller itself. Not a grandchild (that is a level away), not a peer (that is somebody
+                    // else's branch), not an ancestor (that is above), not a session in another workspace (that
+                    // is another department). A workspace is not an organisation chart.
+                    //
+                    // WHY IT IS ONE LINE. The tree edge lives on the conversation itself, so "is this my child?"
+                    // is a comparison, not a walk. The walk up the chain exists only to write a refusal that says
+                    // WHY - it never decides anything.
+                    //
+                    // WHY IT MATTERS. The result callback of a dispatched session goes back to the session that
+                    // owns it, so "who gave the order is who gets the report" holds by construction instead of by
+                    // a second mechanism that could drift.
+                    const verifyTargetScope = (targetConversationId, verb) => verifyDirectChildScope({
+                        store: context.store,
+                        callerConversationId,
+                        targetConversationId,
+                        verb,
+                    });
                     if (action === "dispatch") {
                         if (!body.conversationId)
                             throw new Error("dispatch requires conversationId");
                         if (!body.content)
                             throw new Error("dispatch requires content");
-                        const scope = verifyTargetScope(body.conversationId);
+                        const scope = verifyTargetScope(body.conversationId, "调度");
                         if (!scope.ok) {
-                            json(403, { error: scope.error });
+                            json(scope.status, { error: scope.error });
                             return;
                         }
                         const result = await service.dispatch(body.conversationId, body.content, { wait: body.wait });
@@ -1555,9 +1572,9 @@ export function createHttpServer(options) {
                     if (action === "status") {
                         if (!body.conversationId)
                             throw new Error("status requires conversationId");
-                        const scope = verifyTargetScope(body.conversationId);
+                        const scope = verifyTargetScope(body.conversationId, "读取");
                         if (!scope.ok) {
-                            json(403, { error: scope.error });
+                            json(scope.status, { error: scope.error });
                             return;
                         }
                         const summary = await service.status(body.conversationId, { includeOutput: body.includeOutput });
@@ -1565,26 +1582,22 @@ export function createHttpServer(options) {
                         return;
                     }
                     if (action === "list") {
-                        const store = context.store;
-                        const callerWorkspaceId = store && callerConversationId
-                            ? store.conversation(callerConversationId)?.workspaceId
-                            : undefined;
-                        if (!callerWorkspaceId) {
-                            json(403, { error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。` });
+                        // LISTING IS SCOPED TOO. The parent whose children are listed must be the caller itself,
+                        // so the only sessions on the list are the caller's own direct children. Listing the
+                        // children of the caller's own child would be listing grandchildren - the same cross-level
+                        // reach every other action refuses.
+                        const listScope = verifyListParentScope({
+                            store: context.store,
+                            callerConversationId,
+                            requestedParentId: body.parentConversationId,
+                        });
+                        if (!listScope.ok) {
+                            json(listScope.status, { error: listScope.error });
                             return;
                         }
-                        const requestedParentId = body.parentConversationId?.trim();
-                        if (requestedParentId) {
-                            const targetParent = store?.conversation(requestedParentId);
-                            if (targetParent && targetParent.workspaceId !== callerWorkspaceId) {
-                                json(403, {
-                                    error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，请求的父会话 ${requestedParentId} 所在工作区为 ${targetParent.workspaceId}，拒绝跨工作区查询。父会话必须属于调用方工作区。`,
-                                });
-                                return;
-                            }
-                        }
-                        const effectiveParentId = requestedParentId || callerConversationId;
+                        const effectiveParentId = body.parentConversationId?.trim() || callerConversationId;
                         const sessions = await service.list(effectiveParentId);
+                        const callerWorkspaceId = context.store.conversation(callerConversationId)?.workspaceId;
                         const allowedSessions = sessions.filter((s) => !s.workspaceId || s.workspaceId === callerWorkspaceId);
                         json(200, { ok: true, sessions: allowedSessions });
                         return;
@@ -1592,9 +1605,9 @@ export function createHttpServer(options) {
                     if (action === "stop") {
                         if (!body.conversationId)
                             throw new Error("stop requires conversationId");
-                        const scope = verifyTargetScope(body.conversationId);
+                        const scope = verifyTargetScope(body.conversationId, "停止");
                         if (!scope.ok) {
-                            json(403, { error: scope.error });
+                            json(scope.status, { error: scope.error });
                             return;
                         }
                         const result = await service.stop(body.conversationId, { mode: body.mode, messageId: body.messageId });
@@ -1604,15 +1617,73 @@ export function createHttpServer(options) {
                     if (action === "resume") {
                         if (!body.conversationId)
                             throw new Error("resume requires conversationId");
-                        const scope = verifyTargetScope(body.conversationId);
+                        const scope = verifyTargetScope(body.conversationId, "恢复");
                         if (!scope.ok) {
-                            json(403, { error: scope.error });
+                            json(scope.status, { error: scope.error });
                             return;
                         }
                         const result = await service.resume(body.conversationId, body.prompt, { wait: body.wait });
                         json(200, { ok: true, ...result });
                         return;
                     }
+                    if (action === "report") {
+                        if (!callerConversationId) {
+                            json(400, { error: "汇报操作缺少调用方会话标识" });
+                            return;
+                        }
+                        const callerConv = context.store.conversation(callerConversationId);
+                        if (!callerConv) {
+                            json(400, { error: `找不到会话：${callerConversationId}` });
+                            return;
+                        }
+                        if (!callerConv.parentConversationId) {
+                            json(400, { error: `会话 ${callerConversationId} 没有直属父会话，无法汇报` });
+                            return;
+                        }
+                        const targetId = body.targetConversationId ?? callerConv.parentConversationId;
+                        const scope = verifyReportTargetScope({
+                            store: context.store,
+                            callerConversationId,
+                            targetConversationId: targetId,
+                        });
+                        if (!scope.ok) {
+                            json(scope.status, { error: scope.error });
+                            return;
+                        }
+                        if (body.content === undefined || body.content === null) {
+                            json(400, { error: "report requires content" });
+                            return;
+                        }
+                        const result = await service.report(callerConversationId, {
+                            content: String(body.content),
+                            status: body.status,
+                        });
+                        json(200, { ok: true, ...result });
+                        return;
+                    }
+                    if (action === "watchdog") {
+                        if (!body.conversationId)
+                            throw new Error("watchdog requires conversationId");
+                        const scope = verifyTargetScope(body.conversationId, "看护");
+                        if (!scope.ok) {
+                            json(scope.status, { error: scope.error });
+                            return;
+                        }
+                        const subaction = body.subaction ?? "arm";
+                        if (subaction === "cancel") {
+                            const result = await service.cancelWatchdog(body.conversationId);
+                            json(200, { ...result, ok: true });
+                            return;
+                        }
+                        const timeoutSeconds = Number(body.timeoutSeconds ?? body.timeout_seconds ?? 300);
+                        const result = await service.setWatchdog({
+                            childConversationId: body.conversationId,
+                            parentConversationId: callerConversationId,
+                            timeoutSeconds,
+                        });
+                        json(200, { ...result, ok: true });
+                        return;
+                    }
                     json(400, { error: `不支持的编排操作：${action}` });
                 }
                 catch (error) {
@@ -1672,20 +1743,15 @@ export function createHttpServer(options) {
                     return;
                 }
                 const store = context.store;
-                const callerWorkspaceId = store && callerConversationId
-                    ? store.conversation(callerConversationId)?.workspaceId
-                    : undefined;
-                if (!callerWorkspaceId) {
-                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
-                        error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。`,
-                    }));
-                    return;
-                }
-                const target = store?.conversation(conversationId);
-                if (target && target.workspaceId !== callerWorkspaceId) {
-                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
-                        error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，目标会话 ${conversationId} 所在工作区为 ${target.workspaceId}，拒绝跨工作区操作。目标会话必须属于调用方工作区。`,
-                    }));
+                // THE SAME SCOPE RULE AS THE POST ACTION: the target must be the caller's DIRECT child.
+                const scope = verifyDirectChildScope({
+                    store,
+                    callerConversationId,
+                    targetConversationId: conversationId,
+                    verb: "读取",
+                });
+                if (!scope.ok) {
+                    response.writeHead(scope.status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: scope.error }));
                     return;
                 }
                 try {
@@ -1715,24 +1781,18 @@ export function createHttpServer(options) {
                     return;
                 }
                 const store = context.store;
-                const callerWorkspaceId = store && callerConversationId
-                    ? store.conversation(callerConversationId)?.workspaceId
-                    : undefined;
-                if (!callerWorkspaceId) {
-                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
-                        error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。`,
-                    }));
+                // THE SAME SCOPE RULE AS THE POST ACTION: the parent whose children are listed must be the
+                // caller itself, so only the caller's own direct children can come back.
+                const listScope = verifyListParentScope({
+                    store,
+                    callerConversationId,
+                    requestedParentId: parentId,
+                });
+                if (!listScope.ok) {
+                    response.writeHead(listScope.status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: listScope.error }));
                     return;
                 }
-                if (parentId) {
-                    const targetParent = store?.conversation(parentId);
-                    if (targetParent && targetParent.workspaceId !== callerWorkspaceId) {
-                        response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
-                            error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，请求的父会话 ${parentId} 所在工作区为 ${targetParent.workspaceId}，拒绝跨工作区查询。父会话必须属于调用方工作区。`,
-                        }));
-                        return;
-                    }
-                }
+                const callerWorkspaceId = store.conversation(callerConversationId)?.workspaceId;
                 try {
                     const effectiveParentId = parentId || callerConversationId;
                     const sessions = await service.list(effectiveParentId);

package/dist/server/index.js

@@ -291,6 +291,9 @@ runService.setExecService(execService);
 const scheduledTaskService = new ScheduledTaskService(store, runService, conversationService, broadcaster);
 const sessionLedger = new SessionLedger();
 const sessionOrchestratorService = new SessionOrchestratorService(store, conversationService, runService, sessionLedger, broadcaster);
+void sessionOrchestratorService.restoreWatchdogs().catch((error) => {
+    console.warn("Super Pi: restoring watchdogs failed:", error instanceof Error ? error.message : String(error));
+});
 const serverContext = {
     memory,
     knowledge,

package/dist/server/knowledge-vectors.d.ts

@@ -21,6 +21,8 @@ export declare const KNOWLEDGE_MODEL = "Xenova/bge-small-zh-v1.5";
  * is written in.
  */
 export declare const EMBED_PIECE_CHARS = 300;
+/** Per query. Cosine similarity of unit vectors; threshold raised to 0.35 to filter out semantic noise. */
+export declare const MIN_COSINE = 0.35;
 export type VectorRecord = {
     chunk: number;
     values: number[];
@@ -32,6 +34,8 @@ export type VectorStatus = {
     indexed: number;
     error?: string;
     bundled?: boolean;
+    health?: "ready" | "degraded" | "restarting" | "disabled";
+    available?: boolean;
 };
 /**
  * Splits a retrieval chunk into pieces small enough for the model's window.
@@ -64,6 +68,11 @@ export declare class VectorIndex {
     private workerReady;
     private workerPending;
     private failure?;
+    private consecutiveFailures;
+    private lastFailureTime;
+    private static readonly MAX_FAILURES;
+    private static readonly COOLDOWN_MS;
+    private static readonly EMBED_TIMEOUT_MS;
     private cache;
     private pending;
     private queue;
@@ -92,9 +101,15 @@ export declare class VectorIndex {
      * able to reach, on the first search, for every person who installed the package. Shipping the
      * weights turns a failure mode into a file, and makes the feature work on a machine that has never
      * been online since it was installed.
+     *
+     * RESILIENT WORKER LIFECYCLE:
+     * When the worker encounters an error, crash, or unexpected exit, it cleans up all pending requests
+     * without hanging and marks the instance for automatic, on-demand respawning on the next embed call.
+     * A bounded backoff / cooldown prevents runaway crash loops if the environment is broken.
      */
     private ensureWorker;
     private embed;
+    terminate(): Promise<void>;
     /** Vectors already stored for one workspace, keyed by document then chunk index. */
     private read;
     count(workspaceId: string): Promise<number>;