@cuylabs/agent-physical-capx 5.0.2

package/docs/how-it-works.md

@@ -0,0 +1,151 @@
+# How The CaP-X Adapter Works
+
+`CapxSession` implements the `PhysicalSession` contract from
+`@cuylabs/agent-physical`. CaP-X itself remains the Python robotics
+Code-as-Policy framework.
+
+The long-term runtime path is service-first:
+
+```text
+GPU workstation
+  capx-agent-runtime serve --repo-path ... --config-path ...
+    -> loads CaP-X YAML config
+    -> starts configured CaP-X API servers
+    -> creates one CaP-X environment
+    -> exposes HTTP endpoints
+
+TypeScript client
+  CapxSession.start()
+    -> GET /health
+    -> POST /sessions
+    -> agent-core drives observe/execute-code against that same session
+```
+
+The TypeScript package does not launch `capx-agent-runtime` and does not know
+the CaP-X checkout or YAML path. Those values belong to the Python service
+command because the Python environment is where simulator packages, CUDA
+packages, assets, and CaP-X internals exist.
+
+## Tool Mapping
+
+`createCapxPhysicalTools(session)` delegates to the generic tools from
+`@cuylabs/agent-physical` with a `capx_` prefix.
+
+```text
+capx_status               -> session.getState()
+capx_observe              -> session.observe()
+capx_artifacts            -> session.listArtifacts()
+capx_stop                 -> session.stop()
+capx_run_policy_code      -> POST /sessions/{id}/execute-code
+capx_turn_history         -> GET  /sessions/{id}/turns
+```
+
+`createCapxAgent(options)` is the higher-level convenience wrapper. It creates
+or accepts a `CapxSession`, optionally starts it, generates the `capx_*` tools,
+and passes those tools to `createAgent()` from `@cuylabs/agent-core`.
+
+A `CapxSession` is deliberately stateful. Once it starts, every `capx_observe`,
+`capx_run_policy_code`, `capx_turn_history`, and `capx_artifacts` call targets
+the same runtime session until the host resets or stops it. The model-facing
+tool surface does not include a separate "start a new trial" command, because
+session creation and reset policy belong to the host application and
+`capx-agent-runtime`.
+
+## Prompt And Skill Flow
+
+The adapter does not vendor CaP-X prompts into TypeScript. On reset and observe,
+`capx-agent-runtime` returns the CaP-X task prompt, full prompt, observations,
+policy-code context, and last-step result. The adapter exposes those through
+`capx_observe` so the `agent-core` model can write the next policy-code step.
+
+When `capx_observe` is called with `includeImages=true`, the adapter also asks
+the runtime for a rendered frame. The tool result keeps a text summary for CLI
+logs and session history, and it provides a richer model-facing payload through
+`agent-core` metadata: text observations plus image file data. That lets
+image-capable models inspect the frame on the following reasoning step while
+text-only logs remain readable. If the selected model or provider does not
+support image inputs, use the textual prompt/observation data or the MCP path
+described below.
+
+CaP-X Python skills stay in the runtime. Runtime observations can include
+skill-library summaries and typed policy-code affordances, while programmatic
+clients can still call the runtime skill-library endpoints deliberately when
+they need to inspect source, extract reusable helpers, or inject promoted
+helpers with host approval.
+
+## CaP-X Configs And Multi-Turn
+
+The CaP-X YAML chosen by `capx-agent-runtime serve --config-path ...` selects
+the simulator task, helper API surface, perception/API servers, output
+directory, recording behavior, and prompt text. The TypeScript adapter does not
+choose or reload that YAML; it connects to the already-started runtime service.
+
+The external `agent-core` loop can run multiple turns against any compatible
+CaP-X config because each `capx_run_policy_code` call executes one Python
+program in the same live environment. The config does not need to be named
+`multiturn` for the external loop to continue observing and executing.
+
+CaP-X's `*_multiturn*.yaml` files are still useful because they often add
+task-specific continuation guidance to the prompt and define
+`multi_turn_prompt`. `capx-agent-runtime` exposes that prompt through
+`capx_observe` so the external agent can use it as guidance.
+
+CaP-X's `*_vf.yaml` and `*_vdm.yaml` configs express visual-feedback and
+visual-differencing behavior. In the bring-your-own-agent path, those flags are
+surfaced as runtime config metadata. The external agent should call
+`capx_observe` with `includeImages=true` and perform the visual comparison in
+the host harness/model.
+
+Reduced-API and skill-library configs also work when the selected CaP-X
+environment imports successfully. They change which Python helper functions
+CaP-X binds into the policy-code namespace. The agent should rely on the
+observed CaP-X full prompt and `codeContext`, not hard-coded TypeScript copies
+of those helpers.
+
+## Artifact Mapping
+
+CaP-X writes generated code, logs, prompts, images, videos, and summaries under
+its output directory. `capx-agent-runtime` lists those artifacts over HTTP and
+the adapter maps them into `PhysicalArtifact` records.
+
+In a healthy recorded cube-stack run, the first successful policy-code turn
+returns `success=true`, `taskCompleted=true`, `reward=1`, `terminated=true`,
+and `sandboxRc=0`. The runtime artifact list includes the submitted `code.py`,
+CaP-X response JSON, summary/log files, rendered images, one per-turn MP4 such
+as `video_1.000_turn_00.mp4`, and, after `capx_stop` or
+`CAPX_STOP_ON_EXIT=1`, a `video_session_combined.mp4` artifact.
+
+Short per-turn videos are normal when a policy step fails quickly. The combined
+session video is the best artifact to inspect after a full run because it is
+written once the live runtime session stops.
+
+## Execution Diagnostics
+
+Policy-code failures and runtime observation failures are different.
+
+When CaP-X executes user code and returns a normal failed step, the adapter
+surfaces `stderr`, `sandboxRc`, task-completion state, reward, and compact
+diagnostics such as `failurePhase=policy_execution`,
+`perceptionApiFailure=true`, or `emptyPointCloud=true`. The agent loop can
+inspect that result and try another policy step.
+
+When `env.step(code)` itself raises while collecting the post-policy
+observation, the runtime marks the step as truncated and reports diagnostics
+such as `failurePhase=post_policy_observation`, `observationPipeline=true`, and
+`depthAssertion=true`. The autosolve example can reset the runtime to the next
+trial/seed for that class of failure when
+`CAPX_RECOVER_ON_RUNTIME_ERROR=reset` is enabled.
+
+## Direct Adapter Versus MCP Images
+
+The TypeScript adapter uses `capx_observe(includeImages=true)` for the common
+agent loop. It converts the rendered frame into `agent-core` multimodal
+tool-result metadata so the next model step can receive both text and image
+content.
+
+The MCP wrapper uses MCP-native content semantics instead. `capx_render_frame`
+returns text plus MCP `ImageContent`, and `capx_read_artifact` returns
+`ImageContent` for image artifacts. `agent-core`'s MCP client maps those MCP
+image parts to model file-data parts. In other words, direct adapter and MCP
+integrations both expose images, but they use the natural content contract for
+their transport.

