@nextclaw/x-harness 0.1.0 → 0.2.0

package/skill/references/api.md

@@ -1,37 +1,10 @@
-# Root API usage
+# API navigation
 
-Bind once: `createXGrowthHarness({ tab, ledgerPath, proofDirectory })`. Exactly one `tab` or native `app`. Read operations can use the initialized zero-write plan.
+Compatibility index; normal tasks route directly from the Skill. Load one current reference, not all files.
 
-```js
-await x.readCreator({
-  handle: "USER_HANDLE",
-  target: 10,
-  maxScrolls: 8,
-  mode: "decision",
-});
-await x.searchSources({ query: "AI agents", limit: 5, mode: "decision" });
-await x.readBookmarks({ folder: "FOLDER_NAME", limit: 5, mode: "decision" });
-await x.inspectAccount({ mode: "decision" });
-await x.readPost({ target: { postId, url, evidenceRef }, mode: "decision" });
-await x.readPerson({ target: { handle, url, evidenceRef }, mode: "decision" });
-await x.readFeedback({
-  targets: [{ postId, url, evidenceRef }],
-  mode: "decision",
-});
-await x.inspectRound({ taskId });
-```
+- Reading: [reads](reads.md).
+- Reviewed writes/rounds: [writes](writes.md), matching operation heading.
+- Failure/unknown submission: [recovery](recovery.md).
+- Missing installation/workspace or update: [setup](setup.md).
 
-Targets/evidence come from prior observed results. Exact option types are in the installed `dist/types.d.ts`. `readFeedback` may need your accountURL as documented there. Preserve full relevant content and expose missing fields rather than inventing them.
-
-```js
-await x.publishPost({ taskId, draftPath, preparedAction: originalAction });
-await x.replyToPost({ taskId, postId, text, preparedAction: replyAction });
-await x.followOne({ taskId, handle }); // action already prepared in the original ledger
-await x.followBatch({ taskId, handles, preparedActions });
-await x.verifySubmission({ taskId, actionId });
-await x.verifyPublishedPost({ taskId, draftPath, publicURL, evidenceRef });
-await x.verifyFollow({ handle, url, evidenceRef });
-await x.runGrowthRound({ taskId, maxActions: 3 });
-```
-
-Before preparing writes, read the appropriate installed PreparedAction and operation option types. Required reviewed evidence cannot be replaced with a made-up reference. Original posts include actual draftPath, complete text, observed compose URL/proof, author proof and approvedText/draftFingerprint quality. Reply/follow targets require observed evidence. Concurrent task tabs need an explicitly evidenced executor scope; see HarnessOptions/Executor. Business root calls own capability checks, intent journaling, single submission, public verification and ledger settlement.
+Public declarations are the compatibility contract for custom integrations, not a prerequisite for documented calls.

package/skill/references/reads.md

@@ -0,0 +1,23 @@
+# Read tasks
+
+Load for reading only. A valid root binding `x` with existing ledger/proof paths suffices; no write plan needed. `mode` defaults to `receipt`; use `decision` immediately when drafting/reviewing needs text. `delta` omits only unchanged evidence previously returned by this instance; after context loss use `decision`.
+
+| API | Required | Optional |
+| --- | --- | --- |
+| readCreator | handle | target (default 10, 1–50), maxScrolls, navigate, expand, mode |
+| readBookmarks | folder (observed name) | processedIds, limit, maxPages, mode |
+| searchSources | query | processedIds, limit, maxPages, mode |
+| readPost | target: {postId,url,evidenceRef} | mode |
+| readPerson | target: {handle,url,evidenceRef} | mode |
+| readFeedback | targets: [{postId,url,evidenceRef}] | replyLimit, mode |
+| inspectAccount | none | mode |
+| inspectRound | taskId (original batch ID) | none |
+
+```js
+var result = await x.readCreator({ handle: selectedHandle, target: 5, mode: 'decision' });
+var postResult = await x.readPost({ target: observedPost, mode: 'decision' });
+```
+
+Targets/proof come from actual observations, never guessed URLs or made-up references. API owns navigation/expansion and bounded collection. Native creator collection supports an already selected profile with `navigate:false`; it keeps relative times unknown and stops with partial evidence if the active page changes. Native automatic creator navigation remains `needsCapability`; inspect that signal before changing adapter.
+
+Results include status/evidenceRef/missing/IDs/completeness. In `decision`, creator/bookmark/search use `sources`, post `post`, person `person`, feedback `feedback`; account includes accountHandle/accountURL. `observed` alone does not prove every requested field exists. `pageComplete:false` is a collection boundary, not proof of truncated target text. View media before describing it. Return complete chosen evidence; keep other observations local. Only on failure load recovery.

