@sema-agent/server 1.322.0 → 2.0.0

package/dist/task-settings.d.ts

@@ -1,46 +1,221 @@
+/**
+ * TaskRequest.settings wire — project a client's per-request `SemaSettings` stamp onto the per-task `TaskSpec`,
+ * TIGHTEN-ONLY (deny-wins), at the SAME seam as runtime-governance (after the approval baseline + operator
+ * governance). Backs the remote-mode settings path: sema runs over HTTP→engine with no local Runner, so the
+ * resolved settings can't be applied by a local `tightenTaskSpec` — they ride on `TaskRequest.settings` and the
+ * SERVICE projects them into the engine here.
+ *
+ * Design: `TaskRequest.settings` is a
+ * PER-REQUEST ephemeral stamp = the v2-design TASK layer (a single-run override, NOT durable). It folds into THIS
+ * spec via {@link tightenTaskSpec} and that is all — it is NEVER written to the durable `SessionPolicyStore` (the
+ * operator/principal axis, design/99 §E6, a different trust axis + lifecycle). Re-applying on a resume leg is
+ * idempotent (the same tighten), so no special resume handling is needed (mirrors runtime-governance).
+ *
+ * 🔒 SECURITY INVARIANTS (SDK settings.ts §3.3):
+ *  - permissions are TIGHTEN-ONLY — folded via `tightenTaskSpec` (deny-wins `combinePolicies`); it THROWS on any
+ *    override that would LOOSEN a stricter base safety field. The client can only ADD denies/asks/handsReadOnly on
+ *    top of the deployment + operator baseline, never widen it.
+ *  - permissionMode(轴B #2 注释保鲜,1.254——[816]/[820] 后的真实现):`defaultMode` 收**五**模式
+ *    (default | acceptEdits | plan | bypassPermissions | auto),bypass/auto 被 HONOR 为 gate-shape 选择
+ *    ——但深层不变量未变:bypass=「不加 ask 门」,恒不越部署基线(tightenTaskSpec deny-wins,基线 deny/
+ *    ask 照压);精化语义见 :2xx 行内注释。旧头注的「NEVER honored/三模式白名单」是 pre-[816] 拍照。
+ *
+ * 🔴 SYNC WITH shell `src/sema/settings/seam.ts`: the permissions→toolPolicy + §6.4 permissionMode derive MIRRORS
+ * the shell's LOCAL-Runner resolver — both compose the SAME core primitives (`createAllowDenyPolicy` /
+ * `combinePolicies` / `tightenTaskSpec`), so the deny-wins ENFORCEMENT is core-single-source. Only the COMPOSITION
+ * is duplicated for the remote path; a proposed follow-up extracts it to `@sema-agent/sdk` for true
+ * single-source. Because the core backstops (deny-wins + tighten-throws-on-loosen + this bypass-reject) hold either
+ * way, a composition drift would be a local/remote CONSISTENCY gap, never a privilege escalation.
+ *
+ * v1 scope: `permissions` + `permissions.defaultMode` + `model` + `outputStyle` + `env` (shipped 1.26.0). DEFERRED
+ * (need a seam, flagged to the team + advertised in capabilities so a caller never silently loses a setting):
+ *  - (`env` is NO LONGER deferred — systematic-audit doc fix: core kept no untrusted `TaskSpec.env` seam (types §7
+ *    Q4), so the SERVICE applies it on the TRUSTED host lane: `settings.env` → `cleanEnvMap` → `shellEnv` on the
+ *    executionEnvFactory, single-user-gated. See `deriveSettings` below + main.ts.)
+ *  - (`hooks` NO LONGER deferred either — 轴B #2 注释保鲜:applied 形已接线(本文件 hooks 分片 +
+ *    main.ts 单用户闸),仅 malformed 才报 deferred;旧「需要 remote hook-runner」是接线前拍照。)
+ */
 import { type ExecutionEnv, type TaskSpec, type ThinkingLevel, type ToolPolicy, type PromptProvider } from "@sema-agent/core";
 import type { HooksConfig } from "@sema-agent/registry-core/hooks";
