agent-hitch 0.2.16 → 0.2.17

package/docs/schemas/ordered-eval-control.schema.json

@@ -22,9 +22,15 @@
             "rerun_id": { "type": "string", "pattern": "^rerun_[a-f0-9]{32}$" },
             "rerun_type": { "$ref": "eval-rerun-submission.schema.json#/$defs/rerunType" },
             "selector": { "$ref": "eval-rerun-submission.schema.json#/$defs/selector" },
+            "endpoint_attempt": { "$ref": "endpoint-evaluation-attempt.schema.json" },
             "verifier_runtime_id": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
           },
-          "allOf": [{ "if": { "required": ["verifier_runtime_id"] }, "then": { "properties": { "rerun_type": { "const": "verifier-only" } } } }]
+          "allOf": [
+            { "if": { "required": ["verifier_runtime_id"] }, "then": { "properties": { "rerun_type": { "const": "verifier-only" } } } },
+            { "if": { "required": ["endpoint_attempt"] }, "then": { "properties": { "rerun_type": { "const": "candidate-restart" },
+              "selector": { "type": "object", "additionalProperties": false, "required": ["mode"], "properties": { "mode": { "const": "invalid" } } }
+            } } }
+          ]
         }
       }
     }

package/docs/schemas/ready-endpoint-binding.schema.json

@@ -0,0 +1,201 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/ready-endpoint-binding.schema.json",
+  "title": "Private ready endpoint binding input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "kind",
+    "endpoint_ref",
+    "endpoint_revision",
+    "api",
+    "wire_model",
+    "capabilities",
+    "generation",
+    "connection"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1"
+    },
+    "kind": {
+      "const": "external-endpoint"
+    },
+    "endpoint_ref": {
+      "type": "string",
+      "pattern": "^endpoint/[a-z0-9][a-z0-9._-]{0,63}(@sha256:[a-f0-9]{64})?$"
+    },
+    "endpoint_revision": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "api": {
+      "enum": [
+        "responses",
+        "chat-completions"
+      ]
+    },
+    "wire_model": {
+      "type": "string",
+      "minLength": 1
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "streaming",
+        "tool_calls",
+        "parallel_tool_calls",
+        "input_modalities"
+      ],
+      "properties": {
+        "streaming": {
+          "type": "boolean"
+        },
+        "tool_calls": {
+          "type": "boolean"
+        },
+        "parallel_tool_calls": {
+          "const": false
+        },
+        "input_modalities": {
+          "const": [
+            "text"
+          ]
+        }
+      }
+    },
+    "generation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_output_tokens": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "temperature": {
+          "type": "number"
+        },
+        "top_p": {
+          "type": "number"
+        },
+        "top_k": {
+          "type": "number"
+        },
+        "min_p": {
+          "type": "number"
+        },
+        "repetition_penalty": {
+          "type": "number"
+        },
+        "seed": {
+          "type": "number"
+        }
+      }
+    },
+    "deployment_receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema_version",
+        "model_digest",
+        "wire_model",
+        "deployment_ref",
+        "source",
+        "service_config"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": "1"
+        },
+        "model_digest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "wire_model": {
+          "type": "string",
+          "minLength": 1
+        },
+        "deployment_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "service_config": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "engine"
+          ],
+          "properties": {
+            "engine": {
+              "type": "string",
+              "minLength": 1
+            },
+            "engine_version": {},
+            "engine_digest": {},
+            "quantization": {},
+            "tool_parser": {},
+            "reasoning_parser": {},
+            "tokenizer_digest": {},
+            "chat_template_digest": {},
+            "cache_policy": {},
+            "isolation": {},
+            "parsing": {}
+          }
+        }
+      }
+    },
+    "connection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "base_url",
+        "auth"
+      ],
+      "properties": {
+        "base_url": {
+          "type": "string",
+          "pattern": "^https?://"
+        },
+        "auth": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "kind"
+              ],
+              "properties": {
+                "kind": {
+                  "const": "none"
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "kind",
+                "name"
+              ],
+              "properties": {
+                "kind": {
+                  "const": "env"
+                },
+                "name": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                }
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}

package/docs/schemas/run-manifest.schema.json

@@ -161,6 +161,9 @@
         "inference_id": {
           "type": "string",
           "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "endpoint_binding": {
+          "$ref": "external-endpoint-binding.schema.json"
         }
       }
     },