package/skill/references/recovery.md

@@ -0,0 +1,25 @@
+# Recovery by signal
+
+Load on failure/unknown only. Keep operation/status/missing/code/proof/error; never infer success or repeat identical failures.
+
+| Signal | Next action and exit condition |
+| --- | --- |
+| unknown submission | `await x.verifySubmission({taskId,actionId})`, same IDs; no replacement action or new submission before resolution. |
+| Existing public post needs recovery | `await x.verifyPublishedPost({taskId,draftPath,publicURL,evidenceRef})`; observed URL/proof. Optional sourceLink: {href,resolvedURL,evidenceRef,renderedText?}. |
+| Follow needs independent recovery | `await x.verifyFollow({handle,url,evidenceRef,mode:'decision'})`; honor returned verified. Normal followBatch already verifies. |
+| needsDecision | Resolve returned missing review/proof in original action, resume same ID. Current AI performs internal review under project contract. |
+| waiting | Honor resumeAt/reason, continue independent permitted work; never bypass time/identity/claim gates. |
+| needsCapability | Inspect exact missing method/operation. If a supported binding supplies it, rebind once and retry a necessary read; otherwise repair reported owner with failing sample and targeted validation. |
+| diagnostic.next: inspect-local-proof | Read only `{operation,error}` from diagnostic.evidenceRef; resolve via this reference, keep full proof local. Unknown/intent needs same-ID verification. Unsupported: report code/error and update/support; no private source. |
+| diagnostic.next: restore-proof-store | Restore the workspace's writable proof directory, then resume the same action. Do not replace its ledger or infer submission failure. |
+| Missing fields/partial window | Narrow to target, expand/advance documented bounded window; preserve text. No whole-page output or automatic reload. |
+
+## Host connection or native focus
+
+Failure to list/bind Chrome is a host-connection failure before reaching X, not proof of logged-out X. Per current host documentation rediscover the task tab once; validate navigation plus a necessary visible read. Native focus rejection instead needs latest AX URL/window confirmation and one supported focus correction. Do not repeat discovery or restart editors blindly.
+
+Lost tab: reuse a live owned tab or create a task tab in the same actual browser; preserve other editors. Native fallback changes binding to app, not business calls; unsupported native tasks remain gaps. Network/TUN observations do not authorize setting changes.
+
+## Repair boundary
+
+Normal use/known recovery need no source. Unresolved runtime defect/unsupported capability permits diagnostics: maintainers repair the owner, verify the failed boundary and return to root; consumers report gap/update/support, without private TS. Never scan adapters for arguments, add parsers, bypass refusal or resubmit unknown.

package/skill/references/setup.md

@@ -0,0 +1,23 @@
+# Setup and updates
+
+Load only when runtime/workspace is absent, binding needs refreshing after update, or adapter scope changes.
+
+## Repository runtime
+
+Use `<repository>/dist/index.js` as an absolute file URL; if absent run `npm run build`. Reuse original ledger/proofs and private parent runtime-context entry; do not initialize a second ledger or download another runtime. Use this repository’s skill/ as the development Skill owner.
+
+## Independent installation
+
+Requires Node 22+, compatible CUA and own X login. Run `npx @nextclaw/x-harness@latest setup --target codex` (or `--target claude`); use returned moduleURL/cliPath. Setup substitutes placeholders. Skill text does not add browser access. Missing host/login is a prerequisite, not permission to invent execution.
+
+Initialize once: `node <cliPath> init --directory <user workspace> --account <user handle>`. Reuse returned ledgerPath/proofDirectory/taskId; initialization plans zero writes. Existing project state remains its owner.
+
+## Adapter and parallel scope
+
+Host owns tab/app acquisition: read its current documentation once and reuse the valid handle. Tab needs url(), playwright.evaluate() and locators; native app AX/click/key/paste. Do not launch a separate driver.
+
+Native binding: `{app,ledgerPath,proofDirectory}` instead of tab. Independent task tabs may add `executor:{id:taskId,scopeKinds:['original'],evidenceRef:scopeProof}` using actual authorized scope/proof; kinds are original/reply/follow. Never borrow another executor's editor or claim.
+
+## Update
+
+Independent installs run `npx @nextclaw/x-harness@latest update --target codex` (or claude); it backs up managed runtime/Skill and preserves workspaces. Repository users update the original repository owner. Rebind using the new versioned moduleURL returned by update or written into this Skill; it refreshes the whole dependency graph in a persistent REPL. Never reuse the previous URL or add a root-only query string. Preserve pending actions/editors; reacquire the task tab after a necessary host reset. Verify one necessary read with the new module, not all documents. Distributed Skill/runtime share a version. Free use follows bundled proprietary license; TS source remains private.

