@testin-official/xagent 0.3.7

package/dist/assets/skills/xagent-explore-device/references/single-action-protocol.md

@@ -0,0 +1,59 @@
+# Single-Action Protocol
+
+## Responsibilities
+
+The Agent reads the current image, grounds one action, and decides whether visible business behavior meets the user's request. MCP validates its typed Tool input, maintains the Session lease, returns structured errors, and attaches the screenshot as an image content block. The service validates the resolved action, enforces the current `screen_id` and idempotency contract, executes the device command, and captures the post-action observation.
+
+No layer in this path invokes Exec, a GUI model, natural-language formatting, semantic target resolution, or fallback execution.
+
+## State Machine
+
+| Current state | Operation | Next state |
+| --- | --- | --- |
+| No Session | Acquire one explicit device | Active Session plus initial `observation` |
+| Readable observation | Submit one grounded action with its `screen_id` | Action result plus `after_observation` |
+| Readable `after_observation` | Ground the next action or finish | No Observe call |
+| Missing, unavailable, or genuinely ambiguous evidence | Observe once | Fresh observation and `screen_id` |
+| Stale `screen_id` rejected before execution | Observe once, then re-ground the intended action | Fresh observation; do not reuse old coordinates |
+| Session terminal or unrecoverable infrastructure failure | Stop | Release owned resources when possible |
+
+Acquire combines Session allocation and the initial observation. Calling Observe immediately afterward duplicates the screenshot round trip and is forbidden when the acquired image is readable.
+
+## Action Requests
+
+Execution accepts `{ screen_id, action }`. Use a fresh idempotency key for each intended side effect. Reuse a key only when retrying the identical request after an uncertain transport outcome; changed content with the same key is a conflict.
+
+Coordinates and bounds are normalized against the image associated with `screen_id`. Never use coordinates grounded from a platform console, another Session, or a manually changed device state.
+
+A text action is shaped like:
+
+```json
+{
+  "action": "type",
+  "content": "{{text}}"
+}
+```
+
+Secure keyboard interpretation, semantic target selection, and completion decisions remain in the Agent. Application lifecycle actions use the verified fields in [actions.md](actions.md); installation accepts a project-scoped `app_upload_id` or `package_id`, never an arbitrary download URL.
+
+## Result Evaluation
+
+Evaluate one action result in this order:
+
+1. Read `status`, `result.success`, and any structured error once. Do not revalidate the request schema or authentication in the Agent.
+2. Use the attached `after_observation` image as the authoritative next visible state when it is readable.
+3. For a business-critical action, compare that state with the postcondition derived before acting. Report confirmed only when the evidence proves it, failed when the evidence contradicts it, and inconclusive when it cannot decide.
+4. For intermediate navigation, do not create an extra assertion cycle. Use the returned state directly to ground the next action.
+
+`PASSED` proves only that the device command completed. It does not prove login, navigation, selection, input acceptance, or another business result.
+
+## Recovery Rules
+
+- `FAILED`: the device command reported failure. Use a readable `after_observation` to explain the state; do not Observe again unless the evidence itself is missing or ambiguous.
+- `INFRASTRUCTURE_FAILED` with `result.success: true`: the side effect may have completed but post-action capture or upload failed. Observe once to recover the current state; never resubmit the side effect first.
+- `INFRASTRUCTURE_FAILED` without command success: execution outcome is uncertain or failed. One Observe may establish the current state, but it does not authorize an automatic retry.
+- Stale `screen_id`: Observe once, discard old coordinates, and ground again from the fresh image.
+- Readable but ambiguous image: one Observe is permitted only when a fresh screen can reasonably resolve transient state. If it remains ambiguous, classify the result as inconclusive and stop.
+- Session expiration, allocation failure, unsupported action, or repeated evidence failure: stop without a fallback path.
+
+Do not query Principal before every operation. Protected endpoints perform their own authentication and authorization; use auth inspection only for setup or diagnosis.

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

