@sema-agent/server 1.323.0 → 2.0.1

package/dist/capabilities/collab-workflows.js

@@ -1,9 +1,34 @@
+/**
+ * collab → named-workflow projection — 翻译层**切片 1.5**(design/140 统一解:
+ * 「模式=内置命名 workflow profile,一期零新引擎机制」;core 1.263.0 三件落地后的靶点切换)。
+ *
+ * 切片① 的 runTeamDiscussion 投影(collab-project.ts)已随本切片**整体替换**(同款纪律:别留双路径
+ * 降级)。新形态:每个可投影的 CollabTemplate 翻译成一条**命名 workflow 注册条目**——
+ *
+ *   `Workflow({name: <collab id>})` ⇒ 执行体 = core 内置 `TEAM_DISCUSSION_SCRIPT`(pure script content,
+ *   零新机制)+ `defaultArgs` = 本模板的 slots/rounds/finalizer 翻译(args 合并链第二级:调用时 args >
+ *   本注册 defaults > 脚本内置兜底,core `mergeWorkflowArgs` 在 tool-resolve 时点快照)。center「只配模式
+ *   各 slot 的模型」的拍板意图恰好=defaultArgs 这一级;调用者仍可用 args.topic/members 覆盖。
+ *
+ * 可投影子集(团队讨论 profile 能忠实执行的语义;其余整条跳过+结构化上报,绝不静默降级):
+ *   topology ∈ {ring, pair}(round-based 顺序发言=脚本真实形态;star/layered 等 core 后续 profile)∧
+ *   finalizer.type = "summarize"(→脚本 finalizer;judge/vote/fuse/verify 裁决族=后续 profile)∧
+ *   sharedContext = {transcript, session} ∧ 全 slot 无 tools(工具绑定=执行面后续)。
+ *
+ * 语义注记(投影成功但记录):脚本对 members cap 6 / rounds cap 5(确定性截断)——超界模板照投+note;
+ * CollabTemplate.budget=模板级预算无 per-name workflow 通道(WorkflowLimits 是部署级、per-child 强制轴
+ * 已有)→ 记 note,引擎 budget 硬顶+部署 maxTask* 闸兜底(与切片① 结论一致)。
+ *
+ * 纯函数投影 + 模块级可变注册表(registerTeams 同款单例姿势,applyEffective boot+refresh 热更);
+ * 消费点 = main.ts 的 composite WorkflowScriptStore(resolveName 先查这里——**同名 SHADOW core 内置**,
+ * design/140 §6 1c 契约)。
+ */
 import { TEAM_DISCUSSION_SCRIPT } from "@sema-agent/core";
 export function projectCollabToWorkflows(templates) {
     const out = { workflows: {}, skipped: [], notes: [] };
     for (const t of templates ?? []) {
         if (t.enabled === false)
-            continue;
+            continue; // 运营态关闭(不进 skipped)
         if (t.topology !== "ring" && t.topology !== "pair") {
             out.skipped.push({ id: t.id, reason: `topology "${t.topology}" awaits a dedicated profile (design/140 follow-on)` });
             continue;
@@ -22,11 +47,17 @@ export function projectCollabToWorkflows(templates) {
             out.skipped.push({ id: t.id, reason: "slot tools binding awaits the execution slice" });
             continue;
         }
+        // finalizer.slot → 脚本 finalizer(该席位退出讨论席)。slot **未配** ⇒ 脚本内置综合官兜底(合法形态);
+        // slot 配了但**悬空**(指向不存在的席位——拼错/编辑漂移)⇒ 整条跳过(静默回退默认综合官
+        // = 模板意图被悄悄改写,违「绝不静默降级」纪律;center zod 不做跨字段存在性校验,这里是唯一防线)。
         const finSlot = t.finalizer.slot !== undefined ? t.slots.find((s) => s.id === t.finalizer.slot) : undefined;
         if (t.finalizer.slot !== undefined && finSlot === undefined) {
             out.skipped.push({ id: t.id, reason: `finalizer.slot "${t.finalizer.slot}" does not match any slot id (dangling reference)` });
             continue;
         }
+        // 对抗评审 2026-07-11(MED):finalizer slot 合法可为 cardinality-N 多成员(registry-core 只约束
+        // cardinality=1 ≤1 人),但 team-discussion 的 finalizer 是单席——members[1..] 无席可坐。不静默丢人:
+        // 首成员任综合官,其余 note 上报(与 cap 截断同款有损注记纪律)。
         if ((finSlot?.members?.length ?? 0) > 1) {
             out.notes.push({ id: t.id, note: `finalizer slot "${finSlot.id}" carries ${finSlot.members.length} members — only the first seats as the synthesizer (single-seat finalizer profile)` });
         }
@@ -35,6 +66,10 @@ export function projectCollabToWorkflows(templates) {
         const finalizer = finPrompt !== undefined || finModel !== undefined
             ? { ...(finPrompt !== undefined ? { prompt: finPrompt } : {}), ...(finModel !== undefined ? { model: finModel } : {}) }
             : undefined;
+        // 讨论席展开(cardinality "N" 逐成员出席,role 序号唯一;member 镜头 > slot 镜头;T1 modelRef 缺省=
+        // 不设 model ⇒ 脚本/引擎跟随调用者当前模型,零特判)。members 为空的席位=slot 镜头即人设,一人出席。
+        // cardinality 声明与 members 实况分叉(=1 却配了多成员)不静默 flatten——全员照展开
+        // (丢成员=更糟的静默降级)但 note 上报,center 编辑面可据此标注修正。
         const members = [];
         for (const s of t.slots) {
             if (s === finSlot)
@@ -59,6 +94,8 @@ export function projectCollabToWorkflows(templates) {
             defaultArgs: { members, rounds: t.rounds.max, ...(finalizer ? { finalizer } : {}) },
             listing: {
                 name: t.id,
+                // description=center 起的显示名+描述(工具卡人话);whenToUse 留给 center 未来字段——缺席时
+                // 工具卡回落 description(core workflowWhenToUseText 链)。
                 description: [t.name, t.description].filter(Boolean).join(" — ") || t.id,
             },
         };
@@ -75,15 +112,21 @@ export function projectCollabToWorkflows(templates) {
     }
     return out;
 }
+// ── 模块级注册表(registerTeams 同款可变单例;applyEffective boot+refresh 热更,非粘:整表替换)────────
 let REGISTRY = {};
 export function registerCollabWorkflows(workflows) {
     REGISTRY = { ...workflows };
 }
+/** composite WorkflowScriptStore 的 resolveName 前段:collab 命中 ⇒ 内置 team-discussion 脚本+本模板
+ *  defaultArgs(同名 SHADOW core 内置,design/140 §6 1c)。🔴 Object.hasOwn — `name` 是模型供给的
+ *  (run-workflow-tool 原样传 rawName):裸索引会让 Object.prototype 成员名("constructor"/"toString"/
+ *  "__proto__"…)假命中 ⇒ 零模板注册也能烧真讨论、且同名文件 store 条目被遮蔽(对抗评审 2026-07-11 MED)。 */
 export function resolveCollabWorkflow(name) {
     if (!Object.hasOwn(REGISTRY, name))
         return undefined;
     return { script: TEAM_DISCUSSION_SCRIPT, defaultArgs: REGISTRY[name].defaultArgs };
 }
+/** composite store 的 list() 段(同步——workflow 工具卡只吃同步 list,core 契约注释)。 */
 export function listCollabWorkflows() {
     return Object.values(REGISTRY).map((e) => e.listing);
 }

package/dist/capabilities/oa-tools.d.ts

@@ -1,4 +1,10 @@
 import type { ToolSpec } from "@sema-agent/core";
+/**
+ * OA scenario — tools are thin HTTP clients to the OA backend's existing APIs (read = /api/v1/*,
+ * write = /api/assets/*). The shared service token + the request's principal are forwarded so OA
+ * enforces THAT end-user's RBAC + audit (the service never holds per-user creds). Decoupled: the
+ * service knows no OA schema/DB — OA stays the source of truth (its /api/v1/meta is self-describing).
+ */
 export interface OaCtx {
     baseUrl: string;
     token: string;

package/dist/capabilities/oa-tools.js

@@ -39,6 +39,16 @@ export function oaTools(ctx) {
                 return e; const x = a; return oaFetch(ctx, `/api/assets/${encodeURIComponent(x.type)}/${encodeURIComponent(x.id)}/transition`, { method: "POST", body: { to: x.to, note: x.note ?? null } }); } },
     ];
 }
+// OA business prompt MOVED OUT — migration complete (design/29, 2026-06-05). Persona / 工作准则 / UI
+// markers (::FORM:: / ::GOTO:: / ::SUGGEST:: / ::ISSUE_FORM::) / 分级确认 / 报bug流程 are OA's business,
+// and OA now injects the WHOLE thing per request via `request.systemPrompt` (it holds the service token,
+// content is stable per OA version → cacheable prefix; page context still rides `objective`). Keeping
+// any of it here would just DUPLICATE OA's prompt, so the base is EMPTY — single source of truth = OA.
+// The service stays business-agnostic: it provides the oa_* tools (referenced by NAME from OA's prompt;
+// they carry their own descriptions) and nothing else. `stablePrompt` keeps STABLE→VARIABLE order —
+// OA's systemPrompt is appended after this (empty) base, before core's <user_memory>.
+// (::ISSUE_FORM:: is parsed/rendered + submitted entirely by OA's frontend via OA /api/ai/issue — the
+//  service never touches it; `open_gitea_issue` remains only as the unattended/automated fallback.)
 const OA_SYSTEM = "";
 export const oaPrompt = stablePrompt(OA_SYSTEM);
 //# sourceMappingURL=oa-tools.js.map

package/dist/capabilities/prompt.d.ts

@@ -1,3 +1,17 @@
 import type { PromptProvider } from "@sema-agent/core";
+/**
+ * Build a scenario's prompt provider from just its ROLE base, on core 1.243's 提示词主权 contract:
+ * `stableSystem` returns ONLY the role layer (base + the task's own systemPrompt) and **core appends
+ * the constitution structurally** — harness/safety blocks (Truth/CYBER_RISK/URL_SAFETY), mode blocks,
+ * AND the memory safety/hygiene guidance (`constitutionBlocks`), plus the volatile `<user_memory>`
+ * tail LAST (design/12 prefix-cache discipline; guarded in CI by `assertPromptCacheFriendly`).
+ *
+ * History: the pre-1.243 seam made this helper's whole-prompt replacement silently DROP
+ * core's constitution — oa/code-review/team ran with zero safety blocks. Same batch also moved
+ * MEMORY_SAFETY/MEMORY_HYGIENE into the constitution layer, so the hand-composition this helper used
+ * to do (core 1.62, design/41) would now DOUBLE-inject them — both removed; core owns the discipline
+ * (consolidation mutual-exclusion included). This stays a thin role-layer join so scenarios don't
+ * re-implement the same two-line body five times.
+ */
 export declare function stablePrompt(base: string): PromptProvider;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/capabilities/prompt.js

@@ -1,3 +1,17 @@
+/**
+ * Build a scenario's prompt provider from just its ROLE base, on core 1.243's 提示词主权 contract:
+ * `stableSystem` returns ONLY the role layer (base + the task's own systemPrompt) and **core appends
+ * the constitution structurally** — harness/safety blocks (Truth/CYBER_RISK/URL_SAFETY), mode blocks,
+ * AND the memory safety/hygiene guidance (`constitutionBlocks`), plus the volatile `<user_memory>`
+ * tail LAST (design/12 prefix-cache discipline; guarded in CI by `assertPromptCacheFriendly`).
+ *
+ * History: the pre-1.243 seam made this helper's whole-prompt replacement silently DROP
+ * core's constitution — oa/code-review/team ran with zero safety blocks. Same batch also moved
+ * MEMORY_SAFETY/MEMORY_HYGIENE into the constitution layer, so the hand-composition this helper used
+ * to do (core 1.62, design/41) would now DOUBLE-inject them — both removed; core owns the discipline
+ * (consolidation mutual-exclusion included). This stays a thin role-layer join so scenarios don't
+ * re-implement the same two-line body five times.
+ */
 export function stablePrompt(base) {
     return {
         stableSystem: ({ userSystemPrompt }) => [base, userSystemPrompt].filter(Boolean).join("\n\n"),

package/dist/capabilities/prompts/code-review.d.ts

@@ -1,11 +1,25 @@
+/**
+ * Code-review council copy (bundle-data layer). Pure data — placeholders are `{name}`-style,
+ * filled by the consumer (code-review-council.ts fillPrompt). Guardrail rationale lives with the
+ * consumer's comments; this file is ONLY the words.
+ */
+/** The deployment-owned lens roster. Order = priority (security/correctness first = the bug-finders);
+ *  the caller dials COUNT only (pickLenses), never a named subset. */
 export declare const REVIEW_LENSES: ReadonlyArray<{
     name: string;
     brief: string;
 }>;
+/** Guardrails 2-5: evidence grounding (a CONFIDENCE signal, not a delete), requirement anchoring,
+ *  bucketing, severity×confidence. */
 export declare const GROUNDING: string;
+/** L1 lens reviewer system prompt. Placeholders: {name} {brief} {grounding}. */
 export declare const LENS_SYSTEM_TPL: string;
+/** L2 peer-debate persona (guardrails 5,6). Placeholders: {name} {brief}. */
 export declare const DEBATE_MEMBER_TPL: string;
+/** L2 debate topic body. Placeholders: {objective} {grounding} {findings}. */
 export declare const DEBATE_TOPIC_TPL: string;
+/** Guardrails 4,7: arbitration is not summary — no new findings, ground/dedup/bucket/rank only. */
 export declare const ARBITER_SYSTEM: string;
+/** No-arbiter fallback header ({findings} appended by the consumer). */
 export declare const ARBITER_FALLBACK_HEADER = "[council \u4EF2\u88C1\u65E0\u8F93\u51FA\u2014\u2014\u4EE5\u4E0B\u662F\u672A\u7ECF\u4EF2\u88C1\u7684\u5404 lens \u539F\u59CB\u53D1\u73B0]\n\n";
 //# sourceMappingURL=code-review.d.ts.map

package/dist/capabilities/prompts/code-review.js

@@ -1,3 +1,10 @@
+/**
+ * Code-review council copy (bundle-data layer). Pure data — placeholders are `{name}`-style,
+ * filled by the consumer (code-review-council.ts fillPrompt). Guardrail rationale lives with the
+ * consumer's comments; this file is ONLY the words.
+ */
+/** The deployment-owned lens roster. Order = priority (security/correctness first = the bug-finders);
+ *  the caller dials COUNT only (pickLenses), never a named subset. */
 export const REVIEW_LENSES = [
     { name: "security", brief: "authz/ownership checks, input validation, injection (SQL/command/path), secrets, unsafe deserialization, SSRF, trust boundaries" },
     { name: "correctness", brief: "edge cases, off-by-one, race conditions, resource leaks, missing/incorrect error paths, unhandled rejections" },
@@ -6,6 +13,8 @@ export const REVIEW_LENSES = [
     { name: "tests", brief: "are the risky paths covered? do tests assert behavior (not implementation)? missing edge-case tests" },
     { name: "readability", brief: "naming, dead code, duplication, misleading comments, structure — these are [DESIGN], never [BUG]" },
 ];
+/** Guardrails 2-5: evidence grounding (a CONFIDENCE signal, not a delete), requirement anchoring,
+ *  bucketing, severity×confidence. */
 export const GROUNDING = [
     "RULES:",
     "1. EVIDENCE drives CONFIDENCE (it does NOT delete a finding): cite an exact `path:line` and, whenever you can, **paste the verbatim code snippet** you are flagging. A finding WITH a pasted snippet may carry full confidence/severity; a finding with only a line reference is still allowed but MUST be tagged `[unverified: line-ref only]` and capped at minor severity / low confidence (never a blocker).",
@@ -13,17 +22,21 @@ export const GROUNDING = [
     "3. BUCKET: label each finding [BUG] (provably wrong against the code), [DESIGN] (subjective preference), or [QUESTION]. A design preference is NEVER a [BUG].",
     "4. RATE each: severity (blocker/major/minor) AND confidence (high/med/low).",
 ].join("\n");
+/** L1 lens reviewer system prompt. Placeholders: {name} {brief} {grounding}. */
 export const LENS_SYSTEM_TPL = "You are a {name} code reviewer. Stay strictly in your lane: {brief}.\n" +
     "Read only the files you need — repo_tree to map, then repo_read_file (just-in-time).\n\n{grounding}\n\n" +
     'List findings in your lens only. If you find nothing solid, say "no findings".';
+/** L2 peer-debate persona (guardrails 5,6). Placeholders: {name} {brief}. */
 export const DEBATE_MEMBER_TPL = "You are the {name} reviewer on a review panel ({brief}). Cross-examine the findings in " +
     "the shared transcript: CORROBORATE or REBUT others' claims in your area (raising/lowering their " +
     "confidence), and DEFEND or WITHDRAW your own if rebutted.\n" +
     "You MAY call repo_read_file to VERIFY ONE specific DISPUTED finding (quote the exact path:line) — do " +
     "NOT re-review the whole repo. A finding with no path:line + code quote is invalid. Be concise.";
+/** L2 debate topic body. Placeholders: {objective} {grounding} {findings}. */
 export const DEBATE_TOPIC_TPL = "Cross-examine these specialist code-review findings for: {objective}\n\n{grounding}\n" +
     "5. CONFIDENCE: peer corroboration raises it; an unrebutted rebuttal lowers it; drop findings that " +
     "collapse under scrutiny.\n\nFindings to debate:\n\n{findings}";
+/** Guardrails 4,7: arbitration is not summary — no new findings, ground/dedup/bucket/rank only. */
 export const ARBITER_SYSTEM = "You are the NEUTRAL ARBITER of a code-review council. You are given findings from independent " +
     "specialist reviewers. You do NOT add new findings and do NOT re-review. Your only job:\n" +
     "- TIER by grounding, do NOT silently drop real findings: a finding that PASTES the code keeps its " +
@@ -35,5 +48,6 @@ export const ARBITER_SYSTEM = "You are the NEUTRAL ARBITER of a code-review coun
     "Output the final review: a 2-3 line summary, then findings grouped by bucket then severity, each as " +
     "`path:line` — the problem — a concrete fix. Never invent files or symbols. If a whole lens reported " +
     "nothing groundable, say so rather than inventing.";
+/** No-arbiter fallback header ({findings} appended by the consumer). */
 export const ARBITER_FALLBACK_HEADER = "[council 仲裁无输出——以下是未经仲裁的各 lens 原始发现]\n\n";
 //# sourceMappingURL=code-review.js.map

package/dist/capabilities/prompts/identity.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Sema identity — the branded role layer for the `default` scenario (bundle-data layer; wording
+ * history: neutralized — no baked model/vendor/protocol facts, because the brain
+ * stack has both OpenAI-compatible AND Anthropic-compatible legs and any baked substrate claim is the same
+ * class of lie the neutralization removed. The anti-"I am Claude" design is kept.)
+ */
 export declare const SEMA_IDENTITY: string;
 //# sourceMappingURL=identity.d.ts.map

package/dist/capabilities/prompts/identity.js

@@ -1,3 +1,9 @@
+/**
+ * Sema identity — the branded role layer for the `default` scenario (bundle-data layer; wording
+ * history: neutralized — no baked model/vendor/protocol facts, because the brain
+ * stack has both OpenAI-compatible AND Anthropic-compatible legs and any baked substrate claim is the same
+ * class of lie the neutralization removed. The anti-"I am Claude" design is kept.)
+ */
 export const SEMA_IDENTITY = "You are Sema, an AI agent built by the Sema team. You act through tools to get real work done.\n" +
     "You run on a large language model chosen and configured by your operator — you are NOT Claude, NOT " +
     "GPT, and NOT made by Anthropic or OpenAI. If asked who you are or which model you are, answer honestly " +

package/dist/capabilities/prompts/team.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Built-in team personas (bundle-data layer) — GENERIC personas only; the business prompt is
+ * appended at call time by the consumer (team.ts), never baked in here.
+ */
 export declare const TEAM_PERSONAS: {
     readonly analyst: "You analyze the task: lay out the key considerations, options, and trade-offs. Be concrete.";
     readonly critic: "You challenge the analysis: surface gaps, wrong assumptions, risks, and stronger alternatives.";

package/dist/capabilities/prompts/team.js

@@ -1,3 +1,7 @@
+/**
+ * Built-in team personas (bundle-data layer) — GENERIC personas only; the business prompt is
+ * appended at call time by the consumer (team.ts), never baked in here.
+ */
 export const TEAM_PERSONAS = {
     analyst: "You analyze the task: lay out the key considerations, options, and trade-offs. Be concrete.",
     critic: "You challenge the analysis: surface gaps, wrong assumptions, risks, and stronger alternatives.",

package/dist/capabilities/repo-tools.d.ts

@@ -1,9 +1,19 @@
 import type { ToolSpec } from "@sema-agent/core";
+/**
+ * Read-only repository tools backed by a Git host (Gitea) HTTP API — NOT a clone/shell on the runner.
+ *
+ * The agent reads a repo just-in-time (tree → read file → PR diff) through scoped function tools; the
+ * read token lives only in this server-side client (never in the model/sandbox), and tools are bound
+ * to exactly the repo the task was given. This is the lightweight path for code review (read + reason);
+ * running tests/linters would need a sandboxed ExecutionEnv (a deliberate future extension, not here).
+ */
 export interface RepoCoords {
     owner: string;
     repo: string;
 }
+/** Parse `owner/name` or a repo URL (e.g. http://host:9999/AI-Only/sema-server.git). */
 export declare function parseRepo(input: string): RepoCoords;
+/** Thin read-only Gitea API client. Built once at startup; bound to a repo per task. */
 export declare class GiteaClient {
     private readonly baseUrl;
     private readonly token?;
@@ -15,5 +25,6 @@ export declare class GiteaClient {
     readFile(coords: RepoCoords, path: string, ref: string): Promise<string>;
     pullDiff(coords: RepoCoords, index: number): Promise<string>;
 }
+/** Build the read-only repo tool set bound to one repo (cheap per-task closure; the client is shared). */
 export declare function repoToolsFor(client: GiteaClient, coords: RepoCoords): ToolSpec[];
 //# sourceMappingURL=repo-tools.d.ts.map

package/dist/capabilities/repo-tools.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+/** Parse `owner/name` or a repo URL (e.g. http://host:9999/AI-Only/sema-server.git). */
 export function parseRepo(input) {
     const s = input.trim().replace(/\.git$/, "");
     const m = /^[a-z]+:\/\/[^/]+\/(.+)$/i.exec(s);
@@ -10,7 +11,9 @@ export function parseRepo(input) {
 }
 const MAX_FILE_BYTES = 96 * 1024;
 const MAX_TREE_ENTRIES = 2000;
+/** Bound each Git-host call so a slow/hung host can't pin a review lens to its whole deadline. */
 const REQUEST_TIMEOUT_MS = 15_000;
+/** Thin read-only Gitea API client. Built once at startup; bound to a repo per task. */
 export class GiteaClient {
     baseUrl;
     token;
@@ -43,6 +46,10 @@ export class GiteaClient {
     }
     async readFile(coords, path, ref) {
         const { owner, repo } = coords;
+        // `encodeURIComponent` does NOT escape "." — so a `..` segment survives the per-segment encode and the
+        // WHATWG URL parser collapses it when `fetch` builds the request, letting a crafted `path` climb out of
+        // `/repos/<owner>/<repo>/contents/` to any endpoint the read token can reach (cross-repo / admin). The
+        // tools are contractually bound to exactly one repo (see header), so reject traversal before it hits fetch.
         const segments = path.split("/").filter(Boolean);
         if (segments.some((s) => s === "..")) {
             throw new Error(`invalid path "${path}" (".." segments are not allowed)`);
@@ -62,6 +69,7 @@ export class GiteaClient {
         return text.length > MAX_FILE_BYTES * 4 ? text.slice(0, MAX_FILE_BYTES * 4) + "\n…[diff truncated]" : text;
     }
 }
+/** Build the read-only repo tool set bound to one repo (cheap per-task closure; the client is shared). */
 export function repoToolsFor(client, coords) {
     const ref = (r) => (r ? Promise.resolve(r) : client.defaultBranch(coords));
     return [

package/dist/capabilities/sandbox-file-send.d.ts

@@ -1,24 +1,119 @@
+/**
+ * SendUserFile v2 — the sandbox-lane file source (clay ruling 2026-07-14: Plan B direct upload).
+ *
+ * The tool cannot reach the task's sandbox through core (ToolExecuteContext carries no env handle — core
+ * keeps the per-task ExecutionEnv private to its prepare-task closure). But the server BUILDS the
+ * `executionEnvFactory` core calls, and the factory context carries `taskId` — so we wrap OUR OWN factory
+ * (same posture as withWorktreeIsolation) and keep a replica-local taskId → env registry, unregistering
+ * when core destroys the env. No core change, no parallel abstraction — pure deployment glue on a seam
+ * the deployment already owns.
+ *
+ * The send itself is the anti-relay shape ([747]; k8s workspace-snapshot posture): the server presigns a
+ * single-object PUT (120s, method-bound, STAGING key — 修3), the SANDBOX `curl -T`s the file straight to S3 — bytes never
+ * relay through the server, S3 credentials never enter the sandbox. Tenant isolation = the sandbox can
+ * only read its own filesystem, which is exactly the tenant's task workspace; that is why this lane is
+ * multi-tenant-safe while the host lane never is (host-lane multi-tenant is permanently closed).
+ *
+ * ssh lane (backfill 2026-07-14): the SAME send chain works over the ssh adapter unchanged — its exec
+ * face is contract-identical (Result{stdout,stderr,exitCode}, stderr split, `options.timeout` in SECONDS
+ * ×1000, remote-env-ssh.ts) and the peer is assumed LINUX (`stat -c %s` = GNU/busybox; the fleet is all
+ * Linux — a macOS peer's `stat -f %z` dialect would fail LOUD at the exit-code/stat-parse guards, never
+ * silently). But the TENANT judgment INVERTS: an ssh peer is ONE persistent real machine shared by every
+ * task (sshExecutionEnvFactory ignores ctx — same host + same mountPath for all tasks; destroy() only
+ * disconnects, files persist; capabilities.isolation:false). "Scoped read = tenant boundary" does NOT
+ * hold there, so the ssh lane is SINGLE-USER ONLY (same gate as host) — see `sandboxSendLaneEnabled`.
+ *
+ * The presigned PUT URL is a capability secret: it never enters model context (the tool returns delivery
+ * metadata only) and is REDACTED from every error surfaced from here (curl stderr may echo the URL).
+ *
+ * RESIDUAL CLOSED (修3, 三路复审 2026-07-15; was the accepted dual-review residual of 2026-07-14): the URL
+ * still rides the exec command line (readable via /proc inside the sandbox), but it is now a capability on
+ * a STAGING key only — the server promotes staging→final with its own creds (CopyObject), deletes staging,
+ * and size-verifies the FINAL object, whose write URL never existed outside the server. A /proc reader can
+ * no longer rewrite the delivered object after verification or skew the ledgered size (see
+ * PreparedDirectUpload in send-user-file.ts for the full promotion contract).
+ */
 import type { ExecutionEnv, ExecutionEnvFactory } from "@sema-agent/core";
 import type { IssuedFileLink, PreparedDirectUpload } from "../plugins/send-user-file.js";
+/** Leak backstop (codex review HIGH): core skips destroy on suspend/review paths and a crash may skip it
+ *  entirely — the suspendVM wrap covers the common case, this bound covers the rest. Far above any real
+ *  per-replica concurrency. 修6: at the cap the registry REFUSES the new registration instead of FIFO-evicting
+ *  the oldest entry — every entry here is live-until-destroy/suspend by construction, so there is no
+ *  "terminal/stale" liveness verdict to evict on, and silently breaking an EXISTING live task's send face to
+ *  admit a new one inverts the harm (the old FIFO victim's SendUserFile would report "no sandbox attached"
+ *  while its env kept executing). The refused task gets a TYPED capacity error at send time instead. */
 export declare const TASK_ENV_REGISTRY_MAX = 512;
+/** Replica-local taskId → live ExecutionEnv(s). Registered by the factory wrap, dropped on destroy/suspend.
+ *
+ *  修5 (concurrent-generation guard): deployments WITHOUT a run-store single-active-session claim can race
+ *  two legs of one session through the factory concurrently — previously the second registration silently
+ *  OVERWROTE the first, so leg A's later SendUserFile resolved to leg B's env (wrong-generation read/upload).
+ *  The registry now keeps EVERY live env per key and `get()` fail-louds on ambiguity: neither leg can silently
+ *  read the other's sandbox, and the moment one generation is destroyed/suspended the survivor resolves again.
+ *  (Rejecting the second factory call outright was considered and discarded: a stale never-destroyed entry —
+ *  crash/no-destroy path — would then brick every future leg of that task, and the factory seam must not fail
+ *  env creation for a send-face bookkeeping conflict. Deployments WITH the single-active-session claim
+ *  serialize legs upstream and never see this state.) */
 export declare class TaskEnvRegistry {
     private readonly map;
+    /** 修6: taskIds whose registration was refused at the cap — lets get() report the TRUE reason (typed
+     *  capacity error, not a misleading "no sandbox attached"). Bounded by the same cap (marker-only). */
     private readonly refusedAtCapacity;
     private liveCount;
+    /** Resolve the ONE live env for a task. Throws typed errors on the two governed failure states:
+     *  ambiguity (修5 — concurrent generations both live) and capacity refusal (修6). Returns undefined when
+     *  the task simply has no registered env (caller reports "no sandbox attached"). */
     get(taskId: string | undefined): ExecutionEnv | undefined;
+    /** Wrap the deployment's own factory: register each minted env under the task's CANONICAL id — core hands
+     *  the factory the raw `spec.taskId` but gives tools `hostTaskId = spec.taskId ?? sessionId` (prepare-task
+     *  262/320/428; the sync `/v1/tasks` leg deliberately sets no spec.taskId), so the registry key MUST apply
+     *  the same fallback or every sync-leg lookup misses (codex review HIGH). Unregister when core calls
+     *  destroy() (identity guard: only the env's OWN entry is dropped — a replacement env for a reused key must
+     *  not be evicted by the old one's late destroy). core SKIPS destroy on durable suspend/review (runtask
+     *  keeps the env for the snapshot) — wrap suspendVM the same way so a suspended task doesn't pin its env
+     *  here forever; the bounded-size backstop covers any remaining no-destroy crash path. */
     wrapFactory(factory: ExecutionEnvFactory): ExecutionEnvFactory;
 }
+/**
+ * Which REMOTE_EXEC lanes may register the sandbox-send TaskEnvRegistry (and thus mount the sandbox-lane
+ * SendUserFile source), under which tenancy gate. The judgment per lane (2026-07-14 ssh backfill review):
+ *
+ *  - e2b / k8s: one task = one disposable sandbox; the sandbox filesystem IS the tenant's task workspace,
+ *    so a sandbox-scoped read is tenant-scoped by construction → open to any tenant.
+ *  - ssh: the peer is ONE persistent real machine SHARED across tasks (factory ignores ctx: every task
+ *    gets the same host+mountPath; destroy=disconnect only, files persist). Tenant A's task can read the
+ *    residue of tenant B's task → the isolation premise FAILS. Multi-tenant here would be an
+ *    arbitrary-host-path-read → public-URL exfil face, so the lane opens ONLY single-user
+ *    (`requirePrincipal !== true`), the exact gate the host lane uses. NOT a lane to "fix later with a
+ *    per-task workspace": tasks legitimately operate outside any workspace on a real host (design/61 —
+ *    batch deployment), so per-task dirs would not restore the boundary anyway.
+ *  - adb / local-docker / host / unset: no registry (host+unset use the local-fs source in main.ts;
+ *    adb/local-docker remain a follow-on).
+ */
 export declare function sandboxSendLaneEnabled(provider: string | undefined, requirePrincipal: boolean): boolean;
+/** Single-quote a path for POSIX sh (the only metacharacter inside '' is ' itself). */
 export declare function shq(s: string): string;
+/** Strip the capability URL (and any SigV4 signature) from text before it reaches an error/log — including
+ *  the percent-encoded forms an adapter may echo (the k8s exec transport carries the command in a request
+ *  URI, so an error can quote the URL re-encoded; codex review MED). */
 export declare function redactPutUrl(text: string, url: string): string;
 export interface SandboxFileSendDeps {
     registry: TaskEnvRegistry;
+    /** `scope` = the caller's VERIFIED principal (ToolExecuteContext.principal) — keys the hashed scope segment
+     *  in the object key + rides back on IssuedFileLink.scope for the ledger. Absent on single-user lanes. */
     prepare: (filename: string | undefined, scope?: string) => PreparedDirectUpload;
     maxBytes: number;
 }
+/** The live object `createSandboxFileSend` produces — a bare callable (deps captured in closure), mirroring
+ *  the sibling `SendUserFileIssuer` role (send-user-file.ts) one level down: this is the sandbox-lane half. */
 export type SandboxFileSend = (path: string, ctx: {
     taskId?: string;
     principal?: string;
 }) => Promise<IssuedFileLink>;
+/**
+ * The sandbox-lane `send` seam for the SendUserFile tool: in-sandbox stat (existence + regular file +
+ * size cap, BEFORE any signing) → presign PUT → in-sandbox `curl -T` → finalize the user-facing link.
+ * Throws typed Errors (redacted) — the tool reports them per file.
+ */
 export declare function createSandboxFileSend(deps: SandboxFileSendDeps): SandboxFileSend;
 //# sourceMappingURL=sandbox-file-send.d.ts.map