@nextclaw/x-harness 0.2.66 → 0.2.68

package/SOURCE.md

@@ -1,8 +1,8 @@
 # Corresponding source
 
-Version 0.2.66, commit 0b3b276a3f9390c3ca46514b8ae3845beadf1033.
+Version 0.2.68, commit 9d121f1f8b24f7c1082d8f17a3f6ec473d45d534.
 
-Complete source, build scripts and dependencies: https://github.com/Peiiii/x-harness/tree/0b3b276a3f9390c3ca46514b8ae3845beadf1033
+Complete source, build scripts and dependencies: https://github.com/Peiiii/x-harness/tree/9d121f1f8b24f7c1082d8f17a3f6ec473d45d534
 
 Clone this revision, run npm ci, npm run bootstrap and npm run release:build.
 

package/dist/api.d.ts

@@ -22,7 +22,7 @@ export declare class BusinessHarness implements XGrowthHarness {
         results: never[];
         reason: string;
     } | {
-        status: "needsDecision" | "verified";
+        status: "verified" | "needsDecision";
         results: ActionResult[];
         reason?: undefined;
     }>;
@@ -81,7 +81,9 @@ export declare class BusinessHarness implements XGrowthHarness {
         evidenceRef?: undefined;
         diagnostic?: undefined;
     }>;
+    discoverReplyCandidates(args: import("./types.js").ReplyDiscoveryOptions): Promise<import("./types.js").ReplyDiscoveryResult>;
     searchSources(args: import("./types.js").SearchOptions): Promise<ReadResult>;