@@ -0,0 +1,32 @@
+# Action MCP And Manual CLI Adapters
+
+MCP and CLI call the same direct Device Action API and share the same Session, `screen_id`, action, and idempotency semantics. Agent Hosts use MCP because it provides typed inputs, structured errors, native image content, and process-owned lease management. Shell CLI commands are for humans and explicit diagnostics, not an automatic Agent fallback.
+
+## Agent MCP Workflow
+
+Start the isolated surface with `xagent mcp --mode action`, then load `xagent-explore-device`.
+
+1. Resolve an existing app with `xagent_app_list` or `xagent_app_get`, or upload one explicit local APK with `xagent_app_upload_local`.
+2. Resolve a device with `xagent_device_list` when its ID is unknown.
+3. Call `xagent_device_acquire` once. Relay `console_url` to the user once and use the returned initial image and `screen_id`; do not immediately call `xagent_device_observe`.
+4. Call `xagent_device_action` with one grounded action. Use its `after_observation` image for both the business decision and the next action.
+5. Call `xagent_device_observe` only under the recovery rules in [single-action-protocol.md](single-action-protocol.md).
+6. End with `xagent_device_release`, then release any temporary app upload no longer in use.
+
+## Session Lifecycle
+
+The MCP Host registers the Session returned by acquire, renews it before expiry, and checks freshness before Observe or Action. Explicit `xagent_device_renew` keeps the same Session and console link. An idempotent acquire replay must not repeat the console link. On process interruption or close, the Host performs best-effort release of Sessions it owns.
+
+The observation console link is for human viewing. It does not replace MCP image evidence and is not a valid source for action coordinates unless the same screen is returned through the active Session observation contract.
+
+## Manual CLI
+
+```text
+xagent --json apps list --keyword <text>
+xagent --json apps show <package-id>
+xagent --json device acquire --device-id <device-id> --idempotency-key <key>
+xagent --json device action <session-id> --screen-id <screen-id> --request-json '{"action":"click","bounds":"0.431,0.815,0.566,0.872"}' --idempotency-key <key>
+xagent --json device observe <session-id>
+```
+
+Manual commands do not share the MCP Host's in-memory lease timer. Long workflows must keep the Session alive and release it explicitly. For parity diagnosis, compare the same Profile, Session, screen, action object, idempotency key, request envelope, and response envelope.

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

@@ -0,0 +1,16 @@
+---
+name: xagent-repair-test
+description: Modify an existing XAgent YAML only after the user explicitly requests or authorizes repair, then verify the justified changes and create one confirmed successor Revision. Do not use for analysis-only, action mode, new-script authoring, unchanged Runs, or infrastructure/auth/device failures.
+---
+
+# Repair An XAgent Test
+
+1. Require explicit user authorization before modifying the YAML or proposing a new Revision.
+2. Read the complete current YAML and user-selected failure evidence. Classify the failure; do not repair authentication, authorization, infrastructure, or device-availability errors by changing YAML. Read [repair-workflow.md](references/repair-workflow.md) for failure routing and keyboard-input troubleshooting.
+3. Change only behavior justified by the evidence or user correction. Save the complete candidate YAML in a local repair workspace and validate it.
+4. Use `xagent_authoring_draft_step_execute` to verify affected steps plus required prerequisites on the same Authoring Session device. Save the returned state and apply newer user guidance to the candidate before retrying.
+5. After confirmation, create exactly one successor Revision with `source: agent` and `base_revision_id` pointing to the current Revision. Then complete or leave the Session according to the explicit request.
+
+A personal Token with Authoring capabilities is required. Do not use a project CI Token for interactive repair, and do not overwrite repository YAML until the user accepts the candidate behavior.
+
+This capability may edit only the authorized YAML, verify affected Draft Steps, and create one confirmed successor Revision. It must not use direct scriptless Actions, create a formal Run, broaden the repair beyond evidence, or automatically hand off. If the evidence is not repairable in YAML, report that and stop in this domain.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XAgent Test Repair"
+  short_description: "Repair XAgent YAML with user-approved revisions"
+  default_prompt: "Use $xagent-repair-test only for the existing YAML repair I explicitly authorized. Limit edits to the evidence, verify affected Draft Steps, create one successor Revision after confirmation, and do not create a Run or switch workflows."

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

