@sema-agent/server 1.322.0 → 2.0.0

package/dist/task-workflow.js

@@ -1,26 +1,82 @@
+/**
+ * Workflow super-set unlock — map the per-task `body.selfOrchestration` intent onto
+ * `TaskSpec.selfOrchestration`, the gate that mounts core's LLM-authored `run_workflow` engine (the workflow.ts
+ * agent/parallel/pipeline orchestrator). Same shape as the rank-1 roster gap: the engine (core run_workflow +
+ * workflow.ts) is BUILT, but nothing mapped a body field to the per-task spec flag, so it was unreachable over HTTP
+ * (capabilities advertised `workflows:true` but the LLM could never call run_workflow).
+ *
+ * Gating:
+ *  - DEPLOYMENT: `selfOrchestrationEnabled` must be on (the workflowScriptRunner + stores are wired). Otherwise a set
+ *    flag is a harmless no-op (core fail-closes run_workflow without the sandbox runner), so it's dropped for clarity.
+ *  - MULTI-TENANT: honored ONLY when a per-principal entitlement RESOLVER is wired (`hasEntitlementResolver`). 🔴 core's
+ *    `allowWorkflows` (RuntimeCaps) is TIGHTEN-ONLY — a resolver can only DENY; `undefined` = NO restriction, so the
+ *    deployment capability governs. Therefore WITHOUT a resolver the engine would mount run_workflow UNGATED for every
+ *    tenant. So we fail-closed here (defense-in-depth: a misconfigured multi-tenant deployment with no entitlement
+ *    source must NOT leak the LLM-authored workflow engine). WITH a resolver, core enforces `allowWorkflows`
+ *    per-principal (deny → fail-closed). Single-user (owns its own worker) honors directly. Three-gate: engine-can ∧
+ *    center-may(allowWorkflows) ∧ shell-show.
+ */
 export function selfOrchestrationFromBody(body, config, hasEntitlementResolver) {
     if (body.selfOrchestration !== true || !config.selfOrchestrationEnabled)
         return undefined;
     if (config.requirePrincipal !== true)
-        return true;
-    return hasEntitlementResolver ? true : undefined;
+        return true; // single-user: honor directly
+    return hasEntitlementResolver ? true : undefined; // multi-tenant: fail-closed unless an entitlement resolver gates it
 }
+/**
+ * §4 (Fork) — map the per-task `body.enableFork` intent onto `TaskSpec.enableFork`. core 1.257 (design/136 BREAKING)
+ * RETIRED the standalone `Fork` tool; a fork is now `Agent(subagent_type:"fork")`, and `enableFork` is one of the two
+ * governance axes (`forkGovernanceDenial(spec.enableFork, runtimeCaps.allowFork)`) that gate it.
+ *
+ * 🔴 CONSUME-CRITICAL — the default FLIPPED to opt-OUT: core now treats `enableFork === undefined` as **available**
+ * (only an EXPLICIT `enableFork:false` / `allowFork:false` denies — CC's default posture). So where the SERVICE intends
+ * to DENY, it must return `false` EXPLICITLY — the old "return undefined = not granted" is now fail-OPEN.
+ *  - DEPLOYMENT posture OFF (`!forkEnabled`, e.g. multi-tenant default): `false` (explicit deny — preserve opt-in posture).
+ *  - PER-TASK OPT-OUT (`body.enableFork === false`): `false` (any tenancy).
+ *  - SINGLE-USER TURNKEY: `true` — DEFAULT ON for the LLM (clay 2026-07-01). (core still only lets it fork where the
+ *    session store is fork-capable and never inside a fork / read-only band — graceful degrade, no capability lie.)
+ *  - MULTI-TENANT: `true` ONLY with a per-principal entitlement RESOLVER wired (core then enforces `allowFork`
+ *    tighten-only per-principal); WITHOUT a resolver `false` (fail-closed — `allowFork` is tighten-only so an absent
+ *    resolver = `undefined` = ungated, and now `enableFork:undefined` also auto-grants, so the service must hard-deny).
+ */
 export function enableForkFromBody(body, config, hasEntitlementResolver) {
     if (!config.forkEnabled)
-        return false;
+        return false; // posture must enable the primitive (FORK_ENABLED; posture-OFF multi-tenant) — explicit deny (opt-OUT default)
     if (body.enableFork === false)
-        return false;
+        return false; // explicit per-task opt-OUT (any tenancy)
     if (config.requirePrincipal !== true)
-        return true;
-    return hasEntitlementResolver;
+        return true; // single-user turnkey: DEFAULT ON for the LLM
+    return hasEntitlementResolver; // multi-tenant: honor iff a resolver gates it, else fail-closed (core enforces allowFork per-principal, tighten-only)
 }
