PR #74110: feat(agents): add OPENCLAW_LOG_ABORT_SOURCES diagnostic for embedded run aborts

• Repository: openclaw/openclaw
• Author: chphch
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74110

Description (problem / solution / changelog)

Summary

Add an opt-in structured diagnostic for embedded run aborts. Gated by env var OPENCLAW_LOG_ABORT_SOURCES=1; default off (no behavior change). When enabled, every abortRun() entry in src/agents/pi-embedded-runner/run/attempt.ts emits a [abort-source] line classifying the trigger and capturing five caller stack frames.

No linked upstream issue — this PR adds a missing operator-facing observability seam. Filing it because we hit the gap during real triage and want a first-class hook so the next operator doesn't have to dist-patch.

Problem

When an embedded agent run aborts mid-stream, the user-visible signal is a generic AbortError("This operation was aborted"). Five different paths can trip the abort:

• External params.abortSignal from the caller
• scheduleAbortTimer (run-level timer firing on params.timeoutMs)
• idleTimeoutTrigger (LLM idle wrapper)
• Compaction guard (shouldFlagCompactionTimeout path)
• Public cancel() API

There is no log line distinguishing them. Operators triaging unexpected mid-stream cutoffs end up grepping bundled dist code, hand-instrumenting console.warn(new Error().stack) into selection-*.js:abortRun, redeploying, and waiting for another reproduction. We just walked through that loop on a real ~13s cutoff in our deployment.

Change

src/agents/pi-embedded-runner/run/abort-source-log.ts (new, 76 LOC):

• isAbortSourceLoggingEnabled() reads the env var via existing isTruthyEnvValue helper.
• classifyAbortSource(ctx) returns a discriminated union over five categories: external-signal | llm-idle-timeout | compaction-timeout | run-timer | explicit-cancel. Priority order matches actual abort semantics (external signal beats internal flags).
• logAbortSource(ctx) formats the line via the existing agent/embedded subsystem logger when gated.

src/agents/pi-embedded-runner/run/attempt.ts: 1-line import + 9-line call at the head of the abortRun closure. Captures runId, sessionId, the four state flags (externalAbort, idleTimedOut, timedOutDuringCompaction, isTimeout), and the abort reason.

No public API change. No new dependency. No changelog entry (internal operator-facing diagnostic).

Why this shape

• Default-off: zero log volume / behavior impact for users who don't enable it.
• Single emission point inside abortRun covers every existing call site and any future ones automatically.
• Existing logger keeps formatting consistent with surrounding agent/embedded lines.
• Discriminated union for source prevents freeform-string drift in downstream consumers.
• Stack capture via new Error().stack is gated, so cost is paid only when explicitly enabled.

Alternatives considered: always-on (rejected: log volume), per-call-site instrumentation (rejected: easy to miss new sources), structured AbortError subclass (rejected: API-surface ripple beyond the value of a diagnostic).

Tests

src/agents/pi-embedded-runner/run/abort-source-log.test.ts (new, 10 cases):

• Classification × 5 — one per category, including priority ordering (external beats idle beats compaction beats timeout).
• Gating × 3 — unset / "1" / empty string env var.
• Emission × 2 — silent when gated off; emits expected fields when on, including source=, runId=, reason=, and a non-empty stack= segment.

$ pnpm test src/agents/pi-embedded-runner/run/abort-source-log.test.ts
Test Files  1 passed (1)
     Tests  10 passed (10)

pnpm build clean; the resulting selection-*.js bundle contains the [abort-source] log statement and classifyAbortSource symbol.

Notes

• Env var name follows the existing OPENCLAW_RAW_STREAM precedent (operator-facing diagnostic, off by default, blocked from workspace .env by the OPENCLAW_* prefix policy in src/infra/dotenv.ts).
• Could grow into richer abort tracing later (correlation IDs, downstream propagation) but kept minimal here — single diagnostic line, opt-in, easy to revert.

Changed files

• src/agents/pi-embedded-runner/run/abort-source-log.test.ts (added, +121/-0)
• src/agents/pi-embedded-runner/run/abort-source-log.ts (added, +76/-0)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +10/-0)