@@ -0,0 +1,21 @@
+# Repair Workflow
+
+Repair only after explicit user approval.
+
+1. Preserve the original YAML and current Revision.
+2. Identify the smallest behavior change supported by the failure evidence or user correction.
+3. Write a complete candidate YAML in the local repair workspace; do not create a patch-only Revision.
+4. Validate locally and resolve every schema issue.
+5. Save a numbered local checkpoint and execute affected zero-based steps through `xagent_authoring_draft_step_execute` on the same Authoring Session. Replay prerequisites first when the correction changed navigation, input, branching, variables, package state, or another dependency.
+6. Compare public Draft Attempt status and Artifacts with the intended behavior, and save the returned state locally.
+7. Yield for newer user input before another side effect. On confirmation, create exactly one successor Revision with `source: agent` and `base_revision_id` equal to the current Revision; otherwise update the local candidate or cancel.
+
+Do not repair infrastructure, authentication, authorization, or device availability errors by changing YAML. Do not use a project CI Token for Authoring. Do not overwrite a repository YAML until the user has accepted the candidate behavior. Do not create intermediate Revisions or upload local checkpoints.
+
+## Keyboard Input Troubleshooting
+
+For keyboard input failures, inspect the focused-field screenshot, the requested `inputMode`, the compiled keyboard-layout branch, and the cloud error before changing the scenario.
+
+If `secret` was preserved and the requested layout branch completed but the device returns a secure-keyboard keycode error, treat that as device-input infrastructure evidence rather than an application failure. Do not replace it with fixed key coordinates or literal key-label clicks.
+
+When the user requests ordinary input, use the CLI-local `inputMode: normal`; when a layout is required, use the CLI-local `keyboardLayout` field so the CLI emits an evidence-driven layout-switch branch. Submit the complete candidate as YAML `content` to MCP Tools so these local fields are compiled before the Developer API sees the script.

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

@@ -0,0 +1,16 @@
+---
+name: xagent-run-test
+description: Validate and execute the exact existing XAgent YAML selected by the user with a Personal device or Project CI Target. Use for local execution, CI, smoke tests, or an explicit rerun without edits. Do not use to create, modify, analyze, or repair YAML, or for direct device action mode.
+---
+
+# Run An Existing XAgent Test
+
+1. Read only the YAML explicitly named by the user or checked into the current CI repository.
+2. Validate YAML content before a network mutation. MCP Run creation receives the same YAML content; do not construct a separate raw script object. Stop on schema errors.
+3. Select the Token execution path from [execution-modes.md](references/execution-modes.md). Inspect the Principal only when setup or permission diagnosis requires it.
+4. Resolve the app. If `package_id` is unknown, list project apps and continue only on one unambiguous match. If `package_id` is known, get its authoritative package metadata rather than guessing a package name. A local APK may be uploaded explicitly by either Token type; Personal also supports one-shot `run --apk`.
+5. Resolve execution. Personal uses an explicit device ID. Project CI uses a configured Target and stable idempotency key.
+6. Wait only when the caller needs terminal status in the same process. Do not release a temporary upload until every dependent Run has terminated.
+7. Classify the result with [result-status.md](references/result-status.md) and report the outcome in this domain. When a requested follow-up is outside Run mode, state that boundary and stop without naming, loading, or entering another Skill.
+
+This capability must not create or edit YAML, execute direct device Actions or Draft Steps, create a Revision, automatically retry, or automatically hand off. Run cancellation requires an explicit user request. A schema error stops the Run; it does not authorize an edit.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XAgent Test Run"
+  short_description: "Run confirmed XAgent YAML locally or in CI"
+  default_prompt: "Use $xagent-run-test only to validate and run the exact existing YAML I selected. Do not edit it, create Drafts or Revisions, use direct device actions, retry automatically, or switch workflows."

package/dist/assets/skills/xagent-run-test/references/execution-modes.md