+/**
+ * The workflow-script MODEL allowlist (`agent({model})` picks). core is
+ * fail-closed: NO allowlist configured ⇒ `WorkflowModelNotAllowedError` on ANY model pick, which on a TOC
+ * single-user deployment broke clay's own dual-model scripts (决策 v4-pro + 执行 v4-flash) out of the box —
+ * the operator configured every catalog entry themselves, so there is nothing to protect them from.
+ *  - Explicit `SELF_ORCHESTRATION_MODELS` always wins (any tenancy — the operator's deliberate narrowing).
+ *  - SINGLE-USER: default to the deployment's OWN model catalog (`Object.keys(models)`).
+ *  - MULTI-TENANT: keep core's fail-closed empty default (a model pick is a cost/capability grant the
+ *    operator must make explicitly; a tenant script must not self-select the expensive rung).
+ * Returns undefined when no allowlist should be set (core then fail-closes picks; the script's `agent()`
+ * without a model still runs on the workflow's default role — only PICKING is gated).
+ */
 export function workflowModelAllowlistFor(config) {
     if (config.selfOrchestrationModels.length > 0)
         return config.selfOrchestrationModels;
     return config.requirePrincipal !== true ? Object.keys(config.models) : undefined;
 }
-export const RETAIN_SUBAGENT_TTL_MS_CAP = 24 * 60 * 60 * 1000;
+/** design/122 caps for a caller-supplied `retainSubagentSessions` object (core defaults 30min/16; the ledger
+ *  is run-scoped and fully released at parent end, so these only bound the WITHIN-RUN memory pin). */
+export const RETAIN_SUBAGENT_TTL_MS_CAP = 24 * 60 * 60 * 1000; // 24h — far above any sane interactive run
 export const RETAIN_SUBAGENT_MAX_CAP = 64;
