@nextclaw/x-harness 0.1.0 → 0.1.1

package/README.md

@@ -13,7 +13,7 @@ npx @nextclaw/x-harness@latest update --target codex
 
 Requires Node.js 22+ and a compatible browser-enabled AI host. Codex desktop with CUA is the validated host. `--target claude` installs Skill text into Claude's Skill directory; the Claude host must separately provide compatible CUA tab/app methods. Installing text alone does not add browser control.
 
-The runtime lives in `~/.x-harness/runtime`; the Skill is managed in the selected host's Skill directory. Updates preserve your independent workspaces, back up the previous runtime and Skill, and refuse to overwrite unrecognized directories. Restart the task's module binding after updating.
+The runtime lives in `~/.x-harness/runtime`; the Skill is managed in the selected host's Skill directory. Updates preserve your independent workspaces, back up the previous runtime and Skill, and refuse to overwrite unrecognized directories. Bind the new moduleURL reported by update; its versioned path refreshes the complete module graph, including in a persistent REPL. The stable CLI entry remains usable.
 
 Initialize your own workspace (use the stable CLI path reported by setup):
 
@@ -37,6 +37,6 @@ Read APIs: `readCreator`, `readBookmarks`, `searchSources`, `readPost`, `readPer
 Write APIs: `publishPost`, `replyToPost`, `followOne`, `followBatch`, `runGrowthRound`.
 Recovery: `verifySubmission`, `verifyPublishedPost`, `verifyFollow`.
 
-Writing requires the user's explicit task authorization, reviewed prepared actions and their own ledger plan. Initialization enables no planned writes. Current writing window: 07:00–22:00 Asia/Shanghai; follow quality gates currently require reviewed Chinese-language, blue-check candidates. Read tasks do not require that candidate policy. Missing browser capability, login or decision evidence is returned explicitly. Unknown submissions are verified before any further submission.
+Writing requires the user's explicit task authorization, reviewed prepared actions and their own ledger plan. Initialization enables no planned writes. Current runtime windows (Asia/Shanghai): originals/follows 07:00–22:00; replies 07:00–24:00. Follow any stricter original project contract; follow quality gates currently require reviewed Chinese-language, blue-check candidates. Read tasks do not require that candidate policy. Missing browser capability, login or decision evidence is returned explicitly. Unknown submissions are verified before any further submission.
 
 Free to use under the included proprietary license. The distributed JavaScript is readable; the private TypeScript repository is not published. This is not an official X product. See `LICENSE` for permitted use.

package/cli/main.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync, cpSync, mkdtempSync, openSync, closeSync, unlinkSync, readdirSync, } from "node:fs";
-import { join, resolve, dirname } from "node:path";
+import { join, resolve, dirname, relative } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
@@ -44,6 +44,24 @@ function location() {
         home,
     };
 }
+function stageRuntime(stage, runtime) {
+    const stagedRuntime = join(stage, "runtime");
+    const suffix = join("versions", release.version, "node_modules", ...release.name.split("/"));
+    const installedRoot = join(stagedRuntime, suffix);
+    cpSync(packageRoot, installedRoot, { recursive: true });
+    if (readJSON(join(installedRoot, "package.json")).version !== release.version)
+        throw Error("Installed version mismatch");
+    const finalRoot = join(runtime, suffix);
+    const stableRoot = join(stagedRuntime, "node_modules", ...release.name.split("/"));
+    const stableCLI = join(runtime, "node_modules", ...release.name.split("/"), "cli", "main.js");
+    mkdirSync(join(stableRoot, "cli"), { recursive: true });
+    writeFileSync(join(stableRoot, "package.json"), JSON.stringify({ type: "module" }));
+    const entry = relative(dirname(stableCLI), join(finalRoot, "cli", "main.js"))
+        .split("\\")
+        .join("/");
+    writeFileSync(join(stableRoot, "cli", "main.js"), `#!/usr/bin/env node\nawait import(new URL(${JSON.stringify(entry)}, import.meta.url));\n`);
+    return { stagedRuntime, installedRoot, finalRoot, stableCLI };
+}
 function setup() {
     const target = flags.get("--target") ?? "codex";
     const stateFile = join(home, "installation.json");
@@ -66,23 +84,17 @@ function setup() {
     const changes = [];
     let completed = false;
     try {
-        const stagedRuntime = join(stage, "runtime");
-        mkdirSync(stagedRuntime);
-        const installedRoot = join(stagedRuntime, "node_modules", ...release.name.split("/"));
-        // npx has already fetched this release. Persist its dependency-free runtime once.
-        cpSync(packageRoot, installedRoot, { recursive: true });
-        if (readJSON(join(installedRoot, "package.json")).version !== release.version)
-            throw Error("Installed version mismatch");
+        // Persist npx's already fetched runtime once; versioned URLs invalidate the whole module graph.
+        const { stagedRuntime, installedRoot, finalRoot, stableCLI } = stageRuntime(stage, runtime);
         const metadata = { managedBy: release.name, version: release.version };
         writeFileSync(join(stagedRuntime, ".x-harness-managed.json"), JSON.stringify(metadata));
-        const finalRoot = join(runtime, "node_modules", ...release.name.split("/"));
         const installs = [{ src: stagedRuntime, dest: runtime, key: "runtime" }];
         for (const t of targets) {
             const stagedSkill = join(stage, `skill-${t}`);
             cpSync(join(installedRoot, "skill"), stagedSkill, { recursive: true });
             const content = readFileSync(join(stagedSkill, "SKILL.md"), "utf8")
                 .replaceAll("{{MODULE_URL}}", pathToFileURL(join(finalRoot, "dist", "index.js")).href)
-                .replaceAll("{{CLI_PATH}}", join(finalRoot, "cli", "main.js"));
+                .replaceAll("{{CLI_PATH}}", stableCLI);
             writeFileSync(join(stagedSkill, "SKILL.md"), content);
             writeFileSync(join(stagedSkill, ".x-harness-managed.json"), JSON.stringify(metadata));
             installs.push({
@@ -111,7 +123,7 @@ function setup() {
             status: "installed",
             ...state,
             moduleURL: pathToFileURL(join(finalRoot, "dist", "index.js")).href,
-            cliPath: join(finalRoot, "cli", "main.js"),
+            cliPath: stableCLI,
             skillPaths: targets.map(skillPath),
             backup: changes.some((c) => c.hadOld) ? backup : null,
             next: "Start a fresh module binding using the installed x-harness Skill.",

package/dist/api.js

@@ -7,7 +7,44 @@ export function createBusinessHarness(dependencies) {
     // All public operations share the same error boundary. Full errors remain local proof.
     async function invoke(operation, args) {
         try {
-            return await core[operation](args);
+            const raw = await core[operation](args);
+            // Legacy core decisions can contain a human error without a diagnostic proof.
+            // Expose a bounded recovery route; consumers never need implementation source.
+            const errors = [
+                raw.reason,
+                ...(raw.decision ?? []).flatMap((d) => [
+                    d.reason,
+                    d.error,
+                ]),
+            ].filter((reason) => typeof reason === "string" && stableReason(reason) !== reason);
+            if (errors.length) {
+                const evidenceRef = await store.recordProof({
+                    operation,
+                    error: errors[0],
+                    ...(errors.length > 1 ? { errors } : {}),
+                });
+                return {
+                    ...raw,
+                    ...(raw.reason ? { reason: stableReason(raw.reason) } : {}),
+                    evidenceRef,
+                    ...(raw.decision
+                        ? {
+                            decision: raw.decision.map((d) => ({
+                                ...d,
+                                reason: stableReason(d.reason),
+                            })),
+                        }
+                        : {}),
+                    diagnostic: {
+                        operation,
+                        category: "boundary",
+                        code: "harness-boundary-error",
+                        next: "inspect-local-proof",
+                        evidenceRef,
+                    },
+                };
+            }
+            return raw;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -29,6 +66,15 @@ export function createBusinessHarness(dependencies) {
                 ...(evidenceRef
                     ? { evidenceRef }
                     : { missing: ["local-proof-unavailable"] }),
+                diagnostic: {
+                    operation,
+                    category: "boundary",
+                    code: evidenceRef
+                        ? "harness-boundary-error"
+                        : "evidence-store-unavailable",
+                    next: evidenceRef ? "inspect-local-proof" : "restore-proof-store",
+                    ...(evidenceRef ? { evidenceRef } : {}),
+                },
             };
         }
     }
@@ -112,6 +158,9 @@ export function createBusinessHarness(dependencies) {
             out.decision = issues;
         if (raw.evidenceRef)
             out.evidenceRef = raw.evidenceRef;
+        const d = diagnostic(raw.diagnostic);
+        if (d)
+            out.diagnostic = d;
         if (Array.isArray(raw.settlementErrors))
             out.settlementErrors = raw.settlementErrors
                 .map(stableReason)
@@ -231,6 +280,9 @@ export function createBusinessHarness(dependencies) {
                 output.batchId = raw.batchId;
             if (raw.evidenceRef)
                 output.evidenceRef = raw.evidenceRef;
+            const d = diagnostic(raw.diagnostic);
+            if (d)
+                output.diagnostic = d;
             const issues = decisions(raw.decision);
             if (raw.reason)
                 issues.push({ reason: raw.reason, status: "needsDecision" });

package/dist/browser-dom-capabilities.d.ts

@@ -0,0 +1,4 @@
+import type { DOMDependencies } from "./browser-dom-dependencies.js";
+export declare function createDOMCapabilities(dependencies: Pick<DOMDependencies, "tab" | "nativeSubmit">): {
+    capabilities(operation: any): any;
+};

package/dist/browser-dom-capabilities.js

@@ -0,0 +1,110 @@
+import { missingMethods } from "./browser-common.js";
+export function createDOMCapabilities(dependencies) {
+    const { tab, nativeSubmit } = dependencies;
+    return {
+        capabilities(operation) {
+            const base = missingMethods(tab?.playwright, ["evaluate"]);
+            if (operation === "readCreator") {
+                base.push(...missingMethods(tab, [
+                    "url",
+                    "goto",
+                    "reload",
+                    "getAXState",
+                    "scroll",
+                ]));
+                base.push(...missingMethods(tab.playwright, ["locator"]));
+                if (typeof tab.playwright?.locator === "function") {
+                    const article = tab.playwright.locator("article");
+                    base.push(...missingMethods(article, ["first", "getByRole"]));
+                    if (typeof article.first === "function")
+                        base.push(...missingMethods(article.first(), ["waitFor"]));
+                    if (typeof article.getByRole === "function")
+                        base.push(...missingMethods(article.getByRole("button", { name: "显示更多", exact: true }), ["all"]));
+                }
+                return base;
+            }
+            if (["readBookmarks", "searchSources", "readFeedback"].includes(operation)) {
+                base.push(...missingMethods(tab, ["goto"]));
+                base.push(...missingMethods(tab?.playwright, ["getByRole", "waitForURL"]));
+                if (typeof tab?.playwright?.getByRole === "function")
+                    base.push(...missingMethods(tab.playwright.getByRole("article"), [
+                        "first",
+                        "waitFor",
+                    ]));
+                if (operation !== "readFeedback") {
+                    base.push(...missingMethods(tab?.playwright, [
+                        "getByRole",
+                        "getByText",
+                        "locator",
+                        "waitForURL",
+                    ]));
+                    if (typeof tab?.playwright?.getByRole === "function")
+                        base.push(...missingMethods(tab.playwright.getByRole("main"), [
+                            "count",
+                            "click",
+                            "first",
+                            "waitFor",
+                        ]));
+                    if (typeof tab?.playwright?.locator === "function")
+                        base.push(...missingMethods(tab.playwright.locator("a"), [
+                            "count",
+                            "filter",
+                            "press",
+                        ]));
+                    if (typeof tab?.playwright?.getByText === "function")
+                        base.push(...missingMethods(tab.playwright.getByText(""), ["waitFor"]));
+                }
+                return base;
+            }
+            if (operation !== "read")
+                base.push(...missingMethods(tab?.playwright, ["getByRole"]), ...missingMethods(tab, ["goto"]));
+            if (operation !== "read" &&
+                typeof tab?.playwright?.getByRole === "function") {
+                base.push(...missingMethods(tab.playwright.getByRole("button"), [
+                    "count",
+                    "click",
+                ]));
+                if (operation !== "submitFollow")
+                    base.push(...missingMethods(tab.playwright.getByRole("textbox"), [
+                        "count",
+                        "fill",
+                    ]));
+                if (["submitPost", "submitReply"].includes(operation)) {
+                    base.push(...missingMethods(tab.playwright, ["locator", "waitForLoadState"]));
+                    base.push(...missingMethods(tab.playwright.getByRole("button"), [
+                        "and",
+                        "waitFor",
+                    ]));
+                }
+            }
+            if (operation === "refreshPerson" || operation === "refreshPosts") {
+                base.push(...missingMethods(tab, ["reload"]));
+                base.push(...missingMethods(tab?.playwright, ["waitForLoadState"]));
+                if (typeof tab?.playwright?.getByRole === "function")
+                    base.push(...missingMethods(tab.playwright.getByRole("button"), ["waitFor"]));
+            }
+            if (operation === "openOwnPostMenu") {
+                base.push(...missingMethods(tab?.playwright, ["locator"]));
+                if (typeof tab?.playwright?.getByRole === "function")
+                    base.push(...missingMethods(tab.playwright.getByRole("article"), [
+                        "filter",
+                        "getByRole",
+                    ]));
+            }
+            if (operation === "submitEditedPost") {
+                base.push(...missingMethods(tab?.playwright, ["waitForLoadState"]));
+                if (typeof tab?.playwright?.getByRole === "function")
+                    base.push(...missingMethods(tab.playwright.getByRole("button"), ["press"]));
+            }
+            if (operation === "attachAssets")
+                base.push(...missingMethods(tab?.playwright, [
+                    "waitForEvent",
+                    "getByLabel",
+                    "getByPlaceholder",
+                ]));
+            if (nativeSubmit && ["submitPost", "submitReply"].includes(operation))
+                base.push(...missingMethods(tab, ["getAXState", "click"]));
+            return base;
+        },
+    };
+}

package/dist/browser-dom-dependencies.d.ts

@@ -0,0 +1,16 @@
+export interface DOMSession {
+    current?: any;
+    replyBinding?: any;
+    refreshNotice?: any;
+    editBinding?: any;
+}
+export interface DOMDependencies {
+    tab: any;
+    nativeSubmit: boolean;
+    readDOM: any;
+    session: DOMSession;
+    submitAX: any;
+    observe: (query: any) => Promise<any>;
+    locator: (role: any, name?: any) => any;
+    unique: (loc: any) => Promise<any>;
+}

package/dist/browser-dom-editing.d.ts

@@ -0,0 +1,148 @@
+import type { DOMDependencies } from "./browser-dom-dependencies.js";
+export declare function createDOMEditing(dependencies: Pick<DOMDependencies, "session" | "unique" | "locator" | "tab" | "observe">): {
+    dismissMenu: (command: any) => Promise<{
+        completed: boolean;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    openControl: (command: any) => Promise<{
+        completed: boolean;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    openOwnPostMenu: (command: any) => Promise<{
+        completed: boolean;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    submitEditedPost: (command: any) => Promise<{
+        completed: boolean;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    expandPost: (command: any) => Promise<{
+        completed: boolean;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    nextPosts: (command: any) => Promise<{
+        completed: boolean;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    clearPreparedText: (command: any) => Promise<{
+        completed: boolean;
+        value: Promise<any>;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+        value?: undefined;
+    }>;
+    closePreparedReply: (command: any) => Promise<{
+        completed: boolean;
+        value: Promise<any>;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+        value?: undefined;
+    }>;
+    closePreparedMedia: (command: any) => Promise<{
+        completed: boolean;
+        value: Promise<any>;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+        value?: undefined;
+    }>;
+    removePreparedMedia: (command: any) => Promise<{
+        completed: boolean;
+        value: Promise<any>;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+        value?: undefined;
+    }>;
+    attachAssets: (command: any) => Promise<{
+        completed: boolean;
+        value: {
+            assets: {
+                path: any;
+                alt: any;
+            }[];
+            mediaEvidence: any;
+            composer: any;
+        };
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+        value?: undefined;
+    }>;
+    follow: (command: any) => Promise<{
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    openReply: (command: any) => Promise<{
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    fillComposer: (command: any) => Promise<{
+        completed: boolean;
+        loc?: undefined;
+        submittedEditor?: undefined;
+    } | {
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    submitPost: (command: any) => Promise<{
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+    submitReply: (command: any) => Promise<{
+        completed: boolean;
+        loc: any;
+        submittedEditor: any;
+    }>;
+};