@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/e2b-orphan-reclaim.js

@@ -1,43 +1,10 @@
-/**
- * #242([3738] / design/242 v1)— E2B 孤儿沙盒回收。
- *
- * 病:server 进程崩溃(SIGKILL/OOM)后 core Runner 的 `destroy()` 不跑,E2B 沙盒按自己的
- * timeout 窗继续存活计费;崩溃循环下泄漏累积。create 侧的归属打标早已在
- * (`remote-env-e2b.ts` factory:metadata 带 sessionId/taskId,本批补 `semaManaged:"1"`);
- * 本模块是缺的另一半——回收腿。
- *
- * 判据(全部保守方向,**拿不准恒不杀**——回收是清理型能力,缺席判据=不动作,方向纪律见
- * memory `capability-probe-fail-direction`;误杀的代价是杀死一个活任务的手,漏杀的代价只是钱):
- *   a. `metadata.semaManaged !== "1"`         → 非我方铸造,provider 侧 query 过滤已排除;防御性重验。
- *   b. `metadata.taskId` 缺席                 → 病态形(factory 恒打标),不杀 + failOpen 留痕。
- *   c. run 行在场:
- *        LIVE 词(running/suspended/needs_review)→ 活,跳过;
- *        TERMINAL 词                           → 孤儿,kill;
- *        两表皆不中的词                        → 词表纪律(#157):不杀 + failOpen(新词先安全后收编)。
- *   d. 行不存在:
- *        startedAt 距今 < GRACE                → create→行落库窗口,跳过(防误杀新沙盒);
- *        ≥ GRACE                              → 真孤儿,kill(单库 fleet 方向下行跨副本可见)。
- *   e. `getRun` 抛错                          → 不杀 + failOpen(不知道 ≠ 孤儿)。
- *
- * v1 边界(design/242 §设计②,发车说明同步):跨部署**异库**共用一把 E2B key 的形不支持——
- * 别家沙盒的 taskId 在本库查不到行,超 GRACE 会被误杀;前置=每部署独立 E2B key(本就是推荐姿势)。
- * metadata 无跨重启稳定的部署标识可用(instanceId 每 boot 变,恰是要回收上一世代)是结构原因。
- *
- * kill 逐只 try/catch(一只失败不挡其余);list 整体失败由调用方(reaper throttled catch)兜底。
- */
 import { recordFailOpen } from "../observability/fail-open.js";
-/** create→run 行落库窗口的误杀护栏。非行为表态面,常量不设旋钮(理由:它只需要「远大于一次
- *  create+首写延迟、远小于沙盒 timeout 窗」,10min 对两端都有量级余量;错设它的运维事故面比
- *  它保护的窗口更大)。 */
 export const E2B_ORPHAN_GRACE_MS = 10 * 60 * 1000;
-/** factory 打进 metadata 的归属标(create 半场,remote-env-e2b.ts);值恒 "1"。 */
 export const SEMA_MANAGED_METADATA_KEY = "semaManaged";
-// 构造侧 satisfies 锚类型真源;容器声明 ReadonlySet<string> 让消费侧(窄读口的 status: string)直判。
 const LIVE_STATUSES = new Set(["running", "suspended", "needs_review"]);
 const TERMINAL_STATUSES = new Set(["completed", "blocked", "failed"]);
 const _statusesCovered = true;
 void _statusesCovered;