+/**
+ * design/122 (core 1.225): normalize an untrusted `body.retainSubagentSessions` onto the TaskSpec field.
+ * `true`/`false` pass through (core's own defaults apply); an object keeps only NUMERIC ttlMs/max, each
+ * clamped to a positive integer under the cap (retention pins settled child sessions in memory for the
+ * parent run's lifetime — the knob must not become a caller-controlled resource hold). Anything malformed →
+ * undefined = OFF (core default). Defensive, never throws: RESUME re-runs resolveSpec WITHOUT the HTTP-layer
+ * validation, so this normalizer is the single guard on every path.
+ */
 export function normalizeRetainSubagentSessions(raw) {
     if (raw === true || raw === false)
         return raw;
@@ -31,9 +87,20 @@ export function normalizeRetainSubagentSessions(raw) {
     const ttlMs = clamp(o.ttlMs, RETAIN_SUBAGENT_TTL_MS_CAP);
     const max = clamp(o.max, RETAIN_SUBAGENT_MAX_CAP);
     if (ttlMs === undefined && max === undefined)
-        return undefined;
+        return undefined; // an empty/garbage object grants nothing
     return { ...(ttlMs !== undefined ? { ttlMs } : {}), ...(max !== undefined ? { max } : {}) };
 }
+/**
+ * Per-task wall clock by TENANCY POSTURE (clay 2026-07-04, make-real 教训①:600s 默认墙钟砍掉了健康推进的
+ * 长任务/chaos 恢复 run):
+ *  - SINGLE-USER turnkey(`requirePrincipal !== true`)= the user IS the superadmin → **NO wall clock**
+ *    (undefined; core arms none — its separate wedge safety-net still catches a stuck tool call, so "no wall"
+ *    never means "hangs forever"). CC has no whole-task decapitation either.
+ *  - MULTI-TENANT: base 2400s (big tasks — council/debate/team — 3600s). (PAIR-REVIEW F-4 附带修:此行
+ *    曾写 600s/1500s 与代码漂移——真值以下方 base 为准。)
+ *  - Explicit `TASK_TIMEOUT_SEC` wins in ANY tenancy (the operator's deliberate wall) and keeps its documented
+ *    raise-only floor (`Math.max` with the base, so a misconfigured low value cannot shrink a council budget).
+ */
 export function taskWallClockSec(envTimeoutSec, requirePrincipal, big) {
     const base = big ? 3600 : 2400;
     if (envTimeoutSec > 0)

package/dist/tool-approval.d.ts

@@ -1,17 +1,41 @@
 import { type AskRequest } from "@sema-agent/core";
+/** A live approval frame delivered to whoever tails this run's stream. `type` IS the SSE event name (named-event
+ *  convention, same as question). The shell renders `tool_approval` as the CC three-choice card and dismisses on
+ *  `tool_approval_complete`. */
 export interface ToolApprovalFrame {
     type: "tool_approval" | "tool_approval_complete";
     approvalId: string;
+    /** "tool_approval" only: which tool asked (canonical core name as core sent it) + the policy's ask message. */
     toolName?: string;
+    /** [1939] "tool_approval" only: **core 的 tool-call id**(`AskRequest.toolCallId`,逐字透传)——消费端用它
+     *  把审批卡锚到助手消息里那个 `tool_use` 块。`approvalId` 是审批自己的新 uuidv7、与该块**无关**,
+     *  此前帧上只有它 ⇒ 两个宿主都只能拿它当 key 铸卡,而那个 id 之后再没有任何帧提到过,卡永远停在
+     *  awaiting_approval。「拿最近一次 tool_start 当锚」这类补偿也不成立:**审批帧比 `tool_start` 先到**
+     *  (cli 帧级取证 4020ms vs 4142ms)。durable(parked)腿本来就存着这个值(parked-decide.ts),
+     *  本键 = 把 live 腿的字段集与它对齐。闭合帧(`tool_approval_complete`)不带——它按 approvalId 消卡,
+     *  多一个锚只会多一份歧义。 */
     toolCallId?: string;
+    /** **只在委派子代的 ask 上在场**(现判别键 = {@link ToolApprovalFrame.fromSubagent};本字段本身
+     *  [1546] MED-1 后不再是判别式,core JSDoc 钉明「不是子代判别键」)。值 = 子代的 core session id
+     *  (与 task_progress.taskId / bg_notification.sessionId 同值域,可关联子代行)。旧壳(< fromSubagent
+     *  接线)兜底按在场性渲染归属标仍然正确。 */
     sourceTaskId?: string;
+    /** [1550] RB-39②:core 1.378 显式判别键——委派子代 gate 发起的 ask 恒带 `true`,受信 internals 事实
+     *  (worker 不可伪造/不可抑制)。取代 [1546] MED-1 的「在场 ∧ ≠ 宿主 sessionId」权宜判别式。 */
     fromSubagent?: true;
+    /** [1550] 展示身份(子代 agent 名)——UNTRUSTED-for-display(core 未做秘密脱敏)→ redactSecrets 后渲。
+     *  仅子代 ask 上可能在场(core 未必总能解析出名字)。 */
     sourceAgentName?: string;
     message?: string;
+    /** "tool_approval" only: the tool call's args, secret-redacted, UNTRUSTED-for-display. Absent (with
+     *  `argsOmitted: true`) when over the byte cap or unserializable. */
     args?: unknown;
     argsOmitted?: boolean;
+    /** "tool_approval_complete" only: how the ask settled. `allowed`/`denied` = a human decision; `expired` = TTL/
+     *  abort/disconnect (fail-closed deny the shell should render as such). Cosmetic dialog-dismiss. */
     outcome?: "allowed" | "denied" | "expired";
 }
+/** The per-run context `ask` recovers via ALS (mirrors QuestionRunContext + sessionId, which keys the allow-all). */
 export interface ToolApprovalRunContext {
     taskId: string;
     sessionId?: string;
@@ -20,6 +44,7 @@ export interface ToolApprovalRunContext {
     abortSignal?: AbortSignal;
 }
 export type ToolApprovalDecision = "allow" | "allow_session" | "deny";
+/** Validate the respond body — the closed three-choice enum (rationale in the module header). */
 export declare function parseToolApprovalResponse(body: unknown): {
     ok: true;
     value: ToolApprovalDecision;
@@ -28,28 +53,94 @@ export declare function parseToolApprovalResponse(body: unknown): {
     ok: false;
     error: string;
 };
+/** @deprecated design/158 N22: renamed to {@link parseToolApprovalResponse} — unifies the HITL trio's parse-fn
+ *  vocabulary (`parseQuestionResponse` / `parseElicitationResponse` / `parseToolApprovalResponse`, all "the
+ *  human's reply body"; `ToolApprovalDecision` itself is unchanged — it names the allow/deny VALUE, not the
+ *  parse function). Kept as a compat alias. */
 export declare const parseToolApprovalDecision: typeof parseToolApprovalResponse;
+/**
+ * Coordinates the live tool-approval HITL for the singleton runner. Process-local + same-replica (the pending map is
+ * in memory, like QuestionCoordinator): a respond that lands on another replica finds nothing → 404. Present (passed
+ * into `RunnerDeps.onAsk` + the respond route) ONLY when `TOOL_APPROVAL_ENABLED` — absent ⇒ core's `resolveAsk`
+ * keeps its headless auto-deny for every ask ([819]⑤ fail-closed default, zero behavior change).
+ *
+ * G1 interplay (core 1.290 sync-ask knob, prepare-task): with an onAsk present, a NON-safety ask with NO per-task
+ * `durableApproval` skips the durable park and resolves on this sync leg (zero checkpoint, CC-interactive latency).
+ * A durable-approval deployment (`DURABLE_APPROVAL=true` sets spec.durableApproval on every task) keeps parking every
+ * ask durably — this bridge then only serves legs where the park machinery is absent. Safety asks (irreversible/
+ * egress) always keep the durable park when a checkpointStore exists (core's condition, not ours).
+ */
 export declare class ToolApprovalCoordinator {
     private readonly als;
     private readonly pending;
+    /** Per-capability session grants — keys = sessionAllowKey(owner, sessionId, category) (修2; bounded). */
     private readonly allowAllSessions;
+    /** [1546] HIGH-1(broker)→[1559]四 core 产品裁定「多活集合+广播+首决胜出」:per-(owner, host-session)
+     *  的**当前活跃连接集合**——boundAsk 闭包只携身份,emit 时广播给该 key 下**全部**活连接(宿主重连/
+     *  attach 新 SSE 时 runWithContext 各自注册进同一集合,谁也不覆盖谁);查无活连接 = "unavailable"
+     *  (G1 回路)。旧单指针形的缺口(file-backed local mode 无单活跃 run 409 守卫时,两个真正并发的
+     *  runWithContext 会让后到者的指针覆盖先到者,先到连接的卡静默不可达——core 点名与「1.334 标已告知
+     *  须以投递确认为前提」同族)已随本集合改造解:后到者只是加入集合,不挤走先到者。首个 respond()
+     *  经 `pending` map 天然 CAS 胜出(第二个 respond() 撞 id 已被删 → 404),其余连接靠 completion 帧
+     *  收 dismiss 通知(见 askBroadcast)。 */
     private readonly streams;
     private readonly ttlMs;
     constructor(ttlMs?: number);
+    /** Broker key:宿主 session 优先(retained/续聊子代跨 SSE 找得到新流),sessionless adhoc 退 taskId。
+     *  并发审查加固:显式维度前缀(`"session"`/`"adhoc"`)分隔两个取值域,不再靠 `task:` 字符串前缀"祈祷"
+     *  不会跟一个真实 sessionId 字面重合——此前形式 `sessionId ?? "task:"+taskId` 里,若某会话的
+     *  sessionId 恰好等于另一条 adhoc 流的 `"task:"+taskId`,两者会算出同一把 key(现网因 taskId 由
+     *  服务端 uuidv7 铸造、请求到达前不可预知而几乎不可达,但维度未加标签是编码层面的真实缺口)。 */
     private streamKey;
+    /** Run `fn` with the per-run approval context ambient. On exit, notify every pending broadcast ask that this
+     *  ctx is no longer a live target — an ask only dies once ALL its targets are gone (fail-closed backstop, the
+     *  inverse of question's release-unanswered — but no longer a blunt "any one target exits ⇒ kill it" rule,
+     *  see {@link PendingApproval.onTargetGone}).
+     *  [1535] 注意([1539] core 点名的火):委派子代的 ask 经 {@link boundAsk} 落 pending 时不带
+     *  `targetCtxs`/`onTargetGone`(只有 `originTaskId === undefined` 的宿主自身条目才带)——session-scoped
+     *  bg 子代活过宿主 turn 时其未决卡不被这里触碰(TTL/abortSignal 仍兜底)。 */
     runWithContext<T>(ctx: ToolApprovalRunContext, fn: () => Promise<T>): Promise<T>;
+    /** 测试/可观测性钩子:该 (owner, session/taskId) broker key 下当前活跃连接数——断言多连接注册/清扫
+     *  行为时用,免得伸手进私有内部状态。 */
     liveConnectionCount(owner: string | null, sessionId: string | undefined, taskId: string): number;
+    /** `RunnerDeps.onAsk`. core's resolveAsk calls this for each policy `ask` on the sync leg. [879] G1 三值化
+     *  (core 1.295):boolean = 人的决定;`"unavailable"` = 本 ask 到达时刻判无活人可同步送达 —— core 以
+     *  approverUnavailable 回路把这只 ask 交回 suspendAsk 走 durable park(park 设施缺席的部署 core 自己
+     *  fail-closed deny)。1.199 的「durable 部署不 wire onAsk」止血就此撤除:恒 wire,park 与 live 卡两全。
+     *  Arrow property so it can be passed as `onAsk: coordinator.ask` with `this` bound. */
     ask: (req: AskRequest, signal?: AbortSignal) => Promise<boolean | "unavailable">;
+    /** [1535] server 半场(审批链战役,[1539] 定谳断点①的修;[1546] HIGH-1 broker 形):宿主 sync
+     *  streaming 腿在装配点以本闭包挂 `spec.onAsk`;core 继承链(parentConstraints 冻结
+     *  `spec.onAsk ?? deps.onAsk`,1.294 起)把它逐 ancestor 冻给每个委派子代——子代(bg/嵌套孙代)的
+     *  权限 ask 不再依赖 ALS,直达宿主 live 流的审批卡。**闭包只携身份**(owner/taskId/sessionId),
+     *  emit 时经 broker 取该 (owner, session) 的「当前」活跃流(宿主重连/续聊的新 SSE 自动接卡;
+     *  internalsSnapshot 冻结的闭包因此永不携死流)。查无活流 = "unavailable"(G1 回路:durable 部署
+     *  park;inherited plain-ask 的 park 回路 = core RB-39①,落地前该臂 = deny,与 1.257 前行为一致)。 */
     boundAsk: (identity: {
         owner: string | null;
         taskId: string;
         sessionId?: string;
     }) => ((req: AskRequest, signal?: AbortSignal) => Promise<boolean | "unavailable">);
+    /** 广播版裁决路径——`ask()`(ALS,恒单元素数组)与 `boundAsk`([1559]四多活集合,可能多元素)共用。
+     *  全体 `ctxs` 保证同一 (owner, sessionId)(streamKey 分组不变式;单元素数组平凡成立)。
+     *
+     *  [1559]三 emit-race 加固(回黑板 [1558]三1,core 确认方向):「等 emit 完成」与「等
+     *  TTL/abort/respond 三选一落定」显式 race——`emit` 的类型契约允许异步实现(durable-append 目标),
+     *  若挂死,旧形 `await ctx.emit(...)` 会让整条 ask 乃至调用方 turn 一起卡死,TTL/abort 定时器虽已
+     *  触发也无人读取其结果。核心不变式:race 由非人类结局(TTL/abort)先赢、且 emit 广播尚未有任何一路
+     *  确认完成时,不可扣一个武断的「deny」终局(不知道卡是否曾送达任何人)——按 G1 回路交
+     *  "unavailable"。人类 respond() 落地的裁决永远照旧信任、不受本判据影响:它只可能在 approvalId 已经
+     *  送达某个客户端之后发生(respond 需要客户端手上有这个 id),这是 outcome==="allowed"/"denied" 与
+     *  "expired"(TTL/abort/run-exit-cleanup/emit 广播全灭四类共用)的天然分野。 */
     private askBroadcast;
+    /** `POST /v1/tool-approvals/:id/respond` — settle a parked approval with the shell's decision. Owner-gated with a
+     *  404 (no existence oracle), body validated first (400 is existence-independent) — question/steer parity. The HTTP
+     *  layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
     respond(id: string, principal: string | undefined, body: unknown): {
         status: number;
         body: unknown;
     };
+    /** Test/observability hooks. */
     pendingCount(): number;
     sessionAllowedCount(): number;
 }