@nextclaw/x-harness 0.2.67 → 0.2.68

package/SOURCE.md

@@ -1,8 +1,8 @@
 # Corresponding source
 
-Version 0.2.67, commit 03a90495bd2c781577399aca850742082abe3556.
+Version 0.2.68, commit 9d121f1f8b24f7c1082d8f17a3f6ec473d45d534.
 
-Complete source, build scripts and dependencies: https://github.com/Peiiii/x-harness/tree/03a90495bd2c781577399aca850742082abe3556
+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,6 +81,7 @@ 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, }: {

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,6 +34,7 @@ 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);
@@ -368,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,
@@ -393,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;
@@ -598,6 +601,9 @@ 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);
     }

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/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/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/types.d.ts

@@ -259,6 +259,38 @@ 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 {
@@ -570,6 +602,7 @@ 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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/x-harness",
-  "version": "0.2.67",
+  "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": "03a90495bd2c781577399aca850742082abe3556"
+  "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

@@ -18,7 +18,7 @@ Targets need proof. Native `readCreator` requires a selected profile (`navigate:
 
 Bookmarks `resume:true` continues the bound folder; rendered tail ≠ full proof.
 
-Observed ≠ complete; `pageComplete:false` means finite scope. Preserve full text; view media before describing; keep raw reads local.
+`pageComplete:false`: finite scope. Preserve full text; view media before describing.
 
 Incoming replies: ledger only; carry processedIds; skip settled/intent/unknown. Read parents with `readPost(includeContext:true)`; deduplicate.
 
@@ -31,3 +31,5 @@ Incoming conversations: `readIncomingConversations({targets?,...window})` discov
 Discovery: names only.
 
 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).