@cuylabs/agent-physical-capx 5.0.2 → 5.1.0

package/examples/01-capx-runtime-solver.ts

@@ -11,7 +11,6 @@
  * task context, write policy code, execute one step, observe again, and report.
  *
  * Run:
- *   pnpm --filter @cuylabs/agent-physical-capx build
  *   npx tsx examples/01-capx-runtime-solver.ts
  */
 
@@ -57,9 +56,10 @@ const runId = Date.now();
 const sessionId =
   optionalString(process.env.CAPX_AGENT_SESSION_ID) ??
   `capx-runtime-solver-${runId}`;
-const outputDir =
-  optionalString(process.env.CAPX_OUTPUT_DIR) ??
-  `outputs/capx-agent-runtime/${sessionId}`;
+const sessionOutputDir = optionalString(process.env.CAPX_SESSION_OUTPUT_DIR);
+const sessionSkillLibraryPath = optionalString(
+  process.env.CAPX_SESSION_SKILL_LIBRARY_PATH,
+);
 const recordVideo =
   optionalString(process.env.CAPX_POLICY_EXECUTION_RECORD_VIDEO) ??
   "runtime-default";
@@ -92,10 +92,11 @@ console.log(
     `approval=${allowDestructive ? "policy-code-enabled" : "observe-only"}`,
     `recordVideo=${recordVideo}`,
     `agentSessionId=${sessionId}`,
-    `outputDir=${outputDir}`,
+    `sessionOutputDir=${sessionOutputDir ?? "server-owned"}`,
+    `sessionSkillLibraryPath=${sessionSkillLibraryPath ?? "server-owned"}`,
+    `pathOverrides=${sessionOutputDir || sessionSkillLibraryPath ? "requested" : "none"}`,
     `runtimeServerUrl=${runtimeServerUrl}`,
-  ]
-    .join(" "),
+  ].join(" "),
 );
 
 const { agent, session } = await createCapxAgent({
@@ -125,13 +126,15 @@ const { agent, session } = await createCapxAgent({
     policyExecutionTimeoutMs: optionalNumber(
       process.env.CAPX_POLICY_EXECUTION_TIMEOUT_MS,
     ),
-    policyExecutionTrial: optionalNumber(process.env.CAPX_POLICY_EXECUTION_TRIAL),
+    policyExecutionTrial: optionalNumber(
+      process.env.CAPX_POLICY_EXECUTION_TRIAL,
+    ),
     policyExecutionRecordVideo: optionalBoolean(
       process.env.CAPX_POLICY_EXECUTION_RECORD_VIDEO,
     ),
 
-    outputDir,
-    skillLibraryPath: optionalString(process.env.CAPX_SKILL_LIBRARY_PATH),
+    outputDir: sessionOutputDir,
+    skillLibraryPath: sessionSkillLibraryPath,
   },
   approval: {
     defaultAction: "ask",

package/examples/02-capx-runtime-autosolve.ts

@@ -7,7 +7,6 @@
  * reports task completion or when CAPX_MAX_SOLVER_TURNS is reached.
  *
  * Run:
- *   pnpm --filter @cuylabs/agent-physical-capx build
  *   npx tsx examples/02-capx-runtime-autosolve.ts
  */
 
@@ -76,7 +75,9 @@ function lastStep(observation: PhysicalObservation): LastRuntimeStep | null {
   }
 }
 
-function isUnrecoverableObservationFailure(step: LastRuntimeStep | null): boolean {
+function isUnrecoverableObservationFailure(
+  step: LastRuntimeStep | null,
+): boolean {
   if (!step) {
     return false;
   }
@@ -94,9 +95,9 @@ function isUnrecoverableObservationFailure(step: LastRuntimeStep | null): boolea
   if (diagnostics) {
     return Boolean(
       step.truncated &&
-        (diagnostics.observationPipeline ||
-          diagnostics.depthAssertion ||
-          error.includes("AssertionError")),
+      (diagnostics.observationPipeline ||
+        diagnostics.depthAssertion ||
+        error.includes("AssertionError")),
     );
   }
   const mentionsObservationPath =
@@ -108,8 +109,10 @@ function isUnrecoverableObservationFailure(step: LastRuntimeStep | null): boolea
     (stderr.includes("AssertionError") && stderr.includes("depth"));
   return Boolean(
     sandboxFailed &&
-      step.truncated &&
-      (mentionsObservationPath || mentionsDepthAssertion || error.includes("AssertionError")),
+    step.truncated &&
+    (mentionsObservationPath ||
+      mentionsDepthAssertion ||
+      error.includes("AssertionError")),
   );
 }
 
@@ -148,9 +151,10 @@ const runId = Date.now();
 const sessionId =
   optionalString(process.env.CAPX_AGENT_SESSION_ID) ??
   `capx-runtime-autosolve-${runId}`;
-const outputDir =
-  optionalString(process.env.CAPX_OUTPUT_DIR) ??
-  `outputs/capx-agent-runtime/${sessionId}`;
+const sessionOutputDir = optionalString(process.env.CAPX_SESSION_OUTPUT_DIR);
+const sessionSkillLibraryPath = optionalString(
+  process.env.CAPX_SESSION_SKILL_LIBRARY_PATH,
+);
 const toolExecutionMode = "plan" as const;
 const recordVideo =
   optionalString(process.env.CAPX_POLICY_EXECUTION_RECORD_VIDEO) ??
@@ -178,7 +182,9 @@ console.error(
     `approval=${allowDestructive ? "policy-code-enabled" : "observe-only"}`,
     `recordVideo=${recordVideo}`,
     `agentSessionId=${sessionId}`,
-    `outputDir=${outputDir}`,
+    `sessionOutputDir=${sessionOutputDir ?? "server-owned"}`,
+    `sessionSkillLibraryPath=${sessionSkillLibraryPath ?? "server-owned"}`,
+    `pathOverrides=${sessionOutputDir || sessionSkillLibraryPath ? "requested" : "none"}`,
     `trial=${initialPolicyExecutionTrial}`,
     `recoverOnRuntimeError=${recoverOnRuntimeError ? "reset" : "off"}`,
     `maxRuntimeResets=${maxRuntimeResets}`,
@@ -212,8 +218,8 @@ const { agent, session } = await createCapxAgent({
     policyExecutionRecordVideo: optionalBoolean(
       process.env.CAPX_POLICY_EXECUTION_RECORD_VIDEO,
     ),
-    outputDir,
-    skillLibraryPath: optionalString(process.env.CAPX_SKILL_LIBRARY_PATH),
+    outputDir: sessionOutputDir,
+    skillLibraryPath: sessionSkillLibraryPath,
   },
   approval: {
     defaultAction: "ask",
@@ -232,15 +238,14 @@ try {
 
   for (let turn = 1; turn <= maxTurns; turn += 1) {
     console.error(`\n--- solver turn ${turn}/${maxTurns} ---`);
-    const prompt =
-      resetBeforeTurn
-        ? [
-            "The previous CaP-X runtime session hit an observation/depth failure, so the example reset the runtime before this turn.",
-            "Treat the current runtime state as fresh. Ignore any broken previous physical state.",
-            "Call capx_status and capx_observe with includeImages=true, then solve from the current task prompt and observations.",
-            "Execute one useful Python Code-as-Policy step if approval allows it, then observe again.",
-          ].join(" ")
-        : turn === 1
+    const prompt = resetBeforeTurn
+      ? [
+          "The previous CaP-X runtime session hit an observation/depth failure, so the example reset the runtime before this turn.",
+          "Treat the current runtime state as fresh. Ignore any broken previous physical state.",
+          "Call capx_status and capx_observe with includeImages=true, then solve from the current task prompt and observations.",
+          "Execute one useful Python Code-as-Policy step if approval allows it, then observe again.",
+        ].join(" ")
+      : turn === 1
         ? [
             "Solve the active CaP-X task.",
             "First call capx_status, then capx_observe with includeImages=true.",
@@ -294,7 +299,9 @@ try {
       break;
     }
     if (step?.taskCompleted || step?.terminated) {
-      console.error(`CaP-X reported completion state: ${completionSummary(step)}`);
+      console.error(
+        `CaP-X reported completion state: ${completionSummary(step)}`,
+      );
       break;
     }
     resetBeforeTurn = false;

package/examples/README.md

@@ -8,28 +8,35 @@ runtime by calling its HTTP API directly.
 
 ## Main Examples
 
-`01-capx-runtime-solver.ts` is the default single-turn bring-your-own-agent
-example. It creates an `agent-core` agent, wires in the CaP-X physical tools,
-and gives the agent one user turn. Inside that turn, `agent-core` may still run
-multiple model/tool steps, but the example prompt asks for one useful
-Code-as-Policy action and a summary:
-
-1. observe the CaP-X task and rendered simulator state,
-2. inspect runtime turn history and the CaP-X skill library when available,
-3. write one Python Code-as-Policy step,
-4. execute it through `capx-agent-runtime`,
-5. observe again and summarize reward, stdout/stderr, and task completion.
+There are two solver examples. Both connect an `agent-core` agent to an
+already-running `capx-agent-runtime` service and expose the CaP-X session
+through the `capx_*` tools.
+
+`01-capx-runtime-solver.ts` is the default single-turn example. It creates one
+agent, starts one runtime session, and gives the model one user turn. Inside
+that turn, `agent-core` may still run multiple model/tool steps, but the prompt
+asks for one useful Code-as-Policy action and a short result summary.
 
-`02-capx-runtime-autosolve.ts` keeps the same agent session open across several
-user turns. After each turn, the script observes the runtime and stops when
-CaP-X reports task completion or when `CAPX_MAX_SOLVER_TURNS` is reached. Use
-this when you want the harness to continue attempting the task instead of
-exiting after one scripted turn.
+That flow is:
 
-The example enables the packaged `capx-code-as-policy` agent-core skill by
-default. That skill teaches the model how to use the CaP-X tools. It is not the
-same as CaP-X's runtime-side Python skill library, which is exposed dynamically
-through observation `codeContext` and programmatic runtime APIs.
+1. observe the CaP-X task, simulator state, and rendered frame,
+2. inspect runtime turn history and available policy-code context,
+3. write one Python Code-as-Policy step,
+4. execute that Python through `capx-agent-runtime`,
+5. observe again and summarize reward, stdout/stderr, artifacts, and task
+   completion.
+
+`02-capx-runtime-autosolve.ts` is the multi-turn example. It keeps the same
+agent and runtime session open across several user turns. After each turn, the
+script observes the runtime result and stops when CaP-X reports task completion
+or when `CAPX_MAX_SOLVER_TURNS` is reached. Use it when the harness should keep
+trying the task instead of exiting after one solver turn.
+
+Both examples enable the packaged `capx-code-as-policy` agent-core skill by
+default. That skill teaches the model how to use the `capx_*` tools and how to
+write policy code for the runtime. It is separate from CaP-X's runtime-side
+Python skill library, which appears dynamically in observation `codeContext`
+and deliberate runtime APIs.
 
 ## Service-First Setup
 
@@ -37,9 +44,12 @@ The normal path is to start the runtime service first, usually on a Linux GPU
 workstation, then run the TypeScript agent from your local machine or another
 client.
 
-Follow the runtime workstation setup first:
+Follow the runtime project docs first:
 
-[capx-agent-runtime workstation setup](../../../repos/capx-agent-runtime/docs/workstation-setup.md)
+1. Prepare the GPU workstation with
+   [Workstation Setup](https://github.com/cuylabs-ai/capx-agent-runtime/blob/main/docs/workstation-setup.md).
+2. Start and validate the runtime server with
+   [Runtime Server](https://github.com/cuylabs-ai/capx-agent-runtime/blob/main/docs/runtime-server.md).
 
 The runtime server is typically started from the CaP-X checkout like this:
 
@@ -79,19 +89,25 @@ the service:
 ssh -L 8210:127.0.0.1:8210 <user>@<gpu-host>
 ```
 
-## Local Workspace Setup
+## Client Setup
 
-These examples are meant to run from a local `agents-ts` checkout. The
-`@cuylabs/agent-physical` and `@cuylabs/agent-physical-capx` packages are
-workspace-linked here, so source changes can be tested before publishing.
+In an application that consumes the released packages, install the TypeScript
+client packages and the example runner dependencies:
 
-From the repo root, install dependencies and build this package plus its local
-workspace dependencies:
+```bash
+npm install @cuylabs/agent-core @cuylabs/agent-physical @cuylabs/agent-physical-capx
+npm install --save-dev @ai-sdk/openai dotenv tsx
+```
+
+The released package already includes its built `dist/` files, so there is no
+workspace build step in the normal install path.
+
+If you are running the examples from a local `agents-ts` monorepo checkout
+while changing package source, install workspace dependencies first:
 
 ```bash
 cd /path/to/agents-ts
 pnpm install
-pnpm --filter @cuylabs/agent-physical-capx... build
 ```
 
 Use the `pnpm` already available on your machine. If `pnpm` is missing and your
@@ -99,11 +115,8 @@ Node install includes Corepack, you can enable it with `corepack enable`; if
 `corepack` is not available, install `pnpm` directly with your normal Node
 package-manager setup.
 
-The trailing `...` is intentional. It includes the dependency chain, so
-`@cuylabs/agent-core`, `@cuylabs/agent-physical`, and
-`@cuylabs/agent-physical-capx` are built together.
-
-Then configure the example environment:
+For the checked-in examples, configure the local example environment from this
+package directory:
 
 ```bash
 cd packages/agent-physical-capx
@@ -129,60 +142,63 @@ gateway or hosted inference endpoint.
 
 ## Run Modes
 
-By default, the examples are observe-only. The agent can inspect the runtime
-state, propose policy code, and summarize what it would do, but it cannot call
-`capx_run_policy_code`:
+The examples default to observe-only mode. In that mode, the agent can inspect
+the task, frame, runtime state, and policy-code context, but it cannot call
+`capx_run_policy_code`.
+
+### Observe Only
 
 ```bash
-pnpm exec tsx examples/01-capx-runtime-solver.ts
+npx tsx examples/01-capx-runtime-solver.ts
 ```
 
-Allow the single-turn solver to execute one Python Code-as-Policy action in
-simulation:
+Use this first to confirm that the runtime URL, model provider, session
+creation, observation, and tool wiring are working.
+
+### Single Policy Step
+
+Allow the single-turn example to execute one Python Code-as-Policy action in
+simulation.
 
 ```bash
 CAPX_ALLOW_DESTRUCTIVE=1 \
-pnpm exec tsx examples/01-capx-runtime-solver.ts
+npx tsx examples/01-capx-runtime-solver.ts
 ```
 
-The startup line should include `approval=policy-code-enabled`. If it still
-shows `approval=observe-only`, the environment variable did not reach the Node
-process. In that case, use a single-line command:
+The startup line should show `approval=policy-code-enabled`. If it still shows
+`approval=observe-only`, the environment variable did not reach the Node
+process. Use a single-line command to verify:
 
 ```bash
-env CAPX_ALLOW_DESTRUCTIVE=1 pnpm exec tsx examples/01-capx-runtime-solver.ts
+env CAPX_ALLOW_DESTRUCTIVE=1 npx tsx examples/01-capx-runtime-solver.ts
 ```
 
-When execution is enabled, the log should also show an approval request for
-`capx_run_policy_code` followed by an approval resolution. If the startup line
-shows `approval=policy-code-enabled` but the tool result still says
-`Approval denied for capx_run_policy_code`, rebuild and rerun the local
-workspace; older example code used a hard default deny policy before the
-example callback could approve the tool.
-
-Allow execution and force video recording for that policy-code turn:
+### Single Policy Step With Video
 
 ```bash
 CAPX_ALLOW_DESTRUCTIVE=1 \
 CAPX_POLICY_EXECUTION_RECORD_VIDEO=1 \
-pnpm exec tsx examples/01-capx-runtime-solver.ts
+npx tsx examples/01-capx-runtime-solver.ts
 ```
 
-Run the multi-turn solver in observe-only mode:
+### Multi-Turn Autosolve
+
+Run the autosolver in observe-only mode.
 
 ```bash
-CAPX_MAX_SOLVER_TURNS=6 pnpm exec tsx examples/02-capx-runtime-autosolve.ts
+CAPX_MAX_SOLVER_TURNS=6 npx tsx examples/02-capx-runtime-autosolve.ts
 ```
 
-Allow the multi-turn solver to execute policy code:
+Allow policy-code execution across the autosolver loop.
 
 ```bash
 CAPX_ALLOW_DESTRUCTIVE=1 \
 CAPX_MAX_SOLVER_TURNS=6 \
-pnpm exec tsx examples/02-capx-runtime-autosolve.ts
+npx tsx examples/02-capx-runtime-autosolve.ts
 ```
 
-Allow multi-turn execution and force video recording for each policy-code turn:
+For the most complete demo, enable execution, video recording, one runtime
+recovery reset, and stop-on-exit so the combined video artifact is flushed.
 
 ```bash
 CAPX_ALLOW_DESTRUCTIVE=1 \
@@ -191,21 +207,14 @@ CAPX_MAX_SOLVER_TURNS=6 \
 CAPX_RECOVER_ON_RUNTIME_ERROR=reset \
 CAPX_MAX_RUNTIME_RESETS=1 \
 CAPX_STOP_ON_EXIT=1 \
-pnpm exec tsx examples/02-capx-runtime-autosolve.ts
+npx tsx examples/02-capx-runtime-autosolve.ts
 ```
 
-For the video mode, the startup line should include
-`approval=policy-code-enabled` and `recordVideo=1`.
-`CAPX_STOP_ON_EXIT=1` stops the runtime session at the end of the example so
-`capx-agent-runtime` can flush the combined session video artifact. Stopped
-sessions still keep their artifacts available through the console and HTTP API;
-the session may remain listed there, but the live simulator environment has
-been stopped. This does not shut down the top-level `capx-agent-runtime serve`
-process.
+## Expected Output
 
 For the default Franka cube-stack config, a healthy run usually finishes after
-one useful policy-code turn. The exact sampled poses and artifact URLs vary by
-trial, but the important terminal lines look like this:
+one useful policy-code turn. Exact sampled poses and artifact paths vary, but
+the important terminal lines look like this:
 
 ```text
 executionOk=true, taskCompleted=true, reward=1
@@ -224,47 +233,26 @@ Saved interaction video to .../video_session_combined.mp4
 POST /sessions/<id>/stop ... 200 OK
 ```
 
-The `video_..._turn_00.mp4` file is the per-policy-turn recording. The
-`video_session_combined.mp4` file is written when the session stops, which is
-why `CAPX_STOP_ON_EXIT=1` is recommended for video examples. In the console,
-the combined session video is shown at the top of the artifact list; per-turn
-videos remain linked as individual artifact files.
-
-By default, each example run writes to a unique remote CaP-X output directory
-under `outputs/capx-agent-runtime/<agent-session-id>`. That keeps artifacts
-from separate runs from being mixed together in the console. Set
-`CAPX_OUTPUT_DIR` only when you intentionally want a specific remote output
-directory.
-
-The autosolver also stops early if CaP-X reports a persistent observation or
-depth-rendering failure. This is different from ordinary Python policy-code
-failure. CaP-X can ask an agent to regenerate code when `env.step(code)`
-returns a normal `info_step` with `stderr`. But if the Robosuite observation
-pipeline raises while collecting camera/depth observations, `env.step(code)`
-does not return a normal result. In that state even `pass` can fail before user
-policy code runs, so continuing to submit more code in the same session is not
-useful.
-
-When `CAPX_RECOVER_ON_RUNTIME_ERROR=reset` is set, the autosolver resets only
-for runtime-level `env.step(...)` failures where CaP-X cannot return a normal
-step result. It does not reset for ordinary policy-code `stderr`; those are
-left to the next agent turn so the model can inspect the error and try a better
-policy. Runtime resets use the next CaP-X trial/seed. The default reset budget
-is one reset; set `CAPX_MAX_RUNTIME_RESETS` to change that. If
-`CAPX_POLICY_EXECUTION_TRIAL` is unset, the first session uses trial `1`, the
-first recovery reset uses trial `2`, and so on. `CAPX_STOP_ON_EXIT` is separate
-from this recovery behavior: recovery reset happens during the solver loop,
-while stop-on-exit runs once the example is done, fails, or exhausts its reset
-budget.
-
-If the reset budget is exhausted, or if you are running without automatic
-recovery, do the cleanup first, then retry with a fresh session.
-
-If you used `CAPX_STOP_ON_EXIT=1`, the example asks the server to stop the
-runtime session before exiting and flushes the combined session video. You can
-then rerun the example directly.
-
-If the session is still running, find the runtime session id and stop it:
+The `video_..._turn_00.mp4` file is the per-policy-turn recording.
+`video_session_combined.mp4` is written when the session stops, so
+`CAPX_STOP_ON_EXIT=1` is recommended for video examples. The runtime console
+shows the combined session video first and links the per-turn videos as
+individual artifact files.
+
+## Recovery And Cleanup
+
+The autosolver distinguishes ordinary policy-code failures from runtime-level
+CaP-X failures.
+
+| Case                                                                | What Happens                                                                   |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Python policy returns stderr                                        | The next agent turn can inspect the error and write better code.               |
+| Observation or depth pipeline fails before `env.step(code)` returns | The autosolver stops or uses `CAPX_RECOVER_ON_RUNTIME_ERROR=reset` if enabled. |
+| Recovery reset is enabled                                           | The session resets to the next trial/seed. The default reset budget is `1`.    |
+| `CAPX_STOP_ON_EXIT=1` is set                                        | The example stops the runtime session at exit and flushes the combined video.  |
+
+If the reset budget is exhausted, clean up first and retry with a fresh
+session. When a session is still running, find its id and stop it:
 
 ```bash
 curl -sS http://127.0.0.1:8210/sessions
@@ -281,25 +269,13 @@ curl -X POST \
   http://127.0.0.1:8210/sessions/<session-id>/reset
 ```
 
-Then run the autosolver again:
-
-```bash
-CAPX_ALLOW_DESTRUCTIVE=1 \
-CAPX_POLICY_EXECUTION_RECORD_VIDEO=1 \
-CAPX_MAX_SOLVER_TURNS=6 \
-CAPX_RECOVER_ON_RUNTIME_ERROR=reset \
-CAPX_MAX_RUNTIME_RESETS=1 \
-CAPX_STOP_ON_EXIT=1 \
-pnpm exec tsx examples/02-capx-runtime-autosolve.ts
-```
-
 If the depth assertion repeats immediately on a clean session, restart the
 `capx-agent-runtime serve` process too. That recreates the Python environment
 and the child API services instead of reusing the same process state.
 
-If you want to isolate the TypeScript adapter and `agent-core` loop from the
-vision/depth stack, start `capx-agent-runtime` with a privileged cube-stack
-config when available:
+To isolate the TypeScript adapter and `agent-core` loop from the vision/depth
+stack, start `capx-agent-runtime` with a privileged cube-stack config when that
+config is available:
 
 ```bash
 uv run --no-sync --active capx-agent-runtime serve \
@@ -309,79 +285,59 @@ uv run --no-sync --active capx-agent-runtime serve \
   --port 8210
 ```
 
-That path avoids some vision-derived object-pose calls and is useful for
-checking that HTTP tools, approvals, artifacts, videos, and the external agent
-loop are wired correctly before debugging the Robosuite camera/depth pipeline.
-
-`CAPX_ALLOW_DESTRUCTIVE=1` means "allow side-effecting CaP-X tools" in this
-example harness. It is required for `capx_run_policy_code` because that tool
-executes model-authored Python inside the live CaP-X runtime. For hardware
-configs, policy execution is still blocked unless
-`CAPX_ALLOW_HARDWARE_POLICY_EXECUTION=1` is also set.
-
-The example always uses the live runtime path: `mode: "runtime"`,
-`startSession: true`, `enablePolicyCodeExecution: true`,
-and `policyExecutionMode: "live-runtime"`. The adapter does not accept
-`repoPath` or `configPath`; those belong to the runtime server startup command.
-That keeps the example aligned with the production architecture: the Python
-runtime service owns the CaP-X repo/config/simulator setup, and `agent-core`
-owns the external agent loop.
+That path avoids some vision-derived object-pose calls and is useful when you
+want to validate HTTP tools, approvals, artifacts, videos, and the external
+agent loop before debugging the Robosuite camera/depth pipeline.
+
+## Environment Variables
+
+| Variable                                 | Purpose                                                                                       |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`                         | Configures the `agent-core` model provider.                                                   |
+| `OPENAI_MODEL`                           | Model id. Defaults to `gpt-4o-mini` in `examples/_setup.ts`.                                  |
+| `OPENAI_BASE_URL`                        | Optional OpenAI-compatible provider endpoint.                                                 |
+| `CAPX_RUNTIME_SERVER_URL`                | URL for the running `capx-agent-runtime` service.                                             |
+| `CAPX_ALLOW_DESTRUCTIVE=1`               | Lets the example approval policy execute `capx_run_policy_code`.                              |
+| `CAPX_ALLOW_HARDWARE_POLICY_EXECUTION=1` | Extra gate required before policy execution against hardware configs.                         |
+| `CAPX_MAX_SOLVER_TURNS`                  | Outer loop limit for `02-capx-runtime-autosolve.ts`.                                          |
+| `CAPX_RECOVER_ON_RUNTIME_ERROR=reset`    | Reset the live runtime session after runtime-level observation/depth failures.                |
+| `CAPX_MAX_RUNTIME_RESETS`                | Recovery reset budget. Defaults to `1` when recovery is enabled.                              |
+| `CAPX_POLICY_EXECUTION_RECORD_VIDEO`     | Optional `1` or `0` override for the selected YAML's video setting.                           |
+| `CAPX_STOP_ON_EXIT=1`                    | Stop the runtime session when the example exits and flush combined video artifacts.           |
+| `CAPX_SESSION_OUTPUT_DIR`                | Privileged per-session output override. Leave unset for normal server-owned paths.            |
+| `CAPX_SESSION_SKILL_LIBRARY_PATH`        | Privileged per-session skill-library override. Leave unset unless path overrides are enabled. |
+| `CAPX_TOOL_RESULT_MAX_CHARS`             | Increase printed tool-result previews while debugging.                                        |
+
+By default, each example run uses the runtime server's configured output
+directory and skill-library path. Set `CAPX_SESSION_OUTPUT_DIR` or
+`CAPX_SESSION_SKILL_LIBRARY_PATH` only when the runtime server was started with
+`--allow-client-path-overrides` and allowed roots for those paths.
+
+## Runtime Contract
+
+The examples always use the live runtime path: `mode: "runtime"`,
+`startSession: true`, `enablePolicyCodeExecution: true`, and
+`policyExecutionMode: "live-runtime"`.
+
+The adapter does not accept `repoPath` or `configPath`, and it omits
+`outputDir` and `skillLibraryPath` by default. Those path choices belong to the
+runtime server startup command. That keeps the architecture clean: the Python
+runtime service owns the CaP-X repo/config/output/simulator setup, and
+`agent-core` owns the external agent loop.
 
 The adapter defaults to `toolExecutionMode: "plan"`. In `agent-core`, "plan"
-means framework-owned tool dispatch, not "only produce a written plan." The
-model still reasons normally and emits tool calls; `agent-core` executes those
-tool calls after applying approval and scheduling policy, then records the tool
-results before the next model step. The console output lines such as
-`capx_status({ ... })` and `capx_run_policy_code({ ... })` are the visible
-planned tool calls.
-
-Both examples use `agent-core`'s `createEventPrinter` to render progress:
-steps, tool calls, tool results, approval events, text output, and completion.
-For CaP-X, those logs are the easiest way to see the external agent loop:
-status, observe, optional policy-code execution, observe again, then final
-summary. Set `CAPX_TOOL_RESULT_MAX_CHARS` if you want the terminal to print
-longer tool-result previews while debugging.
-
-## Environment Model
-
-`OPENAI_API_KEY` configures the `agent-core` model provider. `OPENAI_MODEL`
-defaults to `gpt-4o-mini` through `examples/_setup.ts` if you omit it.
-`OPENAI_BASE_URL` is only needed for non-default OpenAI-compatible endpoints.
-
-`CAPX_RUNTIME_SERVER_URL` points to the `capx-agent-runtime` service. When
-the example creates a session, it lets the server's startup arguments define
-the CaP-X repo, YAML config, output directory, and simulator context. This
-matches the workstation setup command above.
-
-`CAPX_ALLOW_DESTRUCTIVE=1` lets the example approval policy allow
-`capx_run_policy_code`. Without it, the agent can observe and propose code but
-will not execute policy code.
-
-`CAPX_MAX_SOLVER_TURNS` controls the outer loop in
-`02-capx-runtime-autosolve.ts`. The same `agent-core` session id is reused for
-each turn so the agent keeps conversation and tool history.
-
-`CAPX_RECOVER_ON_RUNTIME_ERROR=reset` lets
-`02-capx-runtime-autosolve.ts` reset the live CaP-X runtime session to the next
-trial/seed and continue when CaP-X reports an observation/depth failure. This
-is session-level recovery for failures where `env.step(code)` cannot return a
-normal multi-turn result. `CAPX_MAX_RUNTIME_RESETS` controls the reset budget
-and defaults to `1` when recovery is enabled.
-
-`CAPX_POLICY_EXECUTION_RECORD_VIDEO` is optional. Leave it unset to use the
-selected CaP-X YAML's `record_video` setting. Set it to `1` or `0` only when
-you want the TypeScript example to override the runtime server/YAML value.
-
-## Prompt Context
+means framework-owned tool dispatch, not "only write a textual plan." The model
+can still emit tool calls; `agent-core` applies approval and scheduling policy,
+executes approved tools, then records tool results before the next model step.
 
-This package does not copy CaP-X prompt templates into TypeScript. In runtime
-mode, `capx-agent-runtime` loads the selected CaP-X YAML config and trial. Then
-`capx_observe` returns the task prompt, full prompt, observations, API
-descriptions, rendered frame when available, and last-step result to the
-`agent-core` agent.
+Both examples use `agent-core`'s `createEventPrinter` to render steps, tool
+calls, tool results, approval events, text output, and completion. For CaP-X,
+those logs are the easiest way to see the external agent loop: status, observe,
+optional policy-code execution, observe again, then final summary.
 
-The external agent reads that CaP-X-provided context and acts by calling
+This package does not copy CaP-X prompt templates into TypeScript. In runtime
+mode, `capx-agent-runtime` loads the selected CaP-X YAML config and trial.
+`capx_observe` returns the CaP-X task prompt, full prompt, observations, API
+descriptions, rendered frame when available, and last-step result. The external
+agent reads that CaP-X-provided context and acts by calling
 `capx_run_policy_code`.
-
-This is the clean bring-your-own-agent reference: start the runtime service
-first, then connect an external `agent-core` agent to it.