@intsig-xparse/dsh-xparse

Readme

# TextIn xParse for DeepSeek Harness

English | [简体中文](README_zh.md)

`@intsig-xparse/dsh-xparse` installs one structured `xparse` Tool, the bundled
`xparse-parse` Skill, and the reviewed xparse CLI binaries used internally by
the Tool.

## Requirements

- DeepSeek Harness `0.1.1-rc.2`
- Node.js 22.19 or newer, as required by the current Harness dependency set
- Linux or macOS on x64/arm64; Windows binaries are packaged but are not part
  of the current native validation evidence

## Install

```sh
dsh plugin --profile web add @intsig-xparse/dsh-xparse
dsh --profile web --dump-config
dsh --profile web
```

The Tool always executes the binary embedded in this package. It does not use
`PATH`, a global `xparse-cli`, an install script, or a runtime download.

## Operations

The first release exposes:

- `parse`
- `quota`
- `get_doc_info`
- `get_outline`
- `search_text`
- `read_pages`
- `read_content`
- `task_run`
- `task_rerun`
- `task_status`
- `task_read`
- `task_export`
- `task_debug`
- `task_resume`

`get_confidence`, interactive CLI commands, arbitrary CLI arguments, custom
headers, custom base URLs, Task passwords, `task_continue`, foreground Task
waiting controls, `task_status.details`, and encrypted-document passwords are
not exposed. Task submission and rerun operations return Task/Run identity,
status, progress counters, terminal state, and `next_action` immediately; use
the compact exact-Run `task_status` response for later progress checks. Task
debug/export responses expose only whitelisted file status, error code, and
recovery fields rather than raw service payloads.

Parsing sends document data to TextIn. Uploads and explicit paid parsing follow
the Bundle's Harness approval policy. Task auto-routing and reruns are not
pre-approved merely because they may later need paid capacity: the service
first returns `waiting_paid_authorization` or `waiting_funds`, and approval is
requested only for the exact subsequent `task_resume` action. One approval
covers that Task Run, not one approval per file; an `after-funding` retry for
the already-authorized Run does not ask again. Results are written as workspace
artifacts instead of returning a complete long document as Tool text.

## Credentials

The browser card at **Settings > Plugins > Plugin configuration > TextIn
xParse** writes App ID and Secret Code through the Harness
`credentials.set` API. Secret Code never enters plugin settings, Tool
arguments, or the Agent conversation. The card addresses the configured credential
references, which default to `XPARSE_APP_ID` and `XPARSE_SECRET_CODE`.
The non-secret App ID is mirrored into the `xparse` settings namespace so an
existing configuration can display it; Secret Code remains write-only. A
configured card shows App ID and a Modify action, while an unconfigured card
keeps the AppKey form collapsed until the user selects the AppKey configuration
button. The same nested control hides the configured App ID and modification
actions by default. The outer xParse card starts collapsed whenever OAuth is
already logged in or a complete AppKey exists; otherwise it starts expanded.
Deployment-provided environment values remain higher priority and make the
corresponding controls read-only. The same card offers Device OAuth login: the
Host automatically starts the embedded CLI flow while logged out and directly
shows the verification URL/code without a separate login button. Visible login
URLs include `launch_from=deepseek-harness`, and OAuth requests use the public
Client ID `plugin_deepseek_harness`. Grants created for another Client ID are
not reused; the plugin starts a fresh login and replaces them. The Host stores
the resulting `xparse/oauth` grant and refreshes it before use. Tokens never
reach settings, the browser, Tool arguments, or conversation text. Every network operation
(`parse`, `quota`, and Task Runtime) requires OAuth or a complete AppKey; cached
local navigation remains available offline.

OAuth access tokens enter the refresh window five minutes before expiry by
default (`oauthRefreshSkewMs: 300000`).

When a root Agent calls a network operation without usable credentials, the
Tool starts Device OAuth and opens a dedicated xParse login card in the
conversation composer. The card uses an aligned header, authorization panel,
and action footer for the xParse label, login requirement, verification link,
user code, and completion controls; it does not expose the generic question
form, skip, or submit controls. Successful authorization
closes the card, stores the grant Host-side, and continues the original Tool
call. The user may also confirm completion or cancel from the card. Login
waiting occurs before the CLI execution deadline.
Subagents, headless callers, and deployments without a question provider must
use the plugin settings card instead.

Never paste App IDs, Secret Codes, OAuth tokens, or document passwords into a
conversation or Tool call.

## State and artifacts

The adapter assigns a session-scoped state directory below
`<workspace>/.xparse/sessions/` through `XPARSE_STATE_DIR`. Parse artifacts use
per-call directories below `<workspace>/.xparse/calls/`. The sandbox remains
the authority for file access. Every embedded CLI subprocess also receives
`XPARSE_CLIENT_FROM=deepseek-harness`, so TextIn API requests carry
`X-From: deepseek-harness` instead of the standalone `cli` attribution.

## Provenance

`embedded-cli-manifest.json` records the source revision, protocol versions,
paths, and SHA-256 digest of every embedded binary. `skill-source.json` records
the external Skill repository, locked commit, MIT license, and file digests.

## Development

This repository owns only the DeepSeek Harness plugin. The embedded CLI is
built by `xparse-client`, and the generic Skill is maintained by
`xparse-skills`; reviewed revisions are pinned in `release-lock.json` and
materialized only during assembly.

Install dependencies and run the source-level checks with:

```sh
npm install
npm run typecheck
npm test
npm run build
```

Generated release inputs are intentionally not committed. CLI binaries are
downloaded from the six npm platform-package tarballs pinned by URL, npm
integrity, tarball SHA-256, and binary SHA-256 in `release-lock.json`. Populate
or verify the cache with:

```sh
npm run fetch:cli
npm run fetch:skill
```

Then assemble with a clean checkout of the locked Skill:

```sh
python3 scripts/prepare-dsh-xparse.py \
  --skill-dir /path/to/xparse-skills/skills/xparse-parse
```

Use `--offline` to prove the assembly is reproducible from the verified cache
without registry access.

After assembly, validate the package and a real DSH web boot with:

```sh
npm run validate:docker
```

## Release

Build the complete npm tarball and checksum manifest with one command:

```sh
npm run release:build -- --output-dir dist/release
```

The command fetches the locked Skill and CLI artifacts, assembles generated
inputs, compiles TypeScript, runs `npm pack`, verifies the tarball, and writes
`SHA256SUMS`. Add `--offline` to require both verified caches.

GitHub CI performs the same release build on every pull request and uploads the
review artifact. Pushing tag `v<package-version>` runs the release workflow,
publishes the exact verified tarball to npm, and attaches the tarball plus
checksums to a GitHub Release. Configure repository secret `NPM_TOKEN` with
publish access to `@intsig-xparse/dsh-xparse` before creating a release tag.