@sema-agent/server 7.118.0 → 7.120.0

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -46,7 +46,9 @@ which version the server speaks before you spend a handshake finding out.
                                                                                       acquire the connection lease
                                       ◀── helloAck { gen, heartbeatIntervalMs,
                                                      maxInflight, pendingInstructions,
-                                                     chunkWatermarks }
+                                                     chunkWatermarks, reconnectGraceMs,
+                                                     cancelGraceMs, chunkGapTimeoutMs,
+                                                     executionCeilingGraceMs }
                                                   … or helloReject { code }
                                       fence: kill/drain everything from older generations
                                       generationAck { gen }  ───────────────────────▶ now (and only now) the
@@ -79,7 +81,7 @@ which version the server speaks before you spend a handshake finding out.
    | `platformOs` | yes | closed set `darwin` \| `linux` (anything else is a `400`; there is no third value) |
    | `platformArch` | no | ≤ 32 bytes |
    | `displayName` | no | ≤ 255 bytes |
-   | `workspaceRoot` | yes | non-empty, ≤ 1024 bytes — the device-side root that path resolution falls back to |
+   | `workspaceRoot` | yes | ≤ 1024 bytes, **an absolute POSIX path** — the device-side root that path resolution and `exec` `cwd` fall back to. Registration refuses anything else (empty, relative, `~/…`) with `400 request.field_invalid`; the same check runs again when a session's execution environment is created, so a device registered with a non-absolute root by an older server is refused there |
 
    `deviceId` and the owner are **not** inputs: the server mints `dev_<26-char ULID>` and takes the owner
    from the verified credential. The response is `200 { deviceId }` and contains no secret of any kind.
@@ -251,6 +253,17 @@ backoff, exponential to a 60 s ceiling, jittered — except for `revoked`, which
 | `gen` | **canonical decimal string** (`"7"`, never `7`, never `"07"`) | the connection generation. Stamp it on every frame you send |
 | `pendingInstructions` | `string[]` | instruction ids the server still considers in flight for you — see §5 R2 |
 | `chunkWatermarks` | `{ [instructionId]: number }` | per instruction, the highest **contiguous** `streamSeq` the server has already accepted. `-1` means "nothing accepted yet" |
+| `reconnectGraceMs` | integer ms | the reconnect grace **in force on this server** (R4): how long in-flight work survives a dropped socket. Deployment-tunable, default 120000 |
+| `cancelGraceMs` | integer ms | the cancel grace in force (R11): how long after a `cancel` is delivered the server waits for your terminal `result`. Default 10000 |
+| `chunkGapTimeoutMs` | integer ms | the chunk-gap timeout in force (R8): how long the server waits for a missing `streamSeq` before failing the instruction. Default 30000 |
+| `executionCeilingGraceMs` | integer ms | the grace added to an instruction's `timeoutMs` before the server gives up and settles it as outcome-unknown (R12: the ceiling is `timeoutMs + executionCeilingGraceMs`). Default 30000 |
+
+The four grace fields are the values the server's own timers are armed with — not documentation defaults. Size
+your reconnect backoff ceiling, your `cancel` answer deadline, your retransmission cadence and your own
+`timeoutMs` enforcement from them. A server that predates them omits all four; treat absence as "not told" and
+fall back to the defaults in the table above, never as zero. For the same reason the published TypeScript type
+(`DeviceHelloAckFrame` from `@sema-agent/server/device-protocol`) declares the four as optional; a server from
+7.120.0 on always sends all four.
 
 `gen` is a string because it is a 64-bit database value; parse it as an integer only if your language can
 hold it, and always **echo the string you were given** rather than re-formatting a number.
@@ -276,7 +289,7 @@ fenced — that half is yours, and it is the reason a device-level single-instan
 
 Send `goodbye { gen, reason, graceMs? }`. The server stops *starting* new dispatches for this connection
 and keeps collecting results for the ones already in flight, then closes the socket after `graceMs` (if you
-omit it, the deployment's reconnect grace — default 120000 ms — is used). Sending `goodbye` does not settle
+omit it, the deployment's reconnect grace — `helloAck.reconnectGraceMs`, default 120000 ms — is used). Sending `goodbye` does not settle
 anything: finish or fail your in-flight instructions properly before you exit.
 
 ⚠️ **`goodbye` is not a hard barrier.** The check happens when a dispatch *enters* the pipeline, and a
@@ -341,9 +354,9 @@ zeros, a plus sign, whitespace or a float form are rejected as malformed.
 | `t` | Fields | Notes |
 |---|---|---|
 | `challenge` | `nonce` string, `protocolVersion` int | first frame the server sends, immediately on open |
-| `helloAck` | `ok`, `heartbeatIntervalMs`, `maxInflight`, `gen`, `pendingInstructions`, `chunkWatermarks` | §1.5 |
+| `helloAck` | `ok`, `heartbeatIntervalMs`, `maxInflight`, `gen`, `pendingInstructions`, `chunkWatermarks`, `reconnectGraceMs`, `cancelGraceMs`, `chunkGapTimeoutMs`, `executionCeilingGraceMs` | §1.5 |
 | `helloReject` | `code`, `minProtocolVersion?` | §1.4; the socket closes right after |
-| `instruction` | `gen`, `instructionId`, `rootSessionId`, `issuedSeq` int, `kind`, `args`, `cwd?`, `shellEnv?`, `timeoutMs` int | one unit of work (§3) |
+| `instruction` | `gen`, `instructionId`, `rootSessionId`, `issuedSeq` int, `kind`, `args`, `cwd?`, `shellEnv?`, `timeoutMs` int | one unit of work (§3). `cwd` appears on `exec` / `execStream` only, and always there (§3.1) |
 | `payload` | `gen`, `instructionId`, `part` (`begin` \| `chunk` \| `commit`), `offset?`, `dataB64?`, `totalLen?`, `sha256?` | the bytes for a write-family instruction (§3.4) |
 | `cancel` | `gen`, `instructionId` | idempotent; answer with a terminal `result` (§5 R11) |
 | `resultAck` | `gen`, `instructionId` | you may release that instruction's buffers |
@@ -416,8 +429,10 @@ silently forgiven: it becomes a gap or a missing terminal, and the instruction e
 ### 3.1 The closed set, its arguments, and the success outcome each one owes
 
 Every `path` in `args` arrives **already absolute and POSIX-normalized** — the server resolved it against
-the session's working directory before sending. `cwd` (when present) is likewise absolute; when it is
-absent, run in the instruction's implied working directory (the resolution base the server already used).
+the session's working directory before sending. `exec` and `execStream` additionally carry `cwd`, which is
+**always present and always absolute**: run the command in exactly that directory. There is no implicit
+base to fall back to, so an executor needs no branch for a missing or relative `cwd`. Every other kind
+carries no `cwd` — its paths are already absolute.
 
 <!-- closed-set: DEVICE_INSTRUCTION_KINDS -->
 
@@ -551,10 +566,37 @@ payload { part: "commit", instructionId, totalLen, sha256 }
 2. on `commit`, verify the length **and** the digest;
 3. only then rename into place — atomically, honouring the instruction's semantics (exclusive create,
    guarded expectation, append);
-4. any failure at any step fails the **whole instruction** and leaves **no half-written file**.
+4. any failure at any step fails the **whole instruction** and leaves **no half-written file** — with one
+   exception, `appendFile`, which is stated next.
 
 `defaultPayloadPartBytes` is 262144, but do not assume it: use `offset` and `totalLen`.
 
+**`appendFile` is the one write that cannot be all-or-nothing.** Steps 1–3 give `writeFile`,
+`writeFileExclusive` and `writeFileGuarded` their guarantee by building the complete file beside the target
+and swapping it in. An append has no such swap: it extends the existing target **in place**, so there is a
+moment after which the target has changed and the instruction has not finished. What POSIX guarantees for an
+`O_APPEND` write is that the position is taken at end-of-file atomically; it does not promise that the payload
+lands in one piece. This protocol therefore asks you to treat `PIPE_BUF` bytes (the POSIX minimum is 512; Linux
+uses 4096) as the largest append you may regard as indivisible — the conservative bound, borrowed from the
+rule POSIX states for pipe writes — and to assume that anything larger can reach the file in several writes,
+interleave with another writer's appends, or stop part-way. So what you answer depends on *when* you fail:
+
+- **The target cannot have been touched yet** — the payload failed its length or digest check, the target
+  could not be opened, your own containment policy refused the path. Answer the ordinary code
+  (`permission_denied`, `not_found`, `is_directory`, `invalid`, …). Nothing changed, so the caller may safely
+  retry.
+- **The target may already have been changed** — a short write, an I/O error part-way through, or the process
+  or the machine going away while the append was running, so that you cannot say how much landed. Answer
+  `outcome_unknown` (§3.3). Never answer `timeout` or `transport_lost` here: both are retryable, and a retry
+  appends the content a second time.
+- **The whole payload was appended.** Answer `{ok:true, kind:"void"}`. Do not report success for a partial
+  append.
+
+The server settles an executor-reported `outcome_unknown` exactly like one it reaches by its own deadlines:
+the caller gets the code `outcome_unknown`, which nothing upstream retries, and your message is kept and
+followed by a fixed sentence telling the model to verify the file's contents before running the append again.
+So make your message specific about what you know (bytes written, where it stopped).
+
 ### 3.5 `writeFileGuarded` and its `expect`
 
 `expect` is `{ canonicalPath: string, fileId?: string, exclusive?: boolean, noFollow?: boolean }`:
@@ -605,7 +647,7 @@ server delivers in order and buffers out-of-order chunks; it acks with `chunkAck
 **cumulative** watermark meaning "everything up to and including this is accepted" (`-1` = nothing yet).
 You may release buffers at or below the watermark.
 
-- A gap that is not filled within the deployment's gap timeout (default 30 s) **fails the instruction**
+- A gap that is not filled within the deployment's gap timeout (`helloAck.chunkGapTimeoutMs`, default 30 s) **fails the instruction**
   with `outcome_unknown` — output is never silently truncated.
 - The reorder buffer is bounded (default 64 entries / 2 MiB decoded). Running far ahead of the watermark
   overflows it and also fails the instruction.
@@ -711,7 +753,7 @@ process — that work is accounted for as "may have run".
 
 **R4 — no reconnect within the grace ⇒ the books close.**
 *Given* the socket dropped with `I` in flight, *when* no connection for this device is established within
-the reconnect grace (default 120 s), *then* `I` settles `outcome_unknown`; a later reconnect does not list
+the reconnect grace (`helloAck.reconnectGraceMs`, default 120 s), *then* `I` settles `outcome_unknown`; a later reconnect does not list
 it, and its `result` is either refused or memo-acked without being believed (§2.4).
 *Executor:* reconnect promptly. If you were offline longer than the grace, your results are no longer
 deliverable — that is not a licence to re-run anything.
@@ -742,7 +784,7 @@ as the original — the first copy the server buffered is the one it will delive
 
 **R8 — a gap is a failure, not a truncation.**
 *Given* the server is waiting for `streamSeq k`, *when* `k` does not arrive within the gap timeout
-(default 30 s) or the reorder buffer overflows (default 64 entries / 2 MiB), *then* `I` fails with
+(`helloAck.chunkGapTimeoutMs`, default 30 s) or the reorder buffer overflows (default 64 entries / 2 MiB), *then* `I` fails with
 `outcome_unknown` — the command already ran, so the result cannot be faithfully reported.
 *Executor:* never skip a `streamSeq`, never renumber after a reconnect, never "compact" a stream.
 
@@ -766,18 +808,18 @@ machine from taking over the lease mid-command; only you can.
 
 **R11 — `cancel` demands a terminal, within a grace.**
 *Given* the server sent `cancel` for `I`, *when* you do not send a terminal `result` within the cancel
-grace (default 10 s, restarted each time the cancel is delivered), *then* `I` settles `outcome_unknown`.
+grace (`helloAck.cancelGraceMs`, default 10 s, restarted each time the cancel is delivered), *then* `I` settles `outcome_unknown`.
 `cancel` is idempotent, is delivered at most once per generation, and **is replayed on the first active
 tick after a same-epoch reconnect** (a cancel written to a socket that then dropped may never have
 arrived).
 *Executor:* treat a repeated `cancel` for the same `I` as a no-op. Answer exactly one terminal:
 `{ok:true, kind:"cancelled", state:"not_started"}` if the work had not begun, `state:"killed"` if you
-killed it, or the work's ordinary outcome if it had already finished. Answer promptly — 10 s is the budget.
+killed it, or the work's ordinary outcome if it had already finished. Answer promptly — `cancelGraceMs` (default 10 s) is the budget.
 
 **R12 — two-layer timeout: yours is authoritative, the server's is a backstop.**
 *Given* an instruction carrying `timeoutMs`, *when* that budget elapses, *then* you must kill the work and
 answer `{ok:false, errorCode:"timeout"}` — that is the only path to the retryable `timeout` word. *When*
-you answer nothing, the server gives up at `timeoutMs` + a grace (default 30 s) and settles
+you answer nothing, the server gives up at `timeoutMs` + `helloAck.executionCeilingGraceMs` (default 30 s) and settles
 `outcome_unknown`; a later result for `I` is then undeliverable.
 *Executor:* enforce `timeoutMs` yourself, and prefer answering late-but-honestly over not answering.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.118.0",
+  "version": "7.120.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",
@@ -64,7 +64,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.44.0",
+    "@sema-agent/core": "7.46.0",
     "@sema-agent/settings-schema": "8.0.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",