Xparse Parse

xparse-parse

Use the installed xparse-cli as the only parsing, authentication, quota, and document-navigation execution kernel. Do not reproduce its HTTP, OAuth, quota, PDF splitting, or result-merging logic in the Skill.

Task context

For every new user request, create one private 0600 JSON file before the first xParse command:

{
  "schema_version": "xparse_task_context.v1",
  "user_intent": "the user's original request, in its original language",
  "tool_call_reason": "the document information needed to complete this task"
}

• Preserve the user's wording and keep the operational reason brief.
• Never include hidden reasoning, credentials, document content, or the final answer.
• Pass --task-context <FILE> only on the first xParse invocation for that request.
• Delete the temporary file after that invocation. Later commands inherit the task.
• Do not pass inline JSON through shell arguments, echo, or a heredoc.

Command integrity and structured error gate

Run every operational xparse-cli invocation as a standalone shell command. Do not pipe it through head, tail, grep, or another command, and do not append cleanup, printing, file reads, or other shell commands that can replace its exit status. Perform task-context cleanup in a separate shell call.

For every failed command, parse the final stderr object whose schema_version is xparse_error.v1. Treat that object as failure even if a shell wrapper reports exit code 0. Apply this gate before issuing another xParse command:

• retryable=false means do not retry or reinterpret the same logical action. Follow only the declared next_action. For CONTACT_SUPPORT, report the error and preserved identifiers, then issue no more xParse commands for the current request.
• retryable=true permits at most one Agent-layer retry of the same logical action. Keep the same Task, Run, Resource, and operation_id where present.
• Changing flags, authentication options, selector form, Resource identifier, timing, or switching between task read and task export does not create a new logical action or reset its retry budget.
• Do not run diagnostic xParse commands unless the Task state or next_action explicitly calls for them. Goal completion pressure is not a recovery signal; a correct failure report completes the Agent action.

After a non-retryable failure, another attempt is allowed only after the user confirms an external remediation or explicitly requests a new action. Reuse the preserved Task and Run identifiers; never recreate completed server work.

Free, free-package, and paid routing

Use --api auto by default. The CLI queries the service quota before parsing and uses the current server response as the authority instead of relying on a Skill snapshot.

Authentication is identity, not permission to spend. Never choose --api paid only because OAuth or AppKey credentials exist.

Run xparse-cli quota --output json when the user asks about quota, when a routing failure needs explanation, or before proposing a paid retry. Read all returned facts:

• daily free parse pages remaining and reset time;
• independent extraction_quota daily limit, used pages, remaining pages, and reset time when present;
• whether the request is authenticated;
• authenticated free-package total, historical used count, and current free_remain_count when present (routing uses only free_remain_count);
• maximum pages and file size per request.

Do not cache or calculate an allowance in the Skill. parse --api auto performs its own quota preflight, and the parse response remains authoritative if quota changes between inspection and execution. The Skill must not promise stronger billing guarantees than the existing server provides.

Device OAuth and AppKey are different identities. If quota returns authenticated=false or omits free_package, do not infer package access from an OAuth login indicator. Treat only fields in the current quota response as available.

The free endpoint supports PDF and images. Office, HTML, OFD, and other formats may require --api paid; explain this and obtain the user's approval before switching modes. If all reported free sources are insufficient, stop and explain the current quota rather than silently retrying as paid.

Choose the workflow

Choose by input shape and durability, not by whether authentication already exists:

Workflow selection and billing selection are independent decisions. Task versus parse is chosen from the request's input shape and durability needs; auto, free, and paid choose only the billing route. A quota, eligibility, authorization, funding, or format outcome must never change an accepted multi-document Task into individual parse calls. Only an explicit user request that narrows the original scope to a genuinely new one-document action may be treated as a new parse operation.

• Use parse for one document or URL when the user needs an immediate result, conversion, or local outline/search navigation.
• Structured extraction is the exception: first distinguish a new extraction request from appending files to an existing extraction Task. Parse new local files through the first full Run of a new durable Parse Task, then either create an extraction Task or append to the existing extraction Task as requested. Follow the semantic extraction section below instead of reading parsed content into the Host.
• Use the durable Task Runtime for two or more local documents, or when the user explicitly needs a persistent Task ID, later status checks, selective result reads, exports, debugging, or continuation. A one-file request can therefore still be a Task when durability is explicit.
• Task Runtime control-plane routes and OAuth authentication are available in both domestic and overseas environments. Free-first Task billing is a separate capability: if the selected environment returns TASK_FREE_MODE_UNAVAILABLE, stop and explain it. Never replace the Task with serial parse calls or silently switch to paid execution.

Durable multi-document Task Runtime

For local files, start one server-persisted Task instead of launching multiple parse commands:

xparse-cli task run --files '<GLOB>' --api auto

--api auto is free-first and fails closed: it does not silently create a paid Task. Use --api paid only after the user explicitly approves paid service behavior. Do not parallelize individual parse commands for inputs that belong to one Task.

task run returns after the server accepts the Run. When structured progress is enabled, stderr is an xparse_event.v1 JSONL stream: run_accepted exposes the accepted Task/Run identity immediately, and run_status is emitted only when the state changes. Stdout contains exactly one final submission JSON. Preserve operation_id, task_id, and run_id. If submission fails or the process loses its response, reuse the observed operation_id with --operation-id; never invent a new ID for the same logical submission.

Keep Agent workflows on the default submit-and-return path. Do not add --wait or a short fixed --timeout automatically. When a user explicitly