@@ -238,6 +241,9 @@
     "completed_at": {
       "type": "string",
       "format": "date-time"
+    },
+    "endpoint_binding": {
+      "$ref": "external-endpoint-binding.schema.json"
     }
   },
   "$defs": {

package/docs/schemas/run-request.schema.json

@@ -4,19 +4,60 @@
   "title": "Hitch run request",
   "type": "object",
   "additionalProperties": false,
-  "required": ["prompt"],
-  "allOf": [{
-    "if": { "properties": { "context": { "properties": { "kind": { "const": "benchmark_phase" } }, "required": ["kind"] } }, "required": ["context"] },
-    "then": { "required": ["parent"], "properties": { "defer_benchmark_observation": { "const": false } } }
-  }],
+  "required": [
+    "prompt"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "context": {
+            "properties": {
+              "kind": {
+                "const": "benchmark_phase"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          }
+        },
+        "required": [
+          "context"
+        ]
+      },
+      "then": {
+        "required": [
+          "parent"
+        ],
+        "properties": {
+          "defer_benchmark_observation": {
+            "const": false
+          }
+        }
+      }
+    }
+  ],
   "oneOf": [
     {
-      "required": ["harness_ref"],
-      "not": { "required": ["agent"] }
+      "required": [
+        "harness_ref"
+      ],
+      "not": {
+        "required": [
+          "agent"
+        ]
+      }
     },
     {
-      "required": ["agent"],
-      "not": { "required": ["harness_ref"] }
+      "required": [
+        "agent"
+      ],
+      "not": {
+        "required": [
+          "harness_ref"
+        ]
+      }
     }
   ],
   "properties": {
@@ -39,7 +80,11 @@
       "minLength": 1
     },
     "workspace_mode": {
-      "enum": ["shared", "worktree", "copy"],
+      "enum": [
+        "shared",
+        "worktree",
+        "copy"
+      ],
       "default": "shared"
     },
     "prompt": {
@@ -56,21 +101,78 @@
         "type": "string"
       }
     },
-    "context": { "$ref": "run-context.schema.json" },
+    "context": {
+      "$ref": "run-context.schema.json"
+    },
     "parent": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind", "eval_id", "trial_id", "attempt"],
+      "required": [
+        "kind",
+        "eval_id",
+        "trial_id",
+        "attempt"
+      ],
       "properties": {
-        "kind": { "const": "eval" },
-        "eval_id": { "type": "string", "pattern": "^eval_[a-f0-9]{32}$" },
-        "trial_id": { "type": "string", "minLength": 1 },
-        "attempt": { "type": "integer", "minimum": 1 }
+        "kind": {
+          "const": "eval"
+        },
+        "eval_id": {
+          "type": "string",
+          "pattern": "^eval_[a-f0-9]{32}$"
+        },
+        "trial_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1
+        }
       }
     },
-    "model_identity": { "type": "object" },
-    "protocol_identity": { "type": "object" },
-    "defer_benchmark_observation": { "type": "boolean" },
-    "local_inference": { "$ref": "local-inference-selection.schema.json" }
+    "model_identity": {
+      "type": "object"
+    },
+    "protocol_identity": {
+      "type": "object"
+    },
+    "defer_benchmark_observation": {
+      "type": "boolean"
+    },
+    "endpoint_binding": {
+      "$ref": "external-endpoint-binding.schema.json"
+    },
+    "model_binding": {
+      "$ref": "ready-endpoint-binding.schema.json"
+    },
+    "generation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_output_tokens": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "temperature": {
+          "type": "number"
+        },
+        "top_p": {
+          "type": "number"
+        },
+        "top_k": {
+          "type": "number"
+        },
+        "min_p": {
+          "type": "number"
+        },
+        "repetition_penalty": {
+          "type": "number"
+        },
+        "seed": {
+          "type": "number"
+        }
+      }
+    }
   }
 }

package/examples/external-inference/.env.example