+    readExploreRecommendations(args?: import("./types.js").ExploreRecommendationOptions): Promise<ReadResult>;
     readPost({ target, mode, includeContext, includeThread, resolveQuote, }: {
         includeContext?: boolean;
         includeThread?: boolean;

package/dist/api.js

@@ -1,4 +1,6 @@
+import { ReplyDiscovery } from "./reply-discovery.js";
 import { sameHandle, samePublishedText } from "./platform-rules.js";
+import { publicationTime } from "./publication-time.js";
 import { FollowbackAudit } from "./followback-audit.js";
 import { IncomingReactions } from "./incoming-reactions.js";
 import { createGrowthHarness } from "./growth.js";
@@ -32,7 +34,10 @@ export class BusinessHarness {
         this.readPost = this.readPost.bind(this);
         this.readIncomingConversations = this.readIncomingConversations.bind(this);
         this.readIncomingReplies = this.readIncomingReplies.bind(this);
+        this.discoverReplyCandidates = this.discoverReplyCandidates.bind(this);
         this.searchSources = this.searchSources.bind(this);
+        this.readExploreRecommendations =
+            this.readExploreRecommendations.bind(this);
         this.readBookmarks = this.readBookmarks.bind(this);
         this.readCreator = this.readCreator.bind(this);
         const { store, platform } = dependencies;
@@ -366,7 +371,7 @@ export class BusinessHarness {
         const phrases = pending
             .map((a) => '"' + a.text.slice(0, 80).replace(/["\\]/g, " ") + '"')
             .join(" OR ");
-        const query = `from:${pending[0].accountHandle} (${phrases}) since:${new Date(Math.min(...pending.map((a) => Date.parse(a.intentAt)))).toISOString().slice(0, 10)}`;
+        const query = `from:${pending[0].accountHandle} (${phrases}) filter:replies`;
         let found = await this.searchSources({
             query,
             limit: 5,
@@ -391,8 +396,8 @@ export class BusinessHarness {
                 p.url?.toLowerCase() ===
                     `https://x.com/${action.accountHandle}/status/${p.id}`.toLowerCase() &&
                 !(action.beforeIds ?? []).includes(p.id) &&
-                Date.parse(p.datetime ?? "") >= Date.parse(action.intentAt) &&
-                Date.parse(p.datetime ?? "") <= this.#clock() + 5000);
+                publicationTime(p) >= Date.parse(action.intentAt) &&
+                publicationTime(p) <= this.#clock() + 5000);
             if (matches.length !== 1)
                 continue;
             let bound = false;
@@ -596,9 +601,15 @@ export class BusinessHarness {
             pageComplete: false,
         };
     }
+    discoverReplyCandidates(args) {
+        return new ReplyDiscovery((request) => this.searchSources(request), this.#store, this.#clock).run(args);
+    }
     searchSources(args) {
         return this.read("searchSources", args, args.mode);
     }
+    readExploreRecommendations(args = {}) {
+        return this.read("readExploreRecommendations", args, args.mode);
+    }
     readPost({ target, mode, includeContext, includeThread, resolveQuote, }) {
         return this.read("readPost", { ...target, includeContext, includeThread, resolveQuote }, mode);
     }

package/dist/browser-dom-capabilities.js

@@ -45,7 +45,12 @@ export class DOMCapabilities {
         if (operation === "readCreator") {
             return this.creatorCapabilities(base, operation);
         }
-        if (["readBookmarks", "searchSources", "readFeedback"].includes(operation)) {
+        if ([
+            "readBookmarks",
+            "searchSources",
+            "readExploreRecommendations",
+            "readFeedback",
+        ].includes(operation)) {
             return this.collectionCapabilities(base, operation);
         }
         if (operation !== "read")

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

@@ -3,6 +3,7 @@ export declare class DOMNavigation {
     #private;
     openQuote: (command: any) => Promise<any>;
     searchSources: (command: any) => Promise<void>;
+    openExploreRecommendations: (command: any) => Promise<void>;
     waitForFolder: (command: any) => Promise<void>;
     waitForPosts: (command: any) => Promise<void>;
     openObserved: (command: any) => Promise<void>;
@@ -11,6 +12,7 @@ export declare class DOMNavigation {
     constructor(dependencies: Pick<DOMDependencies, "session" | "tab" | "observe">);
     private handleOpenQuote;
     private handleSearchSources;
+    private handleOpenExploreRecommendations;
     private handleWaitForFolder;
     private handleWaitForPosts;
     private handleOpenObserved;

package/dist/browser-dom-navigation.js

@@ -5,6 +5,7 @@ export class DOMNavigation {
     #observe;
     openQuote;
     searchSources;
+    openExploreRecommendations;
     waitForFolder;
     waitForPosts;
     openObserved;
@@ -17,6 +18,8 @@ export class DOMNavigation {
         this.#observe = observe;
         this.openQuote = this.handleOpenQuote.bind(this);
         this.searchSources = this.handleSearchSources.bind(this);
+        this.openExploreRecommendations =
+            this.handleOpenExploreRecommendations.bind(this);
         this.waitForFolder = this.handleWaitForFolder.bind(this);
         this.waitForPosts = this.handleWaitForPosts.bind(this);
         this.openObserved = this.handleOpenObserved.bind(this);
@@ -70,6 +73,10 @@ export class DOMNavigation {
             await this.#tab.goto(destination);
         return;
     }
+    async handleOpenExploreRecommendations() {
+        this.#session.current = null;
+        await this.#tab.goto("https://x.com/explore");
+    }
     async handleWaitForFolder(command) {
         if (command.selected) {
             await this.#tab.playwright

package/dist/browser-native.js

@@ -170,7 +170,13 @@ export class NativeXBrowser {
     capabilities(operation) {
         if (operation === "readPeople")
             return ["native-people-blue-evidence"];
-        if (["readBookmarks", "searchSources", "readFeedback", "likePost"].includes(operation))
+        if ([
+            "readBookmarks",
+            "searchSources",
+            "readExploreRecommendations",
+            "readFeedback",
+            "likePost",
+        ].includes(operation))
             return [`native.${operation}`];
         const names = operation === "read"
             ? ["getAXState"]

package/dist/growth-execution.d.ts

@@ -12,6 +12,7 @@ export declare class GrowthExecution {
     private checkExecutionIdentity;
     private actionIsActionable;
     private admitAction;
+    private readSubmissionWithURLContinuation;
     private handleExecute;
 }
 export declare function createGrowthExecution(...args: ConstructorParameters<typeof GrowthExecution>): GrowthExecution;

package/dist/growth-execution.js

@@ -176,7 +176,7 @@ export class GrowthExecution {
         if (action.kind !== "follow") {
             let baseline;
             try {
-                baseline = await this.#platform.findSubmission({ ...action, intentAt: this.#stamp() }, { phase: "baseline" });
+                baseline = await this.readSubmissionWithURLContinuation({ ...action, intentAt: this.#stamp() }, { phase: "baseline" });
             }
             catch (error) {
                 return {
@@ -202,6 +202,23 @@ export class GrowthExecution {
         }
         return { beforeIds };
     }
+    async readSubmissionWithURLContinuation(action, context) {
+        try {
+            return await this.#platform.findSubmission(action, context);
+        }
+        catch (error) {
+            const preparedBaseline = context?.phase === "baseline";
+            const observedReceipt = !context &&
+                action.observedPublicURL &&
+                this.#evidenceExists(action.observedPublicEvidenceRef);
+            if (action.kind !== "reply" ||
+                !(preparedBaseline || observedReceipt) ||
+                !/Timed out waiting for URL/.test(String(error?.message ?? "")))
+                throw error;
+            // Continue only this read; the existing admission and receipt gates stay intact.
+            return this.#platform.findSubmission(action, context);
+        }
+    }
     async handleExecute(snapshot, action) {
         const executor = this.#executor;
         const recovering = ["intent", "unknown"].includes(action.status);
@@ -215,7 +232,7 @@ export class GrowthExecution {
         if (recovering) {
             let observation;
             try {
-                observation = await this.#platform.findSubmission(action);
+                observation = await this.readSubmissionWithURLContinuation(action);
             }
             catch (error) {
                 observation = {

package/dist/growth-recovery.js

@@ -1,3 +1,4 @@
+import { publicationTime } from "./publication-time.js";
 import { xURL, matchesReviewedAssets } from "./platform-rules.js";
 import { matchesRenderedLinks } from "./source-link-recovery.js";
 import { same } from "./growth-constants.js";
@@ -126,8 +127,8 @@ export class GrowthRecovery {
                     matchesRenderedLinks(action.text, p, sourceLinks, this.#evidenceExists)) &&
                 !p.needsExpansion &&
                 !(action.beforeIds ?? []).includes(p.id) &&
-                Date.parse(p.datetime) >= Date.parse(action.intentAt) &&
-                Date.parse(p.datetime) <= this.#clock() + 5000 &&
+                publicationTime(p) >= Date.parse(action.intentAt) &&
+                publicationTime(p) <= this.#clock() + 5000 &&
                 matchesReviewedAssets(p, action.assets));
         });
         Object.assign(observation, {

package/dist/growth-tasks.d.ts

@@ -10,6 +10,7 @@ export declare class GrowthTasks {
     readPerson(args: any): Promise<any>;
     readBookmarks(args: any): Promise<any>;
     searchSources(args: any): Promise<any>;
+    readExploreRecommendations(args?: any): Promise<any>;
     readFeedback(args: any): Promise<any>;
     runGrowthRound(args: any): Promise<any>;
     resumeGrowthRound(args: any): Promise<any>;

package/dist/growth-tasks.js

@@ -19,6 +19,8 @@ export class GrowthTasks {
         this.runGrowthRound = this.runGrowthRound.bind(this);
         this.readFeedback = this.readFeedback.bind(this);
         this.searchSources = this.searchSources.bind(this);
+        this.readExploreRecommendations =
+            this.readExploreRecommendations.bind(this);
         this.readBookmarks = this.readBookmarks.bind(this);
         this.readPerson = this.readPerson.bind(this);
         this.readPeople = this.readPeople.bind(this);
@@ -40,7 +42,13 @@ export class GrowthTasks {
     }
     preflight({ operation, input = {} }) {
         const executor = this.#executor;
-        if (["readPeople", "readBookmarks", "searchSources", "readFeedback"].includes(operation))
+        if ([
+            "readPeople",
+            "readBookmarks",
+            "searchSources",
+            "readExploreRecommendations",
+            "readFeedback",
+        ].includes(operation))
             return this.#platform.preflight({ operation, input });
         if (["inspectRound", "verifySubmission"].includes(operation))
             return this.#capability("read", input);
@@ -110,6 +118,9 @@ export class GrowthTasks {
     searchSources(args) {
         return this.#readTask("searchSources", args);
     }
+    readExploreRecommendations(args = {}) {
+        return this.#readTask("readExploreRecommendations", args);
+    }
     readFeedback(args) {
         return this.#readTask("readFeedback", args);
     }

package/dist/growth.d.ts

@@ -13,6 +13,7 @@ export declare class GrowthHarness {
     readPerson: (args: any) => Promise<any>;
     readBookmarks: (args: any) => Promise<any>;
     searchSources: (args: any) => Promise<any>;
+    readExploreRecommendations: (args?: any) => Promise<any>;
     readFeedback: (args: any) => Promise<any>;
     runGrowthRound: (args: any) => Promise<any>;
     resumeGrowthRound: (args: any) => Promise<any>;

package/dist/growth.js

@@ -51,6 +51,7 @@ export class GrowthHarness {
     readPerson;
     readBookmarks;
     searchSources;
+    readExploreRecommendations;
     readFeedback;
     runGrowthRound;
     resumeGrowthRound;

package/dist/platform-collections.d.ts

@@ -4,6 +4,7 @@ export declare class PlatformCollections {
     collectSources: ({ processedIds, maxPages, limit }?: any) => Promise<any>;
     readCreator: (args: import("./types.js").CreatorOptions) => Promise<any>;
     readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
+    readExploreRecommendations: (args?: import("./types.js").ExploreRecommendationOptions) => Promise<any>;
     searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
     constructor(dependencies: Pick<PlatformDependencies, "ready" | "observed" | "browser" | "choose">);
     private handleCollectSources;
@@ -15,5 +16,6 @@ export declare class PlatformCollections {
     private bookmarkDiscovery;
     private waitForBookmarkLabel;
     private handleSearchSources;
+    private handleReadExploreRecommendations;
 }
 export declare function createPlatformCollections(...args: ConstructorParameters<typeof PlatformCollections>): PlatformCollections;

package/dist/platform-collections.js

@@ -1,4 +1,15 @@
 import { xURL, source } from "./platform-rules.js";
+const exploreNavigationEvidence = (nav) => ({
+    page: nav.page,
+    headings: (nav.headings ?? []).slice(0, 5),
+    tabs: (nav.controls ?? [])
+        .filter((control) => control.role === "tab")
+        .slice(0, 8)
+        .map((control) => ({
+        label: control.label,
+        selected: control.selected === true,
+    })),
+});
 export class PlatformCollections {
     #ready;
     #observed;
@@ -7,6 +18,7 @@ export class PlatformCollections {
     collectSources;
     readCreator;
     readBookmarks;
+    readExploreRecommendations;
     searchSources;
     constructor(dependencies) {
         const { ready, observed, browser, choose } = dependencies;
@@ -18,6 +30,8 @@ export class PlatformCollections {
         this.readCreator = this.handleReadCreator.bind(this);
         this.readBookmarks = this.handleReadBookmarks.bind(this);
         this.searchSources = this.handleSearchSources.bind(this);
+        this.readExploreRecommendations =
+            this.handleReadExploreRecommendations.bind(this);
     }
     async handleCollectSources({ processedIds = [], maxPages = 3, limit = 1, } = {}) {
         if (!Array.isArray(processedIds) ||
@@ -439,6 +453,134 @@ export class PlatformCollections {
             };
         return { ...value, query };
     }
+    async handleReadExploreRecommendations({ limit = 3, maxPages = 1, processedIds = [], } = {}) {
+        await this.#browser.act({ operation: "openExploreRecommendations" });
+        let nav = await this.#ready({ view: "navigation" });
+        const page = (value) => {
+            try {
+                const url = xURL(value);
+                return url.pathname.replace(/\/+$/, "") === "/explore" ? url : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        const entryPage = page(nav.page);
+        if (!entryPage)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: nav.page,
+                missing: ["explore-page-unconfirmed"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        if (!nav.alerts?.length && nav.needsStateCheck) {
+            try {
+                await this.#browser.act({ operation: "waitForPosts" });
+            }
+            catch (error) {
+                if (!/timed out|timeout/i.test(error.message))
+                    throw error;
+            }
+            nav = await this.#ready({ view: "navigation" });
+        }
+        if (nav.alerts?.length)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: nav.page,
+                missing: ["platform-alert"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        if (nav.needsStateCheck) {
+            const diagnosticRead = await this.handleCollectSources({
+                limit,
+                maxPages,
+                processedIds,
+            });
+            const sameExplorePage = page(diagnosticRead.page);
+            return {
+                ...diagnosticRead,
+                status: "needsDecision",
+                complete: false,
+                missing: [
+                    ...new Set([
+                        "explore-navigation-unconfirmed",
+                        ...(!sameExplorePage ? ["explore-page-changed-during-read"] : []),
+                        ...(diagnosticRead.missing ?? []),
+                    ]),
+                ],
+                sources: sameExplorePage ? (diagnosticRead.sources ?? []) : [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        }
+        const recommended = (nav.controls ?? []).filter((control) => control.role === "tab" &&
+            ["为你推荐", "For you"].includes(control.label.split("\n")[0]));
+        if (recommended.length !== 1)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: entryPage.href,
+                missing: ["explore-recommended-tab-unconfirmed"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        const expectedLabel = recommended[0].label.split("\n")[0];
+        if (!recommended[0].selected &&
+            !(await this.#choose(nav, (control) => control.role === "tab" &&
+                control.label.split("\n")[0] === expectedLabel)))
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: entryPage.href,
+                missing: ["explore-recommended-tab-selection-unavailable"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        nav = await this.#ready({ view: "navigation" });
+        const selected = (nav.controls ?? []).filter((control) => control.role === "tab" &&
+            control.label.split("\n")[0] === expectedLabel &&
+            control.selected);
+        if (!page(nav.page) ||
+            nav.needsStateCheck ||
+            nav.alerts?.length ||
+            selected.length !== 1)
+            return {
+                status: "needsDecision",
+                fresh: true,
+                complete: false,
+                page: nav.page,
+                missing: ["explore-recommended-tab-selection-unconfirmed"],
+                sources: [],
+                navigationEvidence: exploreNavigationEvidence(nav),
+            };
+        const value = await this.handleCollectSources({
+            limit,
+            maxPages,
+            processedIds,
+        });
+        if (!page(value.page))
+            return {
+                ...value,
+                status: "needsDecision",
+                complete: false,
+                missing: ["explore-page-changed-during-read"],
+            };
+        return {
+            ...value,
+            sourceOrigin: {
+                kind: "explore-recommendations",
+                page: entryPage.href,
+                selectedTab: expectedLabel,
+            },
+        };
+    }
 }
 export function createPlatformCollections(...args) {
     return new PlatformCollections(...args);

package/dist/platform-dependencies.d.ts

@@ -19,6 +19,7 @@ export interface PlatformDependencies {
         media: any;
         links: any;
         needsExpansion: any;
+        metrics: string[];
         missing: any[];
     };
     collectSources: ({ processedIds, maxPages, limit }?: any) => Promise<any>;
@@ -28,6 +29,7 @@ export interface PlatformDependencies {
     readAccount: () => Promise<any>;
     readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
     searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
+    readExploreRecommendations: (args?: import("./types.js").ExploreRecommendationOptions) => Promise<any>;
     readFeedback: ({ targets, replyLimit }?: any) => Promise<any>;
     readPerson: (target: any) => Promise<any>;
     readPost: (target: any) => Promise<any>;

package/dist/platform-rules.js

@@ -34,7 +34,13 @@ export const source = (post, page) => ({
     images: post.images ?? [],
     media: post.media ?? [],
     links: post.links ?? [],
-    metrics: [...(post.buttons ?? []), ...(post.metrics ?? [])],
+    metrics: [
+        ...new Set([...(post.buttons ?? []), ...(post.metrics ?? [])]
+            .map((metric) => typeof metric === "string" ? metric : metric?.label)
+            .filter((label) => typeof label === "string" &&
+            /(?:回复|转帖|喜欢|书签|观看|查看|引用|replies|reply|reposts?|retweets?|likes?|bookmarks?|views?|quotes?)/i.test(label) &&
+            /\d/.test(label))),
+    ],
     needsExpansion: post.needsExpansion,
     missing: [
         ...(post.missing ?? []),

package/dist/platform-writing.js

@@ -1,3 +1,4 @@
+import { publicationTime } from "./publication-time.js";
 import { xURL, sameHandle, sameText, samePublishedText, matchesReviewedAssets, } from "./platform-rules.js";
 export class PlatformWriting {
     #observed;
@@ -204,9 +205,9 @@ export class PlatformWriting {
             /^\d+$/.test(post.id ?? "") &&
             matchesReviewedAssets(post, action.assets) &&
             !(action.beforeIds ?? []).includes(post.id) &&
-            Number.isFinite(Date.parse(post.datetime)) &&
-            Date.parse(post.datetime) >= Date.parse(action.intentAt) &&
-            Date.parse(post.datetime) <= this.#clock() + 5000 &&
+            Number.isFinite(publicationTime(post)) &&
+            publicationTime(post) >= Date.parse(action.intentAt) &&
+            publicationTime(post) <= this.#clock() + 5000 &&
             !post.needsExpansion);
     }
     async readQuotedReceipt(value, action, candidate) {

package/dist/platform.d.ts

@@ -1,3 +1,4 @@
+import { createPlatformCollections } from "./platform-collections.js";
 export { xURL } from "./platform-rules.js";
 export declare class XPlatform {
     #private;
@@ -8,6 +9,7 @@ export declare class XPlatform {
     readAccount: () => Promise<any>;
     readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
     searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
+    readExploreRecommendations: ReturnType<typeof createPlatformCollections>["readExploreRecommendations"];
     readFeedback: ({ targets, replyLimit }?: any) => Promise<any>;
     readPerson: (target: any) => Promise<any>;
     readPost: (target: any) => Promise<any>;

package/dist/platform.js

@@ -23,6 +23,7 @@ export class XPlatform {
     #readCreator;
     #readBookmarks;
     #searchSources;
+    #readExploreRecommendations;
     #createPlatformDiagnosticsResult;
     #followStage;
     #captureProof;
@@ -41,6 +42,7 @@ export class XPlatform {
     readAccount;
     readBookmarks;
     searchSources;
+    readExploreRecommendations;
     readFeedback;
     readPerson;
     readPost;
@@ -79,11 +81,12 @@ export class XPlatform {
             browser: browser,
             choose: this.#choose,
         });
-        const { collectSources, readCreator, readBookmarks, searchSources } = this.#createPlatformCollectionsResult;
+        const { collectSources, readCreator, readBookmarks, searchSources, readExploreRecommendations, } = this.#createPlatformCollectionsResult;
         this.#collectSources = collectSources;
         this.#readCreator = readCreator;
         this.#readBookmarks = readBookmarks;
         this.#searchSources = searchSources;
+        this.#readExploreRecommendations = readExploreRecommendations;
         this.#createPlatformDiagnosticsResult = createPlatformDiagnostics({
             clock: this.#clock,
         });
@@ -116,6 +119,7 @@ export class XPlatform {
         this.readAccount = this.#readAccount;
         this.readBookmarks = this.#readBookmarks;
         this.searchSources = this.#searchSources;
+        this.readExploreRecommendations = this.#readExploreRecommendations;
         this.readFeedback = this.#readFeedback;
         this.readPerson = this.#readPerson;
         this.readPeople = this.#createPlatformTargetsResult.readPeople;

package/dist/publication-time.d.ts

@@ -0,0 +1,5 @@
+/** Refine an observed second-resolution timestamp only with its matching public X ID. */
+export declare function publicationTime(post: {
+    id?: string | null;
+    datetime?: string | null;
+}): number;

package/dist/publication-time.js

@@ -0,0 +1,18 @@
+/** Refine an observed second-resolution timestamp only with its matching public X ID. */
+export function publicationTime(post) {
+    const rendered = Date.parse(post.datetime ?? "");
+    if (!Number.isFinite(rendered))
+        return NaN;
+    if (!/^[1-9]\d{17,19}$/.test(post.id ?? ""))
+        return rendered;
+    const id = BigInt(post.id);
+    if (id > 9223372036854775807n)
+        return NaN;
+    // Twitter's published Snowflake layout: 41 timestamp bits, 22 lower bits.
+    const decoded = Number((id >> 22n) + 1288834974657n);
+    if (Math.floor(decoded / 1000) !== Math.floor(rendered / 1000))
+        return NaN;
+    if (rendered % 1000 !== 0 && rendered !== decoded)
+        return NaN;
+    return decoded;
+}

package/dist/reply-discovery.d.ts

@@ -0,0 +1,12 @@
+import type { RoundStore } from "./store.js";
+import type { ReadResult, ReplyDiscoveryOptions, ReplyDiscoveryResult, SearchOptions } from "./types.js";
+/** Read-only discovery; shortlisted evidence still requires semantic review. */
+export declare class ReplyDiscovery {
+    private search;
+    private store;
+    private clock;
+    constructor(search: (args: SearchOptions) => Promise<ReadResult>, store: RoundStore, clock: () => number);
+    private exclusion;
+    private rejection;
+    run(args: ReplyDiscoveryOptions): Promise<ReplyDiscoveryResult>;
+}

package/dist/reply-discovery.js

@@ -0,0 +1,167 @@
+/** Read-only discovery; shortlisted evidence still requires semantic review. */
+export class ReplyDiscovery {
+    search;
+    store;
+    clock;
+    constructor(search, store, clock) {
+        this.search = search;
+        this.store = store;
+        this.clock = clock;
+    }
+    exclusion(state, handles) {
+        const authors = new Set(handles.map((h) => h.replace(/^@/, "").toLowerCase()));
+        const ids = new Set();
+        if (state.accountHandle)
+            authors.add(state.accountHandle.toLowerCase());
+        for (const a of [
+            ...(state.actions ?? []),
+            ...(state.replyAuthorHistory?.entries ?? []),
+        ]) {
+            if (a.kind !== "reply" || a.status === "skipped")
+                continue;
+            const author = a.author ?? a.conversation?.recipientHandle;
+            if (author)
+                authors.add(author.toLowerCase());
+            if (a.postId)
+                ids.add(a.postId);
+        }
+        return { authors, ids };
+    }
+    rejection(p, args, now) {
+        if (!p.id ||
+            !p.author ||
+            !p.url ||
+            !p.body?.trim() ||
+            p.needsExpansion ||
+            p.missing?.length)
+            return "incomplete-source";
+        const time = Date.parse(p.datetime ?? "");
+        if (!Number.isFinite(time) ||
+            time > now ||
+            now - time > (args.maxAgeHours ?? 12) * 3600000)
+            return "source-time";
+        if ((args.chineseOnly ?? true) && !/[\u3400-\u9fff]/u.test(p.body))
+            return "source-language";
+        const raw = p.metrics?.find((m) => /喜欢|点赞|likes?\b/i.test(m));
+        const match = raw?.match(/([\d,]+(?:\.\d+)?)\s*([万千KM])?/i);
+        const multiplier = {
+            万: 10000,
+            千: 1000,
+            K: 1000,
+            M: 1000000,
+        };
+        const likes = match
+            ? Number(match[1].replaceAll(",", "")) *
+                (multiplier[(match[2] ?? "").toUpperCase()] ?? 1)
+            : NaN;
+        if (!Number.isFinite(likes) || likes < (args.minLikes ?? 20))
+            return "source-likes";
+    }
+    async run(args) {
+        const target = args.target ?? 20, maxWindows = args.maxWindows ?? 12;
+        if (!args.queries?.length ||
+            args.queries.length > 10 ||
+            args.queries.some((q) => !q.trim()) ||
+            !Number.isInteger(target) ||
+            target < 1 ||
+            target > 50 ||
+            !Number.isInteger(maxWindows) ||
+            maxWindows < 1 ||
+            maxWindows > 30 ||
+            !Number.isFinite(args.minLikes ?? 20) ||
+            (args.minLikes ?? 20) < 0 ||
+            !Number.isFinite(args.maxAgeHours ?? 12) ||
+            (args.maxAgeHours ?? 12) <= 0) {
+            return {
+                status: "needsDecision",
+                reason: "discovery-options-invalid",
+                candidates: [],
+                examinedIds: [],
+                windows: [],
+                rejections: {},
+                targetReached: false,
+                pageComplete: false,
+            };
+        }
+        const examined = new Set(args.processedIds ?? []), authors = new Set();
+        const candidates = [], windows = [], rejections = {};
+        let reason;
+        for (let i = 0; i < maxWindows && candidates.length < target; i++) {
+            const now = this.clock(), hour = new Date(now + 8 * 3600000).getUTCHours();
+            if (hour < 7) {
+                reason = "night-platform-boundary";
+                break;
+            }
+            const excluded = this.exclusion((await this.store.load()).state, args.excludedHandles ?? []);
+            const query = args.queries[i % args.queries.length];
+            const request = {
+                query,
+                processedIds: [...examined, ...excluded.ids],
+                limit: 5,
+                maxPages: 3,
+                mode: "decision",
+            };
+            let read = await this.search(request);
+            if ((read.reason === "source-page-unconfirmed" ||
+                read.missing?.includes("source-page-unconfirmed")) &&
+                new Date(this.clock() + 8 * 3600000).getUTCHours() >= 7)
+                read = await this.search(request);
+            windows.push({
+                query,
+                evidenceRef: read.evidenceRef,
+                status: read.status,
+                missing: read.missing ?? [],
+                observed: read.sources?.length ?? 0,
+            });
+            if (read.status === "needsCapability" ||
+                read.missing?.includes("platform-alert") ||
+                read.reason === "night-platform-boundary") {
+                reason = read.reason ?? "platform-alert";
+                break;
+            }
+            for (const post of read.sources ?? []) {
+                if (post.id && examined.has(post.id))
+                    continue;
+                if (post.id)
+                    examined.add(post.id);
+                const author = post.author?.toLowerCase();
+                const rejection = author && (excluded.authors.has(author) || authors.has(author))
+                    ? "author-history-or-duplicate"
+                    : post.id && excluded.ids.has(post.id)
+                        ? "target-history"
+                        : this.rejection(post, args, this.clock());
+                if (rejection || !read.evidenceRef) {
+                    const key = rejection ?? "source-proof-missing";
+                    rejections[key] = (rejections[key] ?? 0) + 1;
+                    continue;
+                }
+                candidates.push({
+                    post,
+                    evidenceRef: read.evidenceRef,
+                    query,
+                    requiresReview: true,
+                });
+                authors.add(author);
+                if (candidates.length === target)
+                    break;
+            }
+        }
+        const result = {
+            status: candidates.length >= target ? "observed" : "needsDecision",
+            reason: reason ??
+                (candidates.length < target ? "bounded-candidate-shortage" : undefined),
+            candidates,
+            examinedIds: [...examined],
+            windows,
+            rejections,
+            targetReached: candidates.length >= target,
+            pageComplete: false,
+        };
+        result.evidenceRef = await this.store.recordProof({
+            operation: "discoverReplyCandidates",
+            capturedAt: new Date(this.clock()).toISOString(),
+            result,
+        });
+        return result;
+    }
+}

package/dist/results.js

@@ -90,6 +90,17 @@ export function source(value, page) {
                 : []);
     if (out.links)
         out.links = out.links.filter((link) => isContentLink(link, out));
+    if (raw.metrics !== undefined) {
+        const metrics = list(raw.metrics).flatMap((value) => {
+            if (typeof value === "string")
+                return [value];
+            const label = object(value).label;
+            return typeof label === "string" ? [label] : [];
+        });
+        out.metrics = [
+            ...new Set(metrics.filter((label) => /(?:回复|转帖|喜欢|书签|观看|查看|引用|replies|reply|reposts?|retweets?|likes?|bookmarks?|views?|quotes?)/i.test(label) && /\d/.test(label))),
+        ];
+    }
     if (strings(raw.missing).length)
         out.missing = strings(raw.missing);
     return out;
@@ -200,6 +211,28 @@ export function readResult(operation, value, mode) {
         out.complete = false;
     if (raw.ids !== undefined)
         out.ids = strings(raw.ids);
+    if (operation === "readExploreRecommendations") {
+        const origin = object(raw.sourceOrigin);
+        try {
+            const page = new URL(String(origin.page));
+            if (origin.kind === "explore-recommendations" &&
+                page.protocol === "https:" &&
+                page.hostname === "x.com" &&
+                !page.username &&
+                !page.password &&
+                !page.port &&
+                page.pathname.replace(/\/+$/, "") === "/explore" &&
+                ["为你推荐", "For you"].includes(String(origin.selectedTab)))
+                out.sourceOrigin = {
+                    kind: "explore-recommendations",
+                    page: page.href,
+                    selectedTab: String(origin.selectedTab),
+                };
+        }
+        catch {
+            /* Unverified provenance is omitted at the public business boundary. */
+        }
+    }
     const missing = strings(raw.missing);
     if (list(raw.alerts).length && !missing.includes("platform-alert"))
         missing.push("platform-alert");

package/dist/types.d.ts

@@ -93,6 +93,11 @@ export interface Diagnostic {
     next?: "inspect-local-proof" | "restore-proof-store";
     evidenceRef?: EvidenceRef;
 }
+export interface SourceOriginEvidence {
+    kind: "explore-recommendations";
+    page: string;
+    selectedTab: "为你推荐" | "For you";
+}
 export interface ReadResult {
     status: "observed" | "needsDecision" | "needsCapability";
     fresh?: boolean;
@@ -124,6 +129,7 @@ export interface ReadResult {
         scopeComplete?: boolean;
     };
     sources?: PostEvidence[];
+    sourceOrigin?: SourceOriginEvidence;
     post?: PostEvidence;
     context?: PostEvidence[];
     threadPosts?: PostEvidence[];
@@ -253,6 +259,40 @@ export interface BookmarkOptions extends WindowOptions {
 export interface SearchOptions extends WindowOptions {
     query: string;
 }
+export interface ReplyDiscoveryOptions {
+    queries: string[];
+    target?: number;
+    maxWindows?: number;
+    processedIds?: string[];
+    excludedHandles?: string[];
+    minLikes?: number;
+    maxAgeHours?: number;
+    chineseOnly?: boolean;
+}
+export interface ReplyDiscoveryResult {
+    status: "observed" | "needsDecision";
+    reason?: string;
+    candidates: {
+        post: PostEvidence;
+        evidenceRef: EvidenceRef;
+        query: string;
+        requiresReview: true;
+    }[];
+    examinedIds: string[];
+    windows: {
+        query: string;
+        evidenceRef?: EvidenceRef;
+        status: ReadResult["status"];
+        missing: string[];
+        observed: number;
+    }[];
+    rejections: Record<string, number>;
+    targetReached: boolean;
+    pageComplete: false;
+    evidenceRef?: EvidenceRef;
+}
+export interface ExploreRecommendationOptions extends WindowOptions {
+}
 export interface CreatorOptions {
     handle: string;
     target?: number;
@@ -562,7 +602,9 @@ export interface XGrowthHarness {
     readPeople(args: PeopleOptions): Promise<ReadResult>;
     readFollowbackAudit(args: FollowbackAuditOptions): Promise<FollowbackAuditResult>;
     readBookmarks(args: BookmarkOptions): Promise<ReadResult>;
+    discoverReplyCandidates(args: ReplyDiscoveryOptions): Promise<ReplyDiscoveryResult>;
     searchSources(args: SearchOptions): Promise<ReadResult>;
+    readExploreRecommendations(args?: ExploreRecommendationOptions): Promise<ReadResult>;
     readIncomingReplies(args?: IncomingReplyOptions): Promise<ReadResult>;
     readIncomingConversations(args?: IncomingConversationOptions): Promise<IncomingConversationResult>;
     readPost(args: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/x-harness",
-  "version": "0.2.66",
+  "version": "0.2.68",
   "type": "module",
   "description": "Typed X task harness with compact business results and explicit diagnostics.",
   "main": "./dist/index.js",
@@ -42,5 +42,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "0b3b276a3f9390c3ca46514b8ae3845beadf1033"
+  "gitHead": "9d121f1f8b24f7c1082d8f17a3f6ec473d45d534"
 }

package/skill/references/batch-discovery.md

@@ -0,0 +1,2 @@
+# Batch discovery
+For a batch of active replies, first use `x.discoverReplyCandidates({queries:["互关 min_faves:20", "串门 min_faves:20"],target:20,processedIds})`. One call owns serial paginated searches, original-ledger target/author exclusion, deduplication and deterministic age/likes/language/body gates. It performs no writes. Save/reuse `examinedIds` on the original actor; full candidate text, original per-window proofs and the combined proof stay available locally. `requiresReview:true` means relevance, human identity and suitable text still need review. Review the batch, then use existing `replyBatch`; do not rebuild per-person discovery or infer approval from metadata. Partial shortages include rejection totals and window warnings; `pageComplete:false` never claims all of X was read. Night boundary stops further reads. Missing metrics remain unknown. Repair a concrete missing capability at its original owner, validate it and resume the task; no implementation reading for normal calls.

package/skill/references/reads.md

@@ -6,6 +6,7 @@
 | readCreator | handle | target (10;1–50), maxScrolls, navigate, expand, mode |
 | readBookmarks | folder (observed name), or discoverOnly:true | processedIds, limit (1–5), maxPages (1–10), resume, mode |
 | searchSources | query | processedIds, limit (1–5), maxPages (1–10), mode |
+| readExploreRecommendations | none | processedIds, limit (1–5), maxPages (1–10), mode |
 | readPost | target: {postId,url,evidenceRef} | includeContext, resolveQuote, mode |
 | readPerson | target: {handle,url,evidenceRef} | mode |
 | readPeople | target: {url,evidenceRef} | offset, limit (1–5), advance, mode |
@@ -13,20 +14,22 @@
 | inspectAccount | none | mode |
 | inspectRound | taskId (original batch ID) | none |
 
-Targets require proof. Native creator: selected profile, navigate:false; relative time unknown; stop on page change.
+Targets need proof. Native `readCreator` requires a selected profile (`navigate:false`); relative time is unknown. Stop on route changes.
 
-Bookmarks resume:true continues the bound folder; rendered tail ≠ full proof.
+Bookmarks `resume:true` continues the bound folder; rendered tail ≠ full proof.
 
-observed ≠ field completeness; pageComplete:false = scope. View media before describing; preserve target text; keep other reads local.
+`pageComplete:false`: finite scope. Preserve full text; view media before describing.
 
-`readIncomingReplies`: ledger account; skip settled/intent/unknown and processedIds across dates. readPost(includeContext:true) for ancestors; missing context blocks review. Dedup publicly.
+Incoming replies: ledger only; carry processedIds; skip settled/intent/unknown. Read parents with `readPost(includeContext:true)`; deduplicate.
 
-Incoming: `readIncomingConversations({targets?,...window})` combines discovery/context (≤5); no preceding `readIncomingReplies`. Preflight/source failures remain visible. Returns ancestorPath, nodes, confirmed edges, unknown parents and attempts; rootCandidateId is only the earliest loaded ancestor. Missing context blocks review; never guess roots/edges or inbox clearance.
+Incoming conversations: `readIncomingConversations({targets?,...window})` discovers/reads ≤5 chains in one call. Targets need proof; returns nodes, ancestors, confirmed edges, unknown parents and attempts. `rootCandidateId` may not be root. Missing context blocks review; don't infer edges or clearance.
 
 `resolveQuote:true` follows one observed card and returns `post.quoteSource` only after exact destination/body/author/time binding.
 
-`readPeople`: observed follower/following; offset reuses cells; advance scrolls a fresh unique handle. Full bio/blue/relationship; dedup; unknowns need profiles. No Native.
+`readPeople`: selected followers/following; `offset` reuses cells, `advance` scrolls. Returns bio, blue, relationship; dedup. Unknowns need profiles; Native unsupported.
 
 Discovery: names only.
 
-Source decisions retain visible metric labels for batch screening; absent counts stay unknown.
+Count `sourceOrigin` only with confirmed `/explore` “For you” tab; exclude trends/search. Preserve visible counts; absent stays unknown.
+
+Batch replies: [automated discovery](batch-discovery.md).

package/skill/references/receipt-recovery.md

@@ -0,0 +1,7 @@
+# Observed reply receipt recovery
+
+If the root reports an original unknown but a fresh proof or public search exposes its actual own-account permalink, keep that original action. Never derive a receipt ID from a timestamp or guess URLs. Read the observed candidate with root readPost and its original evidenceRef; confirm the actual author, reviewed text, new ID and time at/after intent. A visible parent in context alone is not the final exact-parent verification.
+
+The original ledger already supports observedPublicURL and observedPublicEvidenceRef. Use the existing diagnostics createFileRoundStore transaction to attach only these two fields to that same unknown/intent reply, preserving other actions, executors and counts. Both fields must come from actual observed proof, not a claimed success. Then call root verifySubmission({taskId,actionId}); its normal fresh author/text/time/assets/exact-parent gates settle the original action. A rejected/ambiguous hint remains unknown. Do not manually mark verified, create a replacement action, resend or bypass alerts.
+
+Prepared reply baseline URL timeouts get one internal read-only continuation. A second timeout, unrelated failure, alerts or unconfirmed content stops before intent. Reusing this root behavior is preferable to model-level per-parent rewarming. This does not grant new platform access or override project budgets/windows.

package/skill/references/recovery.md

@@ -4,7 +4,7 @@ Load on failure/unknown only. Keep operation/status/missing/code/proof/error; do
 
 | Signal | Next action and exit condition |
 | --- | --- |
-| unknown submission | `await x.verifySubmission({taskId,actionId})`, same IDs; no replacement action or new submission before resolution. |
+| unknown submission | `await x.verifySubmission({taskId,actionId})`, same IDs; no resend. [Observed link](receipt-recovery.md). |
 | Existing public post needs recovery | `await x.verifyPublishedPost({taskId,draftPath,publicURL,evidenceRef})`; observed URL/proof. sourceLink/sourceLinks: [link proof](source-link-recovery.md). |
 | 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. |