@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/scheduler-support.d.ts

@@ -2,6 +2,7 @@ import { SchedulerError } from "@sema-agent/core";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "@sema-agent/core";
 import type { SchedulerRecord } from "@sema-agent/registry-core/scheduler-store";
 export type { SchedulerRecord };
+/** core `Result<T,E>` shape (harness/types) — `{ok:true,value} | {ok:false,error}`. */
 type Result<T, E> = {
     ok: true;
     value: T;
@@ -9,6 +10,7 @@ type Result<T, E> = {
     ok: false;
     error: E;
 };
+/** Default caps (fail-closed bounds; design/105 §3.9). Override per deployment. */
 export declare const DEFAULT_SCHEDULER_CAPS: {
     readonly supported: true;
     readonly maxScheduledPerScope: 32;
@@ -19,8 +21,18 @@ export declare const DEFAULT_SCHEDULER_CAPS: {
     readonly supportsSessionWakeup: true;
 };
 type Caps = SchedulerCapability["schedulerCapabilities"];
+/**
+ * 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 declare function validateIntent(intent: ScheduledIntent, caps: Caps, nowMs: number): SchedulerError | null;
+/** The default shared store path: `SEMA_CONFIG_DIR` → `~/.sema`, file `scheduled_tasks.json` (server + shell agree). */
 export declare function defaultSchedulerStorePath(): string;
+/**
+ * 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 declare class FileSchedulerBackend implements SchedulerCapability {
     readonly schedulerCapabilities: Caps;
     private readonly storePath;

package/dist/plugins/scheduler-support.js

@@ -1,3 +1,28 @@
+/**
+ * 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";
@@ -5,15 +30,27 @@ 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,
+    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).
     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}`;
@@ -21,16 +58,30 @@ 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}`);
     }
@@ -52,6 +103,7 @@ 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;
@@ -59,9 +111,15 @@ 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;
@@ -82,6 +140,8 @@ 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)'));
         }
@@ -91,6 +151,7 @@ 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})`));
@@ -99,12 +160,20 @@ export class FileSchedulerBackend {
         const rec = {
             id,
             scope: ctx.scope,
-            ...(ctx.principal ? { principal: ctx.principal } : {}),
+            ...(ctx.principal ? { principal: ctx.principal } : {}), // 🔴 pinned from ctx (Runner-held), never intent
             ...(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,
@@ -125,6 +194,7 @@ export class FileSchedulerBackend {
     async cancel(id, ctx) {
         const records = this.load();
         const idx = records.findIndex((r) => r.id === id);
+        // 🔴 scope isolation: a non-own-scope id is `not_found` (don't leak existence). Idempotent: missing = ok.
         if (idx < 0 || records[idx].scope !== ctx.scope)
             return ok(undefined);
         records.splice(idx, 1);
@@ -138,13 +208,15 @@ export class FileSchedulerBackend {
     }
     async list(ctx) {
         const summaries = this.load()
-            .filter((r) => r.scope === ctx.scope)
+            .filter((r) => r.scope === ctx.scope) // 🔴 scope-scoped, not global
             .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.d.ts

@@ -1,22 +1,29 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { IssuedFileLink } from "./send-user-file.js";
+/** Ledger scope sentinel for single-user issuance (no principal) — mirrors scopeSegment's "_" key segment. */
 export declare const SENDFILE_SINGLE_USER_SCOPE = "_";
 export interface SendFileLedgerEntry {
+    /** uuidv7 — PK and the keyset cursor (time-ordered, newest = lexicographically greatest). */
     id: string;
+    /** Verified principal verbatim ("_" = single-user). NEVER derived from the hashed key segment (one-way). */
     scope: string;
     bucket: string;
     objectKey: string;
     track: "public" | "presigned";
     filename: string;
     size: number;
+    /** 0 = permanent (public track). */
     ttlSec: number;
     taskId?: string;
     sessionId?: string;
     createdAt: number;
 }
 export interface SendFileLedger {
+    /** Record one issued link. Idempotent on `id` (a retry after a lost ack must not duplicate). */
     record(entry: SendFileLedgerEntry): Promise<void>;
+    /** Newest-first page of one scope's links; keyset = `id < beforeId` (listSessions posture: fetch limit+1
+     *  to detect more). `beforeId` absent = first page. */
     listByScope(scope: string, limit: number, beforeId?: string): Promise<SendFileLedgerEntry[]>;
 }
 export declare class TiDBSendFileLedger implements SendFileLedger {
@@ -43,15 +50,23 @@ export declare class FileSendFileLedger implements SendFileLedger {
     constructor(root: string);
     record(entry: SendFileLedgerEntry): Promise<void>;
     listByScope(scope: string, limit: number, beforeId?: string): Promise<SendFileLedgerEntry[]>;
+    /** Release the append-log fd (LocalBackend.close → graceful-restart re-open). */
     dispose(): void;
 }
 export interface LedgerRecordingDeps {
     ledger: SendFileLedger;
+    /** Best-effort reclaim of the uploaded object when the record fails (issuer.deleteObject). */
     deleteObject: (bucket: string, key: string) => Promise<void>;
     warn?: (msg: string, meta?: Record<string, unknown>) => void;
     now?: () => number;
     newId?: () => string;
 }
+/**
+ * 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 declare function withLedgerRecording(send: (path: string, ctx: {
     taskId?: string;
     sessionId?: string;

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

@@ -1,6 +1,30 @@
+/**
+ * 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) {
@@ -8,7 +32,8 @@ 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", [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", // 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)]);
     }
     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 " +
@@ -16,6 +41,7 @@ export class TiDBSendFileLedger {
         return rows.map((r) => rowToEntry(r));
     }
 }
+// ─── PG twin (dialect twin — $n placeholders + ON CONFLICT) ──────────────────────────────────────────────
 export class PgSendFileLedger {
     pool;
     constructor(pool) {
@@ -46,6 +72,7 @@ function rowToEntry(r) {
         createdAt: new Date(r.created_at).getTime(),
     };
 }
+// ─── Memory twin (tests / ephemeral) ─────────────────────────────────────────────────────────────────────
 export class MemorySendFileLedger {
     byScope = new Map();
     async record(entry) {
@@ -55,7 +82,7 @@ export class MemorySendFileLedger {
             this.byScope.set(entry.scope, m);
         }
         if (!m.has(entry.id))
-            m.set(entry.id, { ...entry });
+            m.set(entry.id, { ...entry }); // idempotent on id
     }
     async listByScope(scope, limit, beforeId) {
         const m = this.byScope.get(scope);
@@ -68,6 +95,7 @@ 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();
@@ -77,6 +105,7 @@ 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);
@@ -84,21 +113,29 @@ export class FileSendFileLedger {
     }
     async record(entry) {
         this.log ??= new AppendLog(this.path);
-        this.log.append(entry, true);
+        this.log.append(entry, true); // fsync — the governance row must survive a crash
         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);
@@ -118,6 +155,18 @@ 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 {
@@ -125,7 +174,7 @@ export function withLedgerRecording(send, deps) {
                     await deps.deleteObject(link.bucket, link.key);
                 }
                 catch {
-                    await deps.deleteObject(link.bucket, link.key);
+                    await deps.deleteObject(link.bucket, link.key); // one retry: transient-fault degrade
                 }
             }
             catch (de) {

package/dist/plugins/send-user-file.d.ts

@@ -1,42 +1,119 @@
+/** SigV4 physical ceiling (AWS: X-Amz-Expires max 604800s = 7 days). */
 export declare const PRESIGN_MAX_TTL_SEC = 604800;
+/**
+ * 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 declare function scopeSegment(secretKey: string, scope: string | undefined): string;
 export interface SendUserFileConfig {
+    /** Internal S3/MinIO endpoint the SERVER uploads through (adapter-held creds never leave the server). */
     endpoint: string;
+    /** Public base URL users reach (files. subdomain / NodePort / CDN). Absent ⇒ issue() fail-louds with the fix. */
     publicEndpoint?: string;
+    /** Anonymous-GET bucket for the permanent track. */
     publicBucket: string;
+    /** Private bucket for the presigned track. */
     privateBucket: string;
+    /** Key prefix inside the private bucket (keeps sendfile objects apart from snapshot blobs). */
     privateKeyPrefix: string;
+    /** v2: endpoint the SANDBOX uploads through (presigned PUT Host-binding). Default = publicEndpoint —
+     *  an e2b cloud sandbox can only reach the public face; an in-cluster k8s pod may prefer the internal
+     *  endpoint (SEND_USER_FILE_SANDBOX_PUT_ENDPOINT). */
     sandboxPutEndpoint?: string;
     accessKey: string;
     secretKey: string;
     region?: string;
+    /** Default ttl when the tool call omits it. 0 = permanent (the settled default). */
     defaultTtlSec: number;
 }
 export interface IssuedFileLink {
     url: string;
     filename: string;
     size: number;
+    /** 0 = permanent (public track). */
     ttlSec: number;
     track: "public" | "presigned";
     bucket: string;
     key: string;
+    /** The ORIGINAL tenant scope this link was issued under (verbatim, for the server-side ledger — the KEY only
+     *  carries the hashed segment). Absent on single-user issuance (no principal). */
     scope?: string;
 }
+/**
+ * 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 declare function sanitizeSendFileName(name: string | undefined): string;
+/** v2 (sandbox direct-upload, clay 2026-07-14): the two-phase face. `prepare` mints the FINAL object key
+ *  plus a short-lived single-object presigned PUT on a separate STAGING key (the sandbox `curl -T`s the
+ *  file itself — bytes never relay through the server, creds never enter the sandbox); `finalize` mints the
+ *  user-facing link for the FINAL key. The PUT URL is a capability secret scoped to one object+method+TTL —
+ *  callers must keep it out of model context and redact it from errors/logs (adapter posture,
+ *  remote-env-k8s redactPresigned).
+ *
+ *  STAGING two-phase (修3, closes the 1.190 Plan B residual): the PUT URL rides the sandbox exec argv, so
+ *  any process in the sandbox can read it via /proc and re-PUT while it is valid (120s) — previously that
+ *  meant overwriting the FINAL object AFTER server-side verification, i.e. after the user got the link.
+ *  Now the sandbox can only ever write the staging key (`<privateKeyPrefix>staging/<seg>/<uuidv7>` in the
+ *  PRIVATE bucket — never exposed as a public URL); the server CopyObjects it to the final random key with
+ *  its own creds (the sandbox never sees a write capability for that key), deletes the staging object, and
+ *  verifies size on the now-immutable final object. A late re-PUT of the expired-or-not staging URL can no
+ *  longer touch what the user's link points at. */
 export interface PreparedDirectUpload {
+    /** Presigned PUT the sandbox uploads through — the STAGING key (single object, method-bound, short TTL);
+     *  never the final key, which no sandbox-visible write capability ever exists for. */
     putUrl: string;
+    /** SERVER-side post-upload accounting (codex review: the in-sandbox stat is advisory — the sandbox owns
+     *  its filesystem and the presigned PUT is UNSIGNED-PAYLOAD, so nothing binds the uploaded byte count).
+     *  Runs the staging→final promotion with adapter creds via the internal endpoint: HEAD staging (missing ⇒
+     *  throw — claimed upload didn't land; over-cap ⇒ DELETE staging, throw), CopyObject staging→final, DELETE
+     *  staging, then an authoritative HEAD of the FINAL object (whose size the card must carry — the copy is
+     *  what pins the bytes). 修2: EVERY failure past the object landing reclaims best-effort (staging and/or
+     *  final) before throwing — a transient HEAD 5xx must not leave an unledgered orphan. */
     verifySize(maxBytes: number): Promise<number>;
+    /** Mint the user-facing link once the upload is verified. `size` = verifySize's reading. */
     finalize(size: number): IssuedFileLink;
 }
 export interface SendUserFileIssuer {
+    /** Upload bytes and mint the user-facing URL. Throws (fail-loud, typed message) on config/物理 limits.
+     *  `scope` = the caller's VERIFIED principal (multi-tenant); it keys the hashed scope segment in the object
+     *  key and rides back verbatim on IssuedFileLink.scope for the ledger. Omit on single-user. */
     issue(bytes: Uint8Array, filename: string | undefined, ttlSec?: number, scope?: string): Promise<IssuedFileLink>;
+    /** v2: mint a presigned PUT for a sandbox-side direct upload (no bytes through the server). Same `scope`
+     *  semantics as issue() — prepare and finalize share ONE key, so the segment is fixed at prepare time. */
     prepareDirectUpload(filename: string | undefined, ttlSec?: number, scope?: string): PreparedDirectUpload;
+    /** Best-effort object reclaim (ledger fail-loud path: an uploaded object whose ledger record failed would be
+     *  an unmanageable orphan — delete it). Signed DELETE against the INTERNAL endpoint with adapter creds. */
     deleteObject(bucket: string, key: string): Promise<void>;
+    /** The public endpoint web clients need for rendering context (bootstrap/capabilities透出). */
     readonly publicEndpoint: string | undefined;
 }
 export declare function createSendUserFileIssuer(cfg: SendUserFileConfig, deps?: {
+    /** Injectable upload (tests). Default = SigV4 presigned PUT against the INTERNAL endpoint + fetch. */
     upload?: (bucket: string, key: string, bytes: Uint8Array) => Promise<void>;
+    /** Injectable post-direct-upload accounting (tests). Default = HEAD (+ DELETE when over cap) against
+     *  the INTERNAL endpoint with adapter creds. Returns the object's real size. */
     verify?: (bucket: string, key: string, maxBytes: number) => Promise<number>;
+    /** Injectable object delete (tests). Default = signed DELETE against the INTERNAL endpoint. */
     remove?: (bucket: string, key: string) => Promise<void>;
     now?: () => Date;
 }): SendUserFileIssuer;