@alignfirst/openclaw-test 0.20.0

package/dist/runner-args.d.ts

@@ -0,0 +1,11 @@
+export interface RunnerArgs {
+    scenario: string;
+    channel: string;
+    modelId: string;
+    modelRef: string;
+    iterationIndex: number;
+    iterationWidth: number;
+    baseStamp: string;
+    resultsDir: string;
+}
+export declare function parseArgs(argv: string[]): RunnerArgs;

package/dist/runner-args.js

@@ -0,0 +1,84 @@
+export function parseArgs(argv) {
+    let scenario;
+    let channel;
+    let modelId;
+    let modelRef;
+    let iterationIndex;
+    let iterationWidth;
+    let baseStamp;
+    let resultsDir;
+    for (let i = 0; i < argv.length; ++i) {
+        const a = argv[i];
+        const eat = (flag) => {
+            if (a === flag)
+                return argv[++i] ?? "";
+            return a.slice(`${flag}=`.length);
+        };
+        if (a === "--scenario" || a.startsWith("--scenario=")) {
+            scenario = eat("--scenario");
+        }
+        else if (a === "--channel" || a.startsWith("--channel=")) {
+            channel = eat("--channel");
+        }
+        else if (a === "--model-id" || a.startsWith("--model-id=")) {
+            modelId = eat("--model-id");
+        }
+        else if (a === "--model-ref" || a.startsWith("--model-ref=")) {
+            modelRef = eat("--model-ref");
+        }
+        else if (a === "--iteration-index" || a.startsWith("--iteration-index=")) {
+            iterationIndex = parseNonNegativeInt(eat("--iteration-index"), "--iteration-index", 1);
+        }
+        else if (a === "--iteration-width" || a.startsWith("--iteration-width=")) {
+            iterationWidth = parseNonNegativeInt(eat("--iteration-width"), "--iteration-width", 0);
+        }
+        else if (a === "--base-stamp" || a.startsWith("--base-stamp=")) {
+            baseStamp = eat("--base-stamp");
+        }
+        else if (a === "--results-dir" || a.startsWith("--results-dir=")) {
+            resultsDir = eat("--results-dir");
+        }
+        else {
+            throw new Error(`runner: unknown argument: ${a}`);
+        }
+    }
+    if (!scenario)
+        throw new Error("runner: --scenario <id> is required");
+    if (!channel)
+        throw new Error("runner: --channel <id> is required");
+    if (!modelId)
+        throw new Error("runner: --model-id <id> is required");
+    if (!modelRef)
+        throw new Error("runner: --model-ref <ref> is required");
+    if (iterationIndex === undefined)
+        throw new Error("runner: --iteration-index <n> is required");
+    if (iterationWidth === undefined)
+        throw new Error("runner: --iteration-width <w> is required");
+    if (!baseStamp)
+        throw new Error("runner: --base-stamp <iso> is required");
+    if (!resultsDir)
+        throw new Error("runner: --results-dir <path> is required");
+    return {
+        scenario,
+        channel,
+        modelId,
+        modelRef,
+        iterationIndex,
+        iterationWidth,
+        baseStamp,
+        resultsDir,
+    };
+}
+function parseNonNegativeInt(raw, flag, min) {
+    if (raw === undefined || raw === "") {
+        throw new Error(`runner: ${flag} expects an integer >= ${min}`);
+    }
+    if (!/^-?\d+$/.test(raw)) {
+        throw new Error(`runner: ${flag} expects an integer, got ${JSON.stringify(raw)}`);
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min) {
+        throw new Error(`runner: ${flag} expects an integer >= ${min}, got ${JSON.stringify(raw)}`);
+    }
+    return n;
+}

package/dist/runner.d.ts

@@ -0,0 +1,2 @@
+export declare function main(argv?: string[]): Promise<void>;
+export declare function leadingCli(input: unknown): string | undefined;

package/dist/runner.js