package/docs/limitations.md

@@ -0,0 +1,25 @@
+# Current Limitations
+
+This package is an `agents-ts` adapter for `capx-agent-runtime`, not a full
+CaP-X control plane.
+
+## Runtime Service Required
+
+The TypeScript adapter requires an already-running `capx-agent-runtime` service.
+It does not launch CaP-X, does not launch the runtime service, and does not know
+the CaP-X checkout or YAML config. Start the Python service in the CaP-X
+environment first, then pass `runtimeServerUrl`.
+
+## Runtime-Service Boundary
+
+The runtime path creates and controls sessions through `capx-agent-runtime`.
+The TypeScript package does not attach to arbitrary existing CaP-X processes or
+browser UI state. Keep all CaP-X process integration behind the Python runtime
+service so the TypeScript tool surface stays stable.
+
+## Hardware Safety Remains External
+
+For real robot configs, CaP-X and the robot-side hardware stack still own
+calibration, low-level realtime control, and hardware safety systems. This
+package only provides an `agents-ts` integration boundary and approval-gated
+policy-code tools.

package/examples/.env.example

@@ -0,0 +1,36 @@
+# Required agent model config. `_setup.ts` loads this file automatically when
+# either example runs.
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4o-mini
+# Optional: set only for OpenAI-compatible providers that are not the default
+# OpenAI endpoint.
+OPENAI_BASE_URL=
+
+# Required runtime service URL. Start capx-agent-runtime first, then point this
+# example at the service or SSH tunnel URL. The TypeScript examples do not
+# launch CaP-X or CaP-X Agent0.
+CAPX_RUNTIME_SERVER_URL=http://127.0.0.1:8210
+
+# Safety switches for the example host. Set CAPX_ALLOW_DESTRUCTIVE=1 to allow
+# capx_run_policy_code; otherwise the examples can observe and propose code but
+# execution is denied.
+CAPX_PHYSICAL_MODE=simulation
+CAPX_ALLOW_DESTRUCTIVE=0
+CAPX_ALLOW_HARDWARE_POLICY_EXECUTION=0
+
+# Optional runtime/client tuning.
+CAPX_RUNTIME_SERVER_STARTUP_TIMEOUT_MS=120000
+CAPX_RUNTIME_SERVER_REQUEST_TIMEOUT_MS=1000000
+CAPX_POLICY_EXECUTION_TIMEOUT_MS=1000000
+CAPX_POLICY_EXECUTION_TRIAL=
+# Leave blank to use the CaP-X YAML record_video setting. Set 1 or 0 only to
+# override the server/YAML value for this example run.
+CAPX_POLICY_EXECUTION_RECORD_VIDEO=
+CAPX_STOP_ON_EXIT=0
+CAPX_MAX_SOLVER_TURNS=6
+
+# Optional runtime session overrides. Normally the runtime server startup
+# command owns output paths and skill library paths.
+CAPX_OUTPUT_DIR=
+CAPX_SKILL_LIBRARY_PATH=
+CAPX_AGENT_PROMPT=

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

