@testin-official/xagent 0.3.7

package/dist/assets/contracts/run.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/run.schema.json",
+  "title": "XAgent Run v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "status", "script_snapshot", "device_executions"],
+  "properties": {
+    "schema_version": {"const": "xagent-run/v1"},
+    "id": {"type": "string", "minLength": 1},
+    "status": {
+      "enum": [
+        "validating",
+        "queued",
+        "waiting_device",
+        "running",
+        "passed",
+        "failed",
+        "infrastructure_failed",
+        "cancelling",
+        "cancelled",
+        "timed_out"
+      ]
+    },
+    "script_snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_hash", "canonical_hash", "schema_version", "compiler_version"],
+      "properties": {
+        "source_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "canonical_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "schema_version": {"const": "xagent-script/v1"},
+        "compiler_version": {"const": "xagent-compiler/1"}
+      }
+    },
+    "target_snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target_name", "target_hash", "target", "devices"],
+      "properties": {
+        "target_name": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$"
+        },
+        "target_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "target": {"$ref": "execution-target.schema.json"},
+        "devices": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "device_id",
+              "platform",
+              "brand",
+              "model",
+              "os_version",
+              "resolution",
+              "available"
+            ],
+            "properties": {
+              "device_id": {"type": "string", "minLength": 1, "maxLength": 128},
+              "platform": {"type": "string", "minLength": 1, "maxLength": 64},
+              "brand": {"type": "string", "minLength": 1, "maxLength": 128},
+              "model": {"type": "string", "minLength": 1, "maxLength": 128},
+              "os_version": {"type": "string", "minLength": 1, "maxLength": 64},
+              "resolution": {"type": "string", "minLength": 1, "maxLength": 64},
+              "available": {"type": "boolean"}
+            }
+          }
+        }
+      }
+    },
+    "app_upload_id": {
+      "type": "string",
+      "pattern": "^appup_[a-f0-9]{32}$"
+    },
+    "billing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "estimated_minutes", "billable_minutes", "cost", "discount_rate"],
+      "properties": {
+        "status": {"enum": ["pending", "succeeded", "failed", "unknown"]},
+        "estimated_minutes": {"type": "integer", "minimum": 0},
+        "billable_minutes": {"type": "integer", "minimum": 0},
+        "cost": {"type": "integer", "minimum": 0},
+        "discount_rate": {"type": "number", "minimum": 0}
+      }
+    },
+    "device_executions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "device_id", "status"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "device_id": {"type": "string", "minLength": 1},
+          "device_name": {"type": "string", "minLength": 1},
+          "status": {
+            "enum": [
+              "created",
+              "waiting_resource",
+              "starting",
+              "running",
+              "passed",
+              "test_failed",
+              "infrastructure_failed",
+              "cancelling",
+              "cancelled",
+              "timed_out"
+            ]
+          },
+          "steps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["sequence", "action", "status"],
+              "properties": {
+                "sequence": {"type": "integer", "minimum": 1},
+                "action": {"type": "string", "minLength": 1},
+                "status": {"enum": ["passed", "failed"]},
+                "message": {"type": "string"},
+                "screenshot_url": {"type": "string", "format": "uri"}
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/assets/contracts/skill-catalog.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/skill-catalog.schema.json",
+  "title": "XAgent Effective Skill Catalog v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "skills"],
+  "properties": {
+    "schema_version": {"const": "xagent-skill-catalog/v1"},
+    "skills": {
+      "type": "array",
+      "items": {"$ref": "skill-summary.schema.json"}
+    }
+  }
+}

package/dist/assets/contracts/skill-reference.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/skill-reference.schema.json",
+  "title": "XAgent Skill Reference v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "skill_name", "skill_version", "path", "media_type", "content"],
+  "properties": {
+    "schema_version": {"const": "xagent-skill-reference/v1"},
+    "skill_name": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$"},
+    "skill_version": {"type": "string", "minLength": 1, "maxLength": 64},
+    "path": {"type": "string", "minLength": 1, "maxLength": 512},
+    "title": {"type": "string", "maxLength": 256},
+    "media_type": {"type": "string", "minLength": 1, "maxLength": 128},
+    "content": {"type": "string"}
+  }
+}