package/skill/references/writes.md

@@ -0,0 +1,51 @@
+# Writes and rounds
+
+Load common review plus only the operation heading needed. Existing project contract owns authorization, identity, budgets, policy and original ledger plan. Independent initialization has zero planned writes; set only authorized counts in that ledger before executing. Current runtime window is 07:00–24:00 Asia/Shanghai for replies and 07:00–22:00 for other writes; follow gates require reviewed Chinese-language blue-check candidates. Do not expand scope. Examples below use existing real observations/proof; they are not executable authorization.
+
+## Common review
+
+A prepared action has id (stable original ID), status:'prepared', accountHandle, accountURL, accountEvidenceRef and quality. All proof references are existing files; URLs/identity must be actually observed. Already prepared ledger actions need not be prepared again.
+
+Content quality: `{approved:true,approvedText:text,evidenceRef:reviewProof,draftFingerprint}`; original fingerprint is SHA-256 of exact draft file bytes. Use Node crypto/createHash and fs/readFileSync locally; this requires no runtime source. Reply quality needs approvedText/proof; original also needs draftFingerprint. Any changed text/file needs a fresh review. Follow quality: `{approved:true,handle,blue:true,chinese:true,evidenceRef:reviewProof}`; verify evidence, never infer blue from generic certification.
+
+Action APIs return status/actionId/publicURL/evidenceRef and reason/missing/resumeAt when relevant. Verified requires public proof. Unknown loads recovery, never resubmits. Business calls own intent, submit once, fresh verification and original settlement.
+
+## Publish
+
+Additional fields: kind:'original', draftPath (existing .post.md), text (complete approved text), composeURL, composeEvidenceRef; optional assets:[{path,alt}], activation:'click'|'keyboard'. Every media path must exist and be reviewed.
+
+```js
+var result = await x.publishPost({ taskId, draftPath, preparedAction: {
+  id: actionId, status: 'prepared', kind: 'original',
+  accountHandle, accountURL, accountEvidenceRef,
+  quality: { approved: true, approvedText: text, evidenceRef: reviewProof, draftFingerprint },
+  draftPath, text, composeURL, composeEvidenceRef,
+} });
+```
+
+Optional independentExecution:{tabId,evidenceRef,scopeEvidenceRef} requires real independent task-tab/scope proof; binding executor scope is covered in setup only if needed. Existing original action can omit preparedAction; draftPath still required.
+
+## Reply
+
+Additional fields: kind:'reply', postId, url, evidenceRef (observed parent), text; optional assets/activation as above. Common account/quality fields still required. The exact parent is verified by the API.
+
+```js
+var result = await x.replyToPost({ taskId, postId, text, preparedAction: {
+  id: actionId, status: 'prepared', kind: 'reply',
+  accountHandle, accountURL, accountEvidenceRef,
+  quality: { approved: true, approvedText: text, evidenceRef: reviewProof },
+  postId, url: parentURL, evidenceRef: parentProof, text,
+} });
+```
+
+## Follow
+
+Additional fields: kind:'follow', handle, url, evidenceRef (observed person), plus common account fields and follow quality. Batch uses `{taskId,handles,preparedActions?}`; original contract determines allowed batch sizes. Each preparedAction corresponds to its handle. If already prepared, omit preparedActions. `await x.followOne({taskId,handle})` requires its original prepared action and project-permitted single-action scope. A preexisting relationship is not a new verified follow; honor result counts.
+
+## Round
+
+`await x.inspectRound({taskId})` inspects original state; `await x.runGrowthRound({taskId,maxActions})` runs/resumes it. maxActions bounds this call, not original planned total. Preparation uses decision:{type:'prepareActions',accountHandle,ownershipEvidenceRef,actions}; actions are the reviewed structures above.
+
+Optional decision fields: attemptsCoverage:{complete,since,evidenceRef}, sharedAttempts:[{kind,at}], nextScheduledCheckAt. For follow budgets, coverage must actually cover the required window; unknown history cannot be recorded as zero. Missing data remains a decision gap.
+
+Review an existing action with decision:{actionId,approved,evidenceRef,approvedText?,draftFingerprint?,blue?,chinese?}; use content fields for content, blue/chinese for follow. approved:false skips that candidate without filling original planned count. Preserve intent/unknown/verified states and IDs. Read returned gaps/decision/mayEnd; partial success is not whole-round completion.