@@ -0,0 +1,162 @@
+/**
+ * 01 - CaP-X runtime solver
+ *
+ * This is the default bring-your-own-agent flow:
+ *   1. Start capx-agent-runtime on the GPU workstation.
+ *   2. Point CAPX_RUNTIME_SERVER_URL at that service or SSH tunnel.
+ *   3. Run this TypeScript agent locally.
+ *
+ * The runtime service owns the CaP-X checkout, YAML config, simulator, and API
+ * servers. This agent-core example owns the reasoning loop: observe, inspect
+ * 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
+ */
+
+import { createCapxAgent } from "@cuylabs/agent-physical-capx";
+import { createEventPrinter } from "@cuylabs/agent-core";
+import { exampleOpenAIModel } from "./_setup.js";
+
+function optionalString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function optionalBoolean(value: string | undefined): boolean | undefined {
+  if (value === undefined || value.trim() === "") {
+    return undefined;
+  }
+  return value === "1" || value.toLowerCase() === "true";
+}
+
+function optionalNumber(value: string | undefined): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+const runtimeServerUrl = optionalString(process.env.CAPX_RUNTIME_SERVER_URL);
+
+if (!runtimeServerUrl) {
+  throw new Error(
+    [
+      "CAPX_RUNTIME_SERVER_URL is required.",
+      "Start capx-agent-runtime on the CaP-X workstation, tunnel the port if needed,",
+      "then set CAPX_RUNTIME_SERVER_URL=http://127.0.0.1:8210.",
+    ].join(" "),
+  );
+}
+
+const allowDestructive = process.env.CAPX_ALLOW_DESTRUCTIVE === "1";
+const toolExecutionMode = "plan" as const;
+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 recordVideo =
+  optionalString(process.env.CAPX_POLICY_EXECUTION_RECORD_VIDEO) ??
+  "runtime-default";
+
+function approveExampleTool(tool: string): "allow" | "deny" {
+  if (tool === "skill") {
+    return "allow";
+  }
+  return allowDestructive ? "allow" : "deny";
+}
+
+const userPrompt =
+  optionalString(process.env.CAPX_AGENT_PROMPT) ??
+  [
+    "You are the external agent solving one CaP-X runtime simulation.",
+    "Check capx_status first, then call capx_observe with includeImages=true.",
+    "Use the CaP-X task prompt, full prompt, observations, API context, skill library, and turn history as the source of truth.",
+    "Propose one concise Python Code-as-Policy action toward the task.",
+    "If capx_run_policy_code is available and approval allows it, execute the action, observe again, inspect reward/stdout/stderr/task completion, and summarize the result.",
+    "If skill extraction or injection tools are available, only use them after useful successful code and with approval.",
+    "If execution is denied, explain the exact policy code you would run and why.",
+  ].join(" ");
+
+console.log(
+  [
+    "CaP-X agent mode=runtime",
+    "startSession=true",
+    "policyExecution=live-runtime",
+    `toolDispatch=${toolExecutionMode}`,
+    `approval=${allowDestructive ? "policy-code-enabled" : "observe-only"}`,
+    `recordVideo=${recordVideo}`,
+    `agentSessionId=${sessionId}`,
+    `outputDir=${outputDir}`,
+    `runtimeServerUrl=${runtimeServerUrl}`,
+  ]
+    .join(" "),
+);
+
+const { agent, session } = await createCapxAgent({
+  model: exampleOpenAIModel(),
+  startSession: true,
+  toolExecutionMode,
+  sessionOptions: {
+    mode: "runtime",
+    physicalMode:
+      process.env.CAPX_PHYSICAL_MODE === "hardware" ? "hardware" : "simulation",
+
+    // Normal service-first path: connect to an already-running runtime server
+    // and let that server's --config-path/--repo-path defaults define the
+    // simulation.
+    runtimeServerUrl,
+    runtimeServerStartupTimeoutMs: optionalNumber(
+      process.env.CAPX_RUNTIME_SERVER_STARTUP_TIMEOUT_MS,
+    ),
+    runtimeServerRequestTimeoutMs: optionalNumber(
+      process.env.CAPX_RUNTIME_SERVER_REQUEST_TIMEOUT_MS,
+    ),
+
+    enablePolicyCodeExecution: true,
+    policyExecutionMode: "live-runtime",
+    allowHardwarePolicyExecution:
+      process.env.CAPX_ALLOW_HARDWARE_POLICY_EXECUTION === "1",
+    policyExecutionTimeoutMs: optionalNumber(
+      process.env.CAPX_POLICY_EXECUTION_TIMEOUT_MS,
+    ),
+    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),
+  },
+  approval: {
+    defaultAction: "ask",
+    onRequest: async (request) => {
+      console.log(
+        `approval requested: ${request.tool} risk=${request.risk} description=${request.description}`,
+      );
+      return approveExampleTool(request.tool);
+    },
+  },
+});
+
+try {
+  const printEvent = createEventPrinter({
+    steps: true,
+    completion: true,
+    toolResultMaxChars:
+      optionalNumber(process.env.CAPX_TOOL_RESULT_MAX_CHARS) ?? 2_000,
+  });
+  for await (const event of agent.chat(sessionId, userPrompt)) {
+    printEvent(event);
+  }
+} finally {
+  await agent.close();
+  if (process.env.CAPX_STOP_ON_EXIT === "1") {
+    await session.stop("example exit");
+  }
+}

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