package/dist/assets/contracts/skill-summary.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/skill-summary.schema.json",
+  "title": "XAgent Effective Skill Summary v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "version", "trigger_description", "scope", "references", "updated_at"],
+  "properties": {
+    "name": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$"},
+    "version": {"type": "string", "minLength": 1, "maxLength": 64},
+    "trigger_description": {"type": "string", "maxLength": 1024},
+    "scope": {"enum": ["personal", "project", "enterprise", "platform"]},
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "media_type"],
+        "properties": {
+          "path": {"type": "string", "minLength": 1, "maxLength": 512},
+          "title": {"type": "string", "maxLength": 256},
+          "media_type": {"type": "string", "minLength": 1, "maxLength": 128}
+        }
+      }
+    },
+    "updated_at": {"type": "string", "format": "date-time"}
+  }
+}

package/dist/assets/contracts/skill.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/skill.schema.json",
+  "title": "XAgent Effective Skill v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "name", "version", "trigger_description", "scope", "references", "updated_at", "skill_md"],
+  "properties": {
+    "schema_version": {"const": "xagent-skill/v1"},
+    "name": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$"},
+    "version": {"type": "string", "minLength": 1, "maxLength": 64},
+    "trigger_description": {"type": "string", "maxLength": 1024},
+    "scope": {"enum": ["personal", "project", "enterprise", "platform"]},
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "media_type"],
+        "properties": {
+          "path": {"type": "string", "minLength": 1, "maxLength": 512},
+          "title": {"type": "string", "maxLength": 256},
+          "media_type": {"type": "string", "minLength": 1, "maxLength": 128}
+        }
+      }
+    },
+    "updated_at": {"type": "string", "format": "date-time"},
+    "skill_md": {"type": "string", "minLength": 1}
+  }
+}

package/dist/assets/contracts/target-preview.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xagent.testin.cn/schemas/developer/v1/target-preview.schema.json",
+  "title": "XAgent Target Preview v1",
+  "oneOf": [
+    {"$ref": "#/$defs/request"},
+    {"$ref": "#/$defs/response"}
+  ],
+  "$defs": {
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "target_name", "target_hash", "target"],
+      "properties": {
+        "schema_version": {"const": "xagent-target-preview/v1"},
+        "target_name": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$"
+        },
+        "target_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "target": {"$ref": "execution-target.schema.json"}
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema_version",
+        "target_name",
+        "target_hash",
+        "devices",
+        "previewed_at",
+        "reserved"
+      ],
+      "properties": {
+        "schema_version": {"const": "xagent-target-preview/v1"},
+        "target_name": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$"
+        },
+        "target_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "devices": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {"$ref": "#/$defs/device_summary"}
+        },
+        "previewed_at": {"type": "string", "format": "date-time"},
+        "reserved": {"const": false}
+      }
+    },
+    "device_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "device_id",
+        "platform",
+        "brand",
+        "model",
+        "os_version",
+        "resolution",
+        "available"
+      ],
+      "properties": {
+        "device_id": {"type": "string", "minLength": 1, "maxLength": 128},
+        "platform": {"type": "string", "minLength": 1, "maxLength": 64},
+        "brand": {"type": "string", "minLength": 1, "maxLength": 128},
+        "model": {"type": "string", "minLength": 1, "maxLength": 128},
+        "os_version": {"type": "string", "minLength": 1, "maxLength": 64},
+        "resolution": {"type": "string", "minLength": 1, "maxLength": 64},
+        "available": {"type": "boolean"}
+      }
+    }
+  }
+}

package/dist/assets/integrations/manifest.json

@@ -0,0 +1,17 @@
+{
+  "schema_version": "xagent-skill/v1",
+  "skill_name": "xagent-skill",
+  "skill_version": "0.3.5",
+  "minimum_cli_version": "0.3.5",
+  "default_domain": "action",
+  "mcp_protocol": "stdio",
+  "route_table_hash": "sha256:5aa8f83d0093cbcb93d661e60b1d516ef377402e41619cec2fae6ffb36eb6a5e",
+  "routes": [
+    { "domain": "action", "mode": "action", "skill": "xagent-explore-device", "side_effects": true },
+    { "domain": "author", "mode": "author", "skill": "xagent-author-test", "side_effects": true },
+    { "domain": "run", "mode": "run", "skill": "xagent-run-test", "side_effects": true },
+    { "domain": "analyze", "mode": "analyze", "skill": "xagent-analyze-failure", "side_effects": false },
+    { "domain": "repair", "mode": "repair", "skill": "xagent-repair-test", "side_effects": true },
+    { "domain": "report", "mode": "report", "skill": "xagent-test-report", "side_effects": false }
+  ]
+}

