@testin-official/xagent 0.3.7

package/dist/assets/skills/xagent-author-test/references/host-interaction-adapters.md

@@ -0,0 +1,81 @@
+# Agent Host Interaction Adapters
+
+Choose interaction behavior from the Agent Host, active host mode, exposed interaction Tools, and whether the caller is interactive. Do not branch on the underlying model or provider name. The same model can run in different Hosts with different UI capabilities.
+
+This reference applies only inside an explicitly selected Author workflow. Changing Codex collaboration mode changes the available interaction UI; it does not change the locked XAgent capability domain or authorize a different Skill.
+
+## Resolution Order
+
+Resolve the adapter before creating an Authoring Session:
+
+1. Detect whether the caller is interactive. CI/CD and other non-interactive callers cannot prompt.
+2. Identify the Agent Host and its active collaboration or execution mode when that state is available.
+3. Inspect the interaction Tools the Host actually exposes and permits in that mode.
+4. Use a native structured choice only when it is callable now; otherwise use the text fallback.
+
+Do not send Host, model, mode, prompt, or interaction-capability metadata to XAgent. This is local Agent orchestration state.
+
+## Host Matrix
+
+| Environment | Preferred adapter | Required behavior |
+|---|---|---|
+| Codex Plan mode | `request_user_input` when exposed and permitted | Present native choices. Do not promise that Plan mode permits device side effects; inspect the active Tool policy before execution. |
+| Codex Default mode | Text fallback | Do not call `request_user_input` when the Host reports it unavailable in Default mode. Show the one-time Plan mode notice below. |
+| Claude Code | `AskUserQuestion` when exposed | Present native choices; use text fallback when the Tool is absent or denied. |
+| CodeBuddy Code | `AskUserQuestion` or another documented native choice Tool when exposed | Detect the Tool at runtime; do not infer it from product branding. |
+| WorkBuddy | Any documented native structured-choice Tool when exposed | Probe capabilities at runtime; otherwise use text fallback. |
+| Other interactive MCP Hosts | Host-native choice Tool when exposed | Use text fallback when no such Tool is callable. |
+| CI/CD or another non-interactive caller | No prompt | Require `auto`; fail before creating a Session if an unresolved interactive choice remains. |
+
+## Codex Default Mode Notice
+
+When Codex is in Default mode and structured input is unavailable, show this notice once per Authoring request, localized to the user's language:
+
+```text
+Codex Default mode can execute XAgent Tools but does not currently expose structured choices.
+
+- Continue here with text confirmation: reply "Continue" or "Adjust test requirements: ...".
+- To test structured choices, use the Codex mode selector to switch to Plan mode and resend the Authoring request.
+
+Plan mode Tool permissions are controlled by Codex. Do not assume it can execute device side effects until the active Host confirms those Tools are permitted.
+```
+
+Do not repeat this notice after every Draft Attempt. In `step_confirm`, use the concise text choices after the first notice:
+
+```text
+Continue
+Adjust test requirements: <replacement>
+```
+
+If a user selects the interaction mode in Plan mode and then execution requires Default mode, keep the choice only in the current Agent conversation and explain the mode transition. Do not upload or persist it in XAgent.
+
+When a Host pauses for user input, the active Authoring Session remains owned by that Host. MCP hosts renew the lease before the next side effect. Hosts using separate CLI commands must run `xagent authoring keepalive <sessionId>` in another foreground terminal; a single short-lived CLI invocation cannot maintain a timer after it exits.
+
+## Structured Choices
+
+For initial mode selection, present:
+
+- Confirm each step
+- Execute automatically
+
+After the execution mode is selected, present the authoring entry when it was not already explicit:
+
+- Create from my test objective
+- Optimize an existing test or case
+
+Within the locked Author domain, an explicitly selected YAML, TXT, Markdown, spreadsheet, or existing case resolves to the second entry without a redundant prompt. A natural-language test-authoring request resolves to the first entry unless the user chooses otherwise.
+
+For `step_confirm` after a Draft Attempt, present:
+
+- Confirm and continue
+- Adjust test requirements
+
+A failed, ambiguous, unauthorized, or infrastructure-failed Draft Attempt must not recommend blind continuation. Offer adjustment of the test requirements or Session cancellation. The Agent should infer whether the adjustment changes the overall goal or only a local step from the user's natural-language input and current evidence; update the local complete YAML and checkpoint it before retrying.
+
+## Acceptance Status
+
+Record Host-specific behavior separately. Passing the XAgent MCP lifecycle does not prove that a Host renders structured controls.
+
+- Verify Codex Default text fallback and one-time notice.
+- Verify Codex Plan structured choice separately from device-side-effect permission.
+- Verify Claude Code, CodeBuddy Code, and WorkBuddy with their real installed Host versions before declaring those adapters supported.

package/dist/assets/skills/xagent-author-test/references/interaction-modes.md