+/** The permission MODE a client may request (CC-parity, SDK `SettingsPermissions.defaultMode`), [820]/[822] five-mode
+ *  table. `bypassPermissions` and `auto` joined the set with the [816] fs-write gate: since the gate exists, every
+ *  mode is a choice of HOW MUCH mode-derived gating the interpretation layer ADDS on top of the deployment baseline —
+ *  `bypassPermissions` adds none (= the pre-[816] behavior of every mode: "不加门" not "开门", [820] table row 4; the
+ *  deployment approval/governance baseline is composed OUTSIDE this derive and is untouchable from a settings stamp),
+ *  and `auto` adds the same ask gate as `default` with core's auto-mode classifier screening the asks upstream
+ *  (entitlement-gated in core, [822]②). */
 export type SettingsPermissionMode = "default" | "acceptEdits" | "plan" | "bypassPermissions" | "auto";
+/**
+ * R4: coerce a raw top-level `body.permissionMode` (the LIGHT per-turn wire — the shell sends the
+ * CC permission mode RAW, axis-agnostic; the service interprets) to a service-honored mode, or undefined.
+ * 🔴 TIGHTEN-ONLY vs the DEPLOYMENT baseline still holds for every value: the mode only selects the CLIENT-derived
+ * gate ({@link deriveSettingsPolicy}); it can never subtract from the deployment/operator policy (applyTaskSettings
+ * folds via tightenTaskSpec, deny-wins). Post-[816] the value set is CC's five modes verbatim — `acceptEdits`,
+ * `bypassPermissions` and `auto` are now HONORED as gate-shape choices (they no longer coerce to `default`, which
+ * would FORCE the manual ask gate onto a caller that explicitly asked for less asking — with the gate live, the old
+ * coercion would have been a behavior change for them, incl. a headless-deny regression for bypass callers). An
+ * UNKNOWN string still coerces to `default` (fail-safe: the most-asking mode).
+ */
 export declare function coercePermissionMode(raw: unknown): SettingsPermissionMode | undefined;
+/** L2 ultracode (design/111): the effective `thinking` level given the explicit `reasoningEffort` and the ultracode
+ *  preset. ultracode FLOORS at the "ultra" tier — core's single source `resolveReasoningProfile("ultra").thinking`
+ *  (= "max"), never a hardcoded literal — so an explicit higher tier still wins (none exists above max today;
+ *  future-proof). Awareness rides for free: core composes ORCHESTRATION_AWARENESS from thinking∈{xhigh,max}, no field. */
 export declare function effectiveThinking(reasoningEffort: unknown, ultracode: boolean): ThinkingLevel | undefined;
+/** R4: fold a top-level `body.permissionMode` onto the parsed settings as `permissions.defaultMode` (the top-level
+ *  field is the explicit per-turn intent → it WINS over a bundle defaultMode). Creates a minimal settings object when
+ *  no `body.settings` bundle was sent. The result flows through {@link applyTaskSettings} (tighten-only). */
 export declare function withPermissionMode(settings: ParsedTaskSettings | undefined, mode: SettingsPermissionMode): ParsedTaskSettings;
+/** The validated, service-trusted subset of `SemaSettings` we project onto the spec. `env` is parsed only to REPORT
+ *  it as received-but-deferred when off the host lane (never silently dropped); a MALFORMED `hooks` likewise reports
+ *  deferred (submit 路径另有 400 fail-loud),valid `hooks` 进 applied shape(hook-runner 阶段一)。 */
 export interface ParsedTaskSettings {
     permissions?: {
         allow?: string[];
         deny?: string[];
+        /** Carried for completeness; v1 folds `ask` into the gate via the deny-wins base (see {@link applyTaskSettings}). */
         ask?: string[];
         defaultMode?: SettingsPermissionMode;
     };
     model?: string;
     outputStyle?: string;
+    /** `settings.env` → per-task shell env. core deliberately keeps NO
+     *  `TaskSpec.env` (an untrusted caller must not swap the sandbox — design/44 §7 Q4); per-session shell env rides
+     *  the TRUSTED `executionEnvFactory` seam (`shellEnv`) instead. design/107 "env = capability axis": HONORED only on
+     *  the single-user host lane (`cwdHonored`), IGNORED on any cloud/multi-tenant lane. Parsed here; gated at apply. */
     shellEnv?: Record<string, string>;
+    /** L2 ultracode preset (design/111): a CC-parity `settings.ultracode` boolean that EXPANDS to the two existing
+     *  orthogonal axes — `thinking:"max"` (the reasoning axis) + `selfOrchestration:true` (the orchestration axis,
+     *  through its existing fail-closed gate). NOT a new mechanism; just a preset that fans out to existing spec fields. */
     ultracode?: boolean;
+    /** hooks hook-runner(阶段一):registry-core 0.1.51 契约校验过的 hooks 配置。像 shellEnv 一样
+     *  这里只 PARSE;应用点(main.ts resolveSpec)按单用户闸(`requirePrincipal !== true`)决定翻不翻成
+     *  core `TaskSpec.hooks` 回调——多租户 lane 收到只警告忽略(hook 命令跑在 worker host = class ② 能力授予)。 */
     hooks?: HooksConfig;
 }