@@ -0,0 +1,307 @@
+/**
+ * 02 - CaP-X runtime autosolve loop
+ *
+ * This example keeps the same agent-core session open across multiple user
+ * turns. Each turn lets the agent observe, write policy code, execute it when
+ * approval allows, and inspect the new result. The outer loop stops when CaP-X
+ * 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
+ */
+
+import { createEventPrinter } from "@cuylabs/agent-core";
+import { createCapxAgent } from "@cuylabs/agent-physical-capx";
+import type { PhysicalObservation } from "@cuylabs/agent-physical";
+import { exampleOpenAIModel } from "./_setup.js";
+
+function optionalString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function optionalBoolean(value: string | undefined): boolean | undefined {
+  if (value === undefined || value.trim() === "") {
+    return undefined;
+  }
+  return value === "1" || value.toLowerCase() === "true";
+}
+
+function optionalNumber(value: string | undefined): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+interface LastRuntimeStep {
+  success?: boolean;
+  taskCompleted?: boolean | null;
+  task_completed?: boolean | null;
+  terminated?: boolean;
+  truncated?: boolean;
+  reward?: number | null;
+  sandboxRc?: number;
+  sandbox_rc?: number;
+  stderr?: string;
+  error?: string | null;
+  diagnostics?: {
+    failurePhase?: string;
+    observationPipeline?: boolean;
+    depthAssertion?: boolean;
+  } | null;
+}
+
+function normalizeStep(step: LastRuntimeStep): LastRuntimeStep {
+  return {
+    ...step,
+    taskCompleted: step.taskCompleted ?? step.task_completed,
+    sandboxRc: step.sandboxRc ?? step.sandbox_rc,
+  };
+}
+
+function lastStep(observation: PhysicalObservation): LastRuntimeStep | null {
+  const item = [...observation.items]
+    .reverse()
+    .find((entry) => entry.source === "capx:runtime:last-step");
+  if (!item || item.kind !== "text") {
+    return null;
+  }
+  try {
+    return normalizeStep(JSON.parse(item.text) as LastRuntimeStep);
+  } catch {
+    return null;
+  }
+}
+
+function isUnrecoverableObservationFailure(step: LastRuntimeStep | null): boolean {
+  if (!step) {
+    return false;
+  }
+  const stderr = step.stderr ?? "";
+  const error = step.error ?? "";
+  const sandboxFailed = step.sandboxRc !== undefined && step.sandboxRc !== 0;
+  const diagnostics = step.diagnostics ?? null;
+  if (diagnostics?.failurePhase === "policy_execution") {
+    return false;
+  }
+  const runtimeRaised = Boolean(error) || Boolean(diagnostics);
+  if (!sandboxFailed || !runtimeRaised) {
+    return false;
+  }
+  if (diagnostics) {
+    return Boolean(
+      step.truncated &&
+        (diagnostics.observationPipeline ||
+          diagnostics.depthAssertion ||
+          error.includes("AssertionError")),
+    );
+  }
+  const mentionsObservationPath =
+    stderr.includes("_get_observation") ||
+    stderr.includes("get_observation") ||
+    stderr.includes("get_real_depth_map");
+  const mentionsDepthAssertion =
+    stderr.includes("get_real_depth_map") ||
+    (stderr.includes("AssertionError") && stderr.includes("depth"));
+  return Boolean(
+    sandboxFailed &&
+      step.truncated &&
+      (mentionsObservationPath || mentionsDepthAssertion || error.includes("AssertionError")),
+  );
+}
+
+function completionSummary(step: LastRuntimeStep): string {
+  return [
+    `taskCompleted=${step.taskCompleted ?? "n/a"}`,
+    `terminated=${step.terminated ?? "n/a"}`,
+    `truncated=${step.truncated ?? "n/a"}`,
+    `sandboxRc=${step.sandboxRc ?? "n/a"}`,
+    `reward=${step.reward ?? "n/a"}`,
+  ].join(" ");
+}
+
+const runtimeServerUrl = optionalString(process.env.CAPX_RUNTIME_SERVER_URL);
+
+if (!runtimeServerUrl) {
+  throw new Error(
+    [
+      "CAPX_RUNTIME_SERVER_URL is required.",
+      "Start capx-agent-runtime on the CaP-X workstation, tunnel the port if needed,",
+      "then set CAPX_RUNTIME_SERVER_URL=http://127.0.0.1:8210.",
+    ].join(" "),
+  );
+}
+
+const allowDestructive = process.env.CAPX_ALLOW_DESTRUCTIVE === "1";
+const maxTurns = optionalNumber(process.env.CAPX_MAX_SOLVER_TURNS) ?? 6;
+const recoverOnRuntimeError =
+  optionalString(process.env.CAPX_RECOVER_ON_RUNTIME_ERROR) === "reset";
+const maxRuntimeResets =
+  optionalNumber(process.env.CAPX_MAX_RUNTIME_RESETS) ??
+  (recoverOnRuntimeError ? 1 : 0);
+const initialPolicyExecutionTrial =
+  optionalNumber(process.env.CAPX_POLICY_EXECUTION_TRIAL) ?? 1;
+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 toolExecutionMode = "plan" as const;
+const recordVideo =
+  optionalString(process.env.CAPX_POLICY_EXECUTION_RECORD_VIDEO) ??
+  "runtime-default";
+const printEvent = createEventPrinter({
+  steps: true,
+  completion: true,
+  toolResultMaxChars:
+    optionalNumber(process.env.CAPX_TOOL_RESULT_MAX_CHARS) ?? 2_000,
+});
+
+function approveExampleTool(tool: string): "allow" | "deny" {
+  if (tool === "skill") {
+    return "allow";
+  }
+  return allowDestructive ? "allow" : "deny";
+}
+
+console.error(
+  [
+    "CaP-X agent mode=runtime",
+    `maxTurns=${maxTurns}`,
+    "policyExecution=live-runtime",
+    `toolDispatch=${toolExecutionMode}`,
+    `approval=${allowDestructive ? "policy-code-enabled" : "observe-only"}`,
+    `recordVideo=${recordVideo}`,
+    `agentSessionId=${sessionId}`,
+    `outputDir=${outputDir}`,
+    `trial=${initialPolicyExecutionTrial}`,
+    `recoverOnRuntimeError=${recoverOnRuntimeError ? "reset" : "off"}`,
+    `maxRuntimeResets=${maxRuntimeResets}`,
+    `runtimeServerUrl=${runtimeServerUrl}`,
+  ].join(" "),
+);
+
+const { agent, session } = await createCapxAgent({
+  model: exampleOpenAIModel(),
+  startSession: true,
+  toolExecutionMode,
+  sessionOptions: {
+    mode: "runtime",
+    runtimeServerUrl,
+    physicalMode:
+      process.env.CAPX_PHYSICAL_MODE === "hardware" ? "hardware" : "simulation",
+    runtimeServerStartupTimeoutMs: optionalNumber(
+      process.env.CAPX_RUNTIME_SERVER_STARTUP_TIMEOUT_MS,
+    ),
+    runtimeServerRequestTimeoutMs: optionalNumber(
+      process.env.CAPX_RUNTIME_SERVER_REQUEST_TIMEOUT_MS,
+    ),
+    enablePolicyCodeExecution: true,
+    policyExecutionMode: "live-runtime",
+    allowHardwarePolicyExecution:
+      process.env.CAPX_ALLOW_HARDWARE_POLICY_EXECUTION === "1",
+    policyExecutionTimeoutMs: optionalNumber(
+      process.env.CAPX_POLICY_EXECUTION_TIMEOUT_MS,
+    ),
+    policyExecutionTrial: initialPolicyExecutionTrial,
+    policyExecutionRecordVideo: optionalBoolean(
+      process.env.CAPX_POLICY_EXECUTION_RECORD_VIDEO,
+    ),
+    outputDir,
+    skillLibraryPath: optionalString(process.env.CAPX_SKILL_LIBRARY_PATH),
+  },
+  approval: {
+    defaultAction: "ask",
+    onRequest: async (request) => {
+      console.error(
+        `approval requested: ${request.tool} risk=${request.risk} description=${request.description}`,
+      );
+      return approveExampleTool(request.tool);
+    },
+  },
+});
+
+try {
+  let runtimeResetCount = 0;
+  let resetBeforeTurn = false;
+
+  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
+        ? [
+            "Solve the active CaP-X task.",
+            "First call capx_status, then capx_observe with includeImages=true.",
+            "Use CaP-X's task prompt, API context, observations, skill library, and turn history as source of truth.",
+            "Execute one useful Python Code-as-Policy step if approval allows it.",
+            "After execution, observe again and report whether the task appears complete.",
+          ].join(" ")
+        : [
+            "Continue solving the same CaP-X task from the current runtime state.",
+            "Inspect capx_turn_history and capx_observe before choosing the next action.",
+            "If the last step completed the task, say TASK_COMPLETE and do not execute more code.",
+            "Otherwise execute one more useful Python Code-as-Policy step if approval allows it, then observe again.",
+          ].join(" ");
+
+    for await (const event of agent.chat(sessionId, prompt)) {
+      printEvent(event);
+    }
+
+    const observation = await session.observe({ includeArtifacts: true });
+    const step = lastStep(observation);
+    if (isUnrecoverableObservationFailure(step)) {
+      if (recoverOnRuntimeError && runtimeResetCount < maxRuntimeResets) {
+        runtimeResetCount += 1;
+        const nextTrial = initialPolicyExecutionTrial + runtimeResetCount;
+        session.options.policyExecutionTrial = nextTrial;
+        console.error(
+          [
+            "CaP-X reported an observation/depth failure.",
+            `Resetting runtime session to trial ${nextTrial} before the next solver turn (${runtimeResetCount}/${maxRuntimeResets}).`,
+            step ? `Last step: ${completionSummary(step)}` : "",
+          ]
+            .filter(Boolean)
+            .join(" "),
+        );
+        await session.reset?.();
+        resetBeforeTurn = true;
+        continue;
+      }
+      console.error(
+        [
+          "Stopping autosolve: CaP-X reported an unrecoverable observation/depth failure.",
+          "The current runtime session cannot execute further policy code because env.step() fails while collecting observations.",
+          recoverOnRuntimeError
+            ? "Runtime reset budget is exhausted. Restart capx-agent-runtime serve or retry with a fresh session."
+            : "Set CAPX_RECOVER_ON_RUNTIME_ERROR=reset to let this example reset once and continue.",
+          step ? `Last step: ${completionSummary(step)}` : "",
+        ]
+          .filter(Boolean)
+          .join(" "),
+      );
+      break;
+    }
+    if (step?.taskCompleted || step?.terminated) {
+      console.error(`CaP-X reported completion state: ${completionSummary(step)}`);
+      break;
+    }
+    resetBeforeTurn = false;
+  }
+} finally {
+  await agent.close();
+  if (process.env.CAPX_STOP_ON_EXIT === "1") {
+    await session.stop("example exit");
+  }
+}