@@ -0,0 +1,97 @@
+# Authoring Interaction Modes
+
+Interaction mode is Agent Host orchestration state. It is not an XAgent API field, is not stored in an Authoring Session, and must not be sent with Revision or Attempt requests.
+
+Apply this reference only after the user has explicitly selected the Author capability. A natural-language device-control request does not become Author merely because it can be represented as steps. `step_confirm` and `auto` never replace the locked XAgent capability domain.
+
+## Mode Resolution
+
+Resolve the execution mode before creating a Session:
+
+1. The user's latest explicit instruction for this request.
+2. A Host-local preference that the user explicitly chose to save.
+3. A first-use structured choice presented by the Agent Host.
+
+The supported values are:
+
+- `step_confirm`: show evidence after each Draft Attempt and require an explicit choice before the next side effect. Recommend this mode on first use.
+- `auto`: continue successful Draft Attempts automatically while still accepting active-turn steering.
+
+The input source is separate from execution mode:
+
+- `goal`: a new test from the user's overall objective.
+- `artifact`: a user-selected YAML, TXT, Markdown, spreadsheet, or existing case.
+
+Both sources converge on the same local working-draft workflow. `draft_first` and `state_guided_local` are historical design names; do not present, store, or send them.
+
+If the source is genuinely ambiguous, present one optional source choice:
+
+- Create from my test objective
+- Optimize an existing test or case
+
+Within the already selected Author domain, resolve `goal` when the user described a desired test behavior. Resolve `artifact` when the user selected a file or existing case, without asking a redundant question. Neither choice is sent to XAgent.
+
+## Local Working Draft
+
+The Agent Host owns a durable local workspace selected by the user:
+
+```text
+.xagent/authoring/<session-id>/
+  draft.yaml
+  state.json
+  checkpoints/000001.yaml
+  checkpoints/000002.yaml
+```
+
+Save the current complete YAML snapshot after every edit and after every Attempt. The snapshot is complete for the steps authored so far; it is not a requirement to prewrite the entire future test. Append the next step only after the current device evidence is understood. `state.json` records the next step index, latest Attempt ID/status, execution mode, and semantic script hash. The local checkpoint Tools do not upload this content or scan any other workspace path.
+
+The Agent may execute a provisional step only with the complete current working YAML snapshot through `xagent_authoring_draft_step_execute`. This operation validates and executes the next authored step, records public Attempt evidence and the script hash, and does not create or update a Revision. A final `xagent_authoring_revision_create` is sent once, after the user confirms the finished YAML.
+
+## Goal Entry Behavior
+
+When `goal` is selected and the current user message is coherent, use it directly. Do not ask for a second detailed goal or require a generated YAML review before the first draft step. Generate only the next safe working step locally, save the current snapshot, and use the device observation and Draft Attempt evidence to author subsequent steps.
+
+When `artifact` is selected, copy the selected intent into the same local working-draft directory. Do not create an intermediate Revision merely because the source was an existing file.
+
+## Host Interaction
+
+Use the Host's native structured input only when it is callable now:
+
+- Codex Plan mode: `request_user_input` when exposed and permitted.
+- Codex Default mode: concise text fallback; show the one-time Plan mode notice.
+- Claude Code and CodeBuddy Code: `AskUserQuestion` when exposed.
+- WorkBuddy and other Hosts: a documented native choice when exposed; otherwise text fallback.
+
+Do not branch on model branding. A Host must actually expose and permit the interaction Tool.
+
+Present the execution choices:
+
+- Confirm each step
+- Execute automatically
+
+Save a default only when the user explicitly asks to remember it, and keep it in Host-local state.
+
+## Step-Confirm Mode
+
+After every Draft Attempt:
+
+1. Show status, error details, and available screenshots or Artifacts.
+2. Save the returned local checkpoint before any next side effect.
+3. Present `Confirm and continue` and `Adjust test requirements`.
+4. On adjustment, collect free-form replacement requirements. Treat them as an overall goal change by default; restrict them to one step only when the user explicitly names a step or says the change is local. Observe the device, reconcile the next required entry state, revise only invalid authored steps, and append the next safe step to the current YAML snapshot. Do not rewrite unverified future steps, and do not create a Revision yet. The user does not need to classify the scope or say that the complete draft should be adjusted.
+
+A failed or ambiguous Attempt must not recommend blind continuation. Allow adjustment or Session cancellation.
+
+## Automatic Mode
+
+An action status is not by itself proof of business success; inspect the returned evidence and visible postcondition.
+
+After every successful Draft Attempt, retain its evidence, save the local checkpoint, and continue to the next required step without asking for confirmation. Reconcile newer user input before the next side effect.
+
+Automatic execution stops on a failed or ambiguous Attempt, authentication/permission/resource/infrastructure error, a materially ambiguous choice, new user input, or final completion.
+
+Before `Complete`, use a structured choice to confirm the final local YAML or adjust its requirements. Only after confirmation create the single formal Revision. A formal full-script Run remains a separate explicit user action.
+
+## Session Lease During Interaction
+
+The execution mode does not change resource ownership. The MCP adapter renews a registered Session before the next Session-bound device operation when no more than 15 minutes remain; registration alone does not renew during idle waiting. If a structured choice or long user turn may exceed the server TTL, run a separate foreground `xagent authoring keepalive <sessionId>` process. Before resuming after a failed renewal or an expired Session, create a new Session and Observe the device. Never send `step_confirm`, `auto`, or Host interaction state to the XAgent API.

package/dist/assets/skills/xagent-author-test/references/interactive-steering.md