@@ -0,0 +1,23 @@
+# Execution Modes
+
+## Existing Project Application
+
+When `package_id` is unknown, use `apps list` or `xagent_app_list` with identifying filters. Continue automatically only for one unambiguous match. When `package_id` is already known, use `apps show` or `xagent_app_get` to resolve authoritative package name, version, and launch metadata.
+
+Personal Run uses an explicit device ID and `package_id`. Project CI Run uses a named Target, `package_id`, and stable idempotency key.
+
+## Local APK
+
+Both Token types can create a temporary upload:
+
+    xagent --json apps upload <app.apk>
+
+MCP uses `xagent_app_upload_local`. The response returns upload `id`, `package_id`, `app.package_name`, and `app.launch_path`.
+
+Personal Run passes upload `id` through `--app-upload-id` together with `--device-id`. The one-shot `run --apk` form uploads, binds, and releases automatically when the APK is needed only for that Run.
+
+Project CI Run passes upload `id` through `--app-upload-id` together with `--target` and a stable `--idempotency-key`.
+
+MCP Run creation supplies `app_upload_id` in the request and YAML content separately. Release with `apps release` or `xagent_app_release` only after all dependent Runs terminate. A released upload can no longer be treated as an installable package when it owns the platform package record.
+
+Without `--wait`, Run creation returns immediately. Use `runs wait` or `xagent_run_wait` before release when terminal completion must be observed.

package/dist/assets/skills/xagent-run-test/references/result-status.md

@@ -0,0 +1,13 @@
+# Run Result Status
+
+| Status or error | Meaning | Default action |
+|---|---|---|
+| `passed` | All reported test steps passed | Report success |
+| `failed` / `test_failed` | Test behavior or assertion failed | Report the evidence; do not auto-retry, edit, or switch modes |
+| `infrastructure_failed` | Platform, device, network, file, or execution infrastructure failed | Report infrastructure failure; do not retry or switch modes |
+| `cancelled` | Cancellation reached a terminal state | Report cancellation |
+| `timed_out` / `timeout` | The wait or operation exceeded its deadline | Query final state when an ID exists before concluding business failure |
+| `schema_invalid` | YAML or request does not match the public contract | Fix only with user authorization |
+| `permission_denied` / `token_type_mismatch` | Current Principal cannot perform the operation | Stop; do not seek a bypass |
+
+Use public messages and Artifacts. Never expose Tokens, internal device URLs, callback credentials, or local absolute paths in the report.

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

@@ -0,0 +1,20 @@
+---
+name: xagent-test-report
+description: Write a structured mobile test report from already-collected XAgent Action, Authoring, or Run evidence. Use when the user asks for a test report, test document, Markdown test record, or evidence summary. Do not acquire devices, execute actions, observe devices, rerun tests, or invent missing evidence.
+---
+
+# Write An XAgent Test Report
+
+This Skill consumes evidence; it does not produce new evidence. Use only the results, image blocks, screen IDs, URLs, and cleanup details already present in the Agent context or explicitly supplied by the user. Do not call a device tool merely to fill a report gap.
+
+## Workflow
+
+1. Read [report-template.md](references/report-template.md), [evidence-policy.md](references/evidence-policy.md), and [result-classification.md](references/result-classification.md) before drafting.
+2. Establish the report scope and one title. Record time, device, app, execution domain, Session, upload/package identifiers, and cleanup status only when known.
+3. Group the collected evidence into test cases. For each case, state the goal, concise action summary, expected postcondition, actual visible result, selected evidence, and final status.
+4. Select key screenshots rather than every MCP image: initial state when it establishes context, final proof for completed cases, and the image explaining each failure, ambiguity, or infrastructure problem.
+5. Classify the test case from the strongest available evidence. Never promote an action-level `PASSED` to a test-level `PASSED` without a business postcondition.
+6. Write Markdown to the explicitly selected workspace. For an archiveable report, copy only available image bytes to a sibling `evidence/` directory and use relative links. For a short execution record, retain screen IDs and omit unavailable images.
+7. Run a final consistency pass: every linked image exists, every status has a reason, infrastructure problems are not described as app defects, and cleanup is recorded.
+
+This is a reporting-only capability. It does not control devices, call MCP observation tools, or retry tests. It must not acquire a device Session, rerun tests, change YAML, create Runs, or automatically hand off into another Skill. If required evidence is absent, mark the relevant result `INCONCLUSIVE` and state the missing evidence. A report request may follow an explicitly completed Action, Authoring, or Run workflow, but it must not reopen that workflow.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "XAgent Test Report"
+  short_description: "Write evidence-based mobile test reports"
+  default_prompt: "Use $xagent-test-report to write a structured Markdown test report from the evidence already collected. Select key screenshots, classify infrastructure separately, and do not rerun or re-observe the device."