-/** 一轮回收(boot 一次 + reaper interval 周期共用)。list 抛错穿透给调用方(reaper catch 族)。 */
 export async function reclaimOrphanE2bSandboxes(deps) {
     const now = deps.now ?? Date.now;
     const graceMs = deps.graceMs ?? E2B_ORPHAN_GRACE_MS;
@@ -45,14 +12,12 @@ export async function reclaimOrphanE2bSandboxes(deps) {
     const sandboxes = await deps.provider.listManaged();
     for (const sbx of sandboxes) {
         summary.scanned++;
-        // a. 防御性重验(provider 装配侧已 query 过滤;fake/将来的宽 provider 不许绕过归属判别)。
         if (sbx.metadata[SEMA_MANAGED_METADATA_KEY] !== "1") {
             summary.skippedUnknown++;
             recordFailOpen("server.e2b.orphan-skip-unknown");
             continue;
         }
         const taskId = sbx.metadata.taskId;
-        // b. 病态形:factory 恒打 taskId(ctx.taskId 缺席时连 sessionId 都在而 taskId 不在)——不杀,留痕。
         if (!taskId) {
             summary.skippedUnknown++;
             recordFailOpen("server.e2b.orphan-skip-unknown");
@@ -62,7 +27,6 @@ export async function reclaimOrphanE2bSandboxes(deps) {
         try {
             const run = await deps.runs.getRun(taskId);
             if (run === undefined) {
-                // d. 无行:GRACE 内=create→落库窗口;超窗=真孤儿。
                 verdict = now() - sbx.startedAt.getTime() < graceMs ? "grace" : "kill";
             }
             else if (LIVE_STATUSES.has(run.status)) {
@@ -72,12 +36,10 @@ export async function reclaimOrphanE2bSandboxes(deps) {
                 verdict = "kill";
             }
             else {
-                // c. 词表外的新词:不杀 + failOpen(先安全后收编;收编=上面两表加词,遗漏在 census 计数可见)。
                 verdict = "unknown";
             }
         }
         catch {
-            // e. store 读错:不知道 ≠ 孤儿。
             verdict = "unknown";
         }
         if (verdict === "live")
@@ -105,19 +67,12 @@ export async function reclaimOrphanE2bSandboxes(deps) {
     }
     return summary;
 }
-/** provider RPC 墙钟上限。🔴 codex 对抗复审 R2(验真后修):无超时的 list/kill 一次 provider 挂起会让
- *  调用方的重入旗永挂(finally 等的 promise 永不结算)⇒ 回收腿从此静默死掉。SDK 原生收
- *  `requestTimeoutMs`(SandboxApiOpts),用它而非外包 race——超时语义留在 SDK 的连接层。 */
 const PROVIDER_RPC_TIMEOUT_MS = 30_000;
-/** 真实 provider(E2B SDK 包装)。SDK 静态面动态 import——回收腿只在 e2b 部署形挂载,
- *  非 e2b 形零加载(与 execution-env 的按需装配同姿势)。 */
 export function createE2bOrphanSandboxProvider(cfg) {
     return {
         async listManaged() {
             const { Sandbox } = await import("e2b");
             const out = [];
-            // 服务端 metadata 过滤(SandboxListOpts.query.metadata,AND 语义);state 默认含 running+paused
-            // ——paused 也计费存储位且同样是孤儿人群,刻意不收窄。
             const paginator = Sandbox.list({ apiKey: cfg.apiKey, requestTimeoutMs: PROVIDER_RPC_TIMEOUT_MS, query: { metadata: { [SEMA_MANAGED_METADATA_KEY]: "1" } } });
             while (paginator.hasNext) {
                 const items = await paginator.nextItems();

package/dist/plugins/file-outcome-sink.js

@@ -1,18 +1,9 @@
-/**
- * design/73 §1 consumption, LOCAL lane — the File twin of the TiDB/Pg outcome ledgers for the single-user /
- * no-DB posture: append each core `TaskOutcome` fact VERBATIM to an owner-only JSONL ledger. Read-only v1
- * (dashboard/backtest dataset — mirrors the SQL ledgers' read-only red line); no query surface here, the
- * file IS the dataset. Non-load-bearing observability → no fsync (a crash may lose the tail fact; the run
- * itself is unaffected — same posture as metrics).
- */
 import { mkdirSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 export class FileOutcomeSink {
     path;
     constructor(root) {
         const dir = join(root, "outcomes");
-        // 0o700 dir + 0o600 file: outcome facts carry model/taskSignature/oracle detail — operator-only, parity
-        // with the other File ledgers' posture.
         mkdirSync(dir, { recursive: true, mode: 0o700 });
         this.path = join(dir, "outcomes.jsonl");
     }

package/dist/plugins/file-resume-anchor-store.js

@@ -1,47 +1,23 @@
-/**
- * File-backed resume-at anchor map (E18) — the DURABLE local twin of {@link MemoryResumeAnchorStore}, persisting the
- * service-owned eventId→entryId translation across a process restart (P0.5 variant-1, clay 2026-06-26; the file-backed
- * follow-on the Memory twin's header promised). Behaviour is byte-identical to the Memory store (put/resolve/
- * deleteBySession + the §0.5/2c `listBySession` add); the only difference is durability.
- *
- * Persistence: one append-only JSONL log per session at `<root>/resume-anchors/<sanitizePathComponent(sessionId)>.jsonl`,
- * each line `{eventId, entryId, owner, ts}`. `put` APPENDS (fsync:true — an anchor is a durable rewind boundary; a lost
- * anchor silently breaks the next rewind), and the in-memory index is upserted last-wins so a re-stamped eventId
- * overwrites (parity with the SQL ON DUPLICATE/CONFLICT). On construction the index is HYDRATED by replaying every
- * session log via core's `readJsonlRecords` (torn-tail-safe: a crash mid-append drops only the partial last line, and a
- * later `put` re-records it). `resolve`/`listBySession` read the in-memory index (O(1)/O(per-session)); `deleteBySession`
- * unlinks the file + drops the index entry. owner null-safe guard (`(a??null)===(b??null)`) = the SQL `owner <=> ?`
- * defense-in-depth twin. Single-process (the FileStorageBackend boot lock guarantees one writer per data dir), so there
- * is no per-op lock — the in-process model is the premise (core fs-atomic BootLock).
- */
 import { join } from "node:path";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { AppendLog, ensureDir, readJsonlRecords, sanitizePathComponent } from "@sema-agent/core";
-/** Null-safe owner equality — the JS twin of the SQL `owner <=> ?` guard (a legacy null-owner anchor matches owner=null). */
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 export class FileResumeAnchorStore {
     dir;
-    /** sessionId → (eventId → {entryId, owner}) — the same in-memory shape MemoryResumeAnchorStore holds, hydrated on ctor. */
     bySession = new Map();
-    /** sessionId → the open append log (one O_APPEND fd per session, lazily opened on first put, held for lifetime). */
     logs = new Map();
     constructor(root) {
         this.dir = join(root, "resume-anchors");
         ensureDir(this.dir);
         this.hydrate();
     }
-    /** `<dir>/<sanitizePathComponent(sessionId)>.jsonl` — the per-session log path (sessionId is uuidv7, already safe). */
     pathFor(sessionId) {
         return join(this.dir, `${sanitizePathComponent(sessionId)}.jsonl`);
     }
-    /** Replay every session log into the in-memory index on boot (torn-tail-safe via readJsonlRecords; last-wins upsert
-     *  so a re-stamped eventId reflects the latest appended record). The in-memory index is keyed by the SANITIZED
-     *  sessionId throughout (put/resolve/list/delete all sanitize), and each on-disk file's base name IS
-     *  `sanitizePathComponent(sessionId)` — so the index key is just the file base, with no de-sanitize needed. */
     hydrate() {
         let names;
         try {
-            names = readdirSync(this.dir); // a fresh root has the (just-ensured) empty dir → []
+            names = readdirSync(this.dir);
         }
         catch {
             return;
@@ -49,20 +25,19 @@ export class FileResumeAnchorStore {
         for (const name of names) {
             if (!name.endsWith(".jsonl"))
                 continue;
-            const key = name.slice(0, -".jsonl".length); // the file base IS sanitizePathComponent(sessionId) = the index key
+            const key = name.slice(0, -".jsonl".length);
             const records = readJsonlRecords(join(this.dir, name));
             if (!records.length)
                 continue;
             const m = this.bySession.get(key) ?? new Map();
             for (const r of records) {
                 if (!r || typeof r.eventId !== "string" || typeof r.entryId !== "string")
-                    continue; // skip a malformed record
-                m.set(r.eventId, { entryId: r.entryId, owner: r.owner ?? null }); // last-wins upsert (replay order = append order)
+                    continue;
+                m.set(r.eventId, { entryId: r.entryId, owner: r.owner ?? null });
             }
             this.bySession.set(key, m);
         }
     }
-    /** Open (or reuse) the append log for a session. The file base is the SANITIZED id (matches hydrate's de-sanitize). */
     logFor(sessionId) {
         const key = sanitizePathComponent(sessionId);
         let log = this.logs.get(key);
@@ -72,9 +47,6 @@ export class FileResumeAnchorStore {
         }
         return log;
     }
-    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert; parity with the SQL
-     *  ON DUPLICATE/CONFLICT). Appends a durable record (fsync:true) THEN upserts the index — a crash after the
-     *  fsync is recovered by hydrate (the record is on disk); a crash before it just loses an un-acked anchor. */
     async put(sessionId, eventId, entryId, owner) {
         const key = sanitizePathComponent(sessionId);
         this.logFor(sessionId).append({ eventId, entryId, owner: owner ?? null, ts: new Date().toISOString() }, true);
@@ -85,15 +57,10 @@ export class FileResumeAnchorStore {
         }
         m.set(eventId, { entryId, owner });
     }
-    /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id for TaskSpec.resumeAt; undefined = unknown
-     *  anchor (the route 4xx's before handing core a bad id). owner null-safe guard = the SQL `owner <=> ?` defense-in-depth. */
     async resolve(sessionId, eventId, owner) {
         const e = this.bySession.get(sanitizePathComponent(sessionId))?.get(eventId);
         return e && ownerEq(e.owner, owner) ? e.entryId : undefined;
     }
-    /** 2c session-sync: ALL anchors for a session (every eventId→entryId + its owner), UNFILTERED — a cross-backend
-     *  session EXPORT bundles the whole anchor map so the importer can RE-KEY owner to the target principal (§9). The
-     *  route already proved session ownership (the export gate), so no per-row owner filter here. Twin of the SQL stores. */
     async listBySession(sessionId) {
         const m = this.bySession.get(sanitizePathComponent(sessionId));
         if (!m)
@@ -103,9 +70,6 @@ export class FileResumeAnchorStore {
             out.push({ eventId, entryId: e.entryId, owner: e.owner });
         return out;
     }
-    /** E21 (§0.5 delete) — purge ALL anchors for a session, scoped by session_id ALONE (the route already proved session
-     *  ownership; a per-row owner guard would orphan rows stored under a divergent per-run principal). Idempotent (count).
-     *  Closes + unlinks the session log so the dir does not leak a file, and drops the in-memory index entry. */
     async deleteBySession(sessionId) {
         const key = sanitizePathComponent(sessionId);
         const removed = this.bySession.get(key)?.size ?? 0;
@@ -121,19 +85,16 @@ export class FileResumeAnchorStore {
                 rmSync(path, { force: true });
             }
             catch {
-                /* best-effort — a stale file is harmless (the index entry is already gone) */
             }
         }
         return removed;
     }
-    /** Release every open append-log fd (called by LocalBackend.close so a graceful restart can re-open the data dir). */
     dispose() {
         for (const log of this.logs.values()) {
             try {
                 log.close();
             }
             catch {
-                /* best-effort */
             }
         }
         this.logs.clear();