@@ -0,0 +1,57 @@
+# Interactive Steering And Verification Scope
+
+The newest explicit user instruction is authoritative during interactive Authoring. Keep user prompts, local working YAML, checkpoints, and Agent conversation state in the Agent Host; send XAgent only the complete script and explicit Tool arguments required by the selected action.
+
+## Instruction Scope
+
+- Treat a new behavior, target, sequence, or acceptance requirement as an overall goal change by default. Do not pre-generate or rewrite all future steps. Revise only already-authored steps that are made invalid and author the next safe step from observed evidence.
+- Treat a change as step-local only when the user explicitly names a step, action, or says the change is local.
+- Do not ask the user to identify affected steps when the Agent can infer them from the goal, the working YAML, and the evidence.
+- The scope of re-execution is separate from wording scope. Compute it from prerequisites, navigation state, variables, and device state.
+
+## Working-Draft Meaning
+
+The API requires each Draft Step request to contain a valid complete YAML snapshot. This is a transport requirement, not an instruction to write the whole test in advance. The local working draft contains only the steps known and authored so far; future steps are added after the device state and the previous Attempt evidence are available. A changed goal updates this evolving draft incrementally.
+
+## Device State Reconciliation
+
+An updated goal changes both the intended YAML and the device state that must be reached before the next business action. A rewritten script is not a state reset. Before submitting the next Draft Attempt:
+
+1. Save the previous local state and checkpoint.
+2. Observe the device and record the visible page, app, playback state, dialogs, and available controls.
+3. Determine the required entry state for the next step of the updated goal. For example, a search action requires a visible search entry point; a playback assertion requires the requested title to be visibly selected and playing.
+4. If the entry state is missing, author one explicit recovery or navigation step from observable controls, and verify the recovered state with a nearby `waitFor` or `assert` before authoring the next business step.
+5. Never treat `appLaunch` alone as proof that the app returned to its home page. If the current screen has no required control, do not execute the next business step just because the YAML was regenerated.
+6. If no safe recovery path can be established from the current evidence, stop the flow and ask the user whether to cancel/restart or provide a recovery instruction. Do not silently reset app data or invent unsupported actions.
+
+An app-launch failure is a launch or installation precondition failure. Do not replace it with a launcher-icon assertion: an icon only proves that a launcher surface may contain a shortcut, not that the target package started. If the package is missing and the current script has an install capability, author the install step first; otherwise stop with the package/install prerequisite clearly reported.
+
+## Correction Timing
+
+1. Before a Draft Step is submitted, discard any unsent local draft that conflicts with newer input, save the previous state, Observe the device, reconcile the required entry state, revise the current snapshot only as needed, append the next step, and save a checkpoint. Do not require the user to classify the change or to request continuation explicitly.
+2. If input arrives while a Draft Attempt is running, let the Tool return, save its evidence and local state, and stop before the next side effect.
+3. After every Draft Attempt, present public status and available screenshots or Artifacts. In `step_confirm`, use the Host's continue-or-adjust choice before another side effect. In `auto`, continue only when the Attempt succeeded and no newer input or stop condition exists.
+4. Before the final Revision is created, reconcile the complete local YAML with the latest user instruction and require confirmation.
+
+## Revision Scope And Verification Scope
+
+During interactive drafting, a correction updates the complete local YAML and creates a numbered local checkpoint. It is never stored as a one-step patch or an intermediate Revision. The single formal Revision is created only after final confirmation.
+
+Validation and execution use narrower scopes where safe:
+
+- Validate the current complete YAML snapshot locally before every Draft Step and the final Revision submission.
+- Re-execute only the affected step when the change is isolated and the device is still in that step's valid prerequisite state.
+- Replay required prerequisites when navigation, input, branching, variables, package state, or another dependency changed.
+- Start from a known clean state when prerequisites cannot be established reliably.
+
+## Business Postconditions
+
+A side-effecting action is not a business success by itself. A click, input, or launch Attempt may be `PASSED` while the device is in the wrong screen or has selected the wrong item. For every business-critical selection or transition:
+
+- express the intended result as a nearby `waitFor` or `assert`;
+- verify the selected title, page, state, or other user-visible outcome before continuing;
+- if the postcondition fails, use the evidence to repair the action and its dependent flow, then update the local complete YAML.
+
+## Agent Host Enforcement
+
+Use the Agent Host's active-turn steering when available. A Skill defines the portable workflow but is not itself a lifecycle Hook and cannot create UI controls that the Host does not expose. Hooks must remain host-specific, must not upload raw prompts, and must not change XAgent API semantics.

package/dist/assets/skills/xagent-author-test/references/script-actions.md

