@openclaw/lobster 2026.9.3 → 2026.9.5

package/node_modules/@clawdbot/lobster/dist/src/commands/stdlib/llm_invoke.js

@@ -2,8 +2,10 @@ import path from "node:path";
 import { promises as fsp } from "node:fs";
 import { createHash } from "node:crypto";
 import { Ajv } from "ajv";
-import { ensureDirectory, isJsonSyntaxError, readStateJson, stableStringify, writeFileAtomic, writeStateJson, } from "../../state/store.js";
+import { billableTokens } from "../../core/cost_tracker.js";
+import { diffAndStore, ensureDirectory, atomicWriteWasPublished, isJsonSyntaxError, readStateJsonWithLock, stableStringify, withFileLock, writeFileAtomic, } from "../../state/store.js";
 import { createCompileCached } from "../../validation.js";
+import { httpResponseLimitFromEnv, readResponseTextCapped } from "../../read_response_text.js";
 const ajv = new Ajv({ allErrors: true, strict: false });
 const compileCachedLocal = createCompileCached(ajv);
 const artifactSchema = {
@@ -89,6 +91,369 @@ const validatePayload = ajv.compile(payloadSchema);
 const validateResponseEnvelope = ajv.compile(responseSchema);
 const DEFAULT_MAX_VALIDATION_RETRIES = 1;
 const STATE_VERSION = 1;
+// Identity version of the response cache key. See computeCacheKey.
+const CACHE_KEY_VERSION = 2;
+// Provenance for an item this module emitted: which stored answer it belongs to, and whether
+// it came from a provider call or from run state / the response cache.
+// A symbol key cannot come out of `JSON.parse`, so the JSON a workflow step reads from a
+// command's stdout can never carry it: only objects built here, in this process, take part in
+// the replay exemption in workflow cost accounting.
+const LLM_PROVENANCE = Symbol("lobster.llm.provenance");
+/**
+ * Stamps provenance on a value this module is emitting. The property is enumerable so a
+ * downstream `{ ...value }` keeps it, and `JSON.stringify` ignores symbol keys, so serialized
+ * output — including what is written to the cache — is unchanged.
+ */
+function markProvenance(value, provenance) {
+    return Object.defineProperty(value, LLM_PROVENANCE, {
+        value: provenance,
+        enumerable: true,
+        configurable: true,
+    });
+}
+/**
+ * Marks an item this module is emitting, and its usage record with it. A projection such as
+ * `pick model,usage` builds a new object out of named fields, so the item's own mark does not
+ * reach the consumer — but the usage record crosses by reference, and the usage record is what
+ * gets billed. Marking both means provenance survives an in-process projection without the
+ * consumer having to recognize every command that can build one.
+ */
+function markLlmItem(item, provenance) {
+    if (item.usage && typeof item.usage === "object") {
+        markProvenance(item.usage, provenance);
+    }
+    return markProvenance(item, provenance);
+}
+/**
+ * The provenance of an item — or of a usage record — this module produced in the current
+ * process, and null for anything else. The public `replayed` field is deliberately not
+ * consulted: any command can print it beside a real `usage` object, and honoring that would
+ * drop real spend from `_meta.cost` and `cost_limit`.
+ */
+export function llmProvenanceOf(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const provenance = value[LLM_PROVENANCE];
+    if (!provenance || typeof provenance !== "object")
+        return null;
+    const { cacheKey, replayed } = provenance;
+    if (typeof cacheKey !== "string" || typeof replayed !== "boolean")
+        return null;
+    return { cacheKey, replayed };
+}
+/**
+ * Marks `target` — a structurally identical value rebuilt from `source`'s own JSON — as standing
+ * in for whatever calls `source` was marked with.
+ *
+ * The marks are deliberately not in that JSON, and re-deriving them from it would mean trusting a
+ * payload, which the accounting must never do. Carrying them is a different act: the caller holds
+ * both values in this process and knows one was built from the other, which nothing on disk can
+ * claim for itself.
+ *
+ * What is carried is always a replay, whatever the source was. A value read back out of storage
+ * re-emits an answer that already exists; the call behind it was made once, and this is not that
+ * call happening again.
+ */
+export function carryLlmProvenance(source, target) {
+    if (!source || typeof source !== "object" || !target || typeof target !== "object")
+        return;
+    const provenance = llmProvenanceOf(source);
+    if (provenance)
+        markProvenance(target, { cacheKey: provenance.cacheKey, replayed: true });
+    if (Array.isArray(source) || Array.isArray(target)) {
+        if (!Array.isArray(source) || !Array.isArray(target))
+            return;
+        for (let index = 0; index < Math.min(source.length, target.length); index++) {
+            carryLlmProvenance(source[index], target[index]);
+        }
+        return;
+    }
+    for (const key of Object.keys(source)) {
+        carryLlmProvenance(source[key], target[key]);
+    }
+}
+/**
+ * Restores private replay provenance on completed step results loaded from Lobster's own
+ * workflow-resume state. Resume state is the narrow trusted boundary: ordinary command JSON
+ * never reaches this helper, so copying a public cache key cannot suppress its usage record.
+ */
+export function restoreLlmProvenance(target, charges) {
+    if (!target || typeof target !== "object" || !Array.isArray(charges))
+        return;
+    const settled = charges.filter((charge) => charge &&
+        typeof charge === "object" &&
+        typeof charge.cacheKey === "string" &&
+        charge.cacheKey &&
+        charge.usage &&
+        typeof charge.usage === "object");
+    if (!settled.length)
+        return;
+    const visit = (value) => {
+        if (!value || typeof value !== "object")
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        const record = value;
+        const cacheKey = typeof record.cacheKey === "string" ? record.cacheKey : null;
+        const model = typeof record.model === "string" ? record.model : null;
+        const usage = record.usage;
+        if (cacheKey && usage && typeof usage === "object") {
+            const matches = settled.some((charge) => charge.cacheKey === cacheKey &&
+                (charge.model ?? null) === model &&
+                sameBillableUsage(charge.usage, usage));
+            if (matches) {
+                const provenance = { cacheKey, replayed: true };
+                markProvenance(usage, provenance);
+                markProvenance(record, provenance);
+            }
+        }
+        for (const child of Object.values(record))
+            visit(child);
+    };
+    visit(target);
+}
+// A call nothing ever bills — a step that failed outright — leaves its key behind, so the
+// oldest are dropped to keep a long run's ledger bounded.
+const MAX_UNBILLED_LIVE_INVOCATIONS = 256;
+/**
+ * Creates the ledger for a single run. The run that paid for a call is the only one that can
+ * recover its charge, because no other run holds this ledger: a workflow reusing a cache entry
+ * written by an earlier run, or by an SDK caller outside cost accounting, finds nothing to
+ * claim and is billed nothing. A live call made without a ledger in `ctx` opens no charge.
+ *
+ * A run composed by another one — a `workflow:` step — passes the composing run's ledger as
+ * `parent`. Both bill the same answer at their own boundary: the child bills its step, the
+ * parent bills the output handed back to it. So a charge is opened in both and each settles
+ * its own copy exactly once, while a replay neither of them paid for still claims nothing.
+ */
+export function createLlmSpendLedger(parent) {
+    // Outstanding charges per cache key, held one entry per call rather than as a count: two
+    // identical calls that race on a cold cache are two provider charges under one key, the
+    // replays that later stand in for them have to be able to settle both, and each carries the
+    // cost of the call that opened it.
+    const unbilled = new Map();
+    // Charges this run has already accounted for. A copy of an item that lost its mark can turn
+    // up in any later step, and the only way to tell it from a call nobody has billed yet is to
+    // remember what has been billed. Bounded like the open charges, oldest key first.
+    const billed = new Map();
+    function settle(cacheKey, charge) {
+        const seen = billed.get(cacheKey) ?? [];
+        seen.push(charge ?? {});
+        billed.set(cacheKey, seen);
+        for (const oldest of billed.keys()) {
+            if (billed.size <= MAX_UNBILLED_LIVE_INVOCATIONS)
+                break;
+            billed.delete(oldest);
+        }
+    }
+    return {
+        record(cacheKey, charge) {
+            if (!cacheKey)
+                return;
+            parent?.record(cacheKey, charge);
+            const open = unbilled.get(cacheKey) ?? [];
+            open.push({ ...charge });
+            unbilled.set(cacheKey, open);
+            for (const oldest of unbilled.keys()) {
+                if (unbilled.size <= MAX_UNBILLED_LIVE_INVOCATIONS)
+                    break;
+                unbilled.delete(oldest);
+            }
+        },
+        /**
+         * Settles one outstanding charge and hands back what that call cost, or null for the
+         * caller that must not bill anything. A live item and every replay of it draw on the same
+         * charges, so a provider call is billed exactly once however many steps re-emit its
+         * answer — and N calls under one key can be billed N times, never fewer.
+         *
+         * The cost comes back because a replay is not a reliable witness of it: identical calls
+         * that raced on a cold cache each paid their own way, and every replay of them carries
+         * whichever single answer was stored.
+         */
+        claim(cacheKey, cost) {
+            const open = unbilled.get(cacheKey);
+            if (!open?.length)
+                return null;
+            // A caller that knows what its own call cost settles that call's charge. A step
+            // retried after an attempt that failed *after* paying has more than one charge under
+            // the key, and they did not cost the same: settling the wrong one leaves the other to
+            // be billed at this call's price instead of its own.
+            const own = cost
+                ? open.findIndex((charge) => (charge.model ?? null) === (cost.model ?? null) &&
+                    sameBillableUsage(charge.usage, cost.usage))
+                : -1;
+            // Otherwise: a charge that records no cost settles nothing anyone can bill, so it
+            // must not be the one handed to a caller with a real call to account for. Charges
+            // restored from resume state written before they carried a cost are the ones this
+            // can be.
+            const index = own >= 0
+                ? own
+                : Math.max(open.findIndex((charge) => charge.usage !== undefined), 0);
+            const [charge] = open.splice(index, 1);
+            if (!open.length)
+                unbilled.delete(cacheKey);
+            settle(cacheKey, charge);
+            return charge ?? {};
+        },
+        /**
+         * Whether an item carrying a call's numbers but not its in-process mark should be billed.
+         * A matching open charge is settled so the same provider call is not recorded again by
+         * end-of-step cleanup. Once no charge is open, however, public fields can never suppress
+         * usage: only the private provenance symbol can prove an item is a replay.
+         */
+        billCopy(cacheKey, model, usage) {
+            const isSameCall = (charge) => (charge.model ?? null) === model && sameBillableUsage(charge.usage, usage);
+            // A copy that still names a cache key is read against that key alone: the key is
+            // evidence of which call it came from, and honoring it keeps one call's copy from
+            // settling another call's charge. A transform can emit `{ model, usage }` and drop
+            // the key with the symbols, leaving the cost as the only evidence there is.
+            for (const key of cacheKey === null ? [...unbilled.keys()] : [cacheKey]) {
+                const open = unbilled.get(key);
+                const index = open?.findIndex(isSameCall) ?? -1;
+                if (!open || index < 0)
+                    continue;
+                settle(key, open.splice(index, 1)[0]);
+                if (!open.length)
+                    unbilled.delete(key);
+                return true;
+            }
+            return true;
+        },
+        outstanding() {
+            const charges = [];
+            for (const [cacheKey, open] of unbilled) {
+                for (const charge of open)
+                    charges.push({ cacheKey, count: 1, ...charge });
+            }
+            return charges;
+        },
+        /**
+         * Reopens charges a paused run had not billed. A pipeline can suspend mid-step — at an
+         * `ask` gate — after its LLM call has been paid for but before the step succeeded, so
+         * without this the charge would exist in no run: the paused one never billed it, and the
+         * resumed one would exempt the replay that stands in for it.
+         */
+        restore(charges) {
+            if (!Array.isArray(charges))
+                return;
+            for (const charge of charges) {
+                if (!charge || typeof charge !== "object")
+                    continue;
+                if (typeof charge.cacheKey !== "string" || !charge.cacheKey)
+                    continue;
+                const count = Math.floor(Number(charge.count ?? 0));
+                if (!Number.isFinite(count) || count < 1)
+                    continue;
+                // State written before this field existed carries no cost, and a hand-edited file
+                // should not be able to invent one: only a plain object of numbers is taken.
+                const { cacheKey, count: _count, ...cost } = charge;
+                const restored = sanitizeChargeCost(cost);
+                for (let i = 0; i < count; i++)
+                    this.record(cacheKey, restored);
+            }
+        },
+        /**
+         * The calls this run has already billed. A run that pauses carries this the way it carries
+         * what it spent: the total says how much, and this says which calls it was for.
+         */
+        settled() {
+            const charges = [];
+            for (const [cacheKey, seen] of billed) {
+                for (const charge of seen)
+                    charges.push({ cacheKey, count: 1, ...charge });
+            }
+            return charges;
+        },
+        /**
+         * Restores what a paused run had billed, so the two halves of its accounting agree after
+         * the pause. `cost` brings the money back; without this the run that resumes has no record
+         * of what the money was for, and a later step that re-emits a completed LLM output — `head`
+         * over `$live.json` — hands on a copy the fresh ledger has never heard of. It is billed on
+         * top of the restored total: one provider call, twice in `_meta.cost` and against
+         * `cost_limit`.
+         *
+         * A settled charge is only ever read against a cache key, so what this restores can excuse
+         * a copy of a named call and nothing else. It cannot touch a live call — those settle out
+         * of the open charges — and the spend it is reconstructing is already in the `cost` this
+         * same state carries.
+         */
+        restoreSettled(charges) {
+            if (!Array.isArray(charges))
+                return;
+            for (const charge of charges) {
+                if (!charge || typeof charge !== "object")
+                    continue;
+                if (typeof charge.cacheKey !== "string" || !charge.cacheKey)
+                    continue;
+                const count = Math.floor(Number(charge.count ?? 0));
+                if (!Number.isFinite(count) || count < 1)
+                    continue;
+                const { cacheKey, count: _count, ...cost } = charge;
+                const restored = sanitizeChargeCost(cost);
+                for (let i = 0; i < count; i++)
+                    settle(cacheKey, restored);
+            }
+        },
+    };
+}
+/**
+ * Whether two usage records bill the same, asked of the accounting that bills them. Comparing
+ * the records themselves would answer a different question twice over: a live item's usage
+ * carries this module's provenance symbol, which a copy that went through JSON never can, and a
+ * stage that rebuilds an item can drop or recompute a field nothing is charged for.
+ */
+function sameBillableUsage(left, right) {
+    if (!left || typeof left !== "object" || !right || typeof right !== "object")
+        return false;
+    const billed = billableTokens(left);
+    const other = billableTokens(right);
+    return billed.inputTokens === other.inputTokens && billed.outputTokens === other.outputTokens;
+}
+/**
+ * Opens a charge for a live call, and only for one that costs something. An answer that reports
+ * no usage is billed nowhere however many times it is replayed, so a charge for it would sit in
+ * the ledger with nothing to settle it -- and would be handed to the next caller with a real
+ * call to account for, leaving that one's charge open to be billed a second time.
+ */
+function recordLiveCharge(ctx, cacheKey, item) {
+    const cost = chargeCostOf(item);
+    if (!cost)
+        return;
+    ledgerFrom(ctx)?.record(cacheKey, cost);
+}
+/** The cost of a live call, read from the item this module just built for it. */
+function chargeCostOf(item) {
+    const usage = item?.usage;
+    if (!usage || typeof usage !== "object")
+        return undefined;
+    return { model: typeof item?.model === "string" ? item.model : null, usage };
+}
+function sanitizeChargeCost(cost) {
+    const usage = cost.usage;
+    if (!usage || typeof usage !== "object" || Array.isArray(usage))
+        return {};
+    const numbers = {};
+    for (const [key, value] of Object.entries(usage)) {
+        if (typeof value === "number" && Number.isFinite(value))
+            numbers[key] = value;
+    }
+    if (!Object.keys(numbers).length)
+        return {};
+    return {
+        ...(typeof cost.stepId === "string" ? { stepId: cost.stepId } : null),
+        model: typeof cost.model === "string" ? cost.model : null,
+        usage: numbers,
+    };
+}
+function ledgerFrom(ctx) {
+    const ledger = ctx?.llmSpendLedger;
+    if (!ledger || typeof ledger !== "object")
+        return null;
+    return typeof ledger.record === "function" && typeof ledger.claim === "function" ? ledger : null;
+}
 export const llmInvokeCommand = createLlmInvokeCommand({
     name: "llm.invoke",
     itemKind: "llm.invoke",
@@ -164,7 +529,7 @@ export function createLlmInvokeCommand(config) {
                     "schema-version": { type: "string", description: "Logical schema version for caching" },
                     "max-validation-retries": {
                         type: "number",
-                        description: "Retries when schema validation fails",
+                        description: "Extra model calls allowed after the first when schema validation fails (default 1)",
                     },
                     temperature: { type: "number", description: "Sampling temperature" },
                     "max-output-tokens": { type: "number", description: "Max completion tokens" },
@@ -190,7 +555,8 @@ export function createLlmInvokeCommand(config) {
                 "Features:",
                 "  - Typed payload validation before invoking the adapter.",
                 "  - Run-state + file cache so resumes do not re-call the LLM.",
-                "  - Optional JSON-schema enforcement with bounded retries.",
+                "  - Optional JSON-schema enforcement, retried at most --max-validation-retries times",
+                "    after the first call.",
                 "",
                 "Config:",
                 ...config.helpConfig.map((line) => `  - ${line}`),
@@ -204,6 +570,10 @@ export function createLlmInvokeCommand(config) {
 }
 async function runLlmInvoke({ input, args, ctx, config, }) {
     const env = ctx.env ?? process.env;
+    const signal = ctx?.signal;
+    // Run-state and cache hits return before any adapter call, so a cancelled run
+    // would otherwise still finish as a success.
+    throwIfCancelled(signal);
     const provider = resolveProvider(args, env, config.defaultProvider, ctx);
     const adapter = resolveAdapter({ provider, env, args, config, ctx });
     const prompt = extractPrompt(args);
@@ -236,6 +606,9 @@ async function runLlmInvoke({ input, args, ctx, config, }) {
     const inputArtifacts = [];
     for await (const item of input)
         inputArtifacts.push(item);
+    // Draining pipeline input waits on the upstream step, so a timeout can fire
+    // here. Re-check before the reuse lookups below can answer with a success.
+    throwIfCancelled(signal);
     const normalizedArtifacts = [...inputArtifacts, ...providedArtifacts].map(normalizeArtifact);
     const artifactHashes = normalizedArtifacts.map(hashArtifact);
     const cacheKey = computeCacheKey({
@@ -245,21 +618,29 @@ async function runLlmInvoke({ input, args, ctx, config, }) {
         schemaVersion,
         artifactHashes,
         outputSchema: userOutputSchema,
+        temperature,
+        maxOutputTokens,
     });
     if (stateKey && !forceRefresh) {
-        const stored = await readReusableLlmState(env, stateKey);
+        const stored = await readReusableLlmState(env, stateKey, ctx.signal);
+        // Reading run state is I/O of unbounded duration; a signal that aborted
+        // during it must not be overtaken by the replay below.
+        throwIfCancelled(signal);
         const reused = pickReusableState(stored, cacheKey, config.stateType);
         if (reused) {
+            const replay = { cacheKey, replayed: true };
             return {
-                output: streamOf(reused.items.map((item) => ({ ...item, source: "run_state", cached: true }))),
+                output: streamOf(reused.items.map((item) => markLlmItem({ ...item, source: "run_state", cached: true, replayed: true }, replay))),
             };
         }
     }
     if (!disableCache && !forceRefresh) {
-        const cache = await readCacheEntry(env, cacheKey, config.cacheNamespace);
+        const cache = await readCacheEntry(env, cacheKey, config.cacheNamespace, ctx.signal);
+        throwIfCancelled(signal);
         if (cache) {
+            const replay = { cacheKey, replayed: true };
             return {
-                output: streamOf(cache.items.map((item) => ({ ...item, source: "cache", cached: true }))),
+                output: streamOf(cache.items.map((item) => markLlmItem({ ...item, source: "cache", cached: true, replayed: true }, replay))),
             };
         }
     }
@@ -286,6 +667,7 @@ async function runLlmInvoke({ input, args, ctx, config, }) {
     let attempt = 0;
     let lastValidationErrors = [];
     while (true) {
+        throwIfCancelled(signal);
         attempt += 1;
         if (attempt > 1) {
             payload.retryContext = {
@@ -298,9 +680,16 @@ async function runLlmInvoke({ input, args, ctx, config, }) {
         }
         let responseEnvelope;
         try {
-            responseEnvelope = await adapter.invoke({ env, args, payload });
+            ctx.signal?.throwIfAborted();
+            responseEnvelope = await abortable(adapter.invoke({ env, args, payload, signal: ctx.signal }), signal);
+            ctx.signal?.throwIfAborted();
         }
         catch (err) {
+            // Cancellation is the caller's error, not an adapter failure: surface it
+            // as an abort so workflow timeout and abort handling still recognizes it,
+            // rather than wrapping it in a "request failed" adapter error.
+            if (signal?.aborted)
+                throw asCancellation(err, signal);
             throw new Error(`${config.name} request failed: ${err?.message ?? String(err)}`);
         }
         if (!validateResponseEnvelope(responseEnvelope)) {
@@ -319,37 +708,112 @@ async function runLlmInvoke({ input, args, ctx, config, }) {
             attempt,
             itemKind: config.itemKind,
         });
+        const live = { cacheKey, replayed: false };
+        for (const item of normalized)
+            markLlmItem(item, live);
+        // The provider has answered and been paid, so the charge is opened here rather than at
+        // either of the returns below. An attempt the local validator rejects never reaches one
+        // of them -- it goes round the loop and asks again -- and its call was as real as the one
+        // that eventually satisfies the schema. Opening it here also puts it before the writes
+        // that store the answer: either can fail once run state already holds a replayable copy,
+        // and the retry that replays it must still find a charge to settle.
+        recordLiveCharge(ctx, cacheKey, normalized[0]);
         if (!validator) {
+            ctx.signal?.throwIfAborted();
             await persistOutputs({
                 env,
                 stateKey,
                 cacheKey,
                 items: normalized,
                 stateType: config.stateType,
+                signal: ctx.signal,
+                afterStore: disableCache
+                    ? undefined
+                    : () => writeCacheEntry(env, cacheKey, normalized, config.cacheNamespace, ctx.signal),
             });
-            if (!disableCache)
-                await writeCacheEntry(env, cacheKey, normalized, config.cacheNamespace);
             return { output: streamOf(normalized) };
         }
         const structured = normalized[0]?.output?.data ?? null;
         if (validator(structured)) {
+            ctx.signal?.throwIfAborted();
             await persistOutputs({
                 env,
                 stateKey,
                 cacheKey,
                 items: normalized,
                 stateType: config.stateType,
+                signal: ctx.signal,
+                afterStore: disableCache
+                    ? undefined
+                    : () => writeCacheEntry(env, cacheKey, normalized, config.cacheNamespace, ctx.signal),
             });
-            if (!disableCache)
-                await writeCacheEntry(env, cacheKey, normalized, config.cacheNamespace);
             return { output: streamOf(normalized) };
         }
         lastValidationErrors = collectAjvErrors(validator.errors);
-        if (attempt > maxValidationRetries + 1) {
+        if (attempt > maxValidationRetries) {
             throw new Error(`${config.name} output failed schema validation: ${lastValidationErrors.join("; ")}`);
         }
     }
 }
+/**
+ * Build the error a cancelled run rejects with.
+ *
+ * The workflow runner only treats an error named `AbortError` or coded
+ * `ABORT_ERR` as cancellation; everything else follows the step's retry and
+ * `on_error` policy. A host may abort with any reason it likes, so passing
+ * `signal.reason` straight through means `controller.abort(new Error("stop"))`
+ * leaves a cancelled step looking like an ordinary failure -- retried, or
+ * swallowed by `on_error: continue` and reported as a successful run. Keep the
+ * host's message and hang its reason off `cause`, but mark the rejection so the
+ * runner recognizes it.
+ */
+function cancellationError(signal) {
+    const reason = signal.reason;
+    if (reason === undefined || reason === null) {
+        return new DOMException("The operation was aborted.", "AbortError");
+    }
+    if (reason?.name === "AbortError" || reason?.code === "ABORT_ERR")
+        return reason;
+    const message = typeof reason?.message === "string" && reason.message ? reason.message : String(reason);
+    const error = new Error(message, { cause: reason });
+    error.name = "AbortError";
+    error.code = "ABORT_ERR";
+    return error;
+}
+/** Rethrow `err` when it already reads as cancellation, else the run's reason. */
+function asCancellation(err, signal) {
+    if (err?.name === "AbortError" || err?.code === "ABORT_ERR")
+        return err;
+    return cancellationError(signal);
+}
+function throwIfCancelled(signal) {
+    if (signal?.aborted)
+        throw cancellationError(signal);
+}
+/**
+ * Reject as soon as the run is cancelled instead of waiting for `promise`.
+ * HTTP adapters are cancelled at the socket, but an injected `ctx.llmAdapters`
+ * adapter may ignore `ctx.signal` entirely; without this, one of those keeps a
+ * timed-out step waiting for as long as it likes.
+ */
+function abortable(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(cancellationError(signal));
+        // Observe `promise` before anything can settle the wrapper, including the
+        // already-aborted case below. An adapter can cancel the run from inside its own
+        // `invoke` and reject afterwards; rejecting here without watching that promise
+        // leaves the rejection unhandled, which ends the process under Node's default
+        // handling -- long after this step was cancelled cleanly.
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 function resolveProvider(args, env, defaultProvider, ctx) {
     const explicit = String(args.provider ?? env.LOBSTER_LLM_PROVIDER ?? "")
         .trim()
@@ -385,11 +849,12 @@ function resolveAdapter({ provider, env, args, config, ctx, }) {
         return {
             provider,
             source: typeof direct === "function" ? provider : (direct.source ?? provider),
-            async invoke({ payload }) {
-                return invoke({ env, args, payload, ctx });
+            async invoke({ payload, signal }) {
+                return invoke({ env, args, payload, ctx, signal });
             },
         };
     }
+    const maxResponseBytes = httpResponseLimitFromEnv(env);
     if (provider === "openclaw") {
         const openclawUrl = String(env.OPENCLAW_URL ?? env.CLAWD_URL ?? "").trim();
         if (!openclawUrl) {
@@ -400,8 +865,8 @@ function resolveAdapter({ provider, env, args, config, ctx, }) {
         return {
             provider,
             source: config.sourceForProvider?.(provider) ?? "openclaw",
-            async invoke({ payload }) {
-                return invokeOpenClawAdapter({ endpoint, token, payload });
+            async invoke({ payload, signal }) {
+                return invokeOpenClawAdapter({ endpoint, token, payload, signal, maxResponseBytes });
             },
         };
     }
@@ -414,8 +879,14 @@ function resolveAdapter({ provider, env, args, config, ctx, }) {
         return {
             provider,
             source: config.sourceForProvider?.(provider) ?? "pi",
-            async invoke({ payload }) {
-                return invokeHttpAdapter({ endpoint: buildAdapterEndpoint(adapterUrl), token, payload });
+            async invoke({ payload, signal }) {
+                return invokeHttpAdapter({
+                    endpoint: buildAdapterEndpoint(adapterUrl),
+                    maxResponseBytes,
+                    token,
+                    payload,
+                    signal,
+                });
             },
         };
     }
@@ -427,8 +898,14 @@ function resolveAdapter({ provider, env, args, config, ctx, }) {
     return {
         provider,
         source: config.sourceForProvider?.(provider) ?? "http",
-        async invoke({ payload }) {
-            return invokeHttpAdapter({ endpoint: buildAdapterEndpoint(adapterUrl), token, payload });
+        async invoke({ payload, signal }) {
+            return invokeHttpAdapter({
+                endpoint: buildAdapterEndpoint(adapterUrl),
+                maxResponseBytes,
+                token,
+                payload,
+                signal,
+            });
         },
     };
 }
@@ -451,9 +928,10 @@ function buildAdapterEndpoint(rawUrl) {
     }
     return endpoint;
 }
-async function invokeOpenClawAdapter({ endpoint, token, payload, }) {
+async function invokeOpenClawAdapter({ endpoint, token, payload, signal, maxResponseBytes, }) {
     const res = await fetch(endpoint, {
         method: "POST",
+        signal,
         headers: {
             "content-type": "application/json",
             ...(token ? { authorization: `Bearer ${token}` } : null),
@@ -464,7 +942,7 @@ async function invokeOpenClawAdapter({ endpoint, token, payload, }) {
             args: payload,
         }),
     });
-    const text = await res.text();
+    const text = await readResponseTextCapped(res, maxResponseBytes);
     if (!res.ok) {
         throw new Error(`${res.status} ${res.statusText}: ${text.slice(0, 400)}`);
     }
@@ -488,16 +966,17 @@ async function invokeOpenClawAdapter({ endpoint, token, payload, }) {
     }
     return { ok: true, result: parsed };
 }
-async function invokeHttpAdapter({ endpoint, token, payload, }) {
+async function invokeHttpAdapter({ endpoint, token, payload, signal, maxResponseBytes, }) {
     const res = await fetch(endpoint, {
         method: "POST",
+        signal,
         headers: {
             "content-type": "application/json",
             ...(token ? { authorization: `Bearer ${token}` } : null),
         },
         body: JSON.stringify(payload),
     });
-    const text = await res.text();
+    const text = await readResponseTextCapped(res, maxResponseBytes);
     if (!res.ok) {
         throw new Error(`${res.status} ${res.statusText}: ${text.slice(0, 400)}`);
     }
@@ -603,14 +1082,24 @@ function hashArtifact(artifact) {
     const stable = stableStringify(artifact);
     return createHash("sha256").update(stable).digest("hex");
 }
-function computeCacheKey({ provider, prompt, model, schemaVersion, artifactHashes, outputSchema, }) {
+function computeCacheKey({ provider, prompt, model, schemaVersion, artifactHashes, outputSchema, temperature, maxOutputTokens, }) {
+    // `null` is the identity of an omitted parameter, distinct from any value a caller can
+    // pass, so an omitted request can never resolve to an entry written with an explicit one.
+    // The version separates this identity from the keys earlier releases wrote, where the two
+    // parameters were absent from the payload and a sampled answer therefore shared a key with
+    // an unsampled request. Bump it whenever the fields below change: entries under older
+    // versions become unreachable, which costs one re-invocation and never a wrong replay.
     const payload = {
+        cacheKeyVersion: CACHE_KEY_VERSION,
         provider,
         prompt,
         model: model || `${provider}-default`,
         schemaVersion,
         artifactHashes,
         outputSchema: outputSchema ?? null,
+        // The same predicate that decides whether each parameter is sent to the adapter.
+        temperature: Number.isFinite(temperature ?? NaN) ? Number(temperature) : null,
+        maxOutputTokens: Number.isFinite(maxOutputTokens ?? NaN) ? Number(maxOutputTokens) : null,
     };
     return createHash("sha256").update(stableStringify(payload)).digest("hex");
 }
@@ -646,9 +1135,11 @@ function normalizeResult({ envelope, cacheKey, schemaVersion, artifactHashes, so
     };
     return [item];
 }
-async function persistOutputs({ env, stateKey, cacheKey, items, stateType, }) {
-    if (!stateKey)
+async function persistOutputs({ env, stateKey, cacheKey, items, stateType, signal, afterStore, }) {
+    if (!stateKey) {
+        await afterStore?.();
         return;
+    }
     const record = {
         type: stateType,
         version: STATE_VERSION,
@@ -656,11 +1147,17 @@ async function persistOutputs({ env, stateKey, cacheKey, items, stateType, }) {
         items,
         storedAt: new Date().toISOString(),
     };
-    await writeStateJson({ env, key: stateKey, value: record });
+    await diffAndStore({
+        env,
+        key: stateKey,
+        value: record,
+        signal,
+        afterStore: afterStore ? () => afterStore() : undefined,
+    });
 }
-async function readReusableLlmState(env, stateKey) {
+async function readReusableLlmState(env, stateKey, signal) {
     try {
-        return await readStateJson({ env, key: stateKey });
+        return await readStateJsonWithLock({ env, key: stateKey, signal });
     }
     catch (err) {
         if (isJsonSyntaxError(err))
@@ -684,28 +1181,85 @@ function collectAjvErrors(errors) {
         return [];
     return errors.map((err) => `${err.instancePath || "/"} ${err.message ?? ""}`.trim());
 }
-async function readCacheEntry(env, key, cacheNamespace) {
+async function readCacheEntry(env, key, cacheNamespace, signal) {
     const filePath = path.join(getCacheDir(env), cacheNamespace, `${key}.json`);
+    const read = async () => {
+        try {
+            const text = await fsp.readFile(filePath, "utf8");
+            const parsed = JSON.parse(text);
+            if (parsed?.cacheKey !== key || !Array.isArray(parsed.items))
+                return null;
+            return parsed;
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return null;
+            if (isJsonSyntaxError(err))
+                return null;
+            throw err;
+        }
+    };
     try {
-        const text = await fsp.readFile(filePath, "utf8");
-        const parsed = JSON.parse(text);
-        if (parsed?.cacheKey !== key || !Array.isArray(parsed.items))
-            return null;
-        return parsed;
+        return await withFileLock({ filePath, signal, task: read });
     }
     catch (err) {
-        if (err?.code === "ENOENT")
-            return null;
-        if (isJsonSyntaxError(err))
+        if (err?.code === "ENOENT" || err?.code === "ENOTDIR")
             return null;
+        // A cache mounted read-only cannot have an active local writer because a
+        // writer first creates the same coordination lock. Preserve its reusable
+        // entries instead of requiring a lock-directory write for a read.
+        if (["EACCES", "EPERM", "EROFS"].includes(err?.code))
+            return read();
         throw err;
     }
 }
-async function writeCacheEntry(env, key, items, cacheNamespace) {
+async function writeCacheEntry(env, key, items, cacheNamespace, signal) {
     const dir = path.join(getCacheDir(env), cacheNamespace);
+    signal?.throwIfAborted();
     await ensureDirectory(dir);
     const filePath = path.join(dir, `${key}.json`);
-    await writeFileAtomic(filePath, JSON.stringify({ items, cacheKey: key, storedAt: new Date().toISOString() }, null, 2) + "\n");
+    const content = JSON.stringify({ items, cacheKey: key, storedAt: new Date().toISOString() }, null, 2) + "\n";
+    await withFileLock({
+        filePath,
+        signal,
+        task: async () => {
+            let previousContent = null;
+            try {
+                previousContent = await fsp.readFile(filePath);
+            }
+            catch (err) {
+                if (err?.code !== "ENOENT")
+                    throw err;
+            }
+            const restorePreviousContent = async () => {
+                // No cache reader or competing cache writer can observe this entry
+                // until this lock is released. Restore an entry replaced by a refresh;
+                // only remove the just-published file when none existed beforehand.
+                if (previousContent === null)
+                    await fsp.rm(filePath, { force: true });
+                else
+                    await writeFileAtomic(filePath, previousContent);
+            };
+            let cacheWasPublished = false;
+            try {
+                signal?.throwIfAborted();
+                const result = await writeFileAtomic(filePath, content, { signal });
+                cacheWasPublished = true;
+                if (result?.signalAbortedAfterCommit || signal?.aborted) {
+                    await restorePreviousContent();
+                    cacheWasPublished = false;
+                    signal?.throwIfAborted();
+                    throw new Error("LLM cache publication cancelled");
+                }
+            }
+            catch (err) {
+                if (cacheWasPublished || atomicWriteWasPublished(err)) {
+                    await restorePreviousContent();
+                }
+                throw err;
+            }
+        },
+    });
 }
 function getCacheDir(env) {
     if (env?.LOBSTER_CACHE_DIR)