package/dist/assets/skills/xagent-test-report/references/evidence-policy.md

@@ -0,0 +1,20 @@
+# Evidence Policy
+
+Use evidence proportionally rather than attaching every intermediate screen.
+
+## Required evidence
+
+- The initial screen when it establishes the entry state or environment.
+- One final proof image for each completed test case when an image exists.
+- The relevant screen for a failed, blocked, ambiguous, or infrastructure-affected case.
+
+## Optional evidence
+
+- A keyboard, permission dialog, popup, navigation transition, or other intermediate state that explains the result.
+- A second image when the first image is visibly stale or does not prove the stated postcondition.
+
+## Image handling
+
+MCP image content is the preferred Agent evidence. A `screenshot_url` may expire, so long-lived reports should use locally saved image bytes under `evidence/` and relative Markdown links. Do not download a new screenshot solely for documentation. Do not embed all base64 content in the Markdown file.
+
+For each image, retain the source `screen_id` and describe what is visibly proven. If image bytes are unavailable, keep the screen ID and classify the evidence as unavailable instead of fabricating an image link.

package/dist/assets/skills/xagent-test-report/references/report-template.md

@@ -0,0 +1,41 @@
+# Test Report Template
+
+```markdown
+# <测试报告标题>
+
+## 1. 测试概览
+
+- 测试时间：
+- 测试范围：
+- 执行链路：Action MCP / Authoring / Run
+- 总体结论：
+
+## 2. 测试环境
+
+- 设备：
+- `device_id`：
+- Session：
+- 应用与版本：
+- 包名：
+- APK 或上传 ID：
+- 初始证据：
+
+## 3. 测试用例
+
+### TC-001 <用例名称>
+
+- 目标：
+- 步骤摘要：
+- 预期结果：
+- 实际结果：
+- 状态：`PASSED` / `FAILED` / `BLOCKED` / `INCONCLUSIVE` / `INFRASTRUCTURE_FAILED`
+- 关键证据：
+
+## 4. 异常与基础设施问题
+
+## 5. 资源清理
+
+## 6. 总结
+```
+
+Keep the report concise. Include raw JSON only when it explains a failure or an idempotency/replay decision.

package/dist/assets/skills/xagent-test-report/references/result-classification.md

@@ -0,0 +1,13 @@
+# Result Classification
+
+Use the narrowest status supported by the evidence.
+
+| Status | Meaning |
+| --- | --- |
+| `PASSED` | The requested business postcondition is visibly or otherwise explicitly confirmed. |
+| `FAILED` | The test executed, but the requested business postcondition is contradicted. |
+| `BLOCKED` | The test could not proceed because a required app, device, permission, or precondition was unavailable. |
+| `INCONCLUSIVE` | Execution completed or partially completed, but the available evidence cannot establish success or failure. |
+| `INFRASTRUCTURE_FAILED` | Screenshot capture/upload, transport, service, or device-control infrastructure failed and prevented reliable evidence. |
+
+An action-level `PASSED` status on an individual device action means only that the device command completed. Combine it with the action result and the post-action evidence before assigning a test-case status. A screenshot upload failure must not be reported as an application failure unless independent evidence shows the application failed.

package/dist/authoring/draft-store.d.ts

@@ -0,0 +1,19 @@
+export type CheckpointOptions = {
+    nextStepIndex: number;
+    executionMode?: "step_confirm" | "auto";
+    attemptId?: string;
+    attemptStatus?: string;
+};
+export declare class AuthoringDraftStore {
+    readonly workspace: string;
+    constructor(workspace: string);
+    checkpoint(sessionId: string, content: string, options: CheckpointOptions): Promise<Record<string, unknown>>;
+    resume(sessionId: string): Promise<Record<string, unknown>>;
+    list(): Promise<Record<string, unknown>>;
+    private sessionRoot;
+    private validateSessionId;
+    private readState;
+    private atomicWrite;
+    private publicState;
+}
+//# sourceMappingURL=draft-store.d.ts.map