@@ -0,0 +1,34 @@
+# Authoring Script Actions
+
+These are the actions available when writing XAgent YAML. All fields are case-sensitive. `description` is optional on every action. Targets are semantic descriptions resolved against the current Session screen.
+
+| Action | Required fields | Optional fields |
+|---|---|---|
+| `click` | `target` | `type`, `duration` |
+| `input` | `text` | `target`, `clearFirst`, `inputMode`, `keyboardLayout` |
+| `scroll` | `direction` | `distance`, `target`, `condition`, `maxSwipes`, scope and container fields |
+| `scroll_between` | `from`, `to` | `duration` |
+| `drag` | `from`, `to` | `speed` |
+| `press_key` | `key` | - |
+| `press_home` | - | - |
+| `press_back` | - | - |
+| `press_enter` | - | - |
+| `screenshot` | - | `var` |
+| `extract` | `target`, `varName` | `type` |
+| `waitFor` | `time` or `condition` | `timeout` |
+| `assert` | `condition` or `target` | `conditionType`, `text`, `message` |
+| `set` | `varName`, `value` | - |
+| `randomVar` | `varName`, `type` | `length`, `min`, `max` |
+| `if` | `condition`, non-empty `then` | non-empty `else` |
+| `for` | non-empty `steps`, exactly one of `count` or `condition` | `dead_loop` |
+| `break` | - | - |
+| `throw` | `message` | - |
+| `install` | `appPackage`; execution also needs `packageId` | - |
+| `appLaunch` | at least one of `appPackage` or `appName` | `launchPath` |
+| `appStop` | at least one of `appPackage` or `appName` | - |
+| `appClean` | at least one of `appPackage` or `appName` | - |
+| `uninstall` | at least one of `appPackage` or `appName` | - |
+
+`click.type` is `click`, `tap`, `longPress`, `doubleClick`, or `rightClick`. `click.duration` is accepted only with `longPress` so existing platform scripts round-trip, but current Exec does not transmit the requested duration to the device controller; do not promise an exact hold time. `assert.conditionType` is `textVisible` or `expr`. `scroll.direction` is up/down/left/right and `distance` is greater than 0 and at most 1. `press_key` accepts one key only. `break` is valid only inside `for.steps`, including an `if` nested under that loop. Application actions use the authoritative package identity; never put a download URL in YAML.
+
+An application action can carry both identifiers when available, but it must provide at least one. When `appPackage` is present with a selected package, it must match that package. Validate every complete working snapshot. Do not invent action names, fields, or fallback behavior.

package/dist/assets/skills/xagent-author-test/references/script-format.md

@@ -0,0 +1,100 @@
+# XAgent Script Format
+
+Every script uses `schema_version: xagent-script/v1` and contains one or more steps.
+
+Files exported by the compat platform use the shared `xagent-compat-script/v1` schema instead. The CLI accepts those files for `validate`, `run`, and Authoring commands: it compiles the platform editor fields to the Public Script execution contract while leaving the source YAML unchanged. In a compat file, `userText`, `desc`, `stepIdFront`, `actionLocked`, `descVisible`, and `isEdit` are platform source fields and must be preserved when the file is edited or re-exported. Do not copy those editor fields into a new `xagent-script/v1` file unless the user explicitly asks for a platform export.
+
+```yaml
+schema_version: xagent-compat-script/v1
+name: Platform login smoke
+package_id: 7183
+steps:
+  - action: click
+    frontStepType: step
+    target: 登录
+    type: text
+    userText: 点击登录
+    desc: 登录入口
+  - action: input
+    frontStepType: step
+    target: 用户名
+    text: "${username}"
+    userText: 输入用户名
+    desc: 用户名输入
+```
+
+The compat format uses the platform action set (`click`, `input`, `scroll`, `install`, `uninstall`, `appLaunch`, `appStop`, `appClean`, `waitFor`, `assert`, `screenshot`, `set`, `press_back`, and `press_home`). `xagent-script/v1` remains the CLI's compact execution format and may contain additional CLI-only flow actions.
+
+```yaml
+schema_version: xagent-script/v1
+name: Login smoke
+package_id: 7183
+variables:
+  username: demo
+steps:
+  - action: install
+    appPackage: cn.example.app
+  - action: appLaunch
+    appPackage: cn.example.app
+  - action: click
+    target: 登录
+  - action: input
+    target: 用户名
+    text: "${username}"
+    clearFirst: true
+  - action: waitFor
+    condition: 首页可见
+    timeout: 10000
+  - action: assert
+    target: 首页
+    message: 应进入首页
+```
+
+Optional UI interruptions use an `if` branch. The branch is skipped when its condition is not met, so a missing dialog does not fail the rest of the test:
+
+```yaml
+  - action: if
+    condition: 页面显示用户协议或隐私政策弹窗，并且存在同意按钮
+    then:
+      - action: click
+        target: 当前弹窗中的同意按钮
+```
+
+Use this pattern for first-launch agreements, notifications, permissions, update prompts, login prompts, and similar device-dependent UI. Do not issue an unconditional click for a dialog that may be absent. Keep each optional interruption in its own branch and continue with the main flow after the branch.
+
+## Keyboard-Aware Input
+
+Before authoring an input step, Observe the device and identify whether the focused field currently shows a keyboard and which layout is visible. Do not infer that a visible numeric layout proves that a secure-input adapter will work, and do not hard-code keyboard coordinates or literal key labels such as `123` or `ABC`.
+
+The Public Script accepts two input controls. The authoritative server compiler applies them identically for CLI Run, MCP Run, Draft Step, Revision Step, and scriptless Action:
+
+- `inputMode: secret` keeps the explicit secure-input call.
+- `inputMode: normal` requests ordinary input. The server removes it from canonical execution so Exec does not apply smart secure fallback.
+- `keyboardLayout: numeric` or `keyboardLayout: alphabetic` requests an evidence-driven layout check. The server compiles one logical input step into an atomic `if`: when the layout differs, switch and input in the same branch; otherwise input directly. It never submits fixed coordinates or literal `123`/`ABC` labels.
+
+Focus the field first. Put `keyboardLayout` and the input mode on the following focused `input` step without `target`. The contract rejects `target` together with `keyboardLayout` because a secure input target causes an additional focus click that can change keyboard state:
+
+```yaml
+  - action: click
+    target: 密码输入框
+  - action: input
+    text: "{{pin}}"
+    inputMode: secret
+    keyboardLayout: numeric
+```
+
+For an ordinary field, use `inputMode: normal` only when ordinary input is required explicitly. Omitted `inputMode` is also ordinary input in the XAgent Public Script; do not assume another producer's omitted mode means `smart`. Add `keyboardLayout` only when the required layout is known from the task or current device evidence. Keep secure values in variables and do not put their plaintext values in evidence, notes, or status messages.
+
+If a `secret` input reaches the device adapter with the requested layout but fails with a secure-keyboard keycode error, classify it as device-input infrastructure evidence. Preserve the Run or Attempt ID and screenshots; do not change the application scenario or retry the same secure call blindly.
+
+A successful `click`, `input`, or `appLaunch` Attempt only confirms that the device action completed. It does not prove that the intended business result occurred. After a business-critical action, add a nearby `waitFor` or `assert` for the expected visible result before continuing. For list selection, target the row or title whose text matches the requested item and verify the current title immediately after the click; do not treat any clickable row as a successful selection.
+
+`appLaunch` starts or brings the application to the foreground; it does not guarantee that the application has returned to its home page, cleared playback state, or restored a search control. When a new goal requires a specific entry point, first Observe the current device state and express the necessary navigation or recovery steps in the YAML. Verify the entry point before issuing the business action. Do not silently add app-data clearing, uninstall/reinstall, or unsupported reset actions.
+
+The valid postcondition for `appLaunch` is an observable page belonging to the target application, such as its home page or another explicitly required entry page. Do not assert that a launcher contains the app icon as the launch postcondition, and do not infer that an icon means the package is installed and runnable on the selected device.
+
+The Public Script action set is documented in [script-actions.md](script-actions.md). It includes verified interaction, observation, validation, variables, flow, and application controls. `break` is legal only inside `for.steps`. Use only actions and fields listed in that Author reference, and validate every draft; schema errors include paths and positions when available.
+
+Keep targets tied to the user's intent, not incidental observations from one device. If the user asks to play “大东北是我的家乡”, target a result whose title contains that requested title and do not add a version, artist, album, or VIP qualifier unless the user specified it. If several results exist, choose the first result satisfying the requested behavior and available playback, and describe that selection generically.
+
+The local Agent may derive steps from explicitly selected route code or requirements, but route names and implementation calls are not automatically valid UI targets. Express only behavior that can be observed or operated on the mobile device.