@@ -0,0 +1,16 @@
+# Copy to .env, then replace host paths and GPU UUIDs. Never put a key here.
+SGLANG_IMAGE=lmsysorg/sglang:v0.5.21
+# Official gateway-only release, independently pinned from the workers.
+GATEWAY_IMAGE=lightseekorg/smg:1.12.0@sha256:d08b509491f222c2c9786323a3df90136127364c25b9b9b48e91b4b3e9e695d6
+HF_SNAPSHOT_DIR=/srv/models/Qwen2.5-7B-Instruct/a09a35458c702b33eeacc393d103063234e8bc28
+WIRE_MODEL=qwen25-7b-a09a35458c70
+INFERENCE_API_KEY_FILE=/srv/secrets/hitch-inference-api-key
+INFERENCE_GPU_0=GPU-REPLACE-WITH-FIRST-INFERENCE-UUID
+INFERENCE_GPU_1=GPU-REPLACE-WITH-SECOND-INFERENCE-UUID
+INFERENCE_PORT=30000
+CONTEXT_LENGTH=16384
+MEM_FRACTION_STATIC=0.82
+ENGINE_MAX_RUNNING=4
+ENGINE_MAX_QUEUED=8
+GATEWAY_MAX_CONCURRENT=8
+GATEWAY_QUEUE_SIZE=16

package/examples/external-inference/README.md