package/dist/authoring/draft-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-store.d.ts","sourceRoot":"","sources":["../../src/authoring/draft-store.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,qBAAa,mBAAmB;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,SAAS,EAAE,MAAM;IAEvB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IA4B5G,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAW3D,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAa9C,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,iBAAiB;YACX,SAAS;YAST,WAAW;IAOzB,OAAO,CAAC,WAAW;CACpB"}

package/dist/authoring/draft-store.js

@@ -0,0 +1,104 @@
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stringify } from "yaml";
+import { CliError } from "../core/errors.js";
+import { hashJson } from "../core/json.js";
+import { parseYaml } from "../script/service.js";
+const SESSION_ID = /^[A-Za-z0-9_.-]{1,64}$/;
+const STATE_VERSION = "xagent-local-authoring-state/v1";
+export class AuthoringDraftStore {
+    workspace;
+    constructor(workspace) { this.workspace = path.resolve(workspace); }
+    async checkpoint(sessionId, content, options) {
+        this.validateSessionId(sessionId);
+        if (!Number.isInteger(options.nextStepIndex) || options.nextStepIndex < 0)
+            throw new CliError("invalid_request", "next_step_index must be a non-negative integer");
+        const parsed = await parseYaml(content);
+        if (!parsed.valid)
+            throw new CliError("schema_invalid", "Local Authoring draft is invalid", 2, { issues: parsed.issues });
+        const normalized = stringify(parsed.script, { lineWidth: 0 });
+        const root = this.sessionRoot(sessionId);
+        const checkpoints = path.join(root, "checkpoints");
+        await mkdir(checkpoints, { recursive: true });
+        const previous = await this.readState(root);
+        const number = Number(previous.checkpoint ?? 0) + 1;
+        const state = {
+            schema_version: STATE_VERSION,
+            session_id: sessionId,
+            checkpoint: number,
+            next_step_index: options.nextStepIndex,
+            execution_mode: options.executionMode ?? null,
+            last_attempt_id: options.attemptId ?? null,
+            last_attempt_status: options.attemptStatus ?? null,
+            script_hash: hashJson(parsed.script),
+            updated_at: new Date().toISOString().replace(/\.\d{3}Z$/, "+00:00"),
+        };
+        await this.atomicWrite(path.join(checkpoints, `${String(number).padStart(6, "0")}.yaml`), normalized);
+        await this.atomicWrite(path.join(root, "draft.yaml"), normalized);
+        await this.atomicWrite(path.join(root, "state.json"), `${JSON.stringify(state, null, 2)}\n`);
+        return this.publicState(root, state);
+    }
+    async resume(sessionId) {
+        this.validateSessionId(sessionId);
+        const root = this.sessionRoot(sessionId);
+        const state = await this.readState(root);
+        let content;
+        try {
+            content = await readFile(path.join(root, "draft.yaml"), "utf8");
+        }
+        catch {
+            throw new CliError("resource_not_found", "Local Authoring draft was not found");
+        }
+        if (Object.keys(state).length === 0)
+            throw new CliError("resource_not_found", "Local Authoring draft was not found");
+        return { ...this.publicState(root, state), content };
+    }
+    async list() {
+        const root = path.join(this.workspace, ".xagent", "authoring");
+        const drafts = [];
+        let entries = [];
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch {
+            return { workspace: this.workspace, drafts };
+        }
+        for (const entry of entries.filter((item) => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+            const sessionRoot = path.join(root, entry.name);
+            const state = await this.readState(sessionRoot);
+            if (Object.keys(state).length)
+                drafts.push(this.publicState(sessionRoot, state));
+        }
+        return { workspace: this.workspace, drafts };
+    }
+    sessionRoot(sessionId) { return path.join(this.workspace, ".xagent", "authoring", sessionId); }
+    validateSessionId(sessionId) { if (!SESSION_ID.test(String(sessionId ?? "").trim()))
+        throw new CliError("invalid_request", "session_id is invalid"); }
+    async readState(root) {
+        try {
+            const value = JSON.parse(await readFile(path.join(root, "state.json"), "utf8"));
+            return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return {};
+            throw new CliError("local_draft_invalid", "Local Authoring state cannot be read");
+        }
+    }
+    async atomicWrite(filePath, content) {
+        await mkdir(path.dirname(filePath), { recursive: true });
+        const temporary = `${filePath}.tmp`;
+        try {
+            await writeFile(temporary, content, "utf8");
+            await rename(temporary, filePath);
+        }
+        catch {
+            throw new CliError("local_draft_write_failed", "Local Authoring draft cannot be saved");
+        }
+        finally {
+            await unlink(temporary).catch(() => undefined);
+        }
+    }
+    publicState(root, state) { return { ...state, draft_path: path.join(root, "draft.yaml"), state_path: path.join(root, "state.json") }; }
+}
+//# sourceMappingURL=draft-store.js.map

package/dist/authoring/draft-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-store.js","sourceRoot":"","sources":["../../src/authoring/draft-store.ts"],"names":[],"mappings":"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"}

package/dist/authoring/session-lease.d.ts

@@ -0,0 +1,64 @@
+export type SessionLeaseSnapshot = {
+    id?: unknown;
+    session_id?: unknown;
+    status?: unknown;
+    expires_at?: unknown;
+    device_id?: unknown;
+    session?: SessionLeaseSnapshot;
+};
+export type SessionLeaseClient = {
+    getSession?: (sessionId: string) => Promise<Record<string, any>>;
+    renewSession: (sessionId: string) => Promise<Record<string, any>>;
+    cancel?: (sessionId: string, idempotencyKey: string) => Promise<Record<string, any>>;
+};
+export type SessionLeaseEvent = {
+    type: "registered" | "renewed" | "renewal_failed" | "release_failed" | "unregistered" | "expired";
+    session_id: string;
+    expires_at?: string;
+    error?: string;
+};
+type Timer = ReturnType<typeof setTimeout>;
+type Clock = {
+    now: () => number;
+    setTimeout: (callback: () => void, delay: number) => Timer;
+};
+/**
+ * Owns only the Session leases created or explicitly touched by this process.
+ * The server remains the authority for expiry and device ownership; this class
+ * renews only when active work checks freshness or explicit keepalive is running.
+ */
+export declare class SessionLeaseManager {
+    private readonly client;
+    private readonly leases;
+    private readonly renewals;
+    private readonly clock;
+    private readonly renewBeforeMs;
+    private readonly onEvent?;
+    constructor(client: SessionLeaseClient, options?: {
+        renewBeforeMs?: number;
+        clock?: Partial<Clock>;
+        onEvent?: (event: SessionLeaseEvent) => void;
+    });
+    register(sessionId: string, snapshot?: SessionLeaseSnapshot): void;
+    unregister(sessionId: string): void;
+    has(sessionId: string): boolean;
+    getLease(sessionId: string): Record<string, unknown> | undefined;
+    /** Ensure a Session is known and renew it when it is inside the lease window. */
+    ensureFresh(sessionId: string): Promise<Record<string, any> | undefined>;
+    renew(sessionId: string): Promise<Record<string, any>>;
+    private performRenew;
+    /** Keep one Session alive until it reaches a terminal server state. */
+    keepAlive(sessionId: string, options?: {
+        pollMs?: number;
+        onEvent?: (event: SessionLeaseEvent) => void;
+    }): Promise<void>;
+    /** Best-effort release for resources owned by this MCP process on shutdown. */
+    releaseAll(): Promise<void>;
+    private assertUsable;
+    private readStatus;
+    private readExpiresAt;
+    private emit;
+    private emitTo;
+}
+export {};
+//# sourceMappingURL=session-lease.d.ts.map

package/dist/authoring/session-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lease.d.ts","sourceRoot":"","sources":["../../src/authoring/session-lease.ts"],"names":[],"mappings":"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"}