package/dist/assets/skills/xagent-cli/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: xagent-cli
+description: Configure XAgent, inspect Profiles, Tokens, apps, devices, or capabilities, validate existing YAML, and select one workflow when the user has not already selected a mode. Do not use this Skill to override an explicit action, author, run, analyze, or repair request, or to perform those domain workflows itself.
+---
+
+# Use XAgent
+
+1. Determine the Agent Host mode from [host-modes.md](references/host-modes.md). Use [cli-commands.md](references/cli-commands.md) for setup and read-only lookup with Shell access. MCP defaults to isolated `action`; every other domain, including report generation, requires its explicit `--mode`. A larger Tool surface is never a substitute for selecting one domain.
+2. Look up application identity when setup or the selected workflow needs it. If `package_id` is unknown, query the project application list. If `package_id` is known but `package_name` is not, query that exact package. Never guess `appPackage` or randomly select one of multiple matches.
+3. Look up devices when setup or the selected workflow needs one and no `device_id` was supplied. Apply server-side filters and return only an explicit match; this routing Skill does not acquire it.
+4. Apply [capability-routing.md](references/capability-routing.md) before selecting a workflow. The newest explicit user mode has highest priority and remains locked until the user explicitly changes it.
+5. Inspect the Principal only for setup, explicit capability inspection, or permission diagnosis. Protected operations authenticate and authorize themselves. Read [permissions.md](references/permissions.md).
+6. When no mode is explicit, recommend exactly one workflow using [failure-routing.md](references/failure-routing.md) and the table below. Do not perform the selected domain here. After handing off, do not load or enter a second workflow unless the user explicitly changes modes.
+
+## Workflow Routing
+
+| User request | Skill |
+|---|---|
+| Write a new test from a goal or artifact | `xagent-author-test` |
+| Fix an existing YAML after authorization | `xagent-repair-test` |
+| Run an existing YAML without editing | `xagent-run-test` |
+| Classify a failure without editing | `xagent-analyze-failure` |
+| Explore or diagnose one device step at a time | `xagent-explore-device` |
+| Write a report from already-collected test evidence | `xagent-test-report` |
+| Configure XAgent, inspect apps/devices, or choose an adapter | This Skill |
+
+Scriptless and scripted execution both submit Public Script actions to the authoritative server compiler and the same Exec engine. CLI and MCP are adapters over the same API semantics; neither performs hidden LLM formatting.
+
+This Skill is limited to setup, read-only lookup, validation, and one-time routing. It must not acquire a device Session, execute an action, create or edit YAML, submit a Draft Attempt or Revision, create a Run, or repair a failure.
+
+Never print or pass a Developer Token as a command-line argument. Store Personal credentials through the Profile credential store and Project CI credentials in the configured environment variable.