@@ -0,0 +1,203 @@
+# External SGLang endpoints
+
+These examples deploy an upstream model API independently of Hitch runs and Gear evaluations. Docker Compose owns service restart and device access; SGLang owns generation; upstream SMG owns replica routing. `accept.mjs` is a one-shot HTTP acceptance tool, not a service or model manager.
+
+The configured workers use **SGLang v0.5.21**, release commit `e00930c5489053f26d86b179cee0d087f846acbb`, from `lmsysorg/sglang:v0.5.21`. The two-replica topology uses the separately released **Shepherd Model Gateway (SMG) 1.12.0**, source commit `dcc5cb0b8f2a64694938c10f02c6caaa0c40d5ef`, from the official gateway-only image `lightseekorg/smg:1.12.0`. `GATEWAY_IMAGE` pins its multi-architecture digest independently of `SGLANG_IMAGE`. SMG continues the Gateway codebase in its own repository; its upstream Python package rename from `sglang_router` to `smg` is recorded in [merged PR #69](https://github.com/smg-project/smg/pull/69).
+
+The example model is **Qwen/Qwen2.5-7B-Instruct**, HF revision `a09a35458c702b33eeacc393d103063234e8bc28`, with the `qwen25` tool parser. Pin the pulled worker image digest in `.env` before recording a reproducible deployment.
+
+A bounded GPU smoke on 2026-10-15 passed the checks below. It ran SMG from an official **1.12.0 wheel in a separate virtual environment**, connected to SGLang 0.5.21 workers. The SMG container image was **not started**; wheel results do not validate the Compose/container path. See the [hardware validation record](../../docs/validation/external-inference-gpu-2026-10-15.md) for exact observed configuration and evidence limits.
+
+| Validation | Current status |
+| --- | --- |
+| Compose parsing: single TP=1, single TP=2, two TP=1 replicas | Checked locally; no containers started |
+| Probe syntax and controlled standard HTTP protocol exercise | Checked locally; 15 usage fixture cases passed |
+| Standalone TP=1 direct endpoint | A later Qwen3.5-2B / SGLang 0.5.15.post1 training diagnostic passed strict Hitch verification and real Harbor baseline/candidate evaluations, both valid with reward 0; this is a different model/runtime from the 7B Compose example |
+| Real SGLang TP=2 | Responses and Chat Completions each passed all 9 HTTP checks |
+| SMG 1.12.0 wheel + two TP=1 SGLang workers | Both APIs passed all 9 checks, including forced named JSON/SSE tools, worker distribution and cancellation isolation |
+| Actual Codex 0.145 Harness | TP=2 SHA-256 task and SMG arithmetic task passed with actual terminal tool roundtrips |
+| Legacy bundled `sglang-router` 0.3.2 + two TP=1 workers | Chat Completions passed; Responses rejected the flat named function `tool_choice` with HTTP 400 before reaching a worker |
+| Official SMG 1.12.0 image and Compose container deployment | **NOT RUN; image metadata/source and Compose parsing checked only** |
+| Harbor container execution path | One real local Harbor/Docker canary with remote GPU generation completed training feedback and baseline/candidate evaluation; a complete benchmark and remote Harbor workers remain **NOT RUN** |
+| Static training/inference split, training rollout and HF export regression | A later 2×3090 diagnostic completed one real Slime update/native checkpoint/HF export on GPU 0 and ordinary endpoint evaluation on GPU 1; the shared service survived training cleanup and evidence pairing passed with meanDelta 0. Explicitly validated:false / pending-gpu, zero loss/gradient; complete local artifact closure (108 objects, 35,467,670,234 bytes), offline finite verification and exact-instance rental destruction passed |
+
+The later [training and endpoint diagnostic](../../docs/validation/training-gpu-loop-2026-10-15.md) used the pinned Slime image and Qwen3.5-2B with SGLang 0.5.15.post1, not these Qwen2.5-7B / SGLang 0.5.21 Compose commands. Its one-task results establish a bounded pipeline exercise, not learning, formal runtime certification or container acceptance. Historical custom inference-pool records cannot substitute for these checks. A successful HTTP probe does not establish GPU topology, trusted weight identity, or actual Harness behavior.
+
+## Host and device requirements
+
+Use a Linux NVIDIA GPU host with Docker Engine, NVIDIA Container Toolkit, a driver compatible with the SGLang CUDA 13 worker image, and Docker Compose **2.24.4 or later** (`!override` is used by the TP=2 override). The HTTP probe needs Node.js **22 or later**, with no npm packages or Python runtime on the Hitch client.
+
+For this unquantized 7B BF16 example, plan for an Ampere-or-newer NVIDIA GPU with at least 24 GiB for each TP=1 replica. This is a conservative starting target, not measured capacity: model, kernels, context, batching and KV-cache allocation must fit the chosen hardware. TP=2 needs two suitable GPUs on one host with working NCCL communication. The recorded two-RTX-3090 smoke completed through NCCL after custom allreduce fell back because peer access was unavailable; it establishes successful execution, not a performance target. Validate the interconnect and actual rank execution; two device IDs in a file are not proof of TP execution. The default context is 16384 with memory fraction 0.82, per-worker running/queued request limits are 4/8, and the Gateway running/queued limits are 8/16 with a 30-second queue deadline. The worker commands include the upstream `--disable-cuda-graph` flag used in this smoke (deprecated but accepted by SGLang 0.5.21). These settings accommodate the recorded Codex input of about 10.6k tokens per request; they do not establish capacity for every model or workload. Adjust them to the measured deployment capacity and record the change.
+
+Reserve distinct physical GPU UUIDs for inference and training in the resource owner's allocation system. For example, on a three-GPU host reserve GPU A/B for the two-replica endpoint and GPU C for training. Constrain the trainer to C and the Compose workers to A/B. One inference GPU plus one training GPU needs at least two GPUs; TP=2 or two replicas plus a one-GPU trainer needs at least three. These Compose device selections restrict visibility; they do not exclude other jobs or create a global allocation ledger. Dynamic sharing is outside this example.
+
+## Prepare the immutable snapshot and secret
+
+Run these steps as the deployment owner in this directory, on the GPU host. Edit all paths and UUIDs for that host:
+
+```sh
+cp .env.example .env
+# Edit .env: absolute snapshot/secret paths, reserved GPU UUIDs, worker image digest.
+set -a
+. ./.env
+set +a
+
+install -d -m 700 ./secrets
+(umask 077; openssl rand -hex 32 > ./secrets/api-key)
+# Set INFERENCE_API_KEY_FILE in .env to this file's absolute path.
+```
+
+The same secret protects Gateway and workers in the two-replica example. Compose mounts the file as `/run/secrets/api_key`; a small shell entrypoint reads it and execs the upstream launcher. The official SMG image defaults to UID 65532; this example explicitly runs the Gateway as `0:0` so it can read the existing host-owned `0600` secret without relaxing that file's permissions. Keep the host secret directory private. The released SMG image removes `curl`, so its readiness healthcheck uses the included Python standard library. The secret is absent from endpoint JSON and `.env`. Upstream `--api-key` arguments are visible to privileged process inspectors on the deployment host; use a trusted host and keep its diagnostics private. Never put a real key in a public task, receipt, or report.
+
+Use the existing CAS/HF export flow for a candidate. It must produce a complete, immutable snapshot containing weights, config, tokenizer and template. For the public demonstration model, the fixed image can prepare a snapshot without GPU access:
+
+```sh
+# Reload .env after editing its paths.
+set -a
+. ./.env
+set +a
+mkdir -p "$HF_SNAPSHOT_DIR"
+docker pull "$SGLANG_IMAGE"
+docker run --rm --entrypoint hf \
+  --mount "type=bind,src=$HF_SNAPSHOT_DIR,dst=/model" \
+  "$SGLANG_IMAGE" download Qwen/Qwen2.5-7B-Instruct \
+  --revision a09a35458c702b33eeacc393d103063234e8bc28 --local-dir /model
+
+docker image inspect --format '{{index .RepoDigests 0}}' "$SGLANG_IMAGE"
+# Replace SGLANG_IMAGE in .env with that returned lmsysorg/sglang@sha256:... value.
+```
+
+Download only into a new snapshot directory. Do not point at a mutable `main` checkout or a cache snapshot whose symlinks target files outside the mount. The deployment owner must verify the complete files against the existing model manifest/CAS digest, prevent host-side mutation, and preserve the digest and receipt source. Every worker mounts exactly that directory read-only and runs with Hub/Transformers offline mode. The container mount alone does not prove host immutability or which weights were loaded.
+
+Use a distinct `WIRE_MODEL` for each candidate version, and use the same value in endpoint JSON and the trusted deployment receipt. Do not replace the mounted weights behind an already-frozen model name. All replicas behind one Gateway in this example must serve the same snapshot and parser/template configuration.
+
+## Launch one topology
+
+Reload `.env` after every edit, including the resolved image digest; exported shell values take precedence over `--env-file`:
+
+```sh
+set -a
+. ./.env
+set +a
+```
+
+For one TP=1 replica:
+
+```sh
+docker compose --env-file .env -f compose.single.yaml config --quiet
+docker compose --env-file .env -f compose.single.yaml up -d --wait --wait-timeout 1800
+```
+
+For one TP=2 replica, select two distinct reserved UUIDs in `.env`:
+
+```sh
+docker compose --env-file .env -f compose.single.yaml -f compose.tp2.yaml config --quiet
+docker compose --env-file .env -f compose.single.yaml -f compose.tp2.yaml up -d --wait --wait-timeout 1800
+```
+
+For two TP=1 replicas behind SMG 1.12.0:
+
+```sh
+docker pull "$GATEWAY_IMAGE"
+docker compose --env-file .env -f compose.gateway.yaml config --quiet
+docker compose --env-file .env -f compose.gateway.yaml up -d --wait --wait-timeout 1800
+```
+
+The Gateway image is pinned to `sha256:d08b509491f222c2c9786323a3df90136127364c25b9b9b48e91b4b3e9e695d6` (multi-architecture manifest; Linux amd64 child `sha256:a4041ccb14eed4316aabcba6d8b1ef511c6de49e56c27d90749552496f15f97f`). Its shell command runs `smg launch`; `SGLANG_IMAGE` is used only by the workers. No inference engine or GPU is needed in the Gateway container. `--disable-tokenizer-autoload` keeps this pure HTTP router from trying to load worker tokenizer paths; workers alone load the tokenizer from their immutable snapshot mount.
+
+Choose one topology at a time. These files share a Compose project and public port; changing topology is a deployment-owner operation after existing consumers finish. Gateway explicitly uses `--disable-retries`; the probe uses builtin `fetch` without retries. Disable transparent retries/fallback in the selected Harness or SDK as well for strict evaluation. Docker restarting a service is a deployment policy, not request replay.
+
+The Gateway explicitly has no visible NVIDIA/CUDA devices. Only loopback ports are published: API 30000, two-replica worker diagnostics 30001/30002, Gateway Prometheus 10001. Remote workers and Harbor containers need a genuinely reachable URL; container `127.0.0.1` is not the GPU host. Use the environment's existing private networking/TLS ingress or an operator-managed tunnel, then edit `base_url`. Do not publish these example HTTP ports to an untrusted network.
+
+## Connect Hitch and exercise the actual Harness
+
+`endpoint.responses.example.json` and `endpoint.chat-completions.example.json` explicitly select one API. Their capability declarations are proposed settings until the selected protocol and Harness have passed real requests. This Hitch release accepts serial function tool calls only: both examples declare `parallel_tool_calls: false`, and a declaration of `true` is rejected. Choose the API required by that Harness; there is no protocol autodetection or conversion.
+
+```sh
+cp endpoint.responses.example.json endpoint.json
+# Update base_url and wire_model to the deployed values.
+export INFERENCE_API_KEY="$(cat ./secrets/api-key)"
+hitch models connect --name coder --file endpoint.json
+hitch models inspect endpoint/coder --verify --json
+hitch run --harness "$HARNESS" --model endpoint/coder \
+  --prompt "Use the available shell tool to compute the SHA-256 of README.md and report the result." \
+  --output json
+```
+
+Set `HARNESS` to a concrete supported Harness ref with the required tool and workspace available. Save its version, provider/adapter configuration, full tool roundtrip, result and usage. Its actual upstream HTTP budget must be a normal business value (for example 1024 or 4096) and must pass unchanged. No `+2` compensation or tiny-budget test is part of these examples. Run the actual container/remote execution path if that is what the evaluation uses, with its credential available in the process that sends upstream requests.
+
+Hitch freezes the registered endpoint revision for a task. Gear strict candidate evaluation additionally requires its trusted ready-binding/receipt contract and the matching existing model artifact digest. `deployment.example.json` is public operator metadata for this probe, **not** a signed or trusted receipt and **not** a Gear ready-binding file. Copy the actual deployment pipeline receipt into the Gear binding workflow; a model-name echo or a self-filled digest is insufficient.
+
+## Capture configuration and run the HTTP acceptance tool
+
+Prepare a private evidence directory and copy the metadata template:
+
+```sh
+mkdir -p artifacts
+cp deployment.example.json deployment.json
+docker compose --env-file .env -f compose.single.yaml config > artifacts/compose.resolved.yaml
+docker compose --env-file .env -f compose.single.yaml exec -T engine \
+  python3 -c 'import importlib.metadata as m,json; print(json.dumps({k:m.version(k) for k in ("sglang",)},sort_keys=True))' \
+  > artifacts/package-versions.json
+nvidia-smi --query-gpu=uuid,name,driver_version,memory.total --format=csv > artifacts/gpus.csv
+```
+
+For TP=2 use both Compose files in the capture commands. For Gateway use `compose.gateway.yaml` and capture both worker packages and the separate SMG package:
+
+```sh
+docker compose --env-file .env -f compose.gateway.yaml config > artifacts/compose.resolved.yaml
+for worker in worker-1 worker-2; do
+  docker compose --env-file .env -f compose.gateway.yaml exec -T "$worker" \
+    python3 -c 'import importlib.metadata as m,json; print(json.dumps({"sglang":m.version("sglang")}))' \
+    > "artifacts/$worker-package-versions.json"
+done
+docker compose --env-file .env -f compose.gateway.yaml exec -T gateway \
+  python3 -c 'import importlib.metadata as m,json; print(json.dumps({"smg":m.version("smg")}))' \
+  > artifacts/gateway-package-versions.json
+```
+
+The metadata template defaults to a single replica with `gateway.enabled: false`. For the two-replica topology set it to `true`, update the Compose files/replica count and `configuration.gateway` settings, and fill both engine and Gateway observed versions and resolved image digests. Record exact topology, UUIDs, allocation/receipt references, model/tokenizer/template digest, parser, quantization, cache/isolation policy and any changed capacity settings. Keep the configured and observed versions distinct. Preserve the original trusted receipt alongside the public metadata. Do not copy a process listing containing API-key arguments into public evidence.
+
+Single-replica acceptance (run separately for TP=1 and TP=2):
+
+```sh
+node accept.mjs --endpoint endpoint.json --deployment deployment.json \
+  --budget 1024 --concurrent 4 --worker-metrics http://127.0.0.1:30000/metrics \
+  --expect-workers 1 --out artifacts/single-responses.json
+```
+
+Two-replica acceptance through the Gateway:
+
+```sh
+node accept.mjs --endpoint endpoint.json --deployment deployment.json \
+  --budget 1024 --concurrent 4 \
+  --worker-metrics http://127.0.0.1:30001/metrics \
+  --worker-metrics http://127.0.0.1:30002/metrics \
+  --gateway-metrics http://127.0.0.1:10001/metrics --expect-workers 2 \
+  --out artifacts/gateway-responses.json
+```
+
+Use `endpoint.chat-completions.example.json` and a different output filename when validating that API. A passing result for one API does not declare the other supported. The report records each exact request, HTTP status, generated text/SSE events, raw upstream usage and verified counts with their source field names, tool input/output, local probe version/hash and supplied deployment configuration. Known API keys are redacted; keep reports private because they contain prompts and model output. A failing probe exits nonzero and still saves the observations it obtained.
+
+The checks cover:
+
+- Authentication denial on the generation endpoint, ordinary generation, full-history multi-turn input and unchanged output budget.
+- Text SSE deltas, terminal response/finish reason and real input/output usage; missing usage is an error, not a fabricated zero.
+- Both JSON and streaming tool calls with an explicit named function `tool_choice`: the model emits the requested function call, the tool runs locally, its actual result returns with the call ID, and the model answers using that result.
+- Simultaneous independent requests, followed by two active text streams. After both emit text, only one is aborted; the other must finish, and a subsequent request must succeed. This establishes observed client cancellation isolation, not physical GPU release.
+- For the Gateway, positive before/after deltas of `sglang:num_requests_total` from **each worker**. Gateway aggregate counters alone do not prove replica distribution. The probe does not modify workers, caches, models or deployment state.
+
+Finish hardware acceptance by saving server logs/metrics and GPU process/rank observations establishing actual TP=2 execution, plus the real Harness artifacts. In the static allocation setup, run the retained training rollout and HF export checks while independent evaluation uses its reserved devices; preserve training evidence and allocation records. Mark only those scenarios actually observed as passed. TP=2 with two replicas would require four inference GPUs and is not a first-version requirement.
+
+A completed, cancelled or timed-out evaluation never runs `docker compose down`, stop, drain, cache flush or GPU release. The shared endpoint remains available to other consumers. The deployment owner may stop it after confirming all relevant consumers have ended.
+
+## Verified upstream references
+
+- [SGLang v0.5.21 release and official NVIDIA image](https://github.com/sgl-project/sglang/releases/tag/v0.5.21).
+- [SMG 1.12.0 release](https://github.com/smg-project/smg/releases/tag/v1.12.0), [official Docker image/tag metadata](https://hub.docker.com/v2/repositories/lightseekorg/smg/tags/1.12.0/), [release image build](https://github.com/smg-project/smg/blob/dcc5cb0b8f2a64694938c10f02c6caaa0c40d5ef/.github/workflows/release-docker.yml).
+- [Pinned SMG Dockerfile: Python entrypoint, default non-root user and curl removal](https://github.com/smg-project/smg/blob/dcc5cb0b8f2a64694938c10f02c6caaa0c40d5ef/docker/Dockerfile), [package/CLI entrypoint](https://github.com/smg-project/smg/blob/dcc5cb0b8f2a64694938c10f02c6caaa0c40d5ef/bindings/python/pyproject.toml), [gateway-only startup guide](https://lightseek.org/smg/getting-started#option-b-launch-gateway-only-with-smg-launch).
+- [Pinned SMG launch flags, retries, queue and Prometheus settings](https://github.com/smg-project/smg/blob/dcc5cb0b8f2a64694938c10f02c6caaa0c40d5ef/bindings/python/src/smg/router_args.py), [Responses named tool choice type](https://github.com/smg-project/smg/blob/dcc5cb0b8f2a64694938c10f02c6caaa0c40d5ef/crates/protocols/src/responses.rs).
+- [Legacy bundled Router 0.3.2 and its pinned protocol dependency](https://github.com/sgl-project/sglang/blob/e00930c5489053f26d86b179cee0d087f846acbb/sgl-model-gateway/Cargo.toml).
+- [Pinned engine scheduling/capacity arguments](https://github.com/sgl-project/sglang/blob/e00930c5489053f26d86b179cee0d087f846acbb/python/sglang/srt/arg_groups/fields/schedule.py), [serving/authentication arguments](https://github.com/sgl-project/sglang/blob/e00930c5489053f26d86b179cee0d087f846acbb/python/sglang/srt/arg_groups/fields/serving.py), [TP arguments](https://github.com/sgl-project/sglang/blob/e00930c5489053f26d86b179cee0d087f846acbb/python/sglang/srt/arg_groups/fields/parallel.py).
+- [Pinned Responses implementation](https://github.com/sgl-project/sglang/blob/e00930c5489053f26d86b179cee0d087f846acbb/python/sglang/srt/entrypoints/openai/serving_responses.py), [worker request metric](https://github.com/sgl-project/sglang/blob/e00930c5489053f26d86b179cee0d087f846acbb/python/sglang/srt/observability/metrics_collector.py).
+- [Qwen example snapshot](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct/tree/a09a35458c702b33eeacc393d103063234e8bc28), [Docker Compose GPU device access](https://docs.docker.com/compose/how-tos/gpu-support/), [Compose merge/override behavior](https://docs.docker.com/reference/compose-file/merge/), [NVIDIA CUDA compatibility](https://docs.nvidia.com/deploy/cuda-compatibility/).