package/dist/assets/integrations/xagent-skill/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: xagent-skill
+description: Use XAgent to inspect or control an Android device, author and verify a YAML test, run an existing test, analyze evidence, repair an explicitly selected test, or produce a report. Install this Skill once and let it route each request to exactly one XAgent CLI/MCP workflow.
+---
+
+# XAgent
+
+This is the single Agent Host entry for XAgent. The CLI is the cross-platform execution client and `xagent-local` MCP is the stateful Tool adapter. They use the same public API contracts and route table; this Skill must not reimplement device or test business logic.
+
+## Before Any Operation
+
+1. Check that `xagent` is installed and that its version satisfies `manifest.json`.
+2. Check the configured Profile and MCP connection without printing a Token.
+3. Validate the Skill manifest and route-table hash against the CLI. If a check fails, stop before any upload, device, Authoring, Run, or report side effect.
+4. Present the available behavior choices. `action` is the default; never silently select another side-effect mode.
+5. Select exactly one domain and load only its matching packaged/server Skill.
+
+The choices are: `action` (direct device control), `author` (write and verify a test), `run` (execute existing YAML), `analyze` (read-only evidence analysis), `repair` (authorized test repair), and `report` (evidence report). `setup` is an entry check only and is not a user business mode.
+
+## Execution Boundary
+
+- Prefer the connected MCP mode for Agent work. It keeps the device Session, current screen, renewal, and release state between Tool calls.
+- Use the CLI for terminal and CI workflows. Stateful CLI commands must carry the current `session_id`, latest `screen_id`, and a unique idempotency key.
+- Route with `xagent_workflow_options` and `xagent_workflow_route`, then verify `xagent_skill_load_local` (name, version, hash, and references) before side effects.
+- A routed mode may load only its mapped Skill. Changing mode requires the Host to start the corresponding isolated MCP process or restart `xagent-local`.
+- Never pass a Developer Token on a command line, put it in YAML, or copy it into a Skill. Personal credentials use the OS credential store; CI credentials use an explicitly named environment variable.
+
+Read the relevant file in `references/` only after the domain is selected. The Skill owns routing and safety gates; the routed Skill owns its workflow.

package/dist/assets/integrations/xagent-skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: XAgent
+  short_description: Route XAgent device and test requests through one verified CLI/MCP Skill.
+  default_prompt: Check the XAgent CLI, MCP connection, manifest, and route before any side effect; action is the default.

package/dist/assets/integrations/xagent-skill/references/cli-mcp-interop.md

@@ -0,0 +1,10 @@
+# CLI and MCP Interoperability
+
+CLI and MCP are adapters over the same XAgent Developer API. They do not maintain separate execution semantics:
+
+- `action` MCP owns a long-lived device Session and current screen between calls.
+- Direct CLI action calls are explicit and must include the Session and screen identifiers returned by the previous call.
+- Authoring, Run, upload, analysis, repair, and report use the same public schemas, authorization rules, idempotency behavior, and result statuses in both adapters.
+- The external Skill only routes and validates. It must call the selected CLI/MCP surface instead of copying server or device logic.
+
+If MCP is unavailable, a terminal/CI workflow can still use the CLI after the same manifest, profile, capability, and route checks. A missing MCP connection is not permission to guess a different mode.

package/dist/assets/integrations/xagent-skill/references/host-adapters.md

@@ -0,0 +1,9 @@
+# Host Adapters
+
+Codex, Claude, Trae, and WorkBuddy may expose different Skill reload and MCP configuration UIs. The package remains identical. The Host must:
+
+1. Import the directory containing the root `SKILL.md`.
+2. Launch `xagent` as the stdio MCP command with the selected `--profile` and `mcp --mode`.
+3. Reload the Skill/MCP catalog after an upgrade.
+
+Do not assume that a Host supports structured user-choice UI. If it does not, ask for a plain-text domain choice. `step_confirm` is an Agent Host interaction policy and is never sent to the XAgent API.

package/dist/assets/integrations/xagent-skill/references/installation.md

@@ -0,0 +1,10 @@
+# Installation
+
+The customer installs two independent artifacts:
+
+1. The execution client: `npm install --global @testin-official/xagent`.
+2. This directory, `xagent-skill/`, in the Agent Host's Skill directory.
+
+The Skill does not contain a Token and does not require a Python runtime. On Windows use `scripts/install-cli.ps1`; on macOS/Linux use `scripts/install-cli.sh` when the Host permits scripts. Otherwise show the equivalent npm command and wait for the user to run it.
+
+After installation, restart the Agent Host or reload its Skill catalog and start the `xagent-local` MCP entry configured by the Host. Do not overwrite an existing Host configuration automatically.