package/dist/assets/skills/xagent-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XAgent CLI"
+  short_description: "Configure XAgent and select one isolated workflow"
+  default_prompt: "Use $xagent-cli only for XAgent setup, lookup, validation, or one-time routing. Preserve my newest explicit action, author, run, analyze, or repair mode; never enter another workflow without my explicit request."

package/dist/assets/skills/xagent-cli/references/capability-routing.md

@@ -0,0 +1,36 @@
+# Capability Routing Contract
+
+XAgent workflows are separate capability domains. Loading one Skill grants no authority to enter another domain.
+
+## Precedence And Locking
+
+1. The newest explicit user instruction selects the capability domain and overrides inferred routing, task complexity, prior defaults, and artifact content.
+2. Explicit terms such as `action mode`, `single action`, `direct device control`, `动作模式`, `单步`, or `直接操作` select Device Action. `write/create/generate YAML`, `脚本`, or `编写 YAML` selects Author. `run this existing YAML without changes`, `运行现有脚本`, or `只运行` selects Run. `analyze only` or `只分析` selects Analyze. `repair/edit/fix this YAML`, `修复脚本`, or `修改 YAML` selects Repair. `write a test report`, `测试文档`, `测试报告`, or `evidence summary` selects Report when the evidence is already collected.
+3. After selection, lock the domain for the request. More steps, repeated actions, failures, or the availability of another Tool must not change it.
+4. A newer explicit user instruction may replace the lock. Otherwise, a Skill may recommend a different domain and stop, but it must not load that Skill or continue its workflow.
+5. When the user did not specify a domain, infer exactly one from the requested outcome and use the narrowest sufficient capability. Do not combine domains speculatively.
+
+`step_confirm` and `auto` are interaction policies inside Author. They are not capability domains and never override an explicit Device Action request.
+
+## Capability Boundaries
+
+| Domain | Allowed | Forbidden |
+|---|---|---|
+| CLI Setup | Profile and Token setup, capability inspection, app/device lookup, YAML validation, one-time workflow recommendation | Device acquire/action/release, YAML creation or editing, Draft Attempts, Revisions, Runs, failure repair |
+| Device Action | App resolution needed by the requested action, one device Session, observe, one structured action at a time, release | Creating or editing YAML, local authoring checkpoints, Draft Step execution, Revisions, Runs, automatic handoff |
+| Author | New local YAML working draft, Authoring Session, Draft Step verification, one final Revision after confirmation | Direct scriptless Action workflow, formal Run creation, repair of an existing failed test unless explicitly selected, automatic handoff |
+| Run | Validate and execute the exact existing YAML selected by the user; read, wait for, or explicitly cancel that Run | Creating or editing YAML, direct device Actions, Draft Attempts, Revisions, automatic retry, automatic handoff |
+| Analyze | Read Run/Attempt status and evidence, classify, report, recommend | Any device or application side effect, YAML write, retry, Run creation/cancellation, Draft Attempt, Revision, automatic handoff |
+| Repair | User-authorized edit of an existing YAML, local candidate, affected-step Draft verification, one confirmed successor Revision | Repairing infrastructure/auth/device errors as YAML, unrelated behavior changes, direct scriptless Actions, formal Run creation, automatic handoff |
+| Report | Structure and write a report from existing evidence, select key images, classify results, record cleanup | Device control, new Observe calls, retries, YAML changes, Runs, Revisions, inventing evidence, automatic handoff |
+
+Cleanup belongs to the active domain: Device Action releases its acquired Session and temporary upload; Author or Repair closes its Authoring Session as requested; Run may release only uploads it owns after dependent Runs terminate. Cleanup does not authorize another domain.
+
+## Handoff Protocol
+
+When the requested next operation is forbidden in the locked domain:
+
+1. Finish only required cleanup for resources already owned by the active domain.
+2. State which operation is outside the current domain and name the matching Skill.
+3. Stop before loading that Skill or causing its side effects.
+4. Continue only after the user explicitly requests the new domain.

package/dist/assets/skills/xagent-cli/references/cli-commands.md

@@ -0,0 +1,23 @@
+# CLI Command Reference
+
+Use `--json` for Agent and CI integrations. Global Profile/configuration options appear before the command name.
+
+## Application Catalog
+
+When `package_id` is unknown:
+
+    xagent --json apps list --keyword <text> --page 1 --page-size 20
+    xagent --json apps list --app-name <name>
+    xagent --json apps list --package-name <package-name>
+
+When `package_id` is known:
+
+    xagent --json apps show <package-id>
+
+Use returned `package_id` with returned `package_name`. Continue automatically only when one result unambiguously matches; otherwise narrow the query or obtain an explicit selection.
+
+## Device Discovery
+
+    xagent --json device list --platform Android --model <model> --available
+
+When `device_id` is unknown, list first and return one unambiguous match. This setup reference does not authorize acquiring or controlling it. Domain-specific commands are documented only in their matching Skill.

package/dist/assets/skills/xagent-cli/references/failure-routing.md

