@sema-agent/server 7.150.0 → 7.152.0

package/dist/workspace-space.d.ts

@@ -1,7 +1,7 @@
 /**
  * Workspace persistence by **space** (k8s lane) — the closed word set, the defaults, the retention domain and
- * the policy shape (pure leaf: no value imports from this repo — only a node builtin — so `config.ts`, the capability fact and the adapter
- * in `plugins/` can all import it without a load cycle). The effective policy has ONE reading: the capability fact `workspaceSpace`
+ * the policy shape (pure leaf: its only value imports are a node builtin and the object-store name leaf `object-store-buckets.ts`, itself
+ * import-free — so `config.ts`, the capability fact, the boot bucket check and the adapter in `plugins/` can all import it without a load cycle). The effective policy has ONE reading: the capability fact `workspaceSpace`
  * (`src/capability-facts.ts`).
  *
  * The law (one fact, one seat): a k8s pod's `/workspace` is durable across runs as an object-store "space" owned by the
@@ -63,8 +63,14 @@ export interface WorkspaceSpacePolicy {
 export interface WorkspaceSyncCapability extends WorkspaceSpacePolicy {
     timeoutMs: number;
 }
-/** `WORKSPACE_SNAPSHOT_PREFIX` unset ⇒ this prefix (the first segment of every snapshot object key of both lanes). */
-export declare const WORKSPACE_SNAPSHOT_PREFIX_DEFAULT = "kata";
+/**
+ * The key prefix of a k8s snapshot store — the ONE reading of `WORKSPACE_SNAPSHOT_PREFIX` (unset ⇒ `WORKSPACE_SNAPSHOT_PREFIX_DEFAULT`): the adapter
+ * signs every snapshot key under it, and the boot bucket check lists under it (`<prefix>/`), so the check asks for the same prefix the adapter writes —
+ * a credential whose listing is granted by prefix answers the check exactly as it answers the adapter. Its form is judged by {@link snapshotKeyPrefixProblem}.
+ */
+export declare function workspaceSnapshotPrefixOf(store: {
+    readonly keyPrefix?: string;
+} | undefined): string;
 /**
  * The ONE form of a snapshot-key segment — the partition (incarnation / session id), the snapshot id, the object name and each segment of
  * the key prefix all pass it before a key is signed: it starts with a letter or digit, then letters, digits, `.`, `_`, `-`. No `/`, no `..`,

package/dist/workspace-space.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { WORKSPACE_SNAPSHOT_PREFIX_DEFAULT } from "./object-store-buckets.js";
 export const K8S_WORKSPACE_MOUNT_DEFAULT = "/workspace";
 export const WORKSPACE_PERSIST_WORDS = ["space", "off"];
 export const WORKSPACE_PERSIST_DEFAULT = "space";
@@ -9,7 +10,9 @@ export const WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE = { min: 30_000, max: 3_600_000
 export function workspaceSnapshotTimeoutOf(lane) {
     return lane.workspaceSnapshotTimeoutMs ?? WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT;
 }
-export const WORKSPACE_SNAPSHOT_PREFIX_DEFAULT = "kata";
+export function workspaceSnapshotPrefixOf(store) {
+    return store?.keyPrefix ?? WORKSPACE_SNAPSHOT_PREFIX_DEFAULT;
+}
 export const SNAPSHOT_KEY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export const WORKSPACE_SNAPSHOT_PREFIX_INVALID = "config.workspace_snapshot_prefix_invalid";
 export function snapshotKeyPrefixProblem(prefix) {

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -152,8 +152,9 @@ pre-auth frame closes the connection outright.
 
 **Which revision to declare.** `challenge.protocolVersion` is the highest protocol revision this server speaks
 (`DEVICE_MIN_PROTOCOL_VERSION` is the lowest it accepts, §2.1). Put the highest revision *you* implement that is
-not above `challenge.protocolVersion` into `hello.protocolVersion` — the same integer you sign (§1.3) — and emit
-only the `errorCode` words of that revision (the revision table in §2.1). Nothing is renegotiated after `hello`:
+not above `challenge.protocolVersion` into `hello.protocolVersion` — the same integer you sign (§1.3) — declare in
+`supports` only the instruction kinds of that revision, and emit only the `errorCode` words of that revision (the revision
+table in §2.1). Nothing is renegotiated after `hello`:
 the revision you declared is the contract for the whole connection. If the highest revision you implement is below
 `DEVICE_MIN_PROTOCOL_VERSION`, the server answers `helloReject: protocol_version_unsupported` (§1.4).
 Revisions are cumulative on the executor's side: an executor that implements revision *N* implements every revision
@@ -249,7 +250,7 @@ sign exactly these bytes with the device's Ed25519 private key.
 
 | Code | Meaning | What the executor should do |
 |---|---|---|
-| `auth_failed` | deliberately ambiguous: unknown device id, malformed id, malformed epoch, bad signature, or the server's device registry was unreachable | do **not** hammer: back off exponentially. If it never clears, the enrollment is gone — re-enroll. The server will not tell you which of these it was (anti-enumeration) |
+| `auth_failed` | deliberately ambiguous: unknown device id, malformed id, malformed epoch, bad signature, the server's device registry was unreachable, or — on a deployment that confines service principals — the device's owner is currently named in the operator roster's drain-only tier (a tier whose identity counts only on the drain endpoint, so it may not use the device lane; the device registration and the key stay valid) | do **not** hammer: back off exponentially, and never delete the key on `auth_failed` alone. If it never clears, the enrollment may be gone — re-enroll — unless the owner is confined as described: registering again under that identity is refused with `403 auth.principal_confined`, and the cure is on the operator's side. The server will not tell you which of these it was (anti-enumeration); the confinement cause is judged after the signature verifies, so only the holder of the device key can ever meet it. It is not terminal: when the owner is back in the ordinary tier (the deployment's roster is read at process start), the next reconnect succeeds, and the code set and the revision are unchanged |
 | `revoked` | this device has been revoked. Terminal | stop reconnecting, delete the private key, ask the user to re-enroll (it yields a new `deviceId`) |
 | `protocol_version_unsupported` | your `protocolVersion` is outside the range this server accepts; the frame carries `minProtocolVersion` and a one-line `message` that names your revision, the range and — below the floor — the change at the floor revision (§2.1) | upgrade the executor (`message` is fit to show as is). Never retry-with-a-different-version in a loop |
 | `draining` | this replica is shutting down or upgrading and takes no new connections | reconnect with backoff; a replacement replica will accept you |
@@ -345,7 +346,7 @@ base64 inside JSON fields.
 | Constant | Value | Meaning |
 |---|---|---|
 | `DEVICE_WS_PATH` | `/v1/device/ws` | the upgrade path (prefer the `wsPath` from `/v1/capabilities`) |
-| `DEVICE_PROTOCOL_VERSION` | `5` | the protocol revision this server speaks (the highest it accepts) |
+| `DEVICE_PROTOCOL_VERSION` | `6` | the protocol revision this server speaks (the highest it accepts) |
 | `DEVICE_MIN_PROTOCOL_VERSION` | `5` | the lowest revision it accepts (the revision table says why); below it (or above the highest), a loud `helloReject` — never a silent downgrade |
 | `DEVICE_HELLO_DOMAIN_TAG` | `sema.device.hello.v1` | the handshake signature domain tag (§1.3) |
 
@@ -366,36 +367,43 @@ cap. An instruction whose frame would be over it is refused before dispatch (you
 chunks are sliced so that a chunk frame, base64 and envelope included, fits. You can therefore cap the frames you
 accept at `maxFrameBytes`.
 
-#### Protocol revisions and the `errorCode` set
+#### Protocol revisions: the `errorCode` set and the instruction kinds
 
 The protocol revision is the only thing an executor can read *before* it sends `hello` (the `challenge` frame
 carries it), so everything you must know to be correct on this server is a function of the revision, not a
-separate list: the set of `errorCode` words the server accepts from you, and what the frames it sends you mean.
-The table gives, per revision, the words **added** at that revision and any other change made at it; the word set
-at revision *N* is the union of the rows up to *N*, and the full set at the current revision is the §3.3 table.
+separate list: the set of `errorCode` words the server accepts from you, the set of instruction kinds it may send you,
+and what the frames it sends you mean. The table gives, per revision, the words **added** to each set at that revision
+and any other change made at it; a set at revision *N* is the union of its column's rows up to *N*, and the full sets at
+the current revision are the §3.3 table (`errorCode`) and the §3.1 table (instruction kinds, in this order).
 
 <!-- closed-set: DEVICE_OUTCOME_ERROR_CODES_BY_REVISION -->
 
-| Revision | `errorCode` words added at this revision | Other change at this revision |
-|---|---|---|
-| `1` | `aborted`, `already_exists`, `auth_failed`, `callback_error`, `invalid`, `is_directory`, `not_directory`, `not_found`, `not_supported`, `outcome_unknown`, `permission_denied`, `precondition_failed`, `shell_unavailable`, `spawn_error`, `suspended`, `target_unavailable`, `timeout`, `transport_lost`, `unknown` | — |
-| `2` | `liveness_no_output` | — |
-| `3` | `name_too_long` | — |
-| `4` | `symlink_loop` | — |
-| `5` | — | every path an instruction carries (`args.path`, `args.paths`, `cwd`) arrives **unfolded** (since server 7.150.0): absolute as written, or anchored at the session's working directory, with `.` / `..` / empty segments kept — the server anchors and never folds. Resolve it as your filesystem does and judge containment on where it resolves (§3.1, §6 item 6). An executor written for revision 4 or below expects folded paths, so this is also the lowest revision the server accepts |
+| Revision | `errorCode` words added at this revision | Instruction kinds added at this revision | Other change at this revision |
+|---|---|---|---|
+| `1` | `aborted`, `already_exists`, `auth_failed`, `callback_error`, `invalid`, `is_directory`, `not_directory`, `not_found`, `not_supported`, `outcome_unknown`, `permission_denied`, `precondition_failed`, `shell_unavailable`, `spawn_error`, `suspended`, `target_unavailable`, `timeout`, `transport_lost`, `unknown` | `exec`, `execStream`, `readTextFile`, `readTextLines`, `readBinaryFile`, `writeFile`, `writeFileExclusive`, `writeFileGuarded`, `appendFile`, `fileInfo`, `listDir`, `canonicalPath`, `exists`, `readLink`, `createDir`, `remove`, `createTempDir`, `createTempFile`, `statBatch` | — |
+| `2` | `liveness_no_output` | — | — |
+| `3` | `name_too_long` | — | — |
+| `4` | `symlink_loop` | — | — |
+| `5` | — | — | every path an instruction carries (`args.path`, `args.paths`, `cwd`) arrives **unfolded** (since server 7.150.0): absolute as written, or anchored at the session's working directory, with `.` / `..` / empty segments kept — the server anchors and never folds. Resolve it as your filesystem does and judge containment on where it resolves (§3.1, §6 item 6). An executor written for revision 4 or below expects folded paths, so this is also the lowest revision the server accepts |
+| `6` | — | `openBound` | — |
 
 Rules: adding a frame or a field is additive and does not raise the revision. Every other change
-raises `DEVICE_PROTOCOL_VERSION` and adds a row here — a word added to a closed set the server *accepts from you*
-(today: the `errorCode` set; second column), or a **semantic change**, a change in what a frame the server sends you
-means (third column): a semantic change raises the revision. A released row never changes. When an executor written for
+raises `DEVICE_PROTOCOL_VERSION` and adds a row here — a word added to either closed set of the instruction exchange:
+an `errorCode` word the server *accepts from you* (second column) or an instruction kind the server *sends you*
+(third column) — or a **semantic change**, a change in what a frame the server sends you means (fourth column):
+a semantic change raises the revision. A released row never changes. The server sends a kind only on a connection
+whose declared revision is at or above the row that added it, and only if that connection's `supports` declares it
+(§3.2): a kind above your revision is never sent to you, so an executor written for the older revision still honors
+the newer one and the lowest accepted revision stays where it was (revision 6 added `openBound`; a revision-5 executor
+never receives it). When an executor written for
 an older revision cannot honor the change, the same release raises `DEVICE_MIN_PROTOCOL_VERSION` to the new
 revision, so such an executor is refused once at `hello` (§1.4) instead of failing call by call.
-Declare a revision as §1.2 says and send only the words of that revision: an executor
+Declare a revision as §1.2 says and use only the words of that revision: an executor
 that declared revision 1 never sends `liveness_no_output` (the server does not police this per connection — it
 decodes every connection against the current revision's full set — but a word above your declared revision is outside
-your contract). The same sets are importable:
-`DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` and `deviceOutcomeErrorCodesAt(revision)` from
-`@sema-agent/server/device-protocol`.
+your contract), and a kind above your declared revision in `supports` is ignored like a word the server does not know.
+The same sets are importable: `DEVICE_OUTCOME_ERROR_CODES_BY_REVISION` / `deviceOutcomeErrorCodesAt(revision)` and
+`DEVICE_INSTRUCTION_KINDS_BY_REVISION` / `deviceInstructionKindsAt(revision)` from `@sema-agent/server/device-protocol`.
 
 ### 2.2 Device → server frames
 
@@ -532,6 +540,7 @@ entry can be asked again as written.
 | `createTempDir` | `{ prefix? }` | `{ok:true, kind:"write", canonicalPath}` | the created directory's path **is** the receipt |
 | `createTempFile` | `{ prefix?, suffix? }` | `{ok:true, kind:"write", canonicalPath}` | same |
 | `statBatch` | `{ paths: string[] }` | `{ok:true, kind:"stat", …}` | declared but **not dispatched today** (see §8) |
+| `openBound` | `{ path, op, identity?, kind?, max? }` | per `op`: `open` / `size` / `list` ⇒ `{ok:true, kind:"stat", …}`, `readBytes` ⇒ `{ok:true, kind:"read"}` | **optional face**, revision 6 — a bound read: the object judged is the object read (§3.7) |
 
 The server checks the outcome *kind* against the instruction kind. Answering an `execStream` with
 `{ok:true, kind:"void"}` — a perfectly well-formed frame — is refused as a protocol violation and the
@@ -540,22 +549,26 @@ outcome are always accepted.
 
 ### 3.2 Declaring what you implement: `hello.supports`
 
-`supports` is a plain `string[]` of instruction kinds. The server intersects it with its own closed set;
-**a kind you do not declare is never dispatched to you**, and a call that needs it fails loudly with
-`not_supported` instead of silently doing something else. A kind the server does not recognize is simply
-ignored (that is how a newer executor talks to an older server without breaking it).
+`supports` is a plain `string[]` of instruction kinds. The server intersects it with the kinds of the revision you declared
+(§2.1); **a kind you do not declare is never dispatched to you**, and a call that needs it fails loudly with
+`not_supported` instead of silently doing something else. A kind the server does not recognize — or one above the
+revision you declared — is simply ignored (that is how a newer executor talks to an older server without breaking it).
 
-Three faces are **presence-typed**, which is a stronger statement than "optional":
+Four faces are **presence-typed**, which is a stronger statement than "optional":
 
 - `writeFileExclusive` — atomic create-if-absent
 - `writeFileGuarded` — verify-and-write in one atomic step
 - `readLink` — read a symlink target
+- `openBound` — a bound read (§3.7): every answer is about the object that was opened and checked
 
 The engine decides *at environment-construction time* whether these exist, and when they do not it
 degrades honestly (an advisory check instead of an atomic one). **Therefore: absence is absence. Never
 emulate a guarded or exclusive write with a two-step "check then write".** A two-step emulation reopens
 exactly the race the atomic primitive exists to close, while wearing the face of an atomic operation —
-which is worse than not having it, because nothing downstream can tell.
+which is worse than not having it, because nothing downstream can tell. The same holds for `openBound`:
+**never emulate it with `fileInfo` + `readBinaryFile`** (two path reads cannot tell that the bytes came from the
+object that was judged); without it, the engine simply does not bind a read on this device (a path attachment is
+accepted and reported `not_attached`).
 
 Two more consequences you must design for:
 
@@ -712,8 +725,45 @@ side**. Verifying with `stat` and then writing is exactly the emulation that is
 - `readLink` — optional but strongly recommended: it is the fourth governance read, and its absence makes
   symlink adjudication coarser.
 - `writeFileExclusive`, `writeFileGuarded` — optional; implement them only if you can do them atomically.
+- `openBound` — optional (revision 6); without it a path attachment on this device is accepted but not attached (§3.7).
 - `statBatch` — safe to omit today.
 
+
+### 3.7 `openBound` and its four answers
+
+`openBound` is a revision-6 kind: the server sends it only on a connection whose `hello.protocolVersion` is 6 or above
+**and** whose `supports` declares it. On a revision-5 connection the face is absent, exactly as if you had not declared
+it (the engine does not bind a read; a path attachment is reported `not_attached`).
+
+The protocol has no handle that lives across instructions, so the engine's bound-read object is answered one
+instruction per answer. Every `openBound` instruction is a **complete rebinding**: open `path` locally (do not
+follow a final symbolic link), ask the kernel **once, through that open**, which path the opened object now has and
+what it is, answer **through that same open**, then close it. Never read the path a second time to answer.
+
+<!-- closed-set: DEVICE_BOUND_READ_OPS -->
+
+| `op` | Carries | Answer with | Refuse with |
+|---|---|---|---|
+| `open` | `path` | `{ok:true, kind:"stat", identity, info}` — `identity` = the opened object's `<device>:<inode>`; `info.kind` is `file` or `dir` | `precondition_failed` (the final component is a link, or the opened object is not at `path`); `invalid` (neither a regular file nor a directory) |
+| `size` | `path`, `identity`, `kind` | `{ok:true, kind:"stat", info}` — `info.size` = the current size | `precondition_failed` when the object opened now is not `identity` / `kind` or not at `path` |
+| `readBytes` | `path`, `identity`, `kind`, `max` | `{ok:true, kind:"read"}`, the bytes as `data` chunks | as `size`, plus `invalid` when the file is over `max` bytes when the read starts (read nothing) |
+| `list` | `path`, `identity`, `kind` | `{ok:true, kind:"stat", entries}` — the opened directory's direct children, links not followed; the server reads only each entry's leaf name | as `size` |
+
+Rules:
+
+- **One observation per answer.** The check that the opened object is at `path` must be a single observation of
+  that open (Linux: `readlink("/proc/self/fd/<fd>")`; macOS: an open with `O_NOFOLLOW_ANY` refuses a link on any
+  component, so the open itself is the observation). Separate `fstat` / `lstat` / `realpath` calls are three
+  observations that a directory swapped in and out between them gets through. If your platform cannot give one
+  observation, answer `not_supported` — the engine reads that as "this face is absent here".
+- **Identity and kind both.** For `size` / `readBytes` / `list`, the object you opened must equal both `identity`
+  and `kind` from the `open` answer, else `precondition_failed`. Two opens whose identities are equal do not prove
+  they opened one object after an inode number was reused; that residue is accepted by the engine's contract.
+- **Bounded.** An open can block (a FIFO swapped in under the path); the whole answer must finish within the
+  instruction's `timeoutMs` and your executor must not leave the blocked open behind.
+- **No privilege above the session's own commands.** Open as the same user that runs the session's `exec`.
+- Error codes are the words of your declared revision (§2.1); nothing new is needed.
+
 ---
 
 ## 4. Streaming execution
@@ -1055,6 +1105,7 @@ These two are a real distinction to the caller: `not_started` is safely retryabl
 
 - [ ] `readLink` (recommended soon after — it is the fourth governance read)
 - [ ] `writeFileExclusive`, `writeFileGuarded` — declare only when atomic (§3.2)
+- [ ] `openBound` — declare only with one observation per answer, and only when you declare revision 6 or above (§3.7)
 - [ ] `statBatch` — not dispatched today
 
 **Process shape (recommended)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.150.0",
+  "version": "7.152.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -25,6 +25,10 @@
       "types": "./dist/model-route-env.d.ts",
       "default": "./dist/model-route-env.js"
     },
+    "./object-store-buckets": {
+      "types": "./dist/object-store-buckets.d.ts",
+      "default": "./dist/object-store-buckets.js"
+    },
     "./package.json": "./package.json",
     "./deploy/sema-up/lanes.json": "./deploy/sema-up/lib/lanes.json",
     "./deploy/facts/CHANGES.json": "./deploy/facts/CHANGES.json",
@@ -83,8 +87,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",
-    "@sema-agent/core": "7.66.0",
-    "@sema-agent/settings-schema": "25.1.0",
+    "@sema-agent/core": "7.66.1",
+    "@sema-agent/settings-schema": "26.0.0",
     "e2b": "2.36.0",
     "libsodium-wrappers": "0.8.4",
     "mysql2": "3.22.6",

package/scripts/embed-minimal.mjs

@@ -10,7 +10,7 @@
 //                                                  and a clean-up that did not happen is `failed step=cleanup` — neither is ever reported as a refusal of the omitted seat.
 //
 // The assembly order is the README "Library embedding" chain: `declareServerWithheldEnv()` → `loadConfig()` → `composeExecutionLane(config, ctx)` →
-// `judgeServedModelRoute(config, { envTableIsPlaceholder })` (the route judge, once after the config-source apply; `loadConfig()` does not judge routes) →
+// `judgeServedModelRoute(config, { envTableIsPlaceholder, webAdminIsConfigSource })` (the route judge, once after the config-source apply; `loadConfig()` does not judge routes) →
 // the nine required `createHttpServer` seats (the type `ServiceCoreDeps`) → `createHttpServer(deps)`. It imports the package root `@sema-agent/server` and the
 // engine package `@sema-agent/core` (the server's pinned dependency, owner of the `Runner` class), never a path inside `dist/`.
 // The service it assembles runs on the host lane against a throwaway local data root and listens on a kernel-assigned loopback port; it takes no task,
@@ -84,8 +84,8 @@ try {
   const logger = createLogger("error");
   const config = await composeExecutionLane(loadConfig(), { configSource: undefined, localRoot: dataRoot, logger, entry: HTTP_SERVICE_LANE_ENTRY });
   // The route judge runs after the config-source apply, never inside `loadConfig()`: a model row with no endpoint would otherwise travel to the first model call.
-  // No center here ⇒ the env table is the served table, not a placeholder awaiting a catalog.
-  const routeGap = judgeServedModelRoute(config, { envTableIsPlaceholder: false });
+  // No center here ⇒ the env table is the served table, not a placeholder awaiting a catalog; and no web-admin config source either (`configSource: undefined` above).
+  const routeGap = judgeServedModelRoute(config, { envTableIsPlaceholder: false, webAdminIsConfigSource: false });
   if (routeGap !== undefined) throw new Error(routeGap.reason);
 
   // ── seats: peerDesk, deploymentMods (package root: createPeerDesk; `[]` = no mods) ────────────────────────────────────────────────────────