@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/scheduler-support.js

@@ -1,28 +1,3 @@
-/**
- * src/plugins/scheduler-support.ts — the server-side `SchedulerCapability` backend (R7 self-wake).
- *
- * core 1.165.0 ships the `SchedulerCapability` seam (design/105): core 出接口 + 工具壳 (现名 CronCreate/CronDelete/
- * CronList——L8 订正:CronCancel 旧名、Sleep 已 design/136 撤除、挂载在 core prepare-task 非 createHandsToolkit,
- * `hasScheduler(env)` 门不变) + the `hasScheduler` gate. **持久化 /
- * cron 时钟 / idle 触发 / 起新 task 全在 backend** — core is request-driven, not resident. R7 splits the backend:
- *   - THIS file (server) = the SchedulerCapability impl: the WRITE side — schedule/cancel/list, persisted to the
- *     SHARED on-disk store. Injected into `RemoteHostExecutionEnv` (the TOC host lane). deps `@sema-agent/core` (fine
- *     server-side).
- *   - The TOC shell `SchedulerDaemon` (shell-host, design R7 part3b) = the READ side: a resident process that
- *     polls the SAME store, resolves cron, fires due intents via the SDK (principal pinned), and reaps.
- *
- * The shared on-disk FORMAT is the dep-free `@sema-agent/registry-core/scheduler-store` contract; the fs binding is
- * `@sema-agent/registry-core/node`. server (writer) + shell daemon (reader) share ONE impl ⇒ zero format drift.
- *
- * Logic ported from the shell-host's canonical `scheduler/schedulerBackend.ts` (design doc
- * `R7-scheduler-rewind.md` §1: the server reuses the same schedulerBackend logic verbatim).
- *
- * 🔴 红线 (design/105): `principal` is `ctx` (Runner-held) NOT `intent` (model-controllable) → pinned into the
- * record, passed through to runTask unchanged by the daemon (no privilege escalation). cron via core
- * `isValidCronExpr` (no shell-exec / RCE). scope isolation: cancel/list touch only the caller's scope. durable:
- * the store is on disk (survives a daemon restart). upsert: same (scope, when, label) overwrites (idempotent on a
- * tool retry).
- */
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { randomBytes, createHash } from "node:crypto";
@@ -30,27 +5,15 @@ import { SchedulerError, isValidCronExpr } from "@sema-agent/core";
 import { loadSchedulerStore, saveSchedulerStore } from "@sema-agent/registry-core/node";
 const ok = (value) => ({ ok: true, value });
 const err = (error) => ({ ok: false, error });
-/** Default caps (fail-closed bounds; design/105 §3.9). Override per deployment. */
 export const DEFAULT_SCHEDULER_CAPS = {
     supported: true,
     maxScheduledPerScope: 32,
     minDelaySec: 10,
     minCronIntervalSec: 60,
-    maxScheduledHorizonSec: 60 * 60 * 24 * 30, // 30d
-    // core 1.301 CronCreate durable/session 分层 ([950]): session-scoped jobs are persisted with
-    // lifetime:"session" and reaped by the resident shell daemon when the session ends. True here because
-    // this backend faithfully persists the lifetime field (schedule() below) — without the flag core's
-    // CronCreate refuses durable:false up front (fail-closed at the tool layer).
+    maxScheduledHorizonSec: 60 * 60 * 24 * 30,
     supportsSessionLifetime: true,
-    // core 1.309 ([1000]③ ScheduleWakeup 治本位): true = a resident daemon reads this store and fires
-    // session-wakeup records for its own sessions (the normal co-resident TOC shape). The DEPLOYMENT flips
-    // this to false via SCHEDULER_SESSION_WAKEUP=false when the spawning shell knows no daemon will honor
-    // them (headless spawn without a resident daemon) — core's ScheduleWakeup then refuses up front instead
-    // of parking a wakeup that never fires. Capability = instance-lifetime snapshot (core TOCTOU 契约条款),
-    // so the signal rides construction, never per-call.
     supportsSessionWakeup: true,
 };
