@sema-agent/server 7.136.0 → 7.137.0

package/dist/plugins/remote-env-k8s.d.ts

@@ -110,9 +110,11 @@ export interface K8sEnvConfig extends LaneHomeConfig {
     cacheMisses?: CacheMissMemory;
     /** Operator log seat (the e2b adapter's shape): `workspace_snapshot_failed` / `workspace_snapshot_prune_failed` /
      *  `workspace_space_unavailable` / `workspace_space_unreadable_occupant` / `workspace_commit_abandoned` / `workspace_latest_dangling` /
-     *  `workspace_restore_failed` / `workspace_snapshot_bucket_missing` / `workspace_cache_fresh` / `workspace_cache_unavailable`. */
+     *  `workspace_restore_failed` / `workspace_snapshot_bucket_missing` / `workspace_cache_fresh` / `workspace_cache_unavailable`, and — at `error` level, on a seat
+     *  that has one (the deployment's logger does; the seat itself is optional, and the counter behind the line does not depend on it) — `sandbox_pod_delete_failed`. */
     logger?: {
         warn(event: string, fields?: Record<string, unknown>): void;
+        error?(event: string, fields?: Record<string, unknown>): void;
     };
     /** Run-end outcome seat — called once per `destroy()` that attempted a space snapshot (the factory's caller binds it
      *  to the run, so the run's terminal frame can carry `workspaceSnapshot: "failed"`). */
@@ -130,13 +132,39 @@ export interface K8sEnvConfig extends LaneHomeConfig {
     podSpecPatch?: PodSpecPatch;
     /** RFC B5 (sema-internal server/docs/design/ENV-SELECT-AND-REGION-SOURCE.md 抽象点②): operator-trusted env injected into the
      *  sandbox container (e.g. `SEMA_PKG_SOURCE=cn|global` — the runtime package-source selector the image's
-     *  pkg-source.sh hook materializes at start). Deployment config, NEVER task-controlled. This is the pod's ONE container-env
-     *  seat: the region package-source set AND the deployer-named forwarding (`K8S_SANDBOX_ENV` keys, original values) arrive
-     *  here already merged by the boot assembly (explicit names win). Values go into `containers[0].env[]` and nowhere else —
-     *  never a command string, the workspace or a snapshot. Absent = the pod is byte-identical to today. */
+     *  pkg-source.sh hook materializes at start). Deployment config, NEVER task-controlled. The pod's NON-SECRET env seat: the region
+     *  package-source set (and the cache env layered under it) — values that are no secret go into `containers[0].env[]` as `{ name, value }`.
+     *  Never a command string, the workspace or a snapshot. Absent = no such entries. */
     podEnv?: Record<string, string>;
+    /** The pod's SECRET env seat: the deployer-named forwarding (`K8S_SANDBOX_ENV` keys, original values; disjoint from {@link podEnv} — the boot
+     *  assembly drops a collided name from the non-secret seat, explicit wins; a name in both is read here). The values reach the agent container
+     *  ONLY through this pod's own Secret: the pod spec carries `valueFrom.secretKeyRef` and no value; the Secret is created after the pod, owned by
+     *  it (`ownerReferences`, `immutable`) — a Secret that cannot be created ⇒ the pod is deleted and the connect refused, never a plaintext fallback.
+     *  Absent / empty ⇒ no Secret, the pod as without it. */
+    podSecretEnv?: Record<string, string>;
+    /** The server run that owns this env — the TOP-LEVEL run's id (its task id), handed in by the per-run binding (`boot/execution-env.ts`), which
+     *  hands none to a delegated child, a run the service starts for itself, or a run without a task id. Carried as the pod label `sema.io/run`
+     *  (the reaper's key: a pod whose run is over is removed); a value that is no label value is not carried. Absent ⇒ the pod names no run. */
+    runId?: string;
+    /**
+     * The member git-credential broker seat — present ⇔ the per-run binding found the plane on and this run a member's (`sso`) run
+     * (`sandbox-git-plane.ts` `sandboxBrokerSeatOf`). The pod then carries the broker container (`containers[1]`: the fixed program of
+     * `broker/constants.ts`, image = `image`, the securityContext written key by key, an exec readiness probe), its lease volume (a SECOND
+     * per-pod Secret, `sema.io/sandbox-lease` — mutable, owned by the pod, only `broker.json`; created after the pod holding a placeholder lease
+     * in which every entry is withdrawn), `shareProcessNamespace: false`, and on the agent container one `GIT_CONFIG_*` insteadOf route per
+     * origin (`origins` = the pod's origin table, in order — the same table every lease write is stamped from). The connect waits for the
+     * broker container to be ready; any failure on that path deletes the pod and refuses the connect. A deployment patch that could reach
+     * the broker refuses the connect before any pod is created. Absent ⇒ the pod as without it (byte-identical).
+     */
+    sandboxBroker?: {
+        readonly image: string;
+        readonly origins: readonly string[];
+    };
 }
+import { type SandboxSecretSeatKind, type SandboxSecretVerb } from "./k8s-exec-protocol.js";
 export { type PodSpecPatch, applyPodSpecPatch } from "./k8s-exec-protocol.js";
+import { type SandboxPodApi, type SandboxPodListing } from "./k8s-pod-reaper.js";
+import { type SandboxLeaseEntryInput } from "../sandbox-git-lease.js";
 type ConnectResult = {
     ok: true;
     value: WorkspaceHandle;
@@ -154,11 +182,14 @@ export interface ExecSocket {
  * Test seam ([ref] §9.3 fault-injection): inject the REST `request` and/or the exec-socket factory, so pod
  * lifecycle, retry policy, channel framing and liveness are deterministically testable without a cluster.
  */
+/** One control-plane request's options: its wall-clock, its abort, and the body's media type (default `application/json`; a merge-patch says so). */
+export interface K8sRequestOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    contentType?: string;
+}
 export interface K8sEnvDeps {
-    request?: (method: string, apiPath: string, body?: unknown, opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }) => Promise<{
+    request?: (method: string, apiPath: string, body?: unknown, opts?: K8sRequestOptions) => Promise<{
         status: number;
         json: unknown;
     }>;
@@ -229,6 +260,35 @@ export declare function errorMessageOf(e: unknown): string;
 export { exitCodeFromStatus } from "./k8s-exec-protocol.js";
 /** The sandbox namespace when `K8S_NAMESPACE` is unset (the one spelling: the adapter and the boot's egress line read it). */
 export declare const K8S_SANDBOX_NAMESPACE_DEFAULT = "sandboxes";
+/**
+ * The boot reading of the sandbox Secret seat, a closed set: `granted` — every verb allowed · `denied` — the API answered "not allowed" for these
+ * verbs (a definite answer; it wins over a verb that could not be asked) · `unverified` — some verb could not be asked (the request failed, the
+ * review itself was refused, the answer had no `status.allowed`) and none was denied.
+ */
+export type SandboxSecretSeat = {
+    readonly state: "granted";
+} | {
+    readonly state: "denied";
+    readonly verbs: SandboxSecretVerb[];
+} | {
+    readonly state: "unverified";
+    readonly detail: string;
+};
+/** Where a pod's lease lives and which origin table it was built with — what {@link writeSandboxLease} needs (read it from {@link RemoteK8sExecutionEnv.sandboxLeaseRef}). */
+export interface SandboxLeaseRef {
+    readonly namespace: string;
+    readonly podName: string;
+    readonly leaseSecretName: string;
+    readonly origins: readonly string[];
+}
+/** One lease write's outcome (closed set): written · refused before sending (the broker would refuse it) · refused by the API · the Secret is gone (so is its pod) · any other failure. */
+export type SandboxLeaseWrite = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: "lease_invalid" | "auth_failed" | "gone" | "write_failed";
+    readonly message: string;
+};
 export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /**
      * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
@@ -250,6 +310,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** Cluster-internal pod address, captured when the pod reaches Running — the LSP `getHost` surface.
      *  Lifecycle mirrors podName exactly (set on connect, cleared on suspend/destroy/dead-reconnect). */
     private podIP?;
+    /** The broker lease seat of the pod this env holds (set with {@link podName}; read through {@link sandboxLeaseRef}). */
+    private leaseRef?;
     private destroyed;
     /** Set after a successful resumeVM so workspaceHandle() carries the snapshot it was restored from. */
     private handleSnapshotId?;
@@ -274,6 +336,9 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
+    /** core 7.56.0 [ref]:shell 子进程继承的环境里收不到的条目 —— 本车道 shell 的环境在 pod 里**构建**(本进程的 env 从不注入,只有引擎逐次交的 `env`
+     *  这条显式授予),没有一条是从本进程继承的 ⇒ `[]`(core 契约:「`[]` when its shell environment is built rather than inherited」)。 */
+    readonly withheldEnv: readonly [];
     private readonly cfg;
     private readonly deps;
     /** The known occupant's incarnation (`undefined` = this run has no known occupant: a delegated child, an unread session, a direct construction) — the
@@ -295,6 +360,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private readonly onWorkspaceSnapshot?;
     private readonly cacheMisses?;
     constructor(config: K8sEnvConfig, deps?: K8sEnvDeps);
+    /** The lease seat of the pod this env holds now — `undefined` without a broker seat or without a pod (the server's lease writes follow it: a resumed env holds a new pod and a new seat). */
+    get sandboxLeaseRef(): SandboxLeaseRef | undefined;
     /** 166-T2 — ExecutionEnv 寿命声明:pod `activeDeadlineSeconds = ceil(timeoutMs/1000)` 是平台真硬死线
      *  (k8s 到点杀 pod,无 keepalive 续期机制)⇒ 恒声明,core 在死线−60s 处 suspend(基建合格)或响亮
      *  终局(env.lifetime_expired)。`lifetimeStartedAt` 有意不声明:core 只在 prepare 期读一次,lazy-connect
@@ -410,6 +477,15 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * same merge `createPod` applies). A read that is refused / fails / times out is a `unreadable` gap, never a guess. Never throws.
      */
     egressPolicyGaps(): Promise<SandboxEgressGap[]>;
+    /**
+     * The boot reading of one sandbox Secret seat ({@link SandboxSecretSeat}): one SelfSubjectAccessReview per verb of that seat's row in {@link SANDBOX_SECRET_SEAT_VERBS}
+     * on `secrets` in this env's namespace. An answer with `status.allowed: false` is a denial (RBAC never answers `denied: true` — "no rule allows
+     * it" IS its refusal); a failed request, a refused review or an answer without a boolean `status.allowed` is a verb not asked. The verbs are
+     * asked at once (the boot waits one control-plane bound, not four). Never throws.
+     */
+    secretSeatReading(seat: SandboxSecretSeatKind): Promise<SandboxSecretSeat>;
+    /** The sandbox pods of this env's namespace (selected by the identity labels), read for the reaper ({@link createSandboxPodApi}). Throws on a failed / refused listing. */
+    listSandboxPods(): Promise<SandboxPodListing[]>;
     /** The one spelling of "the reclaim call's deadline passed" — both halves of the reclaim (volume and objects) say it with this. */
     private reclaimDeadlinePassed;
     /** The cache volume could not be had: counted (`recordFailOpen`) and one operator line — once per env. */
@@ -417,6 +493,34 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** Create one pod (with the cache volume when given) and wait for it to run. A {@link CacheMiss} = a pod carrying the
      *  volume did not become ready (its claim unbound past the bind deadline, or bound and still not ready) — already deleted. */
     private createPod;
+    /**
+     * This pod's own Secret — the secret env seat ({@link K8sEnvConfig.podSecretEnv}): created AFTER the pod, owned by it (`ownerReferences` → the
+     * pod's uid, `blockOwnerDeletion: false` — the cluster's garbage collector removes it with the pod), `immutable`, `data["env.<NAME>"]` = the
+     * value (base64). The caller deletes the pod on any refusal: no uid to bind (`connect_failed`), refused (401 / 403 ⇒ `auth_failed`, not
+     * retried), any other answer or a failed request (`connect_failed`). A refusal never carries a value: the API's text is scrubbed of every value
+     * (raw and base64) before it enters the sentence.
+     */
+    private createPodSecret;
+    /**
+     * This pod's lease Secret — the member-credential broker's seat ({@link K8sEnvConfig.sandboxBroker}): created after the pod, owned by it
+     * (the same `ownerReferences` as the env Secret), NOT immutable (the server rewrites the lease: {@link writeSandboxLease}), one data key
+     * `broker.json` = the placeholder lease. Refusals as for the env Secret; the caller deletes the pod on any of them.
+     */
+    private createLeaseSecret;
+    /**
+     * One Secret owned by this pod (`ownerReferences` → its uid, `blockOwnerDeletion: false`; the cluster's garbage collector removes it with
+     * the pod). No uid to bind ⇒ `connect_failed`; refused (401 / 403) ⇒ `auth_failed`; any other answer or a failed request ⇒ `connect_failed`.
+     * A refusal never carries a value: the API's text is scrubbed of every `hidden` string before it enters the sentence.
+     */
+    private createOwnedSecret;
+    /**
+     * Rewrite one pod's lease (the server's ONLY lease write — {@link writeSandboxLease}): the file is built by the one lease builder from the
+     * pod's origin table (fresh `leaseId` per ready entry, the broker's own parser judges it — a file the broker would refuse is never sent) and
+     * lands as a merge-patch of `broker.json` on the pod's lease Secret. Every failure is typed, says one operator line
+     * (`sandbox_lease_write_failed`), carries no credential (the API's text is scrubbed of every secret and of the encoded file), and falls
+     * back to nothing: the broker keeps the lease it has, which lapses on its own clock.
+     */
+    writeLease(ref: SandboxLeaseRef, entries: readonly SandboxLeaseEntryInput[]): Promise<SandboxLeaseWrite>;
     /**
      * Build a validated, presigned URL for a snapshot object of either lane (see {@link SnapshotTarget}) — the ONE place a
      * snapshot object key is spelled, and the one place each lane's partition is chosen (park = the session id, space = the
@@ -584,7 +688,20 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
         error: RemoteExecutionError;
     }>;
     reconnect(_sessionToken: SessionToken): Promise<ConnectResult>;
-    private deletePod;
+    /**
+     * Delete one pod — the ONE request path of "delete a sandbox pod" (the run-end delete, every refusal / reconnect clean-up, and the reaper's face: no grace).
+     * Resolves `"deleted"` (2xx) or `"gone"` (404: the pod never was / is already gone); throws {@link PodDeleteRefused} on any other answer and the request's own error on a transport failure.
+     */
+    deletePod(name: string): Promise<"deleted" | "gone">;
+    /**
+     * Give up the pod a refused connect had already created. The refusal is the caller's answer; the delete is the clean-up behind it — and a clean-up that FAILS leaves
+     * the pod, and the Secret(s) it owns (the deployer-named env values / the lease placeholder: data at rest that no connection carries), in the sandbox namespace until
+     * the pod reaper's backstop reaches them. That is said, not swallowed — through the ONE reporter the reaper's own delete step shares
+     * ({@link reportPodDeleteFailed}: the F-class counter `server.sandbox-pod.delete-failed` and one error line naming the pod, the namespace, why the pod was being
+     * given up and how the delete failed (`http_<status>` / `request_failed`) — never a value, never the API's own text).
+     * Never throws: the refusal the caller goes on to return stays the original one.
+     */
+    private discardRefusedPod;
     /**
      * Delete the sandbox pod. Idempotent, never throws. Space lane open and a pod exists ⇒ FIRST the run-end space
      * snapshot ({@link persistWorkspace}) — after the pod's processes are confirmed stopped, the commands still in flight having ended or been cut first ({@link quiesce}); from the
@@ -766,6 +883,16 @@ export declare function createSpaceReclaimer(config: K8sEnvConfig, deps?: K8sEnv
  * nodes that join after boot are read at the next boot. Never throws (a read failure is an `unreadable` gap).
  */
 export declare function checkSandboxEgressPolicy(config: K8sEnvConfig, deps?: K8sEnvDeps): Promise<SandboxEgressGap[]>;
+/** The boot reading of one sandbox Secret seat for this k8s config ({@link RemoteK8sExecutionEnv.secretSeatReading}; a control-plane env, no pod). Never throws. */
+export declare function readSandboxSecretSeat(config: K8sEnvConfig, seat: SandboxSecretSeatKind, deps?: K8sEnvDeps): Promise<SandboxSecretSeat>;
+/**
+ * The server's one lease writer for a pod that carries the member-credential broker ({@link RemoteK8sExecutionEnv.writeLease}): `ref` is the
+ * pod's lease seat ({@link RemoteK8sExecutionEnv.sandboxLeaseRef}), `entries` one per origin of its table. A control-plane env, no pod.
+ */
+export declare function writeSandboxLease(config: K8sEnvConfig, ref: SandboxLeaseRef, entries: readonly SandboxLeaseEntryInput[], deps?: K8sEnvDeps): Promise<SandboxLeaseWrite>;
+/** The reaper's narrow face onto the sandbox namespace (list by identity labels, delete one) — a control-plane env, no pod, built at first use
+ *  (as the space reclaimer builds its envs per call: the boot never constructs an env just to hold this face). */
+export declare function createSandboxPodApi(config: K8sEnvConfig, deps?: K8sEnvDeps): SandboxPodApi;
 /**
  * `ExecutionEnvFactory` for the k8s pod-sandbox backend — one fresh (unconnected) env per task; the pod is
  * created lazily on connect and deleted by `destroy()` (Runner-owned lifetime; `activeDeadlineSeconds` is the