@@ -0,0 +1,371 @@
+import { pollQaBus } from "@alignfirst/openclaw-channel-mock-core";
+import { randomBytes } from "node:crypto";
+import { createWriteStream, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { cellLeafName, writeCellResult } from "./cell-result.js";
+import { createContext, } from "./context.js";
+import { judgeCostUsd } from "./cost.js";
+import { aggregateAgentToolCalls, fetchTranscriptSnapshot, readTranscriptCost, waitForTranscriptQuiescence, } from "./transcript-log.js";
+import { startMockCliServer } from "./mock-cli-server.js";
+import { parseArgs } from "./runner-args.js";
+const ARTIFACTS_ROOT = process.env.OPENCLAW_TEST_ARTIFACTS_DIR ?? "/opt/openclaw-test/artifacts";
+const SCENARIOS_ROOT = process.env.OPENCLAW_TEST_SCENARIOS_DIR ?? "/opt/openclaw-test/src/scenarios";
+const BUS_URL = process.env.OPENCLAW_TEST_BUS_URL ?? "http://bus:43123";
+export async function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    console.log(`runner: scenario=${args.scenario} channel=${args.channel} iter=${args.iterationIndex}/${args.iterationWidth}`);
+    const exitCode = await runCell(args);
+    process.exit(exitCode);
+}
+async function runCell(args) {
+    const mockCliServer = startMockCliServer();
+    try {
+        const setup = setupRun(args);
+        const { ctx, internals, outDir, conversationId, accountId, startedAtIso, startedAtMs, logStream, } = setup;
+        mockCliServer.bind({
+            conversationId,
+            handlers: internals.getMockHandlers(),
+            emitCliMock: internals.emitCliMock,
+            isScenarioEnded: () => internals.isScenarioEnded(),
+        });
+        const initialCursor = await ctx.getCursor();
+        const subscription = startOutboundSubscription({
+            accountId,
+            conversationId,
+            initialCursor,
+            onMessage: internals.emitOutboundReceived,
+        });
+        const { failure } = await executeScenario(args.scenario, ctx);
+        await subscription.stop();
+        await mockCliServer.release();
+        const finishedAtMs = Date.now();
+        const durationMs = finishedAtMs - startedAtMs;
+        const finishedAtIso = new Date(finishedAtMs).toISOString();
+        const { entries, judgeUsages, result } = internals.finalize({ failure });
+        await waitForTranscriptQuiescence({ conversationId, startedAtIso });
+        const snapshot = await fetchTranscriptSnapshot({ conversationId, startedAtIso });
+        const { cost: agentCostUsd, turns: agentTurns } = readTranscriptCost(snapshot);
+        const judgeUsd = judgeUsages.reduce((sum, u) => sum + judgeCostUsd(u), 0);
+        // The per-session store dies with the stack recreation, so keep the raw
+        // transcripts as a cell artifact for post-mortems.
+        writeFileSync(join(outDir, "transcripts.json"), JSON.stringify(snapshot.sessions));
+        const agentCalls = aggregateAgentToolCalls(snapshot.sessions);
+        pairAgentCallsWithCliMocks(agentCalls, entries);
+        if (agentCalls.length === 0 && (snapshot.error !== undefined || snapshot.databases === 0)) {
+            entries.push({
+                entrySeq: entries.length,
+                ts: finishedAtIso,
+                kind: "scenarioLog",
+                message: snapshot.error !== undefined
+                    ? `agentToolCall parsing failed: ${snapshot.error}`
+                    : "agentToolCall parsing skipped: no agent session store found in the gateway",
+            });
+        }
+        const agentEntries = buildAgentToolCallEntries(agentCalls, entries.length, finishedAtIso);
+        appendAgentCallsToLog(logStream, agentEntries);
+        await closeStream(logStream);
+        const merged = mergeTimeline(entries, agentEntries);
+        const report = {
+            schemaVersion: 4,
+            scenario: args.scenario,
+            channel: args.channel,
+            model: args.modelId,
+            conversationId,
+            accountId,
+            startedAt: startedAtIso,
+            finishedAt: finishedAtIso,
+            durationMs,
+            cost: {
+                agentUsd: agentCostUsd,
+                judgeUsd,
+                totalUsd: agentCostUsd + judgeUsd,
+                agentTurns,
+            },
+            result,
+            entries: merged.map(prepareEntryForReport),
+        };
+        // Write the cell record BEFORE the artifact-dir rename, to a stable sibling path.
+        const leafBase = basename(outDir);
+        const resultsPath = join(args.resultsDir, `${leafBase}.json`);
+        mkdirSync(args.resultsDir, { recursive: true });
+        const finalOutDir = writeReportArtifacts(outDir, result.verdict, report);
+        writeCellResult(resultsPath, {
+            schemaVersion: 3,
+            scenarioId: args.scenario,
+            channel: args.channel,
+            model: args.modelId,
+            iterationIndex: args.iterationIndex,
+            verdict: result.verdict,
+            durationMs,
+            conversationId,
+            artifactDirName: basename(finalOutDir),
+            agentCostUsd,
+            agentTurns,
+            judgeUsd,
+            judgeUsages,
+        });
+        console.log(`[${args.channel}] ${args.scenario} ${result.verdict} in ${durationMs}ms — ${finalOutDir}`);
+        return result.verdict === "pass" ? 0 : 1;
+    }
+    finally {
+        await mockCliServer.close();
+    }
+}
+function setupRun(args) {
+    const conversationId = `${args.scenario}-${args.channel}-${shortRand()}`;
+    const accountId = args.channel;
+    const leaf = cellLeafName({
+        scenarioId: args.scenario,
+        modelId: args.modelId,
+        channel: args.channel,
+        iterationIndex: args.iterationIndex,
+        iterationWidth: args.iterationWidth,
+    });
+    const outDir = join(ARTIFACTS_ROOT, args.baseStamp, leaf);
+    mkdirSync(outDir, { recursive: true });
+    const startedAtIso = new Date().toISOString();
+    const startedAtMs = Date.now();
+    const logStream = createWriteStream(join(outDir, "scenario-log.jsonl"), { flags: "a" });
+    const emitSink = (event) => {
+        if (event.type === "entry") {
+            logStream.write(`${JSON.stringify(event.entry)}\n`);
+        }
+        else {
+            logStream.write(`${JSON.stringify({ entrySeq: event.entrySeq, augment: event.patch })}\n`);
+        }
+    };
+    const { ctx, internals } = createContext({
+        channel: args.channel,
+        conversationId,
+        startedAtIso,
+        emitSink,
+    });
+    return {
+        ctx,
+        internals,
+        outDir,
+        conversationId,
+        accountId,
+        startedAtIso,
+        startedAtMs,
+        logStream,
+    };
+}
+function startOutboundSubscription(params) {
+    const abort = new AbortController();
+    const done = (async () => {
+        let cursor = params.initialCursor;
+        while (!abort.signal.aborted) {
+            let result;
+            try {
+                result = await pollQaBus({
+                    baseUrl: BUS_URL,
+                    accountId: params.accountId,
+                    cursor,
+                    timeoutMs: 1000,
+                });
+            }
+            catch {
+                if (abort.signal.aborted)
+                    return;
+                await new Promise((r) => setTimeout(r, 200));
+                continue;
+            }
+            cursor = result.cursor;
+            for (const e of result.events) {
+                if (e.kind !== "outbound-message" && e.kind !== "message-edited")
+                    continue;
+                if (e.message.conversation.id !== params.conversationId)
+                    continue;
+                params.onMessage(e.message);
+            }
+        }
+    })();
+    return {
+        stop: async () => {
+            abort.abort();
+            await done.catch(() => { });
+        },
+    };
+}
+async function executeScenario(scenarioId, ctx) {
+    try {
+        const mod = await import(`${SCENARIOS_ROOT}/${scenarioId}.ts`);
+        const fn = mod.default;
+        if (typeof fn !== "function") {
+            throw new Error(`scenario ${scenarioId} has no default export function`);
+        }
+        await fn(ctx);
+        return { failure: undefined };
+    }
+    catch (err) {
+        const e = err;
+        const isAssertion = e?.name === "AssertionError";
+        return {
+            failure: {
+                name: e?.name ?? "Error",
+                message: e?.message ?? String(err),
+                stack: e?.stack,
+                source: isAssertion ? "assertion" : "scenarioThrow",
+            },
+        };
+    }
+}
+function pairAgentCallsWithCliMocks(agentCalls, entries) {
+    const cliMockQueues = new Map();
+    for (const e of entries) {
+        if (e.kind !== "cliMock")
+            continue;
+        const q = cliMockQueues.get(e.call.cli) ?? [];
+        q.push(e.ts);
+        cliMockQueues.set(e.call.cli, q);
+    }
+    for (const call of agentCalls) {
+        const cli = leadingCli(call.input);
+        if (!cli)
+            continue;
+        const q = cliMockQueues.get(cli);
+        if (!q || q.length === 0)
+            continue;
+        call.inferredStartedAt = q.shift();
+    }
+}
+export function leadingCli(input) {
+    if (!input || typeof input !== "object")
+        return;
+    const cmd = input.command;
+    if (typeof cmd !== "string")
+        return;
+    const stripped = cmd.replace(/^(?:\s*cd\s+[^&;|]+(?:&&|;|\|\|)\s*)+/, "");
+    const m = stripped.match(/^\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*([A-Za-z0-9_./-]+)/);
+    if (!m)
+        return;
+    // Reject bare env-assignments (e.g. `FOO=bar` alone): the capture class
+    // stops at `=`, so we'd otherwise return "FOO" as if it were a command.
+    if (stripped[m[0].length] === "=")
+        return;
+    return m[1].split("/").pop();
+}
+/**
+ * Build agentToolCall entries with stable `entrySeq` values continuing the live
+ * jsonl emission order. These values are shared by both artifact files —
+ * `scenario-log.jsonl` (appended at the tail in ts order) and `report.json`
+ * (interleaved with live entries by ts).
+ */
+function buildAgentToolCallEntries(agentCalls, liveEntryCount, fallbackTs) {
+    const sorted = [...agentCalls].sort(compareStartedAt);
+    return sorted.map((call, i) => ({
+        entrySeq: liveEntryCount + i,
+        ts: call.startedAt ?? fallbackTs,
+        kind: "agentToolCall",
+        call,
+    }));
+}
+// A call whose message carried no timestamp sorts to the end, never the front.
+function compareStartedAt(a, b) {
+    if (a.startedAt === undefined)
+        return b.startedAt === undefined ? 0 : 1;
+    if (b.startedAt === undefined)
+        return -1;
+    return a.startedAt < b.startedAt ? -1 : 1;
+}
+/**
+ * Append parsed agentToolCall entries to the tail of `scenario-log.jsonl` in
+ * ts order. Their `entrySeq` values continue past the live entries' and are the
+ * same values used in `report.json` — readers can cross-reference by `entrySeq`.
+ */
+function appendAgentCallsToLog(logStream, agentEntries) {
+    for (const entry of agentEntries) {
+        logStream.write(`${JSON.stringify(entry)}\n`);
+    }
+}
+/**
+ * Interleave live entries with agentToolCall entries by `ts` for `report.json`.
+ * Entries keep their original `entrySeq`; the array order is ts, so iterating
+ * gives the unified timeline while `entrySeq` remains a cross-file identifier.
+ */
+function mergeTimeline(entries, agentEntries) {
+    return [...entries, ...agentEntries].sort((a, b) => {
+        if (a.ts !== b.ts)
+            return a.ts < b.ts ? -1 : 1;
+        return kindOrder(a.kind) - kindOrder(b.kind);
+    });
+}
+function kindOrder(k) {
+    return k === "agentToolCall" ? 0 : 1;
+}
+const REPORT_CONTENT_TRUNCATE_AT = 60;
+/**
+ * Replace bulky `content` with `truncatedContent` for `report.json` only. The
+ * original entry (already streamed to `scenario-log.jsonl`) keeps the full
+ * content; this returns a shallow-cloned `agentToolCall` entry with the
+ * truncated `result`.
+ */
+function prepareEntryForReport(entry) {
+    if (entry.kind !== "agentToolCall" || !entry.call.result)
+        return entry;
+    const text = truncatableResultText(entry.call.toolName, entry.call.result.content);
+    if (text === undefined || text.length <= REPORT_CONTENT_TRUNCATE_AT)
+        return entry;
+    const truncatedContent = `${text.slice(0, REPORT_CONTENT_TRUNCATE_AT).replace(/\s+$/, "")}…`;
+    return {
+        ...entry,
+        call: {
+            ...entry.call,
+            result: { isError: entry.call.result.isError, truncatedContent },
+        },
+    };
+}
+/**
+ * The string to truncate for `report.json`, or `undefined` to keep `content`
+ * as-is. The `read` tool returns its file content as text blocks rather than a
+ * string, so its text is joined — the file is identified by `input`, so the
+ * report needs no more than a preview.
+ */
+function truncatableResultText(toolName, content) {
+    if (typeof content === "string")
+        return content;
+    if (toolName === "read")
+        return readBlocksText(content);
+    return;
+}
+function readBlocksText(content) {
+    if (!Array.isArray(content))
+        return;
+    let text = "";
+    for (const block of content) {
+        if (isRecord(block) && block.type === "text" && typeof block.text === "string") {
+            text += block.text;
+        }
+    }
+    return text.length > 0 ? text : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function writeReportArtifacts(outDir, status, report) {
+    writeFileSync(join(outDir, "report.json"), JSON.stringify(report, null, 2));
+    const renamed = `${outDir}-${status.toUpperCase()}`;
+    try {
+        renameSync(outDir, renamed);
+        return renamed;
+    }
+    catch (err) {
+        console.warn(`runner: failed to rename ${outDir} -> ${renamed}:`, err);
+        return outDir;
+    }
+}
+function closeStream(stream) {
+    return new Promise((resolve, reject) => {
+        stream.end((err) => (err ? reject(err) : resolve()));
+    });
+}
+function shortRand() {
+    return randomBytes(3).toString("hex");
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((err) => {
+        console.error("runner crash:", err);
+        process.exit(1);
+    });
+}

package/dist/summary.d.ts

@@ -0,0 +1,3 @@
+import type { CellResult } from "./cell-result.js";
+export declare function printSummary(results: CellResult[], baseStamp: string): void;
+export declare function printTotalCost(results: CellResult[]): void;

package/dist/summary.js

@@ -0,0 +1,64 @@
+import { join } from "node:path";
+import { judgeCostUsd } from "./cost.js";
+function artifactsRoot() {
+    return process.env.OPENCLAW_TEST_ARTIFACTS_DIR ?? "/opt/openclaw-test/artifacts";
+}
+function groupByPair(results) {
+    const order = [];
+    const map = new Map();
+    for (const r of results) {
+        const key = `${r.scenarioId}|${r.channel}|${r.model}`;
+        let agg = map.get(key);
+        if (!agg) {
+            agg = {
+                scenarioId: r.scenarioId,
+                channel: r.channel,
+                model: r.model,
+                runCount: 0,
+                passCount: 0,
+                durationSumMs: 0,
+            };
+            map.set(key, agg);
+            order.push(key);
+        }
+        agg.runCount += 1;
+        agg.durationSumMs += r.durationMs;
+        if (r.verdict === "pass")
+            agg.passCount += 1;
+    }
+    return order.map((k) => map.get(k));
+}
+export function printSummary(results, baseStamp) {
+    const aggregates = groupByPair(results);
+    console.log("");
+    console.log("Summary:");
+    for (const a of aggregates) {
+        const passed = a.passCount === a.runCount;
+        const verdict = (passed ? "PASS" : "FAIL").padEnd(4, " ");
+        const counts = `${a.passCount}/${a.runCount}`.padStart(7, " ");
+        console.log(`  ${verdict}  ${a.channel.padEnd(12, " ")}  ${a.model.padEnd(20, " ")}  ${a.scenarioId.padEnd(40, " ")}  ${counts}  in ${a.durationSumMs}ms`);
+    }
+    console.log("");
+    console.log("Artifacts:");
+    console.log(`  ${join(artifactsRoot(), baseStamp)}`);
+}
+export function printTotalCost(results) {
+    console.log("");
+    console.log(costLine(results));
+    const models = [...new Set(results.map((r) => r.model))];
+    if (models.length > 1) {
+        console.log("Per-model cost:");
+        for (const model of models) {
+            console.log(`  ${model.padEnd(20, " ")}  ${costLine(results.filter((r) => r.model === model))}`);
+        }
+    }
+}
+function costLine(results) {
+    const judgeCost = results
+        .flatMap((r) => r.judgeUsages)
+        .reduce((sum, u) => sum + judgeCostUsd(u), 0);
+    const agentCost = results.reduce((sum, r) => sum + r.agentCostUsd, 0);
+    const agentTurns = results.reduce((sum, r) => sum + r.agentTurns, 0);
+    const totalCost = agentCost + judgeCost;
+    return `Total LLM cost: $${totalCost.toFixed(4)} (agent: $${agentCost.toFixed(4)} over ${agentTurns} turns, judge: $${judgeCost.toFixed(4)})`;
+}

package/dist/transcript-dump.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transcript-dump.js

@@ -0,0 +1,50 @@
+// Gateway-side transcript dump, invoked by the runner through the exec-watcher
+// RPC: `node transcript-dump.js <sinceIso> <conversationId> <outPath> [threadId...]`.
+// OpenClaw 2026.8+ persists each session's transcript as SQLite rows in the
+// per-agent store. Unlike the trajectory diagnostics (whose payloads are
+// node-capped and redacted), the transcript is the full-fidelity record the
+// gateway itself replays, appended per message — tool calls become visible as
+// they happen, not at turn end. This script extracts the transcripts of a
+// conversation's sessions and writes them as JSON to `outPath` (stdout would
+// hit the watcher's 1 MiB cap).
+import { readdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { readConversationSessions } from "./transcript-store.js";
+main();
+function main() {
+    const [sinceIso, conversationId, outPath, ...threadIds] = process.argv.slice(2);
+    if (sinceIso === undefined || conversationId === undefined || outPath === undefined) {
+        console.error("usage: transcript-dump.js <sinceIso> <conversationId> <outPath> [threadId...]");
+        process.exit(2);
+    }
+    const sinceMs = Date.parse(sinceIso);
+    const databases = findAgentDatabases();
+    const sessions = databases.flatMap((dbPath) => readConversationSessions(dbPath, sinceMs, conversationId, threadIds));
+    const tmpPath = `${outPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify({ databases: databases.length, sessions }));
+    renameSync(tmpPath, outPath);
+}
+function findAgentDatabases() {
+    const agentsDir = join(homedir(), ".openclaw", "agents");
+    let agentIds;
+    try {
+        agentIds = readdirSync(agentsDir);
+    }
+    catch {
+        return [];
+    }
+    return agentIds
+        .map((id) => join(agentsDir, id, "agent", "openclaw-agent.sqlite"))
+        .filter(canOpenDatabase);
+}
+function canOpenDatabase(path) {
+    try {
+        new DatabaseSync(path, { readOnly: true }).close();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/transcript-log.d.ts

@@ -0,0 +1,67 @@
+import type { AgentToolCall } from "./report.js";
+export interface TranscriptSnapshot {
+    /** Agent stores found in the gateway. 0 means no store yet — or none at all. */
+    databases: number;
+    sessions: TranscriptSession[];
+    /**
+     * Set when the dump itself failed (non-zero exit, timeout, unreadable
+     * output). `databases` and `sessions` are then placeholders, not
+     * observations — report the failure, not "no store found".
+     */
+    error?: string;
+}
+export interface TranscriptSession {
+    sessionKey: string;
+    sessionId: string;
+    /** OpenClaw's neutral message shape: assistant `toolCall` blocks, `toolResult` messages. */
+    messages: unknown[];
+}
+/** The transcripts of the conversation and its bus-owned thread sessions. */
+export declare function fetchTranscriptSnapshot(opts: {
+    conversationId: string;
+    startedAtIso: string;
+}): Promise<TranscriptSnapshot>;
+/**
+ * Polls the transcripts until they are *quiescent* for this conversation — no
+ * new message for `settleMs` AND no session's turn is demonstrably open — or
+ * the budget expires. The transcript is appended per message, so a settle
+ * window alone would return between two tool calls of one turn (a single
+ * model round-trip routinely exceeds it); the open-turn gate holds until the
+ * turn-final assistant message — the one carrying `usage.cost.total` — has
+ * landed. A conversation spans multiple OpenClaw sessions (e.g. Discord's
+ * channel session plus a per-thread session).
+ */
+export declare function waitForTranscriptQuiescence(opts: {
+    conversationId: string;
+    startedAtIso: string;
+    maxWaitMs?: number;
+    pollMs?: number;
+    settleMs?: number;
+}): Promise<void>;
+/**
+ * A turn is open when a session's last message is a tool result or an
+ * assistant stop for tool use — more of the turn is coming. A trailing user
+ * message does not count as open: some sessions of a conversation never get a
+ * reply (the agent answers in a sibling session), and treating them as open
+ * would burn the whole budget on every cell.
+ */
+export declare function hasOpenTurn(sessions: TranscriptSession[]): boolean;
+/**
+ * Cost lives per assistant message, as `usage.cost.total`. Sum across every
+ * session of the conversation; `turns` counts the cost-bearing messages.
+ */
+export declare function readTranscriptCost(snapshot: TranscriptSnapshot): {
+    cost: number;
+    turns: number;
+};
+/** One-shot fetch + aggregation of the conversation's agent tool calls. */
+export declare function parseAgentToolCalls(opts: {
+    conversationId: string;
+    startedAtIso: string;
+}): Promise<AgentToolCall[]>;
+/**
+ * Walk each session's messages collecting assistant `toolCall` blocks matched
+ * with `toolResult` messages, then union across sessions deduped by
+ * `toolUseId`.
+ */
+export declare function aggregateAgentToolCalls(sessions: TranscriptSession[]): AgentToolCall[];