@@ -0,0 +1,18 @@
+# Failure Workflow Routing
+
+If the user explicitly selected a capability domain, keep that domain locked after a failure. Report the failure within the active Skill's boundary; do not automatically load an analysis or repair Skill.
+
+When the user asks what failed without selecting a workflow, recommend `xagent-analyze-failure`. That Skill is read-only and must not retry, cancel, edit, or execute anything.
+
+When the user asks for a test report after an Action, Authoring, or Run workflow, use `xagent-test-report` only after the active workflow has completed its required cleanup. Report mode consumes the evidence already collected; it does not call Observe or rerun the test.
+
+Use `xagent-repair-test` only when all of the following are true:
+
+- The user explicitly authorizes changing the YAML or creating a new Revision.
+- The failure is test behavior or the user corrected expected behavior.
+- A personal Token has the required Authoring capabilities.
+- One explicit device is available for verification.
+
+Do not route authentication, permission, infrastructure, timeout, or device availability failures into YAML repair.
+
+A recommendation is not authorization to hand off. Stop and wait for an explicit user request before loading or executing another Skill.

package/dist/assets/skills/xagent-cli/references/host-modes.md

@@ -0,0 +1,21 @@
+# Agent Host Modes
+
+Choose exactly one path for the current environment.
+
+| Environment | Use | Credential source |
+|---|---|---|
+| Shell is available | Invoke `xagent` commands directly | Selected Profile |
+| Shell is unavailable, setup or routing is needed | Start `xagent --profile <name> mcp --mode setup` | Selected Profile when cloud lookup is needed |
+| Shell is unavailable, a workflow is explicitly selected | Start `xagent --profile <name> mcp --mode <domain>` with `action`, `author`, `run`, `analyze`, `repair`, or `report` | Selected Profile only for cloud lookup; report is local-only |
+| Local process startup is unavailable | A remote Streamable HTTP MCP is required | Not available in the current release |
+| GitLab or another non-interactive CI runner | Install the Linux CLI package and invoke commands | Explicit project CI Token environment variable |
+
+The stdio Host must launch the executable directly. It must not use a Shell wrapper. Local files remain the Agent Host's responsibility: read an explicitly selected file and send its content to MCP Tools.
+
+Each MCP process exposes one capability domain. Changing domains requires restarting MCP with the new explicit mode after the user requests that change. There is no combined or full mode. A report mode consumes evidence already held by the Agent and does not recover evidence from a device.
+
+The default `xagent-local` MCP is `action` and remains a long-lived stateful device-control process. Direct CLI commands are one-shot calls and must receive the current session, screen and idempotency values explicitly. Do not mix the two invocation styles.
+
+Before selecting a side-effect domain, present the available behavior choices and identify `action` as the default. The CLI command is `xagent integrations options`; the local `xagent_workflow_options` Tool provides the same list without a Profile or side effect. The user must explicitly select a non-default domain.
+
+Do not claim remote MCP support until a public remote endpoint has been delivered and verified.

package/dist/assets/skills/xagent-cli/references/mcp-tools.md

@@ -0,0 +1,26 @@
+# MCP Mode Reference
+
+Start the setup/router surface when the user has not selected a workflow:
+
+```text
+command: xagent
+arguments: --profile, <profile-name>, mcp, --mode, setup
+```
+
+After the user explicitly selects a workflow, restart MCP with exactly one matching mode:
+
+| User-selected domain | MCP mode | Packaged Skill |
+|---|---|
+| Setup, inspect, validate, or route | `setup` | `xagent-cli` |
+| Direct device actions | `action` | `xagent-explore-device` |
+| Create a new YAML test | `author` | `xagent-author-test` |
+| Run existing YAML unchanged | `run` | `xagent-run-test` |
+| Read-only failure analysis | `analyze` | `xagent-analyze-failure` |
+| Authorized YAML repair | `repair` | `xagent-repair-test` |
+| Write report from collected evidence | `report` | `xagent-test-report` |
+
+The selected mode exposes only its permitted Tool set and only allows its matching packaged Skill to be read or loaded. A cross-domain Tool call or Skill load is rejected even if the Agent attempts it. Do not start a second MCP mode until a newer explicit user instruction changes the locked domain.
+
+Use `xagent_workflow_options` before route selection when the user has not chosen a behavior. It returns the default (`action`) and all available domains without requiring a Profile or causing a side effect. Then call `xagent_workflow_route` with exactly one selected domain and restart MCP with the returned mode.
+
+The server can start without a Profile for offline Skill loading and YAML validation. Cloud tools authenticate only when called. Local APK upload reads only the explicit `apk_path` supplied to the upload tool.

package/dist/assets/skills/xagent-cli/references/permissions.md

@@ -0,0 +1,17 @@
+# Principal and Permissions
+
+A Skill describes a workflow; it never grants a capability. Protected operations authenticate and authorize themselves. Inspect the Principal only during setup or permission diagnosis.
+
+| Capability | Permitted operation |
+|---|---|
+| `principal:read` | Read Token type and project scope |
+| `script:validate` | Validate Public Script content |
+| `device:read` | Discover or preview devices |
+| `run:create`, `run:read`, `run:cancel` | Run-domain permissions |
+| `app:upload` | Application package lifecycle permission |
+| `authoring:read`, `authoring:write`, `authoring:execute` | Authoring-domain permissions |
+| `skill:read` | Read the effective cloud Skill catalog |
+
+The service derives `eid` and `project_id` from the authenticated Principal; clients cannot override scope. Capability presence explains whether a domain may be available, but it does not select that domain or authorize this setup Skill to perform its operations.
+
+Recognize Personal and Project CI Token types exactly as returned by the Principal. Domain-specific Token constraints and operation details belong only to the selected domain Skill. Treat `permission_denied` and `token_type_mismatch` as final authorization results; do not switch workflows or try another side-effecting Tool as a fallback.