package/dist/assets/integrations/xagent-skill/references/privacy.md

@@ -0,0 +1,3 @@
+# Credentials and Data
+
+Never put Developer Tokens, browser Cookies, passwords, or APK contents in this Skill package or in a YAML file. The CLI reads credentials from its Profile credential store or the named CI environment variable. Screenshots and test evidence are sent only through the configured XAgent/file-service endpoints when the selected workflow requires them.

package/dist/assets/integrations/xagent-skill/references/routing.md

@@ -0,0 +1,32 @@
+# Routing Contract
+
+The route is an immutable one-to-one mapping. Select one row before a side effect:
+
+| Domain | MCP mode | Routed Skill | Side effects |
+|---|---|---|---|
+| action | action | xagent-explore-device | yes |
+| author | author | xagent-author-test | yes |
+| run | run | xagent-run-test | yes |
+| analyze | analyze | xagent-analyze-failure | no |
+| repair | repair | xagent-repair-test | yes |
+| report | report | xagent-test-report | no |
+
+`setup` is reserved for read-only discovery and routing. It is not in the behavior choices.
+
+Use the CLI equivalents:
+
+```text
+xagent --json integrations options
+xagent --json integrations route action --profile PROFILE
+xagent --json integrations verify-skill PATH_TO_XAGENT_SKILL
+```
+
+Use the MCP equivalents when available:
+
+```text
+xagent_workflow_options
+xagent_workflow_route(domain="action")
+xagent_skill_load_local(skill="xagent-explore-device")
+```
+
+The selected route's `domain`, `mode`, and `skill` must match exactly. A mismatch is a hard stop, not a fallback.

package/dist/assets/integrations/xagent-skill/scripts/install-cli.ps1

@@ -0,0 +1,5 @@
+$ErrorActionPreference = "Stop"
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) { throw "Node.js 20.9 or newer is required" }
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) { throw "npm is required" }
+npm install --global @testin-official/xagent
+xagent --json version

package/dist/assets/integrations/xagent-skill/scripts/install-cli.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+set -eu
+command -v node >/dev/null 2>&1 || { echo "Node.js 20.9 or newer is required" >&2; exit 1; }
+command -v npm >/dev/null 2>&1 || { echo "npm is required" >&2; exit 1; }
+npm install --global @testin-official/xagent
+xagent --json version

package/dist/assets/skills/xagent-analyze-failure/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: xagent-analyze-failure
+description: Read-only analysis of an existing XAgent Run or Authoring Attempt result. Use when the user explicitly asks to analyze, explain, or classify a failure without side effects. Do not use to run, retry, cancel, author, repair, or directly control a device.
+---
+
+# Analyze An XAgent Failure
+
+1. Read the explicit Run or Attempt result, or query it through CLI/MCP when the ID and permission are available.
+2. Classify the outcome using [failure-classification.md](references/failure-classification.md): separate schema/configuration/authentication failures, test behavior failures, infrastructure failures, cancellation, and timeout.
+3. Report the failing device, step index/action, public message, and available Artifact evidence. Do not invent an upstream cause absent from public output.
+4. State whether evidence indicates a transient infrastructure condition or a test-behavior problem. Do not turn that classification into a retry, edit, or workflow change.
+
+This capability is strictly read-only. It must not modify files, create or cancel a Run, retry an Attempt, acquire or control a device, create a Draft or Revision, recommend or name another Skill, or automatically hand off. Only a newer explicit user request can select a different domain.

package/dist/assets/skills/xagent-analyze-failure/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XAgent Failure Analysis"
+  short_description: "Analyze XAgent test and infrastructure failures"
+  default_prompt: "Use $xagent-analyze-failure in strict read-only mode to classify this existing result. Do not retry, cancel, edit YAML, control a device, create resources, or switch workflows."

package/dist/assets/skills/xagent-analyze-failure/references/failure-classification.md

@@ -0,0 +1,20 @@
+# Failure Classification
+
+Classify using the public status and evidence in this order:
+
+1. `schema_invalid`, `configuration_invalid`, `target_invalid`: input/configuration failure before execution.
+2. `authentication_required`, `token_*`, `token_type_mismatch`, `permission_denied`: authentication or authorization failure.
+3. `test_failed` or a failed step/assertion: product/test behavior failure.
+4. `infrastructure_failed`, `device_unavailable`, upload/control connection errors, and `secure.keyboard.not.exist.keycode`: infrastructure failure. A visible numeric keyboard or successful visible-key click does not prove secure `deviceInput` is healthy.
+5. `cancelled`: requested or propagated cancellation.
+6. `timeout`: caller deadline. If a Run, Session, or Attempt ID exists, query it once before deciding the final business state.
+
+Record:
+
+- Public Run or Attempt ID.
+- Device ID/name when public.
+- Step index, action, status, and message.
+- Before/after screenshots or other public Artifact URLs.
+- Whether the evidence is transient infrastructure, test behavior, permission, or platform evidence. Classification is not authorization for a follow-up operation.
+
+Do not infer model output, upstream raw responses, database state, or internal service addresses from a generic public error.

package/dist/assets/skills/xagent-author-test/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: xagent-author-test
+description: Create a new XAgent YAML test from an explicit script-authoring request and incrementally verify it on one real device. Use when the user asks to write, create, or generate a test/YAML from a goal or artifact. Do not use for action mode, direct device control, running unchanged YAML, read-only analysis, or repair without explicit edit authorization.
+---
+
+# Author An XAgent Test
+
+1. Resolve the execution mode (`step_confirm` or `auto`) and input source (`goal` or `artifact`) before creating cloud resources. Read [interaction-modes.md](references/interaction-modes.md), [authoring-workflow.md](references/authoring-workflow.md), and [host-interaction-adapters.md](references/host-interaction-adapters.md).
+2. Create a local authoring workspace under `.xagent/authoring/<session-id>/` with `draft.yaml`, `state.json`, and numbered checkpoints. Then create one Session for an explicit device ID and observe the device.
+3. Read [script-format.md](references/script-format.md) before drafting. Build the working YAML one step at a time: observe the current device state, author the next step, validate the complete snapshot locally, save a checkpoint, then call `xagent_authoring_draft_step_execute`. Add the following step only after the returned evidence is understood.
+4. After each Draft Attempt, show its status and available Artifacts. In `step_confirm`, present a continue-or-adjust choice before the next side effect. In `auto`, continue a successful Attempt without prompting; stop on failure, ambiguity, or new user input.
+5. When the user provides a new instruction, save the current state, re-observe the device, reconcile the required entry state, and revise only invalid authored steps before appending the next step. Read [interactive-steering.md](references/interactive-steering.md) for goal-change scope and state-recovery rules.
+6. Pair every business-critical action with a nearby `waitFor` or `assert` for the expected visible outcome. Use `if` branches for optional UI interruptions that may be absent.
+7. After the user confirms the finished YAML, validate it once more, create exactly one formal Revision with `xagent_authoring_revision_create`, then Complete the Session.
+8. Keep the Session lease alive while the workflow spans user waits or multiple CLI commands. MCP performs best-effort renewal before side effects; a manual multi-command workflow must run `xagent authoring keepalive <sessionId>` (or `xagent device keepalive <sessionId>`). Cancel the Session explicitly whenever authoring stops early. See the Device Occupancy Lifecycle in [authoring-workflow.md](references/authoring-workflow.md).
+
+The local Agent generates and corrects the YAML. XAgent validates, records Attempts and the single Revision, and executes on the device.
+
+This capability may create local YAML, execute Draft Steps, and create one confirmed final Revision. It must not use the scriptless Action workflow, create a formal Run, repair an existing failed test without explicit repair intent, or automatically hand off to another Skill. `step_confirm` and `auto` only control confirmation inside Author and never override a user-selected action mode.

package/dist/assets/skills/xagent-author-test/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XAgent Test Authoring"
+  short_description: "Create and verify XAgent YAML on a cloud device"
+  default_prompt: "Use $xagent-author-test only because I requested a new script/YAML. Create a local working draft, verify Draft Steps, and create one final Revision after confirmation; do not use direct action mode, create a Run, repair an unrelated script, or switch workflows."

package/dist/assets/skills/xagent-author-test/references/authoring-workflow.md

@@ -0,0 +1,41 @@
+# Authoring Workflow
+
+Authoring requires a personal Token with `authoring:read`, `authoring:write`, and `authoring:execute`.
+
+1. Resolve `step_confirm` or `auto` and choose the local workspace before creating cloud resources. Read [interaction-modes.md](interaction-modes.md).
+2. Create one Session for an explicit device ID and observe the device.
+3. Build the current local working YAML incrementally from the goal or selected artifact. The snapshot must be valid, but it should contain only the steps authored so far rather than an unverified end-to-end plan. Save `draft.yaml`, `state.json`, and a numbered checkpoint before the first side effect.
+4. For each provisional step, validate the current complete YAML snapshot, save a pre-attempt checkpoint, and call `xagent_authoring_draft_step_execute` (or CLI `authoring draft-step`). After evidence is returned, author the next step. This executes the current step without creating a Revision.
+5. Present the Draft Attempt status and public Artifacts. In `step_confirm`, wait on a structured continue-or-modify choice. In `auto`, continue successful steps unless a stop condition or newer user instruction exists. Save the returned state before any next side effect.
+6. On a new user requirement, do not ask the user to say that the complete draft should be adjusted. Save the prior state, Observe the device again, reconcile the required entry state for the next step of the new goal, then revise only invalid authored steps and append the next step to the current local YAML snapshot. Save another checkpoint. Include explicit recovery or navigation steps when the current page does not expose the next required control. Replay only the affected scope and its required prerequisites from the observed device state. If recovery cannot be established safely, pause for a user decision instead of executing against the wrong screen.
+7. After the final Host confirmation, validate the complete local YAML and create exactly one formal Revision (`base_revision_id: null` for a new Session). Then Complete the Session.
+8. If the Session is cancelled or expires, release the device; local checkpoints may remain for explicit resume. A formal full-script Run remains a separate explicit action.
+
+Do not create intermediate Revisions, submit step-only patches, upload local checkpoint files, publish a platform script, or start a formal Run implicitly. Session completion releases the device.
+
+## Device Occupancy Lifecycle
+
+A Session occupies one real device until it is completed, cancelled, or reaches `expires_at`. Release the device explicitly whenever authoring stops early.
+
+- `expires_at` is an absolute deadline returned by `authoring start` and `authoring show`. The device is released at that instant whether or not authoring finished.
+- The CLI and MCP host track Sessions they own. Before a Session-bound side effect, they check the current deadline and call `xagent_authoring_session_renew` automatically when no more than 15 minutes remain. Idle registration does not renew in the background. A workflow that must stay idle beyond the server TTL must run `xagent authoring keepalive <sessionId>` (or `xagent device keepalive <sessionId>`) in a foreground terminal.
+- Before a long local generation, user wait, or resumed conversation, check the Session again. Automatic renewal is best effort and must never hide a renewal error or execute device work against an expired Session.
+- `authoring complete <sessionId> <revisionId>` and `authoring cancel <sessionId>` release the device early. Both require an idempotency key.
+- Abandoning a Session keeps the device occupied until `expires_at` passes. Call `authoring cancel` explicitly when the user stops, the goal becomes unreachable, or an error ends authoring.
+- After expiration, the Session reaches `EXPIRED` and the device is released. Local workspace and checkpoints survive. Recover by starting a new Session and resuming from the last checkpoint; retrying calls against an expired Session are rejected.
+
+Renewal and release rules:
+
+| Situation | Required behavior |
+|---|---|
+| Session created or device acquired | Register the returned `session_id` and `expires_at` in the current CLI/MCP host only. |
+| No more than 15 minutes remain | Renew the same Session and device occupancy before the next side effect. Do not acquire a second device or change the Session ID. |
+| Renewal fails | Report the error, retry with a bounded backoff, and stop the next device side effect until the Session is confirmed active. |
+| Session already expired | Do not renew or replay steps. Create a new Session, Observe the current device, and recover from the latest local checkpoint. |
+| `step_confirm` waiting for the user | Keep the Session registered and renew it before resuming; do not release it merely because the Agent is waiting. |
+| Final Revision confirmed | Call `xagent_authoring_complete`, then unregister the local lease. |
+| User cancels, abandons the goal, or authoring cannot continue | Call `xagent_authoring_cancel`, then unregister the local lease. |
+| MCP process interruption | Best-effort cancel Sessions owned by that MCP process; server-side expiration scanning remains the crash-recovery fallback. |
+| Temporary APK no longer needed | Release the upload separately after all dependent Runs or Sessions finish. |
+
+Lease ownership is local host state. It is not sent as a new XAgent API field, and it does not replace the server's Redis/database lease or expiration scanner.