-/** Human-readable `when` summary for list(). */
 function whenSummary(when) {
     if (when.kind === "cron")
         return `cron ${when.expr}`;
@@ -58,30 +21,16 @@ function whenSummary(when) {
         return `at ${new Date(when.atMs).toISOString()}`;
     return `delay ${when.delaySec}s`;
 }
-/** Upsert dedup key — same (scope, LANE, when, label) overwrites (idempotent on tool retry).
- *  The lane term is the lifetime identity (adversarial review F1): without it a session job and a durable
- *  job — or two different sessions' jobs — with the same (when, label) collide, and the daemon's
- *  session-end reap would then silently delete what USED to be a durable/other-session job. core's cron
- *  shorthand defaults to session lifetime with no label, so the collision is normal usage, not an edge. */
 function dedupKey(scope, intent, sessionId) {
     const lane = intent.lifetime === "session" ? `session:${sessionId ?? ""}` : "durable";
     return createHash("sha256").update(JSON.stringify([scope, lane, intent.when, intent.label ?? ""])).digest("hex").slice(0, 16);
 }
-/**
- * PURE validation of an intent against caps + now. Returns a SchedulerError or null (ok). No IO. Testable.
- * cron via core `isValidCronExpr` (RCE-safe, no shell-exec); delay/at bounded by minDelaySec + horizon.
- */
 export function validateIntent(intent, caps, nowMs) {
     if (!intent.prompt || typeof intent.prompt !== "string")
         return new SchedulerError("invalid_schedule", "prompt is required");
     const w = intent.when;
     const horizonMs = caps.maxScheduledHorizonSec * 1000;
     if (w.kind === "cron") {
-        // Validate the cron is WELL-FORMED (RCE-safe — the expr never reaches a shell). The `minCronIntervalSec` FLOOR is
-        // NOT enforced here: realizing a cron's actual fire interval requires cron-next, which the design assigns to the
-        // resident daemon (it computes nextRunMs + can skip/floor a sub-interval fire). A 5-field cron's minimum interval
-        // is 60s, so the default 60s floor is naturally satisfied; a deployment that TIGHTENS minCronIntervalSec relies on
-        // the daemon to honor it. (Adversarial-review LOW: the advertised cap is daemon-enforced, not writer-enforced.)
         if (!isValidCronExpr(w.expr))
             return new SchedulerError("invalid_schedule", `invalid cron expression: ${w.expr}`);
     }
@@ -103,7 +52,6 @@ export function validateIntent(intent, caps, nowMs) {
     }
     return null;
 }
-/** nextRunMs for at/delay (direct); cron left undefined here (the resident daemon computes via a cron lib). */
 function computeNextRunMs(when, nowMs) {
     if (when.kind === "at")
         return when.atMs;
@@ -111,15 +59,9 @@ function computeNextRunMs(when, nowMs) {
         return nowMs + when.delaySec * 1000;
     return undefined;
 }
-/** The default shared store path: `SEMA_CONFIG_DIR` → `~/.sema`, file `scheduled_tasks.json` (server + shell agree). */
 export function defaultSchedulerStorePath() {
     return join(process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema"), "scheduled_tasks.json");
 }
-/**
- * File-backed SchedulerCapability (durable across daemon restarts). Store = a single JSON file (atomic write via
- * the registry-core /node binding). The resident shell daemon reads the same store to fire intents. `now`
- * injectable for tests.
- */
 export class FileSchedulerBackend {
     schedulerCapabilities;
     storePath;
@@ -140,14 +82,9 @@ export class FileSchedulerBackend {
         const bad = validateIntent(intent, this.schedulerCapabilities, nowMs);
         if (bad)
             return err(bad);
-        // A session-scoped job with no session to bind to could never be reaped (a zombie the daemon would
-        // fire forever) — core's CronCreate refuses this at the tool layer; refuse here too for non-tool callers.
         if (intent.lifetime === "session" && !ctx.sessionId) {
             return err(new SchedulerError("invalid_schedule", 'lifetime:"session" requires a session to bind to (ctx.sessionId missing)'));
         }
-        // [2436] 纵深(5.6.0):能力面已声明无 daemon 收割 session-lifetime(headless 部署形,
-        // SCHEDULER_SESSION_LIFETIME=false)⇒ 落盘一条即必然孤儿([2425] 外溢病)。core 的 CronCreate 读
-        // 能力面在工具层前门拒是第一道;这里是第二道——错装配宿主绕过工具层直调也不许落盘。
         if (intent.lifetime === "session" && this.schedulerCapabilities.supportsSessionLifetime === false) {
             return err(new SchedulerError("invalid_schedule", 'lifetime:"session" is not supported on this deployment (no resident daemon reaps session-lifetime records — the row would be an orphan)'));
         }
@@ -157,7 +94,6 @@ export class FileSchedulerBackend {
             const rr = r;
             return r.scope === ctx.scope && dedupKey(r.scope, { when: r.when, label: r.label, lifetime: rr.lifetime }, r.sessionId) === key;
         });
-        // Per-scope cap (excluding the upsert target — overwriting an existing one doesn't grow the count).
         const scopeCount = records.filter((r) => r.scope === ctx.scope).length;
         if (existingIdx < 0 && scopeCount >= this.schedulerCapabilities.maxScheduledPerScope) {
             return err(new SchedulerError("limit_exceeded", `scope at cap (${this.schedulerCapabilities.maxScheduledPerScope})`));
@@ -166,20 +102,12 @@ export class FileSchedulerBackend {
         const rec = {
             id,
             scope: ctx.scope,
-            ...(ctx.principal ? { principal: ctx.principal } : {}), // 🔴 pinned from ctx (Runner-held), never intent
+            ...(ctx.principal ? { principal: ctx.principal } : {}),
             ...(ctx.sessionId ? { sessionId: ctx.sessionId } : {}),
             prompt: intent.prompt,
             when: intent.when,
             ...(intent.label ? { label: intent.label } : {}),
-            // core 1.265 ScheduledIntent.mode(缺省 "task" 向后兼容):persist the execution shape —
-            // ScheduleWakeup's stop:true keys off the LIST face's mode echo (CC 206 D9); a dropped mode forced the
-            // shell onto its label fallback. registry-core SchedulerRecord optional fields are additive by contract.
             ...(intent.mode ? { mode: intent.mode } : {}),
-            // core 1.301 lifetime/recurring ([950]/[954]): persist BOTH so the daemon can reap session-scoped
-            // jobs and delete a recurring:false cron after its first firing. Dropping them here was [954]-(b):
-            // the tool answered "once" while the record said nothing → the daemon fired forever. Additive
-            // SchedulerRecord fields (registry-core contract), same posture as `mode` above. recurring is a
-            // tri-state (undefined = cron default "fire every match") — persist only when explicitly set.
             ...(intent.lifetime ? { lifetime: intent.lifetime } : {}),
             ...(intent.recurring !== undefined ? { recurring: intent.recurring } : {}),
             createdMs: nowMs,
@@ -200,9 +128,6 @@ export class FileSchedulerBackend {
     async cancel(id, ctx) {
         const records = this.load();
         const idx = records.findIndex((r) => r.id === id);
-        // 🔴 scope isolation + 假肯定病修([2425]/[2209],5.6.0):missing 与 non-own-scope **同折**
-        // err(not_found)——存在性仍不泄露(错 id/别人的任务/已删的重试三条到达路径一个答案),但不再
-        // ok(undefined) 谎报「删掉了」。旧形的代价是真实的:模型删错 id 得到成功回执,真任务继续按点起跑。
         if (idx < 0 || records[idx].scope !== ctx.scope) {
             return err(new SchedulerError("not_found", `no scheduled task ${id} in your scope (wrong id, already cancelled, or not yours)`));
         }
@@ -217,15 +142,13 @@ export class FileSchedulerBackend {
     }
     async list(ctx) {
         const summaries = this.load()
-            .filter((r) => r.scope === ctx.scope) // 🔴 scope-scoped, not global
+            .filter((r) => r.scope === ctx.scope)
             .map((r) => ({
             id: r.id,
             when: whenSummary(r.when),
             ...(r.label ? { label: r.label } : {}),
             ...(r.nextRunMs !== undefined ? { nextRunMs: r.nextRunMs } : {}),
-            // echo the persisted mode (additive; pre-1.159.x records lack it → undefined = shell label fallback).
             ...(r.mode ? { mode: r.mode } : {}),
-            // echo lifetime/recurring (ScheduledTaskSummary 1.302 fields; absent on pre-1.215 records).
             ...(r.lifetime ? { lifetime: r.lifetime } : {}),
             ...(r.recurring !== undefined ? { recurring: r.recurring } : {}),
         }));

package/dist/plugins/send-file-ledger.js

@@ -1,30 +1,6 @@
-/**
- * SendUserFile server-side LEDGER (multi-tenant governance face, clay ruling 2026-07-14 — the second half of
- * [768]②a: the object key carries a HASHED scope segment, so the store alone can't answer "which tenant sent
- * what". This ledger is the scope↔object mapping the hash deliberately hides from URLs): one row per issued
- * link, keyed by a uuidv7 `id` (time-ordered → keyset pagination), indexed by `scope` (the VERIFIED principal
- * verbatim; "_" = the single-user sentinel, same as the checkpoint scope column).
- *
- * WRITE SEMANTICS (enforced by {@link withLedgerRecording}, wrapped around BOTH send lanes in main.ts): record
- * AFTER upload+verify succeed and BEFORE the file_link frame is emitted. A record failure is FAIL-LOUD for that
- * file (the governance face MUST have the row — a link the ledger can't see can't be listed or revoked) and the
- * already-uploaded object is DELETED with one retry (a public-track object with no ledger row would be an
- * unmanageable orphan); the thrown message reports the TRUE reclaim outcome (reclaimed vs orphan) but — 修4 —
- * NEVER the coordinates or the cause (it is model-visible via the tool result; a bucket/key leak there would
- * let the model rebuild the capability URL): those go to the operator log under a shared incident id.
- *
- * The ledger does NOT store URLs: the public-track URL is reconstructible from bucket+key, and a presigned-track
- * URL is a decaying capability that would be expired by the time anyone lists it. Reads return metadata + key.
- *
- * Four twins behind one interface (the approval-exemption pattern): TiDB/PG = durable cross-replica SQL rows
- * (`sendfile_link` table, DDL in tidb-pool.ts / pg-pool.ts); File = append-only JSONL hydrated on boot
- * (fsync — a torn tail must not fabricate a row); Memory = tests / ephemeral.
- */
 import { join } from "node:path";
 import { AppendLog, ensureDir, readJsonlRecords, uuidv7 } from "@sema-agent/core";
-/** Ledger scope sentinel for single-user issuance (no principal) — mirrors scopeSegment's "_" key segment. */
 export const SENDFILE_SINGLE_USER_SCOPE = "_";
-// ─── TiDB / MySQL twin ───────────────────────────────────────────────────────────────────────────────────
 export class TiDBSendFileLedger {
     pool;
     constructor(pool) {
@@ -32,8 +8,7 @@ export class TiDBSendFileLedger {
     }
     async record(entry) {
         await this.pool.query("INSERT INTO sendfile_link (id, scope, bucket, object_key, track, filename, byte_len, ttl_sec, task_id, session_id, created_at) " +
-            "VALUES (?,?,?,?,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE id = id", // idempotent on the uuidv7 PK (retry-safe no-op)
-        [entry.id, entry.scope, entry.bucket, entry.objectKey, entry.track, entry.filename, entry.size, entry.ttlSec, entry.taskId ?? null, entry.sessionId ?? null, new Date(entry.createdAt)]);
+            "VALUES (?,?,?,?,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE id = id", [entry.id, entry.scope, entry.bucket, entry.objectKey, entry.track, entry.filename, entry.size, entry.ttlSec, entry.taskId ?? null, entry.sessionId ?? null, new Date(entry.createdAt)]);
     }
     async listByScope(scope, limit, beforeId) {
         const [rows] = await this.pool.query("SELECT id, scope, bucket, object_key, track, filename, byte_len, ttl_sec, task_id, session_id, created_at FROM sendfile_link " +
@@ -41,7 +16,6 @@ export class TiDBSendFileLedger {
         return rows.map((r) => rowToEntry(r));
     }
 }
-// ─── PG twin (dialect twin — $n placeholders + ON CONFLICT) ──────────────────────────────────────────────
 export class PgSendFileLedger {
     pool;
     constructor(pool) {
@@ -72,7 +46,6 @@ function rowToEntry(r) {
         createdAt: new Date(r.created_at).getTime(),
     };
 }
-// ─── Memory twin (tests / ephemeral) ─────────────────────────────────────────────────────────────────────
 export class MemorySendFileLedger {
     byScope = new Map();
     async record(entry) {
@@ -82,7 +55,7 @@ export class MemorySendFileLedger {
             this.byScope.set(entry.scope, m);
         }
         if (!m.has(entry.id))
-            m.set(entry.id, { ...entry }); // idempotent on id
+            m.set(entry.id, { ...entry });
     }
     async listByScope(scope, limit, beforeId) {
         const m = this.byScope.get(scope);
@@ -95,7 +68,6 @@ export class MemorySendFileLedger {
             .map((e) => ({ ...e }));
     }
 }
-// ─── File twin (local lane — single append-only JSONL + boot hydrate, torn-tail-safe) ───────────────────
 export class FileSendFileLedger {
     path;
     mem = new MemorySendFileLedger();
@@ -105,7 +77,6 @@ export class FileSendFileLedger {
         ensureDir(dir);
         this.path = join(dir, "links.jsonl");
         for (const r of readJsonlRecords(this.path)) {
-            // hydrate defensively: a record without the identity triple can't be listed/revoked — skip, don't fabricate
             if (!r || typeof r.id !== "string" || typeof r.scope !== "string" || typeof r.objectKey !== "string")
                 continue;
             void this.mem.record(r);
@@ -113,29 +84,21 @@ export class FileSendFileLedger {
     }
     async record(entry) {
         this.log ??= new AppendLog(this.path);
-        this.log.append(entry, true); // fsync — the governance row must survive a crash
+        this.log.append(entry, true);
         await this.mem.record(entry);
     }
     listByScope(scope, limit, beforeId) {
         return this.mem.listByScope(scope, limit, beforeId);
     }
-    /** Release the append-log fd (LocalBackend.close → graceful-restart re-open). */
     dispose() {
         try {
             this.log?.close();
         }
         catch {
-            /* best-effort */
         }
         this.log = undefined;
     }
 }
-/**
- * Wrap a lane `send` with the ledger write point: upload+verify succeed (the inner send resolved) → record →
- * only then return (the tool emits the file_link frame strictly after). Record failure ⇒ fail-loud for THIS
- * file + delete of the uploaded object with ONE retry; the throw is the contract either way, and its message
- * states the true reclaim outcome (F2: a failed reclaim = permanent orphan, warned with coordinates).
- */
 export function withLedgerRecording(send, deps) {
     return async (path, ctx) => {
         const link = await send(path, ctx);
@@ -155,18 +118,6 @@ export function withLedgerRecording(send, deps) {
             });
         }
         catch (e) {
-            // Governance face MUST have the row — reclaim the object (an unledgered public object is unmanageable),
-            // then fail loud for this file. F2 (codex scope-ledger audit): the DELETE gets ONE retry (S3 DELETE is
-            // idempotent, so a transient blip degrades to a second attempt), and the thrown message reports the TRUE
-            // reclaim outcome — a failed reclaim is a PERMANENT ORPHAN (record failed + object still live) and must
-            // never be described as "reclaimed"; the warns carry the coordinates for manual cleanup.
-            // 修4 (三路复审): the THROWN message is MODEL-VISIBLE (the tool splices per-file errors into its result,
-            // and capabilities already expose the public endpoint) — bucket/key/underlying cause in it would let the
-            // model reconstruct the permanent capability URL of an object the governance face can't see. The message
-            // therefore carries only a fixed error code + a short incident id; coordinates and cause go to the
-            // OPERATOR log (warn) keyed by the same incident id.
-            // Backlog (deliberately not built here): a durable reclaim queue that retries beyond this request's
-            // lifetime — today the orphan is surfaced loudly (incident-tagged warns) and cleaned up by hand.
             const incident = (deps.newId ? deps.newId() : uuidv7()).replace(/-/g, "").slice(-12);
             let reclaimed = true;
             try {
@@ -174,7 +125,7 @@ export function withLedgerRecording(send, deps) {
                     await deps.deleteObject(link.bucket, link.key);
                 }
                 catch {
-                    await deps.deleteObject(link.bucket, link.key); // one retry: transient-fault degrade
+                    await deps.deleteObject(link.bucket, link.key);
                 }
             }
             catch (de) {

package/dist/plugins/send-user-file.js

@@ -1,74 +1,19 @@
-/**
- * SendUserFile — the dual-track public-link ISSUER (design: sema-deploy docs/design/S3-PUBLIC-LINKS.md,
- * settled cross-repo 2026-07-14; tool name SendUserFile is final).
- *
- * The LLM hands a user a file over the web session as a URL the browser fetches DIRECTLY from S3/MinIO
- * (server relay was rejected: double bandwidth on third-party S3 + loses CDN). Two tracks, keyed on ttl:
- *
- *  - ttl == 0 (PERMANENT, the default): upload to the anonymous-GET public bucket under an unguessable
- *    `<scopeSeg>/<uuidv7>/<name>` key (capability URL — GET-only bucket policy, List disabled, so the prefix IS
- *    the secret; scopeSeg = hashed tenant segment, see {@link scopeSegment} — multi-tenant list/revoke handle,
- *    1.190.0 [768]②a). URL = plain `<publicEndpoint>/<bucket>/<key>` — no signature, never expires, CDN-cacheable.
- *    Revocation = delete the object.
- *    ⚠️ Bucket-policy footgun (live-verified 2026-07-14): `mc anonymous set download` ALSO enables
- *    ListBucket — an anonymous `GET /<bucket>/?list-type=2` then enumerates every uuidv7 key and the
- *    capability design collapses. Deployments MUST use a GetObject-only JSON policy
- *    (`mc anonymous set-json` with Action=["s3:GetObject"] on `arn:aws:s3:::<bucket>/*`): GET 200, LIST 403.
- *  - 0 < ttl ≤ 7d: upload to the PRIVATE bucket and return a SigV4 presigned GET. The signature is
- *    computed against the PUBLIC endpoint (SigV4 binds Host — signing with the internal host would 403
- *    the user's browser; the reverse proxy must pass Host through).
- *  - ttl > 7d: fail-loud — SigV4 caps presign at 7 days (physical limit); the caller should use ttl=0.
- *
- * Uploads always go through the INTERNAL endpoint (server-side PUT, its own signed request — Host binding
- * is per-request, so internal-for-write + public-for-read coexist). Zero-dependency posture: presignS3Url
- * + fetch, same as MinioBlobBackend / the k8s adapter.
- */
 import { createHmac } from "node:crypto";
 import { uuidv7 } from "@sema-agent/core";
 import { presignS3CopyUrl, presignS3Url } from "./s3-presign.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "./blob-backend.js";
-/** SigV4 physical ceiling (AWS: X-Amz-Expires max 604800s = 7 days). */
 export const PRESIGN_MAX_TTL_SEC = 604_800;
-/**
- * Multi-tenant governance (clay ruling 2026-07-14, blackboard [768]② variant a with a HASHED segment): every
- * object key carries a per-tenant SCOPE SEGMENT so tenants can be listed/revoked by prefix on the store itself,
- * WITHOUT leaking the principal into the (user-visible, forwardable) URL. The segment is
- * `HMAC-SHA256(secretKey, "sendfile-scope:" + scope)` hex, truncated to 32 chars:
- *  - keyed on the S3 SECRET KEY — server-held and stable, so the mapping is deterministic per deployment but
- *    unforgeable/unenumerable from outside (a URL holder cannot test principal guesses without the key);
- *  - the "sendfile-scope:" DOMAIN SEPARATOR pins this HMAC use — the same secret signs SigV4 requests, and a
- *    cross-protocol collision between "scope segment" and any other HMAC-of-attacker-controlled-string use is
- *    exactly what domain separation exists to prevent;
- *  - 32 hex chars (128 bits) is a NAMESPACE label, not a secret: the cross-tenant BIRTHDAY bound at even a
- *    billion tenants is ~n²/2^129 ≈ 2^-69 — negligible. (The earlier 16-hex/64-bit cut had a ~2.7% birthday
- *    collision probability at that scale — n²/2^65, NOT the per-pair 2^-32 the old note claimed; codex audit
- *    F4, widened pre-release at zero cost.) Capability secrecy still lives in the uuidv7 segment. Key budget
- *    stays comfortable: worst-case private-track key = 9 ("sendfile/") + 32 + 1 + 36 + 1 + 128 = 207 chars,
- *    under both sendfile_link.object_key VARCHAR(512) and S3's 1024-byte key ceiling.
- * scope undefined/"" (single-user deployments have no principal) → the literal "_" sentinel (same sentinel the
- * checkpoint scope column uses for anonymous), so the key SHAPE is uniform across deployments.
- * ⚠️ Objects issued before 1.190.0 have NO scope segment (`<uuidv7>/<name>`); they stay valid — the segment is
- * purely additive (URLs are capability-complete either way), zero migration.
- */
 export function scopeSegment(secretKey, scope) {
     if (scope === undefined || scope === "")
         return "_";
     return createHmac("sha256", secretKey).update(`sendfile-scope:${scope}`).digest("hex").slice(0, 32);
 }
-/**
- * Collapse an arbitrary client-supplied name to ONE safe path segment: strip directories (both
- * separators), control/bidi characters (the session-title sanitize class), leading dots (no hidden
- * files / no "." ".."), and cap the length (S3 key segment budget; keep the extension when truncating).
- * Empty in ⇒ "file".
- */
 export function sanitizeSendFileName(name) {
     const base = (name ?? "").split(/[/\\]/).pop() ?? "";
     let clean = base.replace(/[\u0000-\u001f\u007f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").replace(/^\.+/, "").trim();
     if (clean.length > 128) {
         const dot = clean.lastIndexOf(".");
         const ext = dot > 0 && clean.length - dot <= 16 ? clean.slice(dot) : "";
-        // code-point 安全截断:UTF-16 slice 会切断代理对,留下 lone surrogate → encodeURIComponent 抛
-        // URIError(此时对象已上传,链接却铸不出来)。按 code point 截,预算=128-ext 的 UTF-16 units。
         const budget = 128 - ext.length;
         let head = "";
         for (const ch of clean) {
@@ -81,8 +26,6 @@ export function sanitizeSendFileName(name) {
     return clean.length > 0 ? clean : "file";
 }
 export function createSendUserFileIssuer(cfg, deps) {
-    // C3:六站点统一 abort 上界(半开 S3 端点此前把用户可见的工具调用挂满 undici ~300s,
-    // reclaim 也挂住 ⇒ staging 孤儿+误报「reclaim FAILED」)。上界常量与 blob-backend 同源。
     const f = deps?.fetchImpl ?? fetch;
     const bounded = () => ({ signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
     const upload = deps?.upload ??
@@ -111,11 +54,9 @@ export function createSendUserFileIssuer(cfg, deps) {
             throw new Error(`SendUserFile ttl must be a non-negative INTEGER of seconds (0 = permanent; SigV4 X-Amz-Expires is integer-only); got ${ttl}`);
         const name = sanitizeSendFileName(filename);
         const publicBase = cfg.publicEndpoint.replace(/\/+$/, "");
-        const seg = scopeSegment(cfg.secretKey, scope); // hashed tenant segment ("_" single-user) — see scopeSegment doc
+        const seg = scopeSegment(cfg.secretKey, scope);
         const scopeField = scope !== undefined && scope !== "" ? { scope } : {};
         if (ttl === 0) {
-            // Permanent track: capability URL on the anonymous-GET bucket. Key = <scopeSeg>/<uuidv7>/<name>
-            // (pre-1.190 objects have no scope segment — additive, both shapes stay valid).
             const key = `${seg}/${uuidv7()}/${name}`;
             await upload(cfg.publicBucket, key, bytes);
             const url = `${publicBase}/${cfg.publicBucket}/${key.split("/").map(encodeURIComponent).join("/")}`;
@@ -124,7 +65,6 @@ export function createSendUserFileIssuer(cfg, deps) {
         if (ttl > PRESIGN_MAX_TTL_SEC) {
             throw new Error(`SendUserFile ttl ${ttl}s exceeds the SigV4 presign ceiling (${PRESIGN_MAX_TTL_SEC}s = 7 days) — use ttl=0 for a permanent link`);
         }
-        // Presigned track: private bucket upload, GET signed against the PUBLIC endpoint (Host-bound).
         const key = `${cfg.privateKeyPrefix}${seg}/${uuidv7()}/${name}`;
         await upload(cfg.privateBucket, key, bytes);
         const url = presignS3Url({
@@ -140,9 +80,6 @@ export function createSendUserFileIssuer(cfg, deps) {
         });
         return { url, filename: name, size: bytes.byteLength, ttlSec: ttl, track: "presigned", bucket: cfg.privateBucket, key, ...scopeField };
     };
-    // v2 (sandbox direct-upload): same key/track/URL algebra as issue(), split into sign-then-finalize so
-    // the BYTES move sandbox→S3 directly (server never relays; creds never enter the sandbox — only a
-    // single-object, method-bound, 120s PUT capability on a STAGING key does; see PreparedDirectUpload).
     const prepareDirectUpload = (filename, ttlSec, scope) => {
         if (cfg.publicEndpoint === undefined) {
             throw new Error("SendUserFile is not configured for public links: set S3_PUBLIC_ENDPOINT (the S3/MinIO base URL users can reach; falls back to S3_ENDPOINT when that is already public)");
@@ -157,21 +94,11 @@ export function createSendUserFileIssuer(cfg, deps) {
         const publicBase = cfg.publicEndpoint.replace(/\/+$/, "");
         const putBase = (cfg.sandboxPutEndpoint ?? cfg.publicEndpoint).replace(/\/+$/, "");
         const bucket = ttl === 0 ? cfg.publicBucket : cfg.privateBucket;
-        // Same key algebra as issue() incl. the hashed tenant segment — prepare/finalize share ONE key, so the
-        // segment is fixed here (the PUT capability is already scoped to it).
         const seg = scopeSegment(cfg.secretKey, scope);
         const scopeField = scope !== undefined && scope !== "" ? { scope } : {};
         const key = ttl === 0 ? `${seg}/${uuidv7()}/${name}` : `${cfg.privateKeyPrefix}${seg}/${uuidv7()}/${name}`;
-        // 修3 staging two-phase: the sandbox-visible PUT capability is scoped to a STAGING key in the PRIVATE
-        // bucket (never anonymous-readable, never handed out as a URL) — the final key above gets its bytes via
-        // a server-side CopyObject only, so no /proc reader of the exec argv can ever rewrite what the user's
-        // link points at. The staging key keeps the tenant segment (orphan attribution on manual cleanup).
         const stagingBucket = cfg.privateBucket;
         const stagingKey = `${cfg.privateKeyPrefix}staging/${seg}/${uuidv7()}`;
-        // TTL 120s, not the uploader default 600: the URL rides the sandbox exec argv (visible to the sandbox's
-        // own processes / possibly an apiserver audit log) — anyone who reads it gains nothing they don't already
-        // have DURING the upload (the sandbox owns the file), and since 修3 the writable object is only the
-        // staging key anyway. Keep the window as short as a slow 100MiB upload allows.
         const putUrl = presignS3Url({
             endpoint: putBase,
             bucket: stagingBucket,
@@ -196,21 +123,16 @@ export function createSendUserFileIssuer(cfg, deps) {
                 ...(cfg.region !== undefined ? { region: cfg.region } : {}),
                 expiresSec: 60,
             });
-            // 修2: best-effort reclaim — any failure AFTER the object landed must delete it before throwing
-            // (a transient HEAD 5xx used to strand an unledgered, undelivered orphan in the bucket). Returns the
-            // TRUE outcome so error messages never claim "reclaimed" for a delete that itself failed (F2 posture).
             const reclaim = async (b, k) => {
                 try {
                     const r = await f(sign("DELETE", b, k), { method: "DELETE", ...bounded() });
-                    return r.ok || r.status === 404; // S3 DELETE is idempotent — a missing key IS reclaimed
+                    return r.ok || r.status === 404;
                 }
                 catch {
                     return false;
                 }
             };
             const outcome = (ok, what) => (ok ? `${what} reclaimed` : `${what} reclaim FAILED (orphan; operator cleanup needed)`);
-            // ① HEAD the STAGING object (internal endpoint, adapter creds): existence + a cheap early cap gate
-            // (fail before copying a huge object). Advisory only for size — the authoritative reading is ④.
             let head;
             try {
                 head = await f(sign("HEAD", stagingBucket, stagingKey), { method: "HEAD", ...bounded() });
@@ -222,7 +144,7 @@ export function createSendUserFileIssuer(cfg, deps) {
             if (head.status === 404)
                 throw new Error("SendUserFile upload verification failed: object not found after upload (HEAD 404)");
             if (!head.ok) {
-                const r = await reclaim(stagingBucket, stagingKey); // transient 5xx ≠ missing — the object may be live; reclaim it
+                const r = await reclaim(stagingBucket, stagingKey);
                 throw new Error(`SendUserFile upload verification failed: store error (HEAD ${head.status}) — ${outcome(r, "staged object")}`);
             }
             const staged = Number.parseInt(head.headers.get("content-length") ?? "", 10);
@@ -234,9 +156,6 @@ export function createSendUserFileIssuer(cfg, deps) {
                 await reclaim(stagingBucket, stagingKey);
                 throw new Error(`file exceeds the ${maxBytes >= 1024 * 1024 ? `${Math.floor(maxBytes / (1024 * 1024))} MiB` : `${maxBytes} byte`} per-file cap (uploaded object was ${staged} bytes — deleted)`);
             }
-            // ② Server-side CopyObject staging→final (internal endpoint, signed x-amz-copy-source): the ONLY
-            // write the final key ever receives. NB: S3 can return 200 with an error BODY on slow copies — require
-            // the CopyObjectResult marker, not just the status.
             const copy = presignS3CopyUrl({
                 endpoint: cfg.endpoint,
                 bucket,
@@ -257,15 +176,10 @@ export function createSendUserFileIssuer(cfg, deps) {
             }
             catch (e) {
                 const r1 = await reclaim(stagingBucket, stagingKey);
-                const r2 = await reclaim(bucket, key); // the copy may have half-landed — reclaim both sides
+                const r2 = await reclaim(bucket, key);
                 throw new Error(`SendUserFile upload verification failed: staging promotion failed (${e instanceof Error ? e.message : String(e)}) — ${outcome(r1 && r2, "uploaded object")}`);
             }
-            // ③ Staging object served its purpose — reclaim (best-effort: a leftover is a private-bucket blob
-            // whose write capability expires in ≤120s; it can't become a public link).
             await reclaim(stagingBucket, stagingKey);
-            // ④ Authoritative HEAD of the FINAL object — immutable to the sandbox, so THIS size is what the copy
-            // pinned and what the card must carry (re-checked against the cap: a /proc reader could have re-PUT
-            // staging between ① and ②, swapping in different bytes).
             let fin;
             try {
                 fin = await f(sign("HEAD", bucket, key), { method: "HEAD", ...bounded() });
@@ -309,10 +223,6 @@ export function createSendUserFileIssuer(cfg, deps) {
         };
         return { putUrl, verifySize, finalize };
     };
-    // Ledger reclaim (fail-loud record path): delete an already-uploaded object whose ledger record failed —
-    // a public-track object with no ledger row would be unmanageable (no per-tenant list/revoke handle). Signed
-    // DELETE against the INTERNAL endpoint (adapter creds, same posture as verifySize). S3 DELETE is idempotent
-    // (204 on a missing key), so callers may retry safely.
     const deleteObject = async (bucket, key) => {
         if (deps?.remove)
             return deps.remove(bucket, key);