package/dist/assets/skills/xagent-explore-device/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: xagent-explore-device
+description: Directly observe and control one Android device through XAgent Action MCP, one grounded action at a time. Use for action mode, exploratory interaction, app installation or launch, single-step testing, and direct device control. Do not use to create or edit YAML, verify Drafts, create Revisions or Runs, analyze existing results only, repair scripts, or write a test report.
+---
+
+# Explore An XAgent Device
+
+Run one explicit Action state machine. Read [single-action-protocol.md](references/single-action-protocol.md) before acting, [actions.md](references/actions.md) for executable action fields, and [tool-adapters.md](references/tool-adapters.md) for MCP and manual CLI usage.
+
+## Workflow
+
+1. Resolve only the resources required by the request. When an app or device ID is unknown, filter the corresponding list and continue only with one unambiguous match. Never select randomly.
+2. Acquire one device Session. Use the returned `observation`, MCP image, and `screen_id` as the initial state. Acquire already captures the first screen, so do not call Observe after a successful acquire.
+3. Ground one resolved action from the current image. Send exactly that action with the current `screen_id` and a fresh idempotency key. MCP forwards it to the direct device-control API; it does not invoke Exec or another model.
+4. Use the synchronous result and `after_observation` as one combined response. The service and MCP own schema, authentication, idempotency, stale-screen, transport, and image-format validation. The Agent does not repeat those checks.
+5. For a business-critical action, evaluate the requested visible postcondition once from the returned image. Treat `status: PASSED` only as device-command completion, then classify the business result as confirmed, failed, or inconclusive. For an intermediate navigation action, use the same returned image to ground the next action without a separate verification call.
+6. Call Observe only through the recovery rules in the protocol: returned image evidence is missing or unavailable, the visible state is genuinely ambiguous, or a stale `screen_id` requires a fresh screen. Use at most one recovery Observe for one action result and never Observe merely to duplicate readable `after_observation` evidence.
+7. Do not silently repeat an uncertain side effect. Stop or re-ground from fresh evidence as specified by the failure class. Release the Session when the Action work ends, and release a temporary app upload only after the Session no longer depends on it.
+
+## Boundary
+
+This is an action-only capability. It may resolve an app, upload an explicitly selected APK, acquire one Session, execute resolved device actions, perform evidence recovery, and release resources it owns. It must not create or edit YAML, save Authoring checkpoints, call Draft Step or Revision Tools, create a Run, generate a test report, or automatically hand off or enter another Skill.
+
+If the same explicit user request also requires a report, finish Action cleanup first. The Host may then switch to the separately isolated Report mode because that requested output is already authorized; Action mode itself must not load or execute the report workflow.
+
+Assertions, semantic-only targets, completion decisions, and takeover decisions remain Agent responsibilities and are never sent as device actions.

package/dist/assets/skills/xagent-explore-device/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XAgent Device Exploration"
+  short_description: "Control one XAgent device with equivalent single-step semantics"
+  default_prompt: "Use $xagent-explore-device in action-only mode to control the selected device one observed action at a time. Do not create or edit YAML, Drafts, Revisions, or Runs, and do not switch workflows unless I explicitly request it."

package/dist/assets/skills/xagent-explore-device/references/actions.md

@@ -0,0 +1,24 @@
+# Resolved Device Action Contract
+
+Every request contains one action. Coordinate strings use normalized `0..1` values and must be grounded in the current observation.
+
+| Action | Required fields | Optional fields |
+|---|---|---|
+| `click` | `bounds` | `target`, `label`, `detector`, `actionText` |
+| `long_press` | `bounds` | `target`, `label`, `detector`, `actionText` |
+| `left_double` | `bounds` | `target`, `label`, `detector`, `actionText` |
+| `type` | `content` | `x`, `y`, `is_secure_keyboard` |
+| `scroll` | `start` and exactly one of `end` or `direction` | `distance` |
+| `drag` | `start_point`, `end_point`, `start_bounds`, `end_bounds` | `target`, `label`, `detector`, `actionText` |
+| `press_home` | - | annotations |
+| `press_back` | - | annotations |
+| `press_enter` | - | annotations |
+| `press_key` | `key` | annotations |
+| `open_app` | exactly one of `app_name` or `package_name` | `launch_path` |
+| `install` | exactly one of `app_upload_id` or `package_id` | `launch`, `timeout`, `retry` |
+| `app_stop` | exactly one of `app_name` or `package_name` | - |
+| `app_clean` | exactly one of `app_name` or `package_name` | - |
+| `uninstall` | exactly one of `app_name` or `package_name` | - |
+| `wait` | - | `duration_ms` |
+
+The Agent handles `finished`, `take_over`, `interact`, assertions, semantic target location, and user confirmation. They are not executable service actions.