@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/growth-parallel.js

@@ -0,0 +1,332 @@
+import { randomUUID } from "node:crypto";
+import { same } from "./growth-constants.js";
+export class ParallelRound {
+    #load;
+    #scope;
+    #result;
+    #store;
+    #executor;
+    #runtimeId;
+    #stamp;
+    #evidenceExists;
+    #execute;
+    #clock;
+    #releaseSession;
+    #session;
+    parallelRound;
+    constructor(dependencies) {
+        const { load, scope, result, store, executor, runtimeId, stamp, evidenceExists, execute, clock, releaseSession, session, } = dependencies;
+        this.#load = load;
+        this.#scope = scope;
+        this.#result = result;
+        this.#store = store;
+        this.#executor = executor;
+        this.#runtimeId = runtimeId;
+        this.#stamp = stamp;
+        this.#evidenceExists = evidenceExists;
+        this.#execute = execute;
+        this.#clock = clock;
+        this.#releaseSession = releaseSession;
+        this.#session = session;
+        this.parallelRound = this.handleParallelRound.bind(this);
+    }
+    async handleParallelRound({ taskId, decision, selector, requestedKind, maxActions = 10, } = {}) {
+        const executor = this.#executor;
+        if (!executor)
+            throw new Error("parallel-executor-required");
+        if (this.#session.running)
+            return {
+                status: "needsDecision",
+                mayEnd: false,
+                taskId,
+                decision: [{ reason: "same-tab-operation-running" }],
+            };
+        this.#session.running = true;
+        let completed = 0;
+        const needs = [];
+        try {
+            if (!Number.isInteger(maxActions) || maxActions < 1 || maxActions > 100)
+                throw new Error("maxActions须为1–100");
+            let snapshot = await this.#load(taskId);
+            const activeKinds = this.#scope(snapshot.state);
+            if (requestedKind && !activeKinds.includes(requestedKind))
+                return {
+                    ...this.#result(snapshot),
+                    status: "needsDecision",
+                    decision: [{ reason: "kind-outside-round-scope" }],
+                };
+            snapshot = await this.#store.transaction((latest) => {
+                if (latest.state.batchId !== taskId)
+                    throw new Error("original-task-changed");
+                const next = structuredClone(latest.state);
+                next.executions ??= {};
+                if (Object.values(next.executions).some((e) => (e.tabId === executor.tabId || e.id === executor.id) &&
+                    e.runtimeId !== this.#runtimeId &&
+                    (e.activity || e.actionId) &&
+                    this.#store.ownerAlive(e.pid)))
+                    throw new Error("same-tab-or-executor-claimed");
+                next.executions[executor.id] = {
+                    ...next.executions[executor.id],
+                    ...executor,
+                    runtimeId: this.#runtimeId,
+                    pid: this.#store.processId,
+                    activity: "round",
+                    status: "RUNNING",
+                    updatedAt: this.#stamp(),
+                };
+                if (decision?.type === "prepareActions") {
+                    if (!Array.isArray(decision.actions) ||
+                        !same(next.accountHandle, decision.accountHandle) ||
+                        !this.#evidenceExists(decision.ownershipEvidenceRef))
+                        throw new Error("需原账号核验和完整动作队列");
+                    next.actions ??= [];
+                    for (const action of decision.actions) {
+                        if (!action.id ||
+                            !activeKinds.includes(action.kind) ||
+                            action.status !== "prepared" ||
+                            next.actions.some((a) => a.id === action.id))
+                            throw new Error("原prepared动作ID无效");
+                        next.actions.push(structuredClone(action));
+                    }
+                    if (next.items.some((i) => next.actions.filter((a) => a.kind === i.kind && a.status === "prepared").length >
+                        i.planned - i.verified - i.unknown))
+                        throw new Error("队列超过原目标");
+                    if (decision.sharedAttempts) {
+                        if (!Array.isArray(decision.sharedAttempts))
+                            throw new Error("共享尝试须为数组");
+                        next.attempts = [
+                            ...(next.attempts ?? []),
+                            ...structuredClone(decision.sharedAttempts),
+                        ];
+                    }
+                    if (decision.attemptsCoverage) {
+                        if (!decision.attemptsCoverage.complete ||
+                            !this.#evidenceExists(decision.attemptsCoverage.evidenceRef))
+                            throw new Error("共享历史缺证据");
+                        next.attemptsCoverage = structuredClone(decision.attemptsCoverage);
+                    }
+                    if (decision.nextScheduledCheckAt)
+                        next.executions[executor.id].nextScheduledCheckAt =
+                            decision.nextScheduledCheckAt;
+                }
+                else if (decision) {
+                    const action = next.actions?.find((a) => a.id === decision.actionId);
+                    if (!action ||
+                        !activeKinds.includes(action.kind) ||
+                        action.status !== "prepared" ||
+                        action.claim ||
+                        typeof decision.approved !== "boolean" ||
+                        !this.#evidenceExists(decision.evidenceRef))
+                        throw new Error("审查只绑定职责内未领取的原prepared动作");
+                    if (!decision.approved)
+                        action.status = "skipped";
+                    else
+                        action.quality = {
+                            approved: true,
+                            evidenceRef: decision.evidenceRef,
+                            ...(action.kind === "follow"
+                                ? {
+                                    handle: action.handle,
+                                    blue: decision.blue === true,
+                                    chinese: decision.chinese === true,
+                                }
+                                : {
+                                    approvedText: decision.approvedText,
+                                    ...(action.kind === "original"
+                                        ? { draftFingerprint: decision.draftFingerprint }
+                                        : {}),
+                                }),
+                        };
+                }
+                next.updatedAt = this.#stamp();
+                return next;
+            });
+            for (const kind of activeKinds) {
+                const queue = (snapshot.state.actions ?? [])
+                    .filter((a) => a.kind === kind && (!selector || selector(a)))
+                    .sort((a, b) => Number(["intent", "unknown"].includes(b.status)) -
+                    Number(["intent", "unknown"].includes(a.status)));
+                if (snapshot.state.items.find((i) => i.kind === kind).unknown >
+                    snapshot.state.actions.filter((a) => a.kind === kind && ["intent", "unknown"].includes(a.status)).length) {
+                    needs.push({
+                        status: "needsDecision",
+                        reason: "original-unmapped-unknown-needs-dedup",
+                        kind,
+                    });
+                    continue;
+                }
+                for (const original of queue) {
+                    if (completed >= maxActions)
+                        break;
+                    if (["verified", "preexisting", "skipped"].includes(original.status))
+                        continue;
+                    try {
+                        snapshot = await this.#store.transaction((latest) => {
+                            const next = structuredClone(latest.state), action = next.actions.find((a) => a.id === original.id);
+                            if (next.batchId !== taskId)
+                                throw new Error("original-task-changed");
+                            if (["verified", "preexisting", "skipped"].includes(action.status))
+                                return null;
+                            const sameTarget = (other) => other.kind === action.kind &&
+                                (kind === "follow"
+                                    ? same(other.handle, action.handle)
+                                    : kind === "original"
+                                        ? other.draftPath === action.draftPath
+                                        : other.postId === action.postId &&
+                                            other.text === action.text);
+                            if (next.actions.some((a) => a.id !== action.id &&
+                                sameTarget(a) &&
+                                (a.claim ||
+                                    ["intent", "unknown", "verified"].includes(a.status))))
+                                throw new Error("same-target-already-claimed-or-submitted");
+                            if (action.claim && this.#store.ownerAlive(action.claim.pid))
+                                throw new Error("same-action-claimed");
+                            if (Object.values(next.executions).some((e) => e.tabId === executor.tabId &&
+                                e.actionId &&
+                                e.runtimeId !== this.#runtimeId &&
+                                this.#store.ownerAlive(e.pid)))
+                                throw new Error("same-tab-claimed");
+                            this.#session.claim = {
+                                actionId: action.id,
+                                token: randomUUID(),
+                                executorId: executor.id,
+                                runtimeId: this.#runtimeId,
+                                pid: this.#store.processId,
+                                acquiredAt: this.#stamp(),
+                            };
+                            action.claim = this.#session.claim;
+                            next.executions[executor.id].actionId = action.id;
+                            next.updatedAt = this.#stamp();
+                            return next;
+                        });
+                        if (!this.#session.claim)
+                            continue;
+                        const outcome = await this.#execute(snapshot, snapshot.state.actions.find((a) => a.id === original.id));
+                        snapshot = outcome.snapshot;
+                        completed++;
+                        if (outcome.need) {
+                            needs.push(outcome.need);
+                            break;
+                        }
+                    }
+                    catch (error) {
+                        needs.push({
+                            status: "needsDecision",
+                            kind,
+                            actionId: original.id,
+                            reason: /claimed|same-target/.test(error.message)
+                                ? "action-or-tab-claimed"
+                                : /budget|capacity/.test(error.message)
+                                    ? "shared-reservation-unavailable"
+                                    : "harness-boundary-error",
+                            error: error.message.slice(0, 240),
+                        });
+                        break;
+                    }
+                    finally {
+                        if (this.#session.claim) {
+                            const owned = this.#session.claim;
+                            this.#session.claim = null;
+                            snapshot = await this.#store.transaction((latest) => {
+                                const next = structuredClone(latest.state), action = next.actions?.find((a) => a.id === owned.actionId);
+                                if (action?.claim?.token !== owned.token)
+                                    return null;
+                                delete action.claim;
+                                if (next.executions[executor.id]?.runtimeId === this.#runtimeId)
+                                    delete next.executions[executor.id].actionId;
+                                next.updatedAt = this.#stamp();
+                                return next;
+                            });
+                        }
+                    }
+                }
+            }
+            snapshot = await this.#store.transaction(async (latest) => {
+                const next = structuredClone(latest.state), own = next.executions[executor.id];
+                const pending = next.items.filter((i) => activeKinds.includes(i.kind) &&
+                    (i.verified < i.planned || i.unknown));
+                own.status = pending.length ? "RUNNING" : "COMPLETE";
+                const scheduled = own.nextScheduledCheckAt ??
+                    next.execution?.nextScheduledCheckAt ??
+                    next.stop?.nextScheduledCheckAt;
+                const waits = pending.map((i) => needs.find((n) => n.status === "waiting" &&
+                    next.actions.find((a) => a.id === n.actionId)?.kind ===
+                        i.kind));
+                if (pending.length &&
+                    pending.every((i) => !i.unknown &&
+                        next.actions.filter((a) => a.kind === i.kind && a.status === "prepared").length >=
+                            i.planned - i.verified) &&
+                    waits.every((w) => w && Date.parse(w.resumeAt) > this.#clock()) &&
+                    Date.parse(scheduled) > this.#clock()) {
+                    for (let i = 0; i < pending.length; i++) {
+                        const proof = await this.#store.recordProof({
+                            observedAt: this.#stamp(),
+                            ...waits[i],
+                            attempts: next.attempts,
+                        });
+                        Object.assign(pending[i], {
+                            actionable: false,
+                            reason: `harness:${waits[i].reason}`,
+                            resumeAt: waits[i].resumeAt,
+                            resumeWhen: `不早于${waits[i].resumeAt}重核`,
+                            blockEvidence: [proof],
+                        });
+                    }
+                    own.status = "WAITING";
+                    own.stop = {
+                        independentActionsHandled: true,
+                        nextScheduledCheckAt: scheduled,
+                        nextEligibleCheckAt: waits.map((w) => w.resumeAt).sort()[0],
+                    };
+                }
+                next.status = next.items.every((i) => i.verified === i.planned && !i.unknown)
+                    ? "COMPLETE"
+                    : "RUNNING";
+                own.updatedAt = next.updatedAt = this.#stamp();
+                return next;
+            });
+            const out = this.#result(snapshot, needs);
+            if (!out.mayEnd && !needs.length && completed >= maxActions)
+                return {
+                    ...out,
+                    status: "checkpoint",
+                    checkpoint: {
+                        taskId,
+                        executorId: executor.id,
+                        completed,
+                        resume: "resumeGrowthRound",
+                    },
+                };
+            if (!out.mayEnd && !needs.length)
+                out.decision = [
+                    { reason: "prepared-queue-does-not-cover-original-targets" },
+                ];
+            return out;
+        }
+        catch (error) {
+            return {
+                status: "needsDecision",
+                mayEnd: false,
+                taskId,
+                evidenceRef: this.#store.path,
+                decision: [
+                    {
+                        reason: "harness-boundary-error",
+                        error: error.message.slice(0, 240),
+                    },
+                ],
+            };
+        }
+        finally {
+            try {
+                await this.#releaseSession(taskId);
+            }
+            finally {
+                this.#session.running = false;
+            }
+        }
+    }
+}
+export function createParallelRound(...args) {
+    return new ParallelRound(...args);
+}

package/dist/growth-plan.d.ts

@@ -0,0 +1,9 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare class PlannedRound {
+    #private;
+    round: ({ taskId, decision, selector, requestedKind }?: any) => Promise<any>;
+    constructor(dependencies: Pick<GrowthDependencies, "store" | "load" | "result" | "evidenceExists" | "save" | "execute" | "clock" | "stamp">);
+    private applyRoundDecision;
+    private handleRound;
+}
+export declare function createPlannedRound(...args: ConstructorParameters<typeof PlannedRound>): PlannedRound;

package/dist/growth-plan.js

@@ -0,0 +1,229 @@
+import { kinds, same } from "./growth-constants.js";
+export class PlannedRound {
+    #store;
+    #load;
+    #result;
+    #evidenceExists;
+    #save;
+    #execute;
+    #clock;
+    #stamp;
+    round;
+    constructor(dependencies) {
+        const { store, load, result, evidenceExists, save, execute, clock, stamp } = dependencies;
+        this.#store = store;
+        this.#load = load;
+        this.#result = result;
+        this.#evidenceExists = evidenceExists;
+        this.#save = save;
+        this.#execute = execute;
+        this.#clock = clock;
+        this.#stamp = stamp;
+        this.round = this.handleRound.bind(this);
+    }
+    async applyRoundDecision(snapshot, decision, activeKinds) {
+        if (decision?.type === "prepareActions") {
+            if (!Array.isArray(decision.actions) ||
+                !/^[A-Za-z0-9_]{1,15}$/.test(decision.accountHandle ?? "") ||
+                !this.#evidenceExists(decision.ownershipEvidenceRef) ||
+                (snapshot.state.execution?.owner &&
+                    snapshot.state.execution.owner !== "harness"))
+                throw new Error("需原账号执行权核验和完整动作队列；不接管已有执行者");
+            if (snapshot.state.accountHandle &&
+                !same(snapshot.state.accountHandle, decision.accountHandle))
+                throw new Error("不能变更原账号");
+            const next = structuredClone(snapshot.state);
+            next.actions ??= [];
+            for (const action of decision.actions) {
+                if (!action.id ||
+                    !activeKinds.includes(action.kind) ||
+                    action.status !== "prepared" ||
+                    next.actions.some((a) => a.id === action.id))
+                    throw new Error("仅添加职责范围内唯一ID的prepared原动作");
+                next.actions.push(structuredClone(action));
+            }
+            if (next.items.some((item) => next.actions.filter((a) => a.kind === item.kind && a.status === "prepared").length >
+                item.planned - item.verified - item.unknown))
+                throw new Error("prepared队列不能越过原批次未决目标");
+            next.accountHandle = decision.accountHandle;
+            next.execution = {
+                ...next.execution,
+                owner: "harness",
+                exclusive: true,
+                ownershipEvidenceRef: decision.ownershipEvidenceRef,
+                ...(decision.nextScheduledCheckAt
+                    ? { nextScheduledCheckAt: decision.nextScheduledCheckAt }
+                    : {}),
+            };
+            if (decision.attemptsCoverage) {
+                if (!decision.attemptsCoverage.complete ||
+                    !this.#evidenceExists(decision.attemptsCoverage.evidenceRef))
+                    throw new Error("共享历史须完整取证；不能默认为零");
+                next.attemptsCoverage = structuredClone(decision.attemptsCoverage);
+            }
+            if (decision.sharedAttempts) {
+                if (!Array.isArray(decision.sharedAttempts))
+                    throw new Error("共享尝试记录必须为数组");
+                next.attempts = [
+                    ...(next.attempts ?? []),
+                    ...structuredClone(decision.sharedAttempts),
+                ];
+            }
+            snapshot = await this.#save(snapshot, next);
+        }
+        else if (decision) {
+            const action = snapshot.state.actions?.find((a) => a.id === decision.actionId);
+            if (action && !activeKinds.includes(action.kind))
+                throw new Error("kind-outside-round-scope");
+            if (!action ||
+                action.status !== "prepared" ||
+                typeof decision.approved !== "boolean" ||
+                !this.#evidenceExists(decision.evidenceRef))
+                throw new Error("决策仅能绑定原prepared动作及真实审查证据");
+            const next = structuredClone(snapshot.state), target = next.actions.find((a) => a.id === action.id);
+            if (!decision.approved)
+                target.status = "skipped";
+            else
+                target.quality = {
+                    approved: true,
+                    evidenceRef: decision.evidenceRef,
+                    ...(action.kind === "follow"
+                        ? {
+                            handle: action.handle,
+                            blue: decision.blue === true,
+                            chinese: decision.chinese === true,
+                        }
+                        : {
+                            approvedText: decision.approvedText,
+                            ...(action.kind === "original"
+                                ? { draftFingerprint: decision.draftFingerprint }
+                                : {}),
+                        }),
+                };
+            snapshot = await this.#save(snapshot, next);
+        }
+        return snapshot;
+    }
+    async handleRound({ taskId, decision, selector, requestedKind, } = {}) {
+        try {
+            return await this.#store.withLock(async () => {
+                let snapshot = await this.#load(taskId);
+                const activeKinds = snapshot.state.scopeKinds ?? kinds;
+                if (requestedKind && !activeKinds.includes(requestedKind))
+                    return {
+                        ...this.#result(snapshot),
+                        status: "needsDecision",
+                        mayEnd: false,
+                        decision: [
+                            { kind: requestedKind, reason: "kind-outside-round-scope" },
+                        ],
+                    };
+                snapshot = await this.applyRoundDecision(snapshot, decision, activeKinds);
+                const needs = [];
+                for (const kind of activeKinds) {
+                    const queue = (snapshot.state.actions ?? [])
+                        .filter((a) => a.kind === kind && (!selector || selector(a)))
+                        .sort((a, b) => Number(["intent", "unknown"].includes(b.status)) -
+                        Number(["intent", "unknown"].includes(a.status)));
+                    // A selector narrows this invocation, not the original unresolved ledger.
+                    const unresolved = (snapshot.state.actions ?? []).filter((a) => a.kind === kind && ["intent", "unknown"].includes(a.status)).length;
+                    if (snapshot.state.items.find((i) => i.kind === kind).unknown >
+                        unresolved) {
+                        needs.push({
+                            status: "needsDecision",
+                            reason: "original-unmapped-unknown-needs-dedup",
+                            kind,
+                        });
+                        continue;
+                    }
+                    for (const original of queue) {
+                        const item = snapshot.state.items.find((i) => i.kind === kind);
+                        const action = snapshot.state.actions.find((a) => a.id === original.id);
+                        if (["verified", "preexisting", "skipped"].includes(action.status))
+                            continue;
+                        if (item.verified >= item.planned && action.status === "prepared")
+                            continue;
+                        const outcome = await this.#execute(snapshot, action);
+                        snapshot = outcome.snapshot;
+                        if (outcome.need) {
+                            needs.push(outcome.need);
+                            break;
+                        } // Stop only this kind; continue independent kinds.
+                    }
+                }
+                if (snapshot.state.items
+                    .filter((i) => activeKinds.includes(i.kind))
+                    .every((i) => i.verified === i.planned && i.unknown === 0)) {
+                    const next = structuredClone(snapshot.state);
+                    next.status = "COMPLETE";
+                    snapshot = await this.#save(snapshot, next);
+                }
+                else {
+                    const pending = snapshot.state.items.filter((i) => activeKinds.includes(i.kind) &&
+                        (i.verified < i.planned || i.unknown > 0));
+                    const waits = pending.map((item) => needs.find((n) => n.status === "waiting" &&
+                        snapshot.state.actions.find((a) => a.id === n.actionId)
+                            ?.kind === item.kind));
+                    const scheduled = snapshot.state.execution?.nextScheduledCheckAt ??
+                        snapshot.state.stop?.nextScheduledCheckAt;
+                    const covered = pending.every((item) => item.unknown === 0 &&
+                        (snapshot.state.actions ?? []).filter((a) => a.kind === item.kind && a.status === "prepared").length >=
+                            item.planned - item.verified);
+                    if (covered &&
+                        waits.every((w) => w && Date.parse(w.resumeAt) > this.#clock()) &&
+                        Date.parse(scheduled) > this.#clock()) {
+                        const next = structuredClone(snapshot.state);
+                        for (let i = 0; i < pending.length; i++) {
+                            const item = next.items.find((a) => a.kind === pending[i].kind), wait = waits[i];
+                            const proof = await this.#store.recordProof({
+                                observedAt: this.#stamp(),
+                                reason: wait.reason,
+                                resumeAt: wait.resumeAt,
+                                attempts: next.attempts,
+                            });
+                            Object.assign(item, {
+                                actionable: false,
+                                reason: `harness:${wait.reason}`,
+                                resumeAt: wait.resumeAt,
+                                resumeWhen: `不早于${wait.resumeAt}重核预算及fresh状态`,
+                                blockEvidence: [proof],
+                            });
+                        }
+                        next.status = "WAITING";
+                        next.stop = {
+                            independentActionsHandled: true,
+                            nextScheduledCheckAt: scheduled,
+                            nextEligibleCheckAt: waits.map((w) => w.resumeAt).sort()[0],
+                        };
+                        snapshot = await this.#save(snapshot, next);
+                    }
+                    else if (!needs.length)
+                        needs.push({
+                            status: "needsDecision",
+                            reason: "prepared-queue-does-not-cover-original-targets",
+                        });
+                }
+                return this.#result(snapshot, needs);
+            });
+        }
+        catch (error) {
+            return {
+                status: "needsDecision",
+                mayEnd: false,
+                taskId,
+                evidenceRef: this.#store.path,
+                decision: [
+                    {
+                        reason: error.code === "CONFLICT"
+                            ? "original-ledger-conflict"
+                            : "harness-boundary-error",
+                        error: error.message.slice(0, 240),
+                    },
+                ],
+            };
+        }
+    }
+}
+export function createPlannedRound(...args) {
+    return new PlannedRound(...args);
+}

package/dist/growth-policy.d.ts

@@ -0,0 +1,18 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare class GrowthPolicy {
+    #private;
+    authorizedWindow: (state: any, kind: string) => boolean;
+    scope: (state: any) => any;
+    project: (state: any) => any;
+    capability: (operation: any, input?: any) => any;
+    waitBudget: (state: any) => any;
+    guardInput: (state: any, action: any, independentExecution?: any) => any;
+    constructor(dependencies: Pick<GrowthDependencies, "executor" | "clock" | "evidenceExists" | "platform" | "store">);
+    private handleCapability;
+    private handleWaitBudget;
+    private handleGuardInput;
+    private handleAuthorizedWindow;
+    private handleScope;
+    private handleProject;
+}
+export declare function createGrowthPolicy(...args: ConstructorParameters<typeof GrowthPolicy>): GrowthPolicy;