+/** The result of parsing an untrusted `body.settings`: the applied subset + the names of present-but-deferred
+ *  fields (so the caller can log/advertise them — no silent drop). `null` settings ⇒ `{ settings: undefined }`. */
 export interface ParseTaskSettingsResult {
     settings?: ParsedTaskSettings;
+    /** Sub-fields the caller SENT but this version does not wire(`env`;`hooks` 仅在 MALFORMED 时入列——valid hooks
+     *  已是 applied 字段)。Empty when none. */
     deferred: string[];
 }
+/** Cap on `outputStyle` length — it lands in the system prompt, so it shares the `MAX_SYSTEM_PROMPT_CHARS` (16384)
+ *  posture (an uncapped prompt body is a per-turn token-cost hole; adversarial review). Exported so the HTTP layer
+ *  (prepareSpec) can 400 fail-loud on submit with the SAME bound this defensive parse enforces on every path. */
 export declare const MAX_SETTINGS_OUTPUT_STYLE_CHARS = 16384;
+/** Cap on the element count of each permission list (allow/deny/ask) — bounds a pathological rule blast. */
 export declare const MAX_SETTINGS_PERMISSION_RULES = 1000;
+/** Caps on `settings.env` — bound a pathological env blast (count + per-value length; values land in the shell env). */
 export declare const MAX_SETTINGS_ENV_VARS = 256;
 export declare const MAX_SETTINGS_ENV_VALUE_CHARS = 32768;
 export declare const MAX_SETTINGS_ENV_KEY_CHARS = 256;
+/**
+ * Validate an untrusted `body.settings` (raw `unknown` off the wire) into the service-trusted {@link
+ * ParsedTaskSettings}. NEVER trusts the wire type — every field is shape-checked; unknown keys are ignored
+ * (forward-compatible, matching the SDK's open `[k: string]: unknown`). `defaultMode` accepts the FIVE modes
+ * (post-[816]; unknown values coerce to `default` — see the header note). Returns the
+ * present-but-deferred field names so the caller can warn/advertise rather than silently dropping `env`/`hooks`.
+ */
 export declare function parseTaskSettings(raw: unknown): ParseTaskSettingsResult;
+/** Defensive acceptance of the `appendSystemPrompt` rider ([1478] R2 + codex F2): the HTTP 400 gate (prepareSpec,
+ *  MAX_SYSTEM_PROMPT_CHARS) only covers FRESH submits — every resume family re-enters resolveSpec on a STORED body,
+ *  and a pre-1.243 store preserved unknown request keys verbatim (the field was INERT then), so an over-cap legacy
+ *  value must not become active prompt content after rollout (context exhaustion / spend hole). Over-cap ⇒ dropped +
+ *  warned — the rider was inert pre-upgrade, so dropping preserves the stored task's prior behavior; a 4xx here would
+ *  permanently brick that task's resume instead (same defensive posture as parseTaskSettings' outputStyle drop).
+ *  Cap value = the submit gate's (16384; MAX_SETTINGS_OUTPUT_STYLE_CHARS — both land in the same spec field). */
+/** TRUE when `text` is an ALREADY-ASSEMBLED system prompt — core's migration guard detects the same three
+ *  constitution anchors and takes the pass-through assembler arm, whose section subset (OPAQUE_KEPT, dist-read)
+ *  has NO `core/role.append`: any append rider (top-level or settings.outputStyle) would be SILENTLY discarded
+ *  there. Shared predicate for the submit 400 gate, the resolveSpec resume mirror, and the center-declaration
+ *  probe — one definition so the three gates can't drift. */
 export declare function hasConstitutionAnchors(text: unknown): boolean;
+/** codex R9 (provider-aware append-less detection): mirrors core's ACTUAL pass-through triggers instead of a raw
+ *  body-text heuristic — the assembler's migration guard probes (a) `stableBlocks` identity declarations and
+ *  (b) `stableSystem` OUTPUT for the three anchors; a plain `userSystemPrompt` under the DEFAULT provider (no
+ *  scenario provider) never triggers it and `core/role.append` is retained, so an anchored systemPrompt there
+ *  must NOT block/strip a rider (R9 false-positive: unbranded default / scan rejected valid combos). Probing
+ *  calls the provider hooks with a minimal ctx — server providers (and centerPromptProvider) are pure functions
+ *  of ctx, and the same hooks run again inside core's assembly; a hook throw = conservative false (core will
+ *  fail the task loudly on its own). `replaceAll` owns the whole prompt(legacy free-form `system()` 腿已随 core 2.0.0 删除)
+ *  (REPLACE_ALL_EXCLUDED strips role.append) → append-less true. */
 export declare function providerDropsAppend(provider: PromptProvider | undefined, userSystemPrompt: string | undefined): boolean;
 export declare function acceptAppendSystemPrompt(v: unknown, warn?: (detail: string) => void, packDropsAppend?: boolean): string | undefined;
+/** [1248]②/codex F2 — what the workflow ask leg needs from the deployment, on EVERY lane (unlike
+ *  {@link FsWriteGateWiring}, which is host-lane-only because it adjudicates against a real fs; the workflow
+ *  gate is name-keyed and fs-independent). */
 export interface WorkflowGateWiring {
+    /** The session "don't ask again" probe (approvalExemptionStore.has, canonical toolName key) — same store and
+     *  key space as the fs-write gate's probe; one remember="session" grant serves both. */
     isExempt?: (toolName: string) => boolean | Promise<boolean>;
 }
+/** [816]/[820]① — everything the mode-derived fs-write ask gate needs from the deployment, provided by main.ts
+ *  ONLY on a HOST-SEMANTICS lane (`REMOTE_EXEC` unset or "host"). Absent ⇒ no gate is derived (the pre-[816]
+ *  behavior). WHY lane-gated: core's `createFsWriteGatePolicy` canonicalizes every target/dir through the given
+ *  `env` (real `exists`/`canonicalPath`/`readLink` fs access — read in dist, 1.290 fs-write-gate-policy.js), so the
+ *  env's fs MUST be the fs the hand tools write. On e2b/k8s/ssh/adb/local-docker the tools run OFF this box and the
+ *  per-task sandbox env is minted inside core (executionEnvFactory) AFTER spec build — a worker-local env here would
+ *  adjudicate against the WRONG fs (symlink/exists answers from the worker host). Honest absence over a wrong gate
+ *  (same honest-facts axis as envFacts.scratchpadDir). */
 export interface FsWriteGateWiring {
+    /** The env whose fs the gate canonicalizes against — the worker host env on the host lane. */
     env: ExecutionEnv;
+    /** The task's working directory: the factory's `rootPath` (relative-path base) AND the acceptEdits accept domain. */
     cwd: string;
+    /** The session scratchpad dir (envFacts.scratchpadDir, [820]③) — writes there are always auto-allowed. */
     scratchpadDir?: string;
+    /** [841]① / core 1.294 exemption seam: the session "don't ask again" probe (approvalExemptionStore.has),
+     *  consulted by the gate RIGHT BEFORE it would ask (after the exempt/accept dir layering — dist 亲读:true ⇒
+     *  allow with decisionReason "rule", a THROWN probe ⇒ not exempt = fail-closed to ask). Same canonical
+     *  toolName key space as the ask-policy layer's exemption probe — ONE grant serves both layers; the gate-level
+     *  check is what makes "allow all session" bite SAME-TURN for the parent and inherited child tasks (the ask
+     *  path is never re-entered). (codex M1 的边界注记已闭合:core 1.295 起本仓在 gate 腿上组合
+     *  createSensitivePathPolicy —— 见 `sensitivePatterns`,deny 在 combinePolicies 折叠里恒胜,豁免/acceptDirs
+     *  越不过它。) */
     isExempt?: (toolName: string, canonicalPath: string) => boolean | Promise<boolean>;
+    /** ③ (core 1.295): the sensitive-path write DENY set composed onto the fs-write gate leg —
+     *  `createSensitivePathPolicy({env, patterns, rootPath: cwd})`, deny-wins in the SAME combinePolicies fold, so a
+     *  session exemption (isExempt) or an acceptEdits auto-allow can never cross it (the 1.199-batch documented gap,
+     *  now closed). Source = config `SENSITIVE_WRITE_PATTERNS` (unset ⇒ core RECOMMENDED_SENSITIVE_PATTERNS; the
+     *  set curation is core's — the server passes through). Absent/empty ⇒ no sensitive policy (pre-1.295 shape). */
     sensitivePatterns?: string[];
+    /** [1557]§四 opt-in(cli[1555]②「echo -n … > file 绕写门」缺口的部署侧补丁,core[1556] 建议):
+     *  CC manual 系模式(default/auto/acceptEdits — 见 {@link deriveSettingsPolicy})額外把
+     *  `TaskSpec.shellGate` 收紧到这个值,让 Bash 走同一 fs-write 审批链(core `bashReversibilityProbe`
+     *  在 `"classify"` 下只拦构造性不可逆命令——含 shell 重定向 `>`/`>>` 等,纯读命令白名单自动放行)。
+     *  **Absent(缺省)= 零行为变化**(config `MANUAL_MODE_SHELL_GATE` 未设置时不传本字段,pre-此批行为
+     *  byte-for-byte;这是个 tighten-only opt-in,不是默认开启——运营方需要显式选择开启)。 */
     shellGate?: "always" | "classify";
 }
+/**
+ * Build the per-request permission ToolPolicy from the parsed settings (mirrors shell `seam.ts` — see header).
+ *  - base = name-keyed allow/deny (`createAllowDenyPolicy`): an `allow` list narrows to those tools; a `deny` list
+ *    hard-blocks — composed deny-wins with an ASK-list ({@link createAskListPolicy}) so `permissions.ask` actually
+ *    forces an approval gate (NOT silently dropped — review finding). `deny` > `ask` > `allow` on overlap.
+ *  - `defaultMode` derive onto that base ([820]/[822] five-mode table; the fs-write gate needs `gate` wiring —
+ *    without it every mode degrades to the base rules only, the pre-[816] behavior):
+ *      `default`           → base + `createFsWriteGatePolicy({rootPath: cwd, exemptDirs:[scratchpad], ask})` — CC
+ *                            manual: every fs write asks (the [816] P0 fix), scratchpad writes ride free.
+ *      `acceptEdits`       → base + the same factory with `acceptDirs:[cwd]` — writes INSIDE the cwd subtree
+ *                            auto-allow, OUTSIDE still ask (CC 207 dirname-variant card). NOT a loosen vs the
+ *                            deployment: the factory only ever emits allow/ask and is folded deny-wins, so a
+ *                            baseline deny/ask still wins; vs `default` it is simply a narrower CLIENT gate, and
+ *                            both are client-side ADDITIONS the client may size itself.
+ *      `plan`              → handsReadOnly + present_plan (unchanged; the write tools never reach an ask).
+ *      `bypassPermissions` → base only, NO factory ([820] table: bypass = "不加门" not "开门" — deployment
+ *                            approval/governance baselines still apply; this is exactly every mode's pre-[816]
+ *                            derive, so bypass grants nothing that wasn't already granted).
+ *      `auto`              → base + the `default` factory (ask 兜底) — core's auto-mode classifier (entitlement-
+ *                            gated: RunnerDeps.autoMode ∧ runtimeCaps.autoMode, 1.276/1.277) screens asks UPSTREAM
+ *                            of resolveAsk, allowing safe calls and leaving suspicious ones on the ask path ([822]②).
+ *      absent (undefined)  → base only, NO factory: an expressed-no-mode request keeps its pre-[816] behavior
+ *                            (attaching the ask gate on a mere allow/deny-list stamp would regress headless callers
+ *                            that never asked for a mode; the shell always sends its mode explicitly).
+ * Returns the composed ToolPolicy + whether `handsReadOnly` should tighten. Returns `undefined` policy when there
+ * is no permission rule and no mode-derived gate (nothing to project).
+ */
 export declare function deriveSettingsPolicy(settings: ParsedTaskSettings, gate?: FsWriteGateWiring, workflowGate?: WorkflowGateWiring): {
     toolPolicy?: ToolPolicy;
     handsReadOnly?: boolean;