deepdebug-local-agent 1.8.0 → 1.10.0

package/src/la-protocol-v2/contract/README.md

@@ -5,13 +5,16 @@ sides. Design: vault `10 Library/Plans/Fase 3 Desenho Tecnico 2026-10-28.md` sec
 implements it behind `deepdebug.agent-ws.protocol-v2.enabled` (default off, F3-05a); the LA side (F3-05b) does not
 exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json` from this folder as classpath
 `la-protocol-v2/` (pom resource; both Dockerfiles copy this folder), so this folder stays the only source.
+**Revision 2.1** (`index.json` `revision`, Fase 3, last section): optional LLM key delivery, chunked webhooks, size/model in `incident.candidate`, `ready.capabilities`, `job.assign.options` and the capabilities `job.assign` / `job.options`.
 
 ## Files
 - `envelope.schema.json`: common frame, closed (`additionalProperties:false`). `<type>.schema.json` (22):
   one per allowlisted type, each `$ref`s the envelope and closes `payload`. `defs.schema.json`: shared types.
 - `file.list.body.schema.json` (F3-07c): not a frame type; the schema of the DECODED body of a `content.response` for kind `file.list`
   (below). `vectors/file.list.body.vectors.json` holds its vectors (same format, `schema` names that file).
-- `index.json`: allowlist, direction, signed/control flags, content class per type, and the limits below.
+- `index.json`: allowlist, direction, signed/control flags, content class per type (`none`, `relay`, `transit`, `secret`), the limits below and the contract `revision`.
+- Vector files of a BODY that travels inside a frame (not a frame) are named `*.body.vectors.json` and their schema `*.body.schema.json`; the frame
+  suites skip them (`ProtocolV2ContractTest` checks them against their own schema, `SchemaLaV2ContractTest` does not read them as frames).
 - `vectors/<type>.vectors.json` (+ `cross-type`): valid and invalid messages with `expect` (`valid`, error `code`,
   optional JSON Schema `keyword`, optional session `rule`). `vectors/traces/*.json`: whole sessions for the stateful rules.
 
@@ -30,7 +33,8 @@ ack timeout 5 s, <= 3 retransmissions; handshake steps 10 s; `ping`/`heartbeat`
 (= Redis `la:session` TTL); clock skew <= 60 s. Duplicate detection (gateway, F3-05a): the last 512 `seq`->`msgId` pairs
 per session, in memory (`dedupe-entries`); the 10 min Redis window of the design (`dedupeWindowSeconds` in `index.json`)
 is NOT implemented, a replay older than those 512 frames is `seq_replayed`. CP->LA frames repeat the payload in
-`paramsRaw`, so their effective payload budget is about 20 KiB; larger inputs travel by `ref`.
+`paramsRaw`, so their effective payload budget is about 20 KiB; larger inputs travel by `ref`. Webhook chunking (2.1) has its own limits
+(`webhook*` in `index.json`: 16 KiB raw per chunk, 64 chunks, 1 MiB per webhook, see the last section).
 
 ## State machine
 `AWAIT_REGISTER -> AWAIT_HELLO -> AWAIT_READY -> READY`, after the WS upgrade authenticates (Bearer, as v1).
@@ -45,7 +49,9 @@ is NOT implemented, a replay older than those 512 frames is `seq_replayed`. CP->
   handshake state, `seq` (same seq + same `msgId` = idempotent duplicate, re-ack; same seq + other `msgId` =
   `seq_replayed`; skip = `seq_gap`), chunks (index 0.., `total` constant, `last` iff last index, none after last; then `payload.byteLength` must equal the size of
   the base64-DECODED `payload.data`, else `chunk_inconsistent`: JSON Schema cannot state it, so the vector files carry
-  `expect.rule:"byteLength-decoded"` and both validators apply it).
+  `expect.rule:"byteLength-decoded"` and both validators apply it). Since 2.1 two more stateless rules of the same kind:
+  `webhook-chunk-size` and `llmKey-id-sha256` (last section); `webhook.forward` chunks are also grouped by `payload.webhookId` and the reassembled
+  body must hash to `bodySha256` (`chunk_inconsistent` otherwise).
 - **Errors** (`error{code,retryable}`, then WS close 4400-4499 when fatal): `bad_frame unknown_type schema_violation
   frame_too_large payload_too_large wrong_direction handshake_violation not_ready seq_gap seq_replayed
   chunk_out_of_order chunk_inconsistent tenant_mismatch agent_mismatch params_mismatch signature_mode_insufficient
@@ -64,6 +70,7 @@ Everything is closed: no free-text fields, no extra properties, free strings <=
 hashes, counts). Client content may exist only in three declared fields (`x-content-class`, pinned by the test):
 `content.response.data` (relay, LA->CP, never persisted or logged by the CP), `job.assign.inputs[].inline` and
 `webhook.forward.bodyB64` (transit, CP->LA, `transient:true`, not persisted; `paramsRaw` echoes them).
+Since 2.1 there is one more classified field and it is the only SECRET: `config.update.llmKey.key` (`x-content-class: secret`, see the last section).
 Long non-content strings are marked `x-large-metadata` (`paramsRaw`, `signedPutUrl`, `vhapr1` token). `error.detail` <= 200 chars
 and `audit.event` have no summary text; stack traces, diffs, logs and paths go only through `content.*`.
 
@@ -186,3 +193,120 @@ existing kinds, `ref` convention, ids, envelope and chunking are reused; the cha
   answer is HTTP 501 `not_supported`. That announcement is also how the front/CP discovers that listing exists on a given agent.
 - **Compatibility.** Additive: the kind is added to the `content.request` and `content.index` enums, nothing else changes there. The
   `content.request` payload gained no field. With `deepdebug.content-relay.enabled` off nothing is mapped, as before.
+
+## Revision 2.1 (Fase 3, contract v2.1): LLM key, chunked webhooks, size and model of a candidate
+Decisions of Edu 2026-11-03 (ADR-0017, adenda (c)). **No new frame type** (still 22), every change is additive and optional, and each is gated by a
+capability so a 2.0 peer keeps working unchanged. The gateway code that uses these fields is a later task (G); here only the contract moved.
+
+**Capabilities (negotiation).** The LA announces, in `register` and `hello` `capabilities`: `contract.v2.1` (it has the 2.1 schemas, so it can read the
+new optional `ready.payload.capabilities`), `llm.key` (it handles `config.update.llmKey`) and `webhook.chunked` (it reassembles chunked `webhook.forward`;
+it announces `webhook.forward` too). The CP announces, in `ready.payload.capabilities` (array, <= 32, same name pattern): `incident.candidate.size-model` (it
+accepts `stackBytes` and `model`). Rules: the CP sends `llmKey` only to a session that announced `llm.key`, a chunked webhook only to one that announced
+`webhook.chunked`, and `ready.capabilities` only to one that announced `contract.v2.1` (a 2.0 LA's closed `ready` schema does not know the field, so without
+`contract.v2.1` the `ready` is exactly the 2.0 one); an LA sends `stackBytes`/`model` only if `ready` listed `incident.candidate.size-model` (a 2.0 CP would
+answer the closed schema with `schema_violation`). A name that is absent means 2.0 behaviour.
+One more LA capability, `llm.key.held` (section (e)), tells the CP the LA holds a valid key right now; it is optional and only informs the CP.
+
+### (a) LLM key delivery: `config.update.payload.llmKey`
+`config.update` already carried only flags, a DLP hash, a minimum version, a retention and the data-plane mode: it had no way to hand the LA the virtual
+LiteLLM key (F3-09). `llmKey` is a closed `oneOf`:
+- `{op:"set", keyId, endpoint, key, models[], expiresAt}`, all required. `keyId` is the 64-hex lower-case sha256 of the UTF-8 bytes of `key` (it is
+  LiteLLM's token id and the CP's `la_llm_keys.key_id`; semantic rule `llmKey-id-sha256`: the LA recomputes it and refuses a mismatch). `endpoint` is the AI
+  gateway base URL, `https://` only, host[:port][/path], no credentials, no query, no fragment, <= 256 chars. `key` is 16..256 chars of
+  `[A-Za-z0-9._~+/=-]` (no whitespace, no control character). `models` is 1..32 unique aliases (the scope of the key). `expiresAt` is UTC.
+- `{op:"revoke", keyId}`: names the key by id, never repeats it.
+- A `config.update` that carries `llmKey` carries NOTHING else (`maxProperties: 1`), so the frame can be recognised and redacted as a whole.
+- **The key is a secret.** `x-content-class: secret` on `llmKey.key`; `index.json` marks `config.update` `contentClass: "secret"`. It travels only on the v2
+  channel (TLS plus the Ed25519 signature) and, between gateway instances, only inside the AEAD-sealed relay (F3-04). It appears twice in the frame, in
+  `payload` and in the `paramsRaw` copy: BOTH are secret. The CP never writes it to a log, a metric, a trace, the audit trail, a table or an unsealed Redis
+  value (it keeps it only in the in-memory unacked frame until acked or the session ends). The LA keeps it **only in memory or in a file mode `0600`
+  (directory `0700`) outside every workspace and outside what the content handlers can serve**, never logs it, never puts it in `hello`, `alert`,
+  `audit.event`, `job.event`, `content.response` or an error, and never passes it on a command line.
+- **The ack never returns it.** The answer is the plain `ack` (its payload is only `ackSeq`, `status`, `errorCode`; the contract test pins that no LA->CP
+  frame has a field named `key`, `llmKey` or `keyId`): `accepted`, or `rejected` + `schema_violation` when the LA refuses the key (expired
+  `expiresAt`, `keyId` not the sha256 of `key`).
+- **Rotation.** A `set` with another `keyId` replaces the key the LA holds, atomically (one key per LA); the same `keyId` again is idempotent. The CP should
+  revoke the old key at the AI gateway only after the `accepted` ack of the new one.
+- **Revocation.** The key revoked at the AI gateway is the authoritative revocation; the `revoke` frame only makes the LA drop its copy (delete from memory,
+  unlink and overwrite the file) and stop using it. A `revoke` of an id the LA does not hold is a no-op and is acked `accepted` (it never tells which key it
+  has). The LA also drops the key at `expiresAt`.
+
+### (b) Chunking of `webhook.forward` (CP -> LA)
+2.0 allowed one frame with `bodyB64` <= 12288 chars (9216 raw bytes). That stays: **a body of at most 9216 bytes is sent as ONE frame without `chunk`, exactly
+as in 2.0** (a 2.0 LA reads it). A bigger body (up to **1 MiB**) is chunked, reusing the `content.response` pattern but CP -> LA:
+- Each chunk is a signed `webhook.forward` frame with the envelope `chunk{index,total,last}` (index from 0), its own `seq` and `msgId`, and the same
+  `webhookId`, `source`, `contentType`, **`bodyBytes`** (size of the WHOLE decoded body, 0..1048576) and **`bodySha256`** (sha256 of the whole decoded body,
+  lower-case hex). `bodyBytes` and `bodySha256` are required in a chunked frame and forbidden in an unchunked one (schema `if/then/else` on `chunk`).
+- **Fixed chunk size**: 16384 raw bytes (`bodyB64` <= 21848 chars; twice in the frame with `paramsRaw` it still fits 48 KiB: a vector pins it).
+  `total = max(1, ceil(bodyBytes / 16384))` (<= 64); every non-last chunk has exactly 16384 bytes; the last has `bodyBytes - 16384 * (total - 1)`. That is the
+  stateless rule `webhook-chunk-size` (`chunk_inconsistent` when a frame breaks it), so the LA can size the buffer from the first chunk. A body above
+  9216 bytes is never sent unchunked; a chunked frame with a small body (`total` 1) is valid.
+- **Order and integrity** (reference model, same codes as `content.response`): chunks in index order, `total` constant, `last` iff the last index, none after
+  the last (`chunk_out_of_order` / `chunk_inconsistent`); `bodyBytes`, `bodySha256`, `source`, `contentType` must not change between chunks; on the last
+  chunk the reassembled body must have `bodyBytes` bytes and hash to `bodySha256`, else `chunk_inconsistent`. Each chunk is also authentic on its own (signature).
+- **Acks.** Every chunk is a normal v2 frame: the LA acks each by `seq` (piggyback or `ack{ackSeq,status}`), `accepted` = stored. The `accepted` ack of the
+  LAST chunk means the body was reassembled and its hash verified: that is the ack the CP waits for before answering the webhook (decision: ack AFTER the
+  forward). The LA answers `rejected` + `chunk_inconsistent` / `chunk_out_of_order` / `payload_too_large` / `rate_limited` and drops the assembly; the CP then
+  stops sending chunks of that `webhookId` and treats the webhook as not delivered.
+- **LA limits** (`index.json`): an assembly older than 30 s (`webhookAssemblySeconds`) without its last chunk is dropped; at most 4 open assemblies per session
+  (`webhookMaxOpenAssemblies`; the CP sends one chunked webhook at a time per session) and 4 MiB buffered; beyond that `rejected` + `rate_limited`. The body
+  stays in memory, is never written or logged by the CP, and the LA applies its DLP to it as to any client content.
+- `webhookId` is the group key; a retransmitted chunk (same `seq` and `msgId`) is the existing idempotent duplicate; the same `webhookId` redelivered as a
+  whole is the application's dedup (a deterministic `webhookId` is the consumer's job).
+
+### (c) `incident.candidate`: `stackBytes` and `model`
+Two OPTIONAL fields, no required field added: `stackBytes` (integer 0..16777216: size in bytes of the stack the LA saw; the LA saturates at the cap) and
+`model` (string 1..48, `^[A-Za-z0-9][A-Za-z0-9._:+-]{0,47}$`: detector/parser version, e.g. `stack-detector-1.8.0`; no space, no slash, so no name, path or
+error text fits). The frame still carries no stack, no message and no name. Sent only after `ready` announced `incident.candidate.size-model`.
+
+### (d) `ready.payload.capabilities`
+Optional array (<= 32 capability names). It is what lets (c) be sent safely; it carries no limit and no content. A CP that does not send it is a 2.0 CP, or the
+session did not announce `contract.v2.1`.
+
+### (e) `llm.key.held`: the LA says whether it still has its key
+Problem it solves: an LA that keeps the key only in memory (the default) loses it on restart, but the CP's table still says ACTIVE, and the CP only
+delivers again when the key is close to expiry (< 14 days), so the LA would stay without a key. Rather than the CP guessing, the LA announces it.
+- **Name and place.** The capability string `llm.key.held` (it already matches the `capability` pattern, so no schema enum changes), announced in
+  `register.payload.capabilities` and in `hello.payload.capabilities`, never in `ready.payload.capabilities` (that list is the CP's). It is optional and
+  needs no `contract.v2.1` decision of its own: a CP that does not know it ignores an unknown capability name, as it ignores any other.
+- **Rule for the LA.** It announces `llm.key.held` ONLY when it holds a key that is still valid (`expiresAt` in the future, accepted and
+  `keyId`-verified through `config.update.llmKey`) and that it is IN USE (it is the key its LLM calls would use). No key, an expired key, a revoked key
+  or a key it refused: it does not announce it. The announcement is a snapshot at connect time: `register` and `hello` of one session carry the same
+  answer, and the LA never announces it without also announcing `llm.key` (an LA that cannot receive a key cannot hold one). That dependency is in the
+  schema (`if capabilities contains llm.key.held then it must contain llm.key`, `register` and `hello`), so `llm.key.held` alone is `schema_violation`.
+- **Rule for the CP.** At connect, if the capability is NOT announced (in `register` and `hello`; the CP should treat the key as held only when both
+  say so), the CP delivers a key (mint, then `config.update.llmKey set`) even when an ACTIVE row exists for that agent; the previous key follows the
+  rotation rule of (a) (revoked at the AI gateway only after the `accepted` ack of the new one). If it IS announced, the CP keeps the existing rule:
+  nothing to deliver until the key is within 14 days of `expiresAt`. A 2.0 LA, or a 2.1 LA that does not know the capability, never announces it, so
+  the CP treats it as "holds no key" and delivers one if the channel is on (`llm.key` announced): the safe direction.
+- **Compatible.** Optional and additive: a register/hello without it is valid (2.0, or 2.1 after a restart), and one with it is valid under 2.1 only
+  together with `llm.key`. No frame type, no new field and no new limit. The CP side of this rule is gateway runtime code (a later task, not this contract).
+
+### (f) Jobs: `job.assign`, `job.cancel`, `job.event`, `job.result` and the capabilities `job.assign` and `job.options` (F3-10)
+The four job frames exist since 2.0 (their schemas did not change, except `options` below). What F3-10 adds is the negotiation and one optional field.
+- **Capability `job.assign`.** An LA that runs jobs announces `job.assign` in `register.payload.capabilities` and in `hello.payload.capabilities`. It covers BOTH
+  `job.assign` and `job.cancel` (one name, because an LA that can take a job can stop it): the CP sends neither to a session that did not announce it, and a CP
+  that has no agent with it answers its caller `503 AGENT_UNSUPPORTED`. A LA announces it only when it has a runner to run the job (no runner, no capability).
+  An LA that announced it but still answers `job.assign` with `rejected protocol_unsupported` (its jobs feature is off) did NOT take the job: the CP may offer
+  it to another agent of the tenant.
+- **Capability `job.options`.** An LA that understands `job.assign.payload.options` announces `job.options` (it implies `job.assign`). The CP sends `options` ONLY to
+  such a session. Both names match the `capability` pattern, so no enum changes.
+- **`job.assign.payload.options` (optional, closed object, `minProperties` 1).** How to run the job; absent means the LA's own defaults, exactly as in 2.0.
+  Fields (all optional): `ticketKey` (a `shortId`: the ticket of the request), `branchName` (<= 255, `^(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*[./]$)(?!.*\.lock(/|$))[A-Za-z0-9_][A-Za-z0-9_./-]{0,254}$`:
+  no `..`, no `//`, no component starting with `.`, no trailing `.` or `/`, no `.lock` suffix, no space or shell character, no leading `-`), `createBranch` (bool),
+  `createPullRequest` (bool), `dryRun` (bool), `maxIterations` (integer 1..100). None of them is content (an id, a ref name, flags, a counter), so none is a
+  `transit` field; the request text itself still travels only in `inputs[].inline`. There is no field for a token or a path (the object is closed).
+- **What an LA must do with it.** `dryRun:true` means: run the whole loop but push nothing, open no pull request and notify nobody. `createPullRequest:false`
+  means: do not open one (the branch may be pushed when `createBranch` is not false). `createBranch:false` means: work on `repoRef.branch` without creating a branch.
+  `maxIterations` caps the agent loop below the LA's own cap (never above it). `branchName`/`ticketKey` name the branch to create. An LA never widens its own policy because
+  of an option: the budget and the policy of the same payload still bound the job.
+- **Rule for the CP.** Options that change external effects (`dryRun:true`, `createPullRequest:false`) are sent only to an LA that announced `job.options`; if none
+  did, the CP REFUSES the job (`OPTION_NOT_SUPPORTED`) instead of running one with a real pull request. The other options (ticket, branch, `createBranch`,
+  `maxIterations`) are an optimisation of the same default behaviour: for an LA without `job.options` the CP sends the job without `options`.
+- **Compatible.** A `job.assign` without `options` is valid under 2.0 and 2.1 and means what it always meant. The CP gateway side is `deepdebug.jobs.dispatch-to-la.enabled`
+  (default off); the vectors are `vectors/job.assign.vectors.json` (`options-*`).
+
+### Compatibility and roll-out order
+Everything is additive and optional: a 2.0 frame is valid under the 2.1 schemas (the vectors of 2.0 are unchanged and still pass), and a 2.1 peer talking to a
+2.0 peer sends nothing the 2.0 peer cannot read, because each new field is gated by a capability the other side announced (above). Roll out the gateway that
+has the 2.1 schemas first (it accepts both shapes), then the LAs. The files changed by 2.1 are listed with their sha256 in the PR; the LA re-syncs exactly those.

package/src/la-protocol-v2/contract/config.update.schema.json

@@ -52,9 +52,93 @@
         },
         "dataPlaneMode": {
           "$ref": "defs.schema.json#/$defs/dataPlaneMode"
+        },
+        "llmKey": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "op": {
+                  "const": "set"
+                },
+                "keyId": {
+                  "$ref": "defs.schema.json#/$defs/sha256"
+                },
+                "endpoint": {
+                  "type": "string",
+                  "minLength": 12,
+                  "maxLength": 256,
+                  "pattern": "^https://[A-Za-z0-9]([A-Za-z0-9.-]{0,251}[A-Za-z0-9])?(:[0-9]{1,5})?(/[A-Za-z0-9._~/-]{0,200})?$"
+                },
+                "key": {
+                  "type": "string",
+                  "minLength": 16,
+                  "maxLength": 256,
+                  "pattern": "^[A-Za-z0-9._~+/=-]{16,256}$",
+                  "x-content-class": "secret"
+                },
+                "models": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 32,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 96,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,95}$"
+                  }
+                },
+                "expiresAt": {
+                  "$ref": "defs.schema.json#/$defs/ts"
+                }
+              },
+              "required": [
+                "op",
+                "keyId",
+                "endpoint",
+                "key",
+                "models",
+                "expiresAt"
+              ]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "op": {
+                  "const": "revoke"
+                },
+                "keyId": {
+                  "$ref": "defs.schema.json#/$defs/sha256"
+                }
+              },
+              "required": [
+                "op",
+                "keyId"
+              ]
+            }
+          ]
         }
       },
-      "minProperties": 1
+      "minProperties": 1,
+      "if": {
+        "type": "object",
+        "properties": {
+          "llmKey": true
+        },
+        "required": [
+          "llmKey"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "llmKey": true
+        },
+        "maxProperties": 1
+      }
     },
     "seq": {
       "type": "integer",

package/src/la-protocol-v2/contract/hello.schema.json

@@ -94,7 +94,32 @@
         "clockEpochMs",
         "diskFreeBytes",
         "queueDepth"
-      ]
+      ],
+      "if": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key.held"
+            }
+          }
+        },
+        "required": [
+          "capabilities"
+        ]
+      },
+      "then": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key"
+            }
+          }
+        }
+      }
     },
     "seq": {
       "const": 0

package/src/la-protocol-v2/contract/incident.candidate.schema.json

@@ -72,6 +72,17 @@
             "security",
             "other"
           ]
+        },
+        "stackBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 16777216
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 48,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:+-]{0,47}$"
         }
       },
       "required": [

package/src/la-protocol-v2/contract/index.json

@@ -1,5 +1,6 @@
 {
   "protocol": 2,
+  "revision": "2.1",
   "baseId": "https://schemas.visionhammer.io/la-protocol-v2/",
   "limits": {
     "maxFrameBytes": 49152,
@@ -12,7 +13,13 @@
     "heartbeatSeconds": 30,
     "sessionDeadSeconds": 90,
     "dedupeWindowSeconds": 600,
-    "clockSkewSeconds": 60
+    "clockSkewSeconds": 60,
+    "webhookChunkRawBytes": 16384,
+    "webhookMaxChunks": 64,
+    "webhookMaxBytes": 1048576,
+    "webhookSingleFrameRawBytes": 9216,
+    "webhookAssemblySeconds": 30,
+    "webhookMaxOpenAssemblies": 4
   },
   "types": {
     "register": {
@@ -118,7 +125,7 @@
       "direction": "cp->la",
       "control": false,
       "signed": true,
-      "contentClass": "none"
+      "contentClass": "secret"
     },
     "scan.upload": {
       "schema": "scan.upload.schema.json",

package/src/la-protocol-v2/contract/job.assign.schema.json

@@ -184,6 +184,37 @@
               }
             ]
           }
+        },
+        "options": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Optional (revision 2.1, capability job.options): how to run the job. Absent = the Local Agent's own defaults. Sent only to a Local Agent that announced job.options; none of these fields is content (a ticket id, a branch name, flags and a counter).",
+          "properties": {
+            "ticketKey": {
+              "$ref": "defs.schema.json#/$defs/shortId"
+            },
+            "branchName": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 255,
+              "pattern": "^(?!.*\\.\\.)(?!.*//)(?!.*/\\.)(?!.*[./]$)(?!.*\\.lock(/|$))[A-Za-z0-9_][A-Za-z0-9_./-]{0,254}$"
+            },
+            "createBranch": {
+              "type": "boolean"
+            },
+            "createPullRequest": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "maxIterations": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            }
+          },
+          "minProperties": 1
         }
       },
       "required": [

package/src/la-protocol-v2/contract/ready.schema.json

@@ -81,6 +81,14 @@
             "maxRetries",
             "heartbeatSeconds"
           ]
+        },
+        "capabilities": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "defs.schema.json#/$defs/capability"
+          }
         }
       },
       "required": [

package/src/la-protocol-v2/contract/register.schema.json

@@ -75,7 +75,32 @@
         "capabilities",
         "signatureMode",
         "workspaces"
-      ]
+      ],
+      "if": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key.held"
+            }
+          }
+        },
+        "required": [
+          "capabilities"
+        ]
+      },
+      "then": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key"
+            }
+          }
+        }
+      }
     },
     "seq": {
       "const": 0

package/src/la-protocol-v2/contract/webhook.forward.schema.json

@@ -40,9 +40,17 @@
         "bodyB64": {
           "type": "string",
           "minLength": 0,
-          "maxLength": 12288,
+          "maxLength": 21848,
           "pattern": "^[A-Za-z0-9+/]*={0,2}$",
           "x-content-class": "transit"
+        },
+        "bodyBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1048576
+        },
+        "bodySha256": {
+          "$ref": "defs.schema.json#/$defs/sha256"
         }
       },
       "required": [
@@ -57,7 +65,7 @@
       "minimum": 1,
       "maximum": 9007199254740991
     },
-    "chunk": false,
+    "chunk": true,
     "sig": true,
     "paramsRaw": true
   },
@@ -65,5 +73,66 @@
     "payload",
     "sig",
     "paramsRaw"
-  ]
+  ],
+  "if": {
+    "type": "object",
+    "properties": {
+      "chunk": true
+    },
+    "required": [
+      "chunk"
+    ]
+  },
+  "then": {
+    "type": "object",
+    "properties": {
+      "payload": {
+        "type": "object",
+        "properties": {
+          "bodyBytes": true,
+          "bodySha256": true
+        },
+        "required": [
+          "bodyBytes",
+          "bodySha256"
+        ]
+      }
+    }
+  },
+  "else": {
+    "type": "object",
+    "properties": {
+      "payload": {
+        "type": "object",
+        "properties": {
+          "bodyB64": {
+            "type": "string",
+            "maxLength": 12288
+          }
+        },
+        "not": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "bodyBytes": true
+              },
+              "required": [
+                "bodyBytes"
+              ]
+            },
+            {
+              "type": "object",
+              "properties": {
+                "bodySha256": true
+              },
+              "required": [
+                "bodySha256"
+              ]
+            }
+          ]
+        }
+      }
+    }
+  }
 }

package/src/la-protocol-v2/contract.js

@@ -10,8 +10,10 @@
  *   unknown_type       `type` is not in the allowlist (index.json)
  *   schema_violation   the frame does not satisfy the closed schema of its type
  *   payload_too_large  ... because a string under /payload is above its maxLength (same rule as the gateway)
- *   chunk_inconsistent content.response whose byteLength differs from the decoded size of data
+ *   chunk_inconsistent content.response whose byteLength differs from the decoded size of data; webhook.forward chunk of the wrong size (2.1)
+ *   (rule llmKey-id-sha256 of 2.1 is a schema_violation: the keyId is not the sha256 of the key)
  */
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -21,16 +23,52 @@ const DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "contract");
 const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 const readJson = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
 
-/** Rules JSON Schema cannot state (README of the contract): byteLength == size of the decoded `data`. */
-export function semanticRules(frame) {
+/** The base64 alphabet with padding, canonical form (no whitespace, length multiple of 4). */
+export const isCanonicalBase64 = (s) => typeof s === "string" && BASE64.test(s);
+const decodedLength = (s) => (isCanonicalBase64(s) ? Buffer.from(s, "base64").length : -1);
+
+/**
+ * Contract 2.1, rule `webhook-chunk-size`: a chunked webhook.forward has total == max(1, ceil(bodyBytes / chunkRaw)), a non-last chunk
+ * decodes to exactly chunkRaw bytes and the last one to bodyBytes - chunkRaw * (total - 1). Stateless (one frame).
+ * @returns {boolean} true when the frame BREAKS the rule
+ */
+export function webhookChunkSizeViolation(payload, chunk, chunkRaw = 16384) {
+    if (!payload || !chunk || typeof payload.bodyB64 !== "string" || !Number.isSafeInteger(payload.bodyBytes)) return false;
+    const { index, total } = chunk;
+    const expectedTotal = Math.max(1, Math.ceil(payload.bodyBytes / chunkRaw));
+    const expectedSize = index < total - 1 ? chunkRaw : payload.bodyBytes - chunkRaw * (total - 1);
+    return total !== expectedTotal || index >= total || decodedLength(payload.bodyB64) !== expectedSize;
+}
+
+/** Contract 2.1, rule `llmKey-id-sha256`: llmKey (op set) keyId == lower-case hex sha256 of the UTF-8 bytes of key. @returns {boolean} true when it BREAKS the rule */
+export function llmKeyIdMismatch(llmKey) {
+    if (!llmKey || llmKey.op !== "set" || typeof llmKey.key !== "string") return false;
+    return crypto.createHash("sha256").update(Buffer.from(llmKey.key, "utf8")).digest("hex") !== llmKey.keyId;
+}
+
+/** Rule -> wire code (the `code` the vectors expect). */
+export const RULE_CODES = Object.freeze({ "byteLength-decoded": "chunk_inconsistent", "webhook-chunk-size": "chunk_inconsistent", "llmKey-id-sha256": "schema_violation" });
+
+/**
+ * Rules JSON Schema cannot state (README of the contract): byteLength == size of the decoded `data` (content.response), and since 2.1
+ * `webhook-chunk-size` and `llmKey-id-sha256`. `skip` names rules the caller applies itself later (the session defers the two 2.1
+ * rules to the handlers: they are answered with a non-fatal `rejected` ack, in the order of the reference model: state first).
+ */
+export function semanticRules(frame, { skip = [] } = {}) {
     const rules = [];
-    if (frame && frame.type === "content.response" && frame.payload && typeof frame.payload.data === "string") {
+    const on = (name) => !skip.includes(name);
+    if (frame && frame.type === "content.response" && frame.payload && typeof frame.payload.data === "string" && on("byteLength-decoded")) {
         const d = frame.payload.data;
         if (!BASE64.test(d) || Buffer.from(d, "base64").length !== frame.payload.byteLength) rules.push("byteLength-decoded");
     }
+    if (frame && frame.type === "webhook.forward" && frame.chunk && on("webhook-chunk-size")
+        && webhookChunkSizeViolation(frame.payload, frame.chunk, loadLimits().webhookChunkRawBytes)) rules.push("webhook-chunk-size");
+    if (frame && frame.type === "config.update" && frame.payload && on("llmKey-id-sha256") && llmKeyIdMismatch(frame.payload.llmKey)) rules.push("llmKey-id-sha256");
     return rules;
 }
 
+const loadLimits = () => loadContract().limits;
+
 let singleton = null;
 
 /** Loads and compiles the contract once per process (about 20 ms). */
@@ -73,7 +111,7 @@ export function loadContract() {
             if (!v) throw new Error(`contract: no schema ${schemaFile}`);
             return v(value) === true;
         },
-        validateFrame(frame) {
+        validateFrame(frame, { skipRules = [] } = {}) {
             if (frame === null || typeof frame !== "object" || typeof frame.type !== "string") {
                 // no `type` at all (a v1 command frame, say): the envelope says what is missing
                 const envelope = ajv.getSchema(index.baseId + "envelope.schema.json");
@@ -90,8 +128,8 @@ export function loadContract() {
                 const tooLong = errs.some((e) => e.keyword === "maxLength" && String(e.instancePath).startsWith("/payload"));
                 return { ok: false, code: tooLong ? "payload_too_large" : "schema_violation", keywords, rules: [] };
             }
-            const rules = semanticRules(frame);
-            if (rules.length) return { ok: false, code: "chunk_inconsistent", keywords: [], rules };
+            const rules = semanticRules(frame, { skip: skipRules });
+            if (rules.length) return { ok: false, code: RULE_CODES[rules[0]] || "chunk_inconsistent", keywords: [], rules };
             return { ok: true };
         },
     });