@sema-ai/core 1.276.0 → 1.277.1

package/docs/vendor-history.md

@@ -1,385 +0,0 @@
-# Vendored core — provenance & modifications
-
-Distilled from **openclaw** (https://github.com/openclaw/openclaw).
-
-- Baseline commit: `e3a6da0f51` (2026-06-12; advanced by the monthly diff review below)
-- Previous baseline: `2664f5951916f374907d693132f5315207f62fb6` (`2026.6.2`)
-- License: MIT (see openclaw/LICENSE)
-
-## What was copied
-
-| vendor path | source in openclaw |
-|-------------|--------------------|
-| `src/vendor/llm-core/src/` | `packages/llm-core/src/` (full) — **since naturalized to `src/engine/llm/` (design/118 ①②, 2026-07-02)** |
-| `src/vendor/agent-core/src/` | `packages/agent-core/src/` (full) |
-
-~~The two-package relative layout is preserved so agent-core's `../../llm-core/src/index.js` imports
-resolve against the vendored llm-core.~~ **Superseded (design/118 ①②)**: agent-core now imports the
-llm layer from the engine path (`../../../engine/llm/index.js`) — see the naturalized section below.
-
-## Modifications applied
-
-1. Deleted all `*.test.ts`.
-2. Rewrote 3 package-name imports `@openclaw/llm-core` → relative
-   `../../llm-core/src/index.js` (in `agent-core/src/{validation,agent-loop,llm}.ts`),
-   since the workspace package is not published to npm. *(Superseded by design/118 ①②:
-   these now point at `../../../engine/llm/index.js`.)*
-3. **F2 optimistic-lock seam** (additive, backward-compatible — see `design/07`). Lets a durable
-   `SessionStorage` make writes conditional so two instances waking the same session can't silently
-   fork the tree. Touched 5 files:
-   - `harness/types.ts` — `SessionErrorCode` += `"conflict"`; new `SessionWriteOptions`;
-     `appendEntry`/`setLeafId` gain optional `opts?: SessionWriteOptions`.
-   - `harness/session/storage-base.ts` — `protected assertExpectedLeaf(opts)`; abstract signatures
-     accept `opts`.
-   - `harness/session/memory-storage.ts` + `jsonl-storage.ts` — call `assertExpectedLeaf(opts)`
-     before persisting. (`jsonl-storage.ts` since deleted — design/71 P0.)
-   - `harness/session/session.ts` — `appendTypedEntry` passes `{ expectedLeafId: entry.parentId }`
-     (the only site that threads it; intentional moves stay unconditional).
-
-4. **F7 entry-id entropy** (`harness/session/storage-base.ts`). `generateEntryId` now slices the
-   **random tail** of a uuidv7 (`slice(-8)`, the `rand_b` group) instead of the leading timestamp
-   bytes (`slice(0,8)`), which only changed ~once per 65s and collided for every entry in a window.
-5. **F3 branch-floor seam** (additive, backward-compatible). Lets a durable backend wake with only
-   the bounded tail `[floorEntryId .. leaf]` instead of the whole tree.
-   - `harness/session/storage-base.ts` — `BaseSessionStorage` constructor gains optional 4th arg
-     `opts?: { floorEntryId? }`; `getPathToRoot` stops at the floor (its missing parent is expected,
-     not an error); new `getFloorId()`. Unset floor = unchanged full-tree behavior.
-   - `harness/session/memory-storage.ts` — `InMemorySessionStorage` options gain `floorEntryId`.
-
-6. **`FileErrorCode` += `"timeout"`** (additive, backward-compatible — same shape as mod #3's
-   `SessionErrorCode += "conflict"`). `harness/types.ts` only. Lets a **remote** `FileSystem` op surface a
-   liveness/idle-timeout (a hung provider RPC) as a typed, retryable `FileError("timeout")` instead of
-   `"unknown"`, symmetric with the core-owned `RemoteExecutionError` code `"timeout"`. For the
-   service[45]/[49] remote-RPC-hang class-fix (`src/core/remote-env.ts` universal liveness contract). No
-   behavior change — the base `NodeExecutionEnv`/`StubExecutionEnv` never emit it; only remote adapters do.
-
-7. **Summarization-prompt anti-drift sections** (`harness/compaction/compaction.ts`, design/64 §22 /
-   design/66 D / channel [73]). Added CC's anti-drift sections to `SUMMARIZATION_PROMPT` /
-   `UPDATE_SUMMARIZATION_PROMPT` (verbatim "## User Messages", "## Errors & Fixes", Next-Steps guard,
-   `<analysis>` scratch block stripped in core's `maybeCompact`). Prompt-only; no control-flow change.
-
-8. **`turn_boundary` hook seam** (design/64 §25 (A), within-task compaction — additive,
-   backward-compatible). The loop previously had no between-turn extension point, so LLM compaction
-   could only run between tasks (`finish()`); within a task only the lossy trim floor applied.
-   - `harness/types.ts` — new `TurnBoundaryEvent { type: "turn_boundary"; model }` in
-     `AgentHarnessOwnEvent` + `AgentHarnessEventResultMap` (result `undefined` — pure timing signal).
-   - `harness/agent-harness.ts` — `createLoopConfig.prepareNextTurn` emits it AFTER
-     `flushPendingSessionWrites()` and BEFORE `createTurnState()`, so a handler that persists a
-     session mutation (e.g. `session.appendCompaction`) is rebuilt into the very next request.
-     Policy (thresholds, model, breaker) stays in core's runtask. No handlers ⇒ no behavior change.
-
-9. **`ExecutionErrorCode` / `FileErrorCode` += `"transport_lost"`** (additive, backward-compatible —
-   same shape as mod #6's `FileErrorCode += "timeout"`). `harness/types.ts` only. Lets a remote
-   adapter (SSH channel death without exit-status, ADB device offline) surface a mid-session
-   transport drop as a typed, retry-whitelist-visible error instead of `"unknown"` (service[63];
-   the adapters previously had to encode it as a `[transport_lost]` message prefix). Exec outcome
-   is UNKNOWN on this code — retry only per the op's idempotency, after reconnect.
-
-10. **Compaction-estimate usage anchor follows usage SIGNAL, not stopReason**
-    (`harness/compaction/compaction.ts` `getAssistantUsage`, design/64 §26.5 council #1). Was: skip
-    `stopReason "error"|"aborted"`. Now: skip `"aborted"` and any assistant whose usage carries no
-    signal (`calculateContextTokens(usage) === 0` — e.g. a synthetic loop-failure `EMPTY_USAGE`); an
-    `"error"` assistant with REAL usage anchors. Closes both failure directions: error-only histories
-    no longer fall back to the chars/4 heuristic for everything (≈2× underestimate on dense content ⇒
-    missed compaction ⇒ provider truncation), and a zero-usage anchor can no longer swallow the whole
-    prior history from the estimate.
-
-11. **Compaction cut-point fallback + empty-preparation guards** (audit A-2 / design/64 §28.3;
-    `harness/compaction/compaction.ts`). `findCutPoint`: when the keep budget is exhausted inside the
-    trailing tool-result batch (no valid cut point at/after `i`), fall back to the LARGEST cut point
-    ≤ `i` (was: the EARLIEST — which kept nearly everything, fed an empty conversation to the
-    summarizer, and produced a hallucinated summary that GREW the context and shut within-task
-    compaction down via the §25.2 floor). `prepareCompaction` returns `undefined` (quiet no-op) when
-    nothing remains to summarize on a non-split cut; `compact()` errors loudly on an empty
-    non-split preparation (defense-in-depth). Normal-path semantics unchanged.
-
-12. **Interrupt leaves a legal session** (audit A-1 / design/64 §28.3; `agent-loop.ts`,
-    `harness/agent-harness.ts`). (a) The inner loop checks the abort signal BEFORE streaming the next
-    turn — an abort during a tool batch no longer triggers a doomed request whose synthetic empty
-    `stopReason:"aborted"` assistant landed in the session between the interrupted batch and its
-    reconcile tool_results (a permanently API-invalid sequence on strict providers). (b)
-    `handleAgentEvent` skips PERSISTING empty failure assistants (aborted/error with no
-    text/thinking/toolCall content — not model output); they still flow to live subscribers and the
-    prompt() result. Callers signal interrupts via the run-loop's own abort flag (core
-    `ResultFlags.abortedLive`), not the now-absent synthetic message.
-
-13. **Signal-terminated exec is not exit 0** (audit round-2 A-3; `harness/env/nodejs.ts`). The
-    `close` handler now receives `(code, signal)`: a signal-killed child (OOM SIGKILL, SIGSEGV,
-    external kill) reports the conventional `128 + signum` exit code (best-effort 137 for unknown
-    names) with a `[process terminated by <SIG>]` stderr marker, instead of `code ?? 0` = a fake
-    success with half an output that the model advanced on.
-
-14. **Full-output capture race** (audit round-2 A-4; `harness/utils/shell-output.ts`). ⚠️ FILE DELETED
-    (design/118 ⓪, 2026-07-02): `shell-output.ts` + `truncate.ts` were runtime-dead (zero src consumers —
-    the Bash tool and the engine `NodeExecutionEnv` own their own capture/truncation; zero downstream
-    npm-dist consumers — the package `exports` map pins `.` + `./bench` only and none of the symbols are
-    re-exported from `src/index.ts`). The A-4 edit is preserved here as history; its tests went with the file.
-    `fullOutputRequested` flips SYNCHRONOUSLY on the first over-threshold chunk (was gated on
-    `fullOutputPath`, assigned only inside the queued creation task — two fast chunks could create a
-    second temp file that overwrote the path: in-between chunks landed in the orphaned file while the
-    model was pointed at the new one = silent data loss). Appends now resolve the path INSIDE the
-    queued task, so writes queued during creation land in the single created file.
-
-15. **`ExecutionEnv.readLink` (optional, additive/backward-compatible)** (design/72 §2.1;
-    `harness/types.ts` interface + `harness/env/nodejs.ts` impl). One-hop symlink target read (raw,
-    not followed). Lets the canonical resolver follow a DANGLING leaf symlink — one whose target
-    doesn't exist yet, which `canonicalPath`'s `realpath` cannot resolve — so a sensitive-path guard
-    or rootPath containment sees the real target of `write_file innocent.txt` where
-    `innocent.txt -> .git/hooks/payload`. Optional: a remote env that omits it keeps the prior
-    best-effort behavior (canonicalize to the raw path). `NodeExecutionEnv` implements it.
-
-16. **Wire the existing `shouldStopAfterTurn` callback** (design/74 R3-A; `harness/agent-harness.ts`).
-    The loop already defines a clean-exit callback (`agent-loop.ts`: `if (await config.shouldStopAfterTurn?.(…))
-    { emit agent_end; return }`) but `createLoopConfig` never provided it. Added a one-way `_stopAfterTurn`
-    flag + a public `requestStopAfterTurn()` setter + wired `shouldStopAfterTurn: () => this._stopAfterTurn`.
-    Lets the runner's resource-slice suspend (design/74) stop the loop CLEANLY at the turn boundary
-    (`agent_end` + return) instead of via `abort()` — a hard abort with no `suspendRef` would drive the
-    orphan-[INTERRUPTED] session reconcile and corrupt the resumed state. Additive + opt-in (flag defaults
-    `false` → zero behavior change for any run that never calls `requestStopAfterTurn`).
-    Council design/74 #1: the flag is reset to `false` at the top of `prompt()` so the stop is ONE-SHOT per
-    prompt — a re-prompt/reuse of the harness can't inherit a stale stop and silently end after one turn.
-
-17. **Null-coercion fail-open closed** (`llm-core/src/validation.ts`, CC-parity bug-hunt A1; ⚠️ this file
-    was previously BYTE-IDENTICAL to openclaw — this is the first divergence). `coercePrimitiveByType`
-    fabricated `null → 0/0/false/""` for plain JSON-schema (non-TypeBox) params. That is library-grade
-    leniency; in our autonomous/GATED/MCP executor it is a FAIL-OPEN — a model emitting explicit `null` on a
-    required non-nullable scalar (a deliberate decline) of a side-effecting/MCP tool was silently rewritten to
-    a concrete `0` and executed, hidden from the design/37 policy gate. The four `value === null` fabricate
-    rules were removed so `null` falls through to `return value` → `validator.Check` rejects → surfaced as a
-    malformed tool call. Reachable only when null is NOT a valid union member (nullable schemas short-circuit
-    before this branch via `matchesUnionMember`), so benign `"5"→5` leniency is untouched. (Directly analogous
-    to the D1 env-scrub adjudication: openclaw's library defaults carry a changed meaning in our threat model.)
-18. **Compaction "preserved verbatim" anchor** (`agent-core/src/harness/messages.ts`, CC-parity bug-hunt B4).
-    Appended CC's `Recent messages are preserved verbatim below.` to `COMPACTION_SUMMARY_SUFFIX`. openclaw
-    has the identical neutral wrapper with no anchor; our engine ALWAYS retains the `keepRecentTokens` recent
-    tail after the summary, so (unconditionally, mirroring CC `services/compact/prompt.ts`) the model is told
-    the post-summary messages are the real recent context, not re-summarized — avoids redundant re-acknowledgment.
-
-19. **D1 secret-env protection NATURALIZED to first-party** (`harness/env/nodejs.ts` → imports
-    `src/core/secret-env.ts`). The D1 shell-env scrubber (`scrubSecretEnv` + the secret-key pattern) was OUR
-    security invariant, not openclaw — it was extracted to the first-party `src/core/secret-env.ts` (the
-    canonical, vendor-independent home) so (a) the package's public exports `isSecretEnvKey`/`scrubSecretEnv`
-    point at a STABLE path that survives the planned de-vendoring, and (b) a downstream host/exec adapter
-    (service [265]) reuses the SAME pattern with zero drift. ⚠️ This is the FIRST vendored→first-party import,
-    so the vendored tree no longer typechecks fully standalone — an intentional naturalize step (the D1 logic
-    is first-party; this temporary vendored env merely consumes it ahead of NodeExecutionEnv's de-vendoring).
-20. **D2 exec output-tail bound NATURALIZED to first-party** (`harness/env/nodejs.ts` → imports
-    `src/core/exec-output-tail.ts`). Same rationale as #19: the D2 rolling-tail output bound (`RollingTailBuffer`
-    + `MAX_EXEC_OUTPUT_BYTES` + the model-facing `markTruncated`) is OUR robustness invariant, extracted to the
-    first-party `src/core/exec-output-tail.ts` so the public exports survive de-vendoring and a downstream exec
-    adapter (service [267], 5 adapters with the same OOM vector) reuses ONE implementation + ONE marker. The
-    vendored env now consumes it (string chunks for the onStdout/onStderr callbacks are pushed as Buffers; the
-    bound is now byte-precise vs the old char-count — a strict improvement for OOM protection).
-
-21. **Session type-only coupling REMOVED via dependency inversion** (`harness/types.ts`). The vendored harness
-    used to `import type { Session }` from the first-party `engine/session/session.ts` (a concrete class) and
-    re-export it — a vendored→first-party TYPE coupling. Replaced with a vendored-local `interface SessionApi`
-    (the session CONTRACT the harness consumes); the first-party `class Session implements SessionApi`. The
-    substrate now defines the interface it needs and never reaches into first-party for a session type. Named
-    `SessionApi` (not `Session`) so it coexists with the public, constructable `class Session` — no breaking
-    public-API change (the public `Session` stays a class; `SessionApi` is an additive export). Consumers that
-    receive a session from a `SessionRepo`/`SessionStore` (session-store, memory-repo, `AcquiredSession`) now
-    type it as `SessionApi`; only `new Session` sites use the concrete class.
-22. **Residual null-fabrication fail-open closed** (`llm-core/src/validation.ts`, R3 adversarial bug-hunt).
-    The A1 edit (#17) dropped the `null→scalar` coercion rules but left the REVERSE `case "null"`:
-    `"" | 0 | false → null`. For a null-FIRST nullable union (`type:["null","string"]`) the coercion loop
-    tries `"null"` first, so a model sending a concrete falsy scalar (0/false/"") had it silently fabricated
-    into `null` and executed past the design/37 gate (reachable via a plain-JSON-schema MCP tool). Now
-    `case "null"` returns the value unchanged — only a literal `null` satisfies a null type, symmetric with
-    #17's closed direction.
-
-23. **`message_end` carries its committed `entryId`** (message-identity Phase 1; `agent-core/src/types.ts`,
-    `agent-core/src/harness/agent-harness.ts`). Additive optional `entryId?: string` on the `message_end`
-    `AgentEvent`. `handleAgentEvent` KEEPS the id `session.appendMessage` already RETURNS (`session.ts:168`)
-    instead of discarding it, and threads it onto the emitted event via a fresh `{ ...event, entryId }` (never
-    mutates `event`). Captured **synchronously at the append site** — NOT a post-hoc `getLeafId()` read (which
-    races the continuing loop). The empty-failure-assistant skip (`agent-harness.ts:601`) appends nothing ⇒
-    `entryId` undefined ⇒ the event is emitted as-is and first-party publishes no `message_committed`. First-party
-    (`runtask.ts` `onMessageEnd`) re-publishes it as the `message_committed` wire event for the renderable roles
-    `message_end` carries (user/assistant/toolResult — see `types.ts:486`); resume tool-results are first-party
-    -owned and need no vendored edit. Additive, optional; no reader outside core ⇒ zero behavior change. TRIPWIRE
-    for an upstream re-apply = `test/streaming.test.ts` "message-identity Phase 1" — it cross-checks each wire
-    `entryId` against the real session entry AND asserts EXACTLY one commit per persisted message (so a broken
-    capture → undefined `entryId` → missing commits → RED; the empty-failure skip → no phantom commit by count).
-    *Considered + rejected:* a first-party `onEntryCommitted` sink at `engine/session/session.ts` (covers all
-    append kinds in one place, zero vendored edit) — reserved as the Phase-2 escape hatch for non-message floor
-    types; it over-emits for non-rendered appends and couples the reusable `Session` to run-loop wire bookkeeping.
-
-24. **Tool aliases for CC canonical-name convergence** (design/115 P0; `llm-core/src/types.ts`,
-    `llm-core/src/validation.ts`, `agent-core/src/types.ts`, `agent-core/src/validation.ts`, `agent-core/src/agent-loop.ts`).
-    Additive optional `Tool.aliases?: string[]` / `AgentTool.aliases?: string[]`, plus a shared `findToolByName`
-    resolver that tries the canonical name first and then aliases. The live loop now uses it both for validation/
-    preparation and for the sequential-batch pre-scan, so a legacy model/SDK call like `Task` or `KillShell`
-    dispatches to the canonical `Agent`/`TaskStop` tool without bypassing per-tool execution mode. This is an
-    engine compatibility shim for durable transcripts and old clients; new tool rosters still expose canonical
-    names.
-
-Vendored core typechecks standalone with ZERO vendored→first-party imports (verified 2026-07-02,
-design/118 ⓪): `harness/env/nodejs.ts` — the former home of the D1/D2 naturalization imports (#19/#20)
-and the A-3 signal fix (#13) and readLink (#15) — was itself naturalized into
-`src/engine/execution-env/node-execution-env.ts`, taking those couplings with it. The vendored tree's
-only external dependency is `typebox`. The Session TYPE coupling (#21) is gone. (Reconcile / F1 in 1.2.0
-was pure `src/core/` — no vendor edit.)
-
-## Deleted dead code (design/71 P0, 2026-06-12)
-
-Zero-consumer files (verified by symbol-level grep over `src/` + `test/`, barrel narrowed in the
-same commit; retreat path = git history, one commit per deletion):
-
-| deleted | LOC | why dead here |
-|---|---|---|
-| `agent-core/src/agent.ts` | 611 | upstream high-level `Agent` API; our entry is `Runner` → `harness.prompt` |
-| `agent-core/src/harness/session/jsonl-{storage,repo}.ts` | 450 | on-disk sessions; we use in-memory + first-party PG storage (both derive `BaseSessionStorage`) |
-| `agent-core/src/harness/compaction/branch-summarization.ts` + `AgentHarness.navigateTree()` | 323+137 | upstream interactive branch navigation/summary; zero callers, unreachable from `Runner` → `harness.prompt`. Historical `branch_summary` entries still read/replay fine (`session.moveTo` + compaction handle the entry type) |
-| `agent-core/src/harness/system-prompt.ts` | 39 | we build system prompts in the core-layer roles system |
-| `agent-core/src/node.ts` | 2 | upstream entry remnant (`NodeExecutionEnv` is re-exported via `src/internal/harness.ts` deep path) |
-
-Types referenced only by deleted code (`Jsonl*`, `NavigateTreeResult`, `BranchSummaryError`,
-`session_before_tree` hook shape) stay in `harness/types.ts` for now — design/71 P1 adjudicates them.
-
-## Deleted dead code (design/118 ⓪ de-vendoring pre-clean, 2026-07-02)
-
-| deleted | LOC | why dead here |
-|---|---|---|
-| `harness/utils/truncate.ts` | 370 | zero src consumers (only `shell-output.ts` imported it); first-party tools own their truncation (`core/tool-errors.ts`, `core/exec-output-tail.ts`) |
-| `harness/utils/shell-output.ts` | 202 | zero runtime consumers (`executeShellWithCapture` unused by the Bash tool / any src path); downstream npm-dist consumption impossible (package `exports` = `.` + `./bench` only; symbols never re-exported from `src/index.ts`; downstream repos grep-verified zero imports, installed `node_modules/@sema-ai/core` 1.208/1.209 exports maps confirm) |
-
-The only in-repo consumers were the A-4 describes in `test/exec-shell.test.ts` (tests of the dead code) —
-removed with the files. Mod #14 above records the A-4 edit as history. Retreat path = git history.
-
-## Naturalized out of this tree (design/71 P2 — ownership transferred to src/engine)
-
-- `harness/compaction/{compaction,utils}.ts` → `src/engine/compaction/` (2026-06-13). First-party
-  ownership: no VENDORED EDIT discipline, direct unit tests, no upstream sync promise (upstream
-  compaction diffs become reference reading). The vendored `agent-harness.ts` now imports the
-  compaction entry points from the engine path (one import-line diff vs upstream). Boundary table:
-  `src/engine/README.md`.
-- `harness/session/{session,storage-base,memory-storage,memory-repo,repo-utils,uuid}.ts` →
-  `src/engine/session/` (2026-06-13, P2-②). Same terms. `harness/session/timestamps.ts` stayed
-  vendor at the time (since moved — design/118 ③, see below); `harness/types.ts` imports the `Session` type from the engine
-  path (one import-line diff vs upstream). design/71 hot path now fully naturalized.
-- `harness/env/nodejs.ts` → `src/engine/execution-env/node-execution-env.ts` (design/103). Carries
-  mods #13 (signal exit), #15 (readLink), #19/#20 (D1/D2 first-party imports) with it — those mods'
-  `harness/env/nodejs.ts` references now mean the engine file. `harness/env/kill-tree.ts` stayed vendor
-  at the time (moved by de-vendoring unit ③ — see below).
-- **the agent loop itself** → `src/engine/loop/{agent-loop,types,runtime-deps}.ts` (2026-07-02,
-  design/118 ④a de-vendoring). agent-loop.ts is a REWRITE, not a move: the vendored nested
-  while-loops became an explicit state machine (named `LoopTerminal`/`LoopContinue` transitions,
-  assertable via a trace sink — `test/loop-transitions.test.ts`), behavior-1:1 with the vendored
-  loop. Carries mod #12(a) (A-1 abort-before-stream), the durable double-execution gate
-  (design/45 §4.ter), the D4 post-hook posture, #24 alias dispatch, and the C9 partial-less delta
-  reconstruction with it — each pinned red→green by counterfactual. The dual steer/followUp drain
-  points are now named Continue reasons (`steer_injected`/`follow_up_injected`) with a direct
-  dual-drain contract test. types.ts/runtime-deps.ts moved near-verbatim (mod #23
-  `message_end.entryId`, `AgentTool.aliases`). Live-verified (tool/multi-turn + steering/interrupt
-  4/4 on the real gateway). ④b recovery chains build on this skeleton.
-- **harness contract layer** → `src/engine/harness/{types,messages}.ts`,
-  `harness/env/kill-tree.ts` → `src/engine/execution-env/kill-tree.ts`,
-  `harness/session/timestamps.ts` → `src/engine/session/timestamps.ts` (2026-07-02, design/118 ③
-  de-vendoring). Carries mods #3 (F2 types), #6/#9 (timeout/transport_lost error codes), #8
-  (turn_boundary event/result-map), #15's interface half (readLink), #18 (B4 compaction anchor),
-  #21 (SessionApi inversion), and the design/116 detach seam (`detachSignal`/`detached`) with it —
-  those mods' `harness/types.ts`/`harness/messages.ts` references now mean the engine files. The
-  vendored `agent-harness.ts` imports the contract layer from the engine path; the agent-core barrel
-  re-exports it so the facade surface is unchanged. After ③ the vendor tree = agent-loop.ts +
-  agent-harness.ts + types.ts + runtime-deps.ts + barrels (units ④⑤ retire it).
-- **`llm-core` (ALL of it)** → `src/engine/llm/{types,diagnostics,event-stream,validation}.ts`
-  (2026-07-02, design/118 ①② de-vendoring). Carries mods #17/#22 (validation fail-open closures),
-  #24 (Tool.aliases + `findToolByName`), the C9 `text_delta.partial` cherry-pick, and the
-  design/71 `end()` deadlock fix with it. The vendored agent-core now imports the llm layer from
-  the engine path (`../../../engine/llm/index.js`, 8 import-line diffs vs upstream — same
-  transitional pattern as compaction/session; these vanish when units ④⑤ retire the tree). The
-  "zero vendored→first-party imports" note below predates this and is superseded accordingly.
-
-## Latent surface adjudicated (design/71 P1, 2026-06-12)
-
-The "present but unused" C-class surface is now resolved — full record (per-file verdicts + the
-error-path audit) in `docs/audit-2026-06-12-design71-P1潜伏面裁决与吞错审计.md`:
-
-- **Deleted**: `prompt-templates.ts` + `prompt-template-arguments.ts` + `file-loader-utils.ts` +
-  `skills.ts` (766 LOC) and the zero-caller `AgentHarness.skill()`/`promptFromTemplate()` methods
-  (VENDORED EDIT markers in `agent-harness.ts`); npm deps `ignore`/`yaml` dropped with them.
-  Deeper than the original plan: `formatSkillInvocation`'s only caller was itself uncalled, so the
-  WHOLE skills surface was dead — which exposed `TaskSpec.skills` as a silently-inert public API
-  (black-box instance #5; the field is kept with an honest ⚠️INERT JSDoc until its disposition is
-  decided).
-- **Kept (type-level only)**: `Skill` (used by core `toSkill`), `PromptTemplate`, `Jsonl*`,
-  `NavigateTreeResult`, `BranchSummaryError`, `session_before_tree` — removing them means
-  refactoring the `AgentHarness<TSkill,TPromptTemplate,TTool>` generic threading = a big cold-path
-  diff against upstream. Swept per-file during P2 naturalization instead.
-
-(`env/nodejs.ts` + `kill-tree.ts` are NOT unused — `NodeExecutionEnv` is the default hands
-execution env since design/44.)
-
-### 2026-06-25 bug-hunt adjudications (round-5 deferred items)
-
-- **#10 — Deleted `AgentHarness.compact()`** (`agent-harness.ts`, with its 3 first-party imports
-  `compact`/`prepareCompaction`/`DEFAULT_COMPACTION_SETTINGS`). Zero callers (within-task compaction goes
-  through the first-party `maybeCompact` turn-end seam), `AgentHarness` not exported, AND it skipped the
-  first-party `<analysis>`-strip + empty-summary guard — an unreachable divergence landmine. Same precedent as
-  `navigateTree`/`skill` above; deleting it also removed a vendored→first-party import.
-- **#5 — `pendingSessionWrites` flush vs `reconcileInterruptedSession` ordering: adjudicated UNREACHABLE,
-  fix deferred to de-vendoring.** A caller-queued non-toolResult write (`appendMessage`/`setModel`) flushed
-  during a mid-batch abort could land between an open `tool_call` and its synthetic reconcile result =
-  invalid transcript for strict providers. But it is unreachable in this package: `AgentHarness` is not
-  exported (no external library consumer can queue mid-batch), and the engine's ONLY mid-task queuer
-  (`setModel` at `runtask.ts` onTurnEnd) is a clean turn boundary with no open batch. A real fix would
-  entangle the harness flush with the first-party reconcile ordering (risk for zero current benefit), so it
-  is deferred to the harness de-vendoring/refactor rather than patched in soon-to-move vendored code.
-
-## Monthly upstream diff review (design/71 §2.6 routine)
-
-| date | upstream range | commits | verdicts (要/不要/已有) | notes |
-|---|---|---|---|---|
-| 2026-06-13 | `2664f595..e3a6da0f51` | 13 touching the two packages | **1 要 / 9 不要 / 0 已有** (+3 out-of-scope) | first run; details below |
-| 2026-06-20 | `e3a6da0f51..d72f7edf2d` | 3 touching the two packages | **0 要 / 3 不要** (+2179 out-of-scope) | all 3 diverged; details below |
-
-### 2026-06-13 adjudication detail (cold path only; hot path = engine, reference reading)
-- **要 → cherry-picked `6fcc945702`** (trim dense text-delta snapshots): `text_delta.partial` is now
-  optional + the loop reconstructs partial-less deltas (`resolveAssistantMessageUpdate`). For us:
-  zero behavior change today (our brains always send `partial`), but it removes a transient
-  `context.messages` corruption window if a brain ever omits it, enables the snapshot-per-token
-  memory trim brain-side later, and keeps the type contract upstream-aligned. Pinned by
-  vendor-contracts C9 (e2e; see its honesty note on discrimination).
-- **不要 `0e7b5c3429`** (Claude Fable 5 adaptive thinking, + new `reasoning.ts`/`model-contracts/anthropic.ts`):
-  upstream solves it in their provider-contract layer, which we deliberately replaced with the
-  design/46 brain-compat system — equivalent handling belongs in `src/brain/anthropic.ts` compat
-  if/when Fable 5 runs through it (flagged as a design/46 follow-up), not in the vendored loop.
-- **不要 `f80f472190`** (`AssistantMessage.errorCode/errorType/errorBody`): our error classification
-  is the `[code]` prefix → `TaskResult.errorCode` pipeline; adding three reader-less optional fields
-  violates the #5 liveness discipline (a brain author setting `errorCode` would be silently
-  ignored). If we migrate to structured error fields, do it WITH the readers as a design item.
-- **不要 `1824aa07a0`/`72bfc5e9bf`** (`Model.supportsPromptCacheKey`/`authHeader`): consumed by their
-  provider layer only; our brains own auth/cache behavior. Reader-less flags here = #5-shaped.
-- **不要 `b4dfa950b5`** (rename `AgentHarness`→`CoreAgentHarness` + re-export, surface refactor):
-  cosmetic; our harness has deliberately diverged (deleted navigateTree/skill etc.) — churn for
-  diff aesthetics only.
-- **不要 `81234fbf12`** (Skill `promptVersion`): skills are first-party now (design/71 #5 fix);
-  noted as a possible future addition to OUR skills block, not a vendor sync.
-- **不要 docs×3** (`4df95d3c3f`/`bdfeece562`/`0b8aabe864`): header-comment passes (+1 line per file).
-- **Out of scope**: `462092936a` (their app layer `src/agents/`, not the vendored packages);
-  hot-path/deleted-file changes (compaction/session/skills/agent.ts upstream diffs = reference only).
-
-### 2026-06-20 adjudication detail (`e3a6da0f51..d72f7edf2d`; 3 commits touch the two vendored packages — all 不要)
-- **不要 `1a002c2d9d`** (preserve prompt-released session state, #93193): targets upstream **side-append (`appendMode:"side"`) + JSONL transcripts + transcript-navigation + doctor-repair** concurrency — all DELETED here (jsonl-storage + navigateTree, design/71 P0) or never present (no side-append concept). Our session concurrency is the F2 optimistic-lock CAS (design/07, `expectedLeafId`), a different model; the leaf-chain append has no side-append/stale-manager/navigation interaction to fix.
-- **不要 `0314819f91`** (replace prose terminal classifiers → `executionStarted` boolean): an agent-loop-INTERNAL terminal/tool classifier field. Our terminal + error classification is in the CORE layer (`runtask.ts` `errorCodeOf`/`isError` + the design/37 tool gate + the `[code]`-prefix → `TaskResult.errorCode` pipeline). Adding `executionStarted` to the vendored loop with no core reader = #5-shaped reader-less flag (same rejection class as 2026-06-13's `f80f472190`/`1824aa07a0`). Structured per-tool execution provenance, if wanted, is a core design item WITH a reader — not a vendor sync.
-- **不要 `965fa05df3`** (tool search directory mode → `resolveDeferredTool` agent-loop callback): we already have the equivalent via **design/36** (`deferMode:"auto"` + an injected `tool_search` driving `setTools`/rematerialize — types.ts:1150 / prepare-task.ts:592), a DIFFERENT mechanism needing no run-loop change. Upstream's `resolveDeferredTool` is a loop callback (changes the vendored loop); ours stays out of the loop. No sync.
-- **Out of scope**: 2179 commits not touching `packages/{llm-core,agent-core}/src`, or touching our naturalized hot path (compaction/session = engine path, reference reading) or deleted files (jsonl/agent.ts/navigateTree).
-- **baseline NOT advanced** (0 cherry-pick → vendored code unchanged, still `e3a6da0f51` + the mods above). Next monthly diff starts from `d72f7edf2d` (this review's HEAD). The 3 rejections confirm the deliberate divergence holding: deleted dead code, naturalized hot path, and different concurrency/tool/error-classification designs mean upstream's cold-path churn keeps not applying.
-
-## Updating from upstream
-
-Re-copy the two `src/` dirs from a newer openclaw checkout, re-apply the modifications above,
-re-run `npm run typecheck`. Record the new baseline commit here.
-
----
-
-## RETIRED (design/118 ⓪-⑤, 2026-07-02)
-
-`src/vendor/` no longer exists. The whole tree was de-vendored into first-party code — see the
-"Naturalized out of this tree" entries above for the per-unit map (llm → `src/engine/llm/`,
-harness contract + AgentHarness → `src/engine/harness/`, loop → `src/engine/loop/`, kill-tree →
-`src/engine/execution-env/`, timestamps → `src/engine/session/`). This file is preserved as the
-provenance/modification HISTORY of the vendored era (openclaw distillation, mods #1-#24, the
-monthly upstream-diff routine — now terminated). Behavior pins live in the test suite
-(vendor-contracts C1-C10, loop-transitions, streaming TRIPWIRE), not in an upstream diff.

package/docs/vendored-upstream-diff-2026-07.md

@@ -1,83 +0,0 @@
-# 月度上游 diff 例行 — 2026-07(design/71 例行,design/118 后首次)
-
-- **上游**:openclaw(https://github.com/openclaw/openclaw),本地 checkout `/Users/clay/开发/gittea/openclaw`,fetch 成功。
-- **Baseline(上月)**:`e3a6da0f51`(2026-06-12)
-- **新 HEAD(本月)**:`53d0c4ca50` origin/main(2026-07-07)
-- **区间总提交**:6514;**命中原 vendored 来源目录**(`packages/agent-core` + `packages/llm-core`,见旧 VENDOR.md 出处表):**31 条**。
-- 背景:design/118 后 `src/vendor/` 不复存在,推理循环/compaction/session 已 first-party 化(`src/engine/`)。本例行仍以这两个上游目录为参照面逐条判决。
-
-## 判决表(31 条,按主题聚类)
-
-档位:**PORT** = 值得吸收(逐条给了落点);**KEEP** = 我们 first-party 实现已覆盖同类(含更强形态);**IGNORE** = 形状不存在于我们代码/纯上游内务。
-
-### A. 压缩(compaction)— 5 条
-
-| 上游提交 | 内容 | 判决 | 依据(我们侧) |
-|---|---|---|---|
-| `2ece2945ae` | cut-point 估算器不数 user 消息里的 image 块 → 图重会话压缩 no-op 循环 | **PORT ①** | **同类 bug 在我们代码坐实**:`src/engine/compaction/compaction.ts` `estimateTokens` user 分支(~L314-327)只数 `text` 块,image 块记 0;toolResult 分支已有 `IMAGE_TOKEN_ESTIMATE`(design/123 D2)。修法:user 分支复用同一 image 计权(以及 document/PDF 计权对称)。危害比上游轻(A-2 修已挡住 no-op 灾难形态),但估算不对称仍在。 |
-| `f826a665a2` | 结尾超大 toolResult 时 findCutPoint 卡在 keep-everything → 压缩 no-op | KEEP | 我们早于上游修过同类:audit A-2 / design/64 §28.3(`findCutPoint` fallback = 最大的 ≤i cut point,L500-517),覆盖同一失效类。 |
-| `413acc2e63` | 数嵌套 toolResult 块内容(content 数组里出现 `toolResult` 型块) | IGNORE | 我们 `ToolResultMessage.content` 类型 = `(Text\|Image\|Document)[]`(`src/engine/llm/types.ts:368-376`),嵌套 toolResult 块形状不存在。 |
-| `e6ec74c254` | `calculateContextTokens` 优先用 provider 的 `usage.contextUsage`(available/unavailable 态) | IGNORE(WATCH) | 依赖 openclaw `packages/ai` 新 Usage 形状(Anthropic context-tracking 字段),我们 brains 的 Usage 没有该字段;现行 `totalTokens \|\| 各项和` 已含 cacheRead/cacheWrite。若日后 brains 接 Anthropic context_management,再回看。 |
-| `486033b183` | 压缩失败/超时恢复不再留下 assistant-last 卡死尾;typed 错误码,不触发 model-fallback 降级 | KEEP | 架构不同:我们压缩失败=抛出→调用方计入 §17.4 breaker(`src/core/auto-compaction.ts:264-266`),1.214 已做 errorKind 契约+length-recovery;无「恢复 pre-compaction 状态」路径,assistant-last 有 loop 侧防卫(agent-loop L218/286)。 |
-
-### B. 推理循环(agent-loop)— 4 条
-
-| 上游提交 | 内容 | 判决 | 依据 |
-|---|---|---|---|
-| `7fe287b0d3` | abort 后停循环并落盘 aborted assistant 结局 | KEEP | design/118 State 机重写已覆盖:`aborted_before_stream` 终态(L583-591)、error/aborted 终态收割+合成 toolResult(L783-815,design/120 §5.4 + design/130 P2b),比上游补丁形态完整。 |
-| `56259606d1` | 只有 `stopReason==="toolUse"` 才派发工具;`removeNonExecutableToolCalls` 剥离截断调用 | KEEP(记设计立场差异) | 截断调用类:design/120 P2.0 契约已封死(`toolcall_end` 仅在输入 COMPLETE 且 JSON 有效时发,malformed 走 finalize 丢弃路径,`src/engine/llm/types.ts:449-461`;S2 恢复处理全丢场景)。剩余差异是**立场**:我们 length-stop 携完整工具调用时照常执行(④b 注释明确,L888),上游改为一律不派发——我们的是带恢复链的 deliberate 设计,不盲从。 |
-| `5ea80c8d80` | 工具 `execute` 返回/抛出后仍来的 onUpdate 回调被丢弃(`acceptingUpdates` 门) | **PORT ③(LOW)** | 我们 `executePreparedToolCall`(agent-loop L1771-1817)无此门:不守规矩的工具在 resolve 后再调 onUpdate 会在 `tool_execution_end`/结果落盘**之后**再发 `tool_execution_update`,事件序违约。三行零风险端口。 |
-| `0314819f91` | prose 终局分类器换掉(agents 层) | IGNORE | 上游 embedded-runner 私有面。 |
-
-### C. 工具参数校验(validation)— 3 条
-
-| 上游提交 | 内容 | 判决 | 依据 |
-|---|---|---|---|
-| `9202dbb1b6` | 字符串化 JSON 数组/对象参数(`'["a","b"]'`)先 JSON.parse 再校验(MiMo/Ollama 类 provider) | **PORT ②** | 我们 `src/engine/llm/validation.ts` 无 JSON.parse 协迫路径;弱 provider(我们真跑 DeepSeek/Qwen/网关)确会字符串化复杂参数。与我们 fail-closed 宪法兼容:parse 出的候选仍须过 `validator.Check` 才接受,不通过原样拒。 |
-| `361869e434` | anyOf 联合里 null 不再被协迫成 "" | KEEP | 我们的 union 协迫走 `coerceWithUnionSchema`(clone→coerce→**Check 通过才接受**,L205-215),且有更严的 null 双向不虚构宪法(A1 + mod #22,L95-102/153-158)。 |
-| `c030b305a4` | 模板参数 tokenizer 保留空引号参数 `""` | IGNORE | 上游 slash-command 模板参数展开;我们侧该资源面从未接线(agent-harness L958 注释),tokenizer 不存在。 |
-
-### D. 执行环境(exec/process)— 3 条
-
-| 上游提交 | 内容 | 判决 | 依据 |
-|---|---|---|---|
-| `e779abf70e` | NodeExecutionEnv.exec 给 child.stdout/stderr 挂 `error` 监听(EPIPE → 未捕获异常炸整进程) | **PORT ④** | 我们 `src/engine/execution-env/node-execution-env.ts` exec 路径只挂了 `child.on("error")`(L609),stdout/stderr 流本身无 error 监听(L586-607);流 EPIPE = 未捕获异常炸宿主。同文件 L178 起的辅助 exec 同缺。小而零风险。 |
-| `55fa22b482` | taskkill spawn 错误处理(spawn 错误是异步 `error` 事件,不是同步 throw) | **PORT ⑤(LOW,win32)** | 我们 `kill-tree.ts` `runTaskkill`(L112-120)只有 try/catch 包 spawn,spawn 的异步 error 事件无监听 → ENOENT/EPERM 时未捕获 `error` 事件炸进程。一行 `.on("error", noop)`。win32 面本就标注未真机验([379])。 |
-| `78399a194c` | localize exec timeout helper | IGNORE | 纯重构。 |
-
-### E. 会话/缓存/用量 — 4 条
-
-| 上游提交 | 内容 | 判决 | 依据 |
-|---|---|---|---|
-| `1a002c2d9d` | prompt 释放期并发转写更新跨 stale session manager 保留 | IGNORE | 上游 session-manager 并发模型;我们有 F2 乐观锁 seam(`expectedLeafId` CAS)防树分叉,架构不同。 |
-| `f5931f5516` | 活跃轮 inbound 元数据挪到尾部 runtime-context 消息,保 byte-stable prompt cache | IGNORE(WATCH 原则) | 上游 channel 元数据装饰面我们没有。**原则记档**:任何「活跃轮装饰≠历史回放字节」的注入都会每轮打穿前缀缓存——我们 reminders/attachWorkingFiles 类注入若改形态,须守「落盘什么就回放什么」。 |
-| `53580e13a4` | provider 计费 0 值保留 + openrouter 延迟 generation 元数据重试 | IGNORE | 上游 usage/cost provenance 模型;我们 `totalTokens \|\|` 兜底不受 0 值类问题影响(0 会落到求和分支,行为正确)。 |
-| `614e87cce1` | 依赖升级 | IGNORE | 内务。 |
-
-### F. 新特性/内务 — 12 条
-
-`f305e707a3`/`1f6ddb5df0`(Mythos 5 / Sonnet 5 模型目录)= IGNORE(我们模型面配置驱动,无内置目录);`0acd851a3b`(managed git worktree 生命周期 create/provision/snapshot/restore/GC)= IGNORE-参考(我们 1.255 已自研 Worktree 工具对,GC 思路可日后对照);`965fa05df3`(tool search directory mode)= IGNORE(我们 ToolSearch=design/36 延迟披露,设计不同);`062f88e3e3`/`65a9cb4ed1`/`49cc59b1e8`/`328a44695f`/`464adfe5e5`(重构/deadcode)、`95ebb3dc1e`(TUI)、`3d404478b8`(Discord)、`19617b0b45`(grep 截断劈 surrogate pair —— KEEP:我们 fs 截断已 surrogate-safe,`src/tools/fs/index.ts:702` + core/arg-summary/exec-gate/untrusted-text 全族早修过)= 均不动。
-
-## PORT 候选汇总(5 条,按优先级)
-
-1. **PORT ①(MED)** `2ece2945ae` 同类:`estimateTokens` user 分支补 image(+document)计权 — 我们代码坐实同 bug。
-2. **PORT ②(MED)** `9202dbb1b6` 同类:validation 加「字符串化 JSON 数组/对象 → parse→Check 通过才接受」协迫路径。
-3. **PORT ④(MED-LOW)** `e779abf70e` 同类:node-execution-env 两处 exec 给 stdout/stderr 挂 error 监听(防 EPIPE 炸宿主)。
-4. **PORT ⑤(LOW)** `55fa22b482` 同类:kill-tree `runTaskkill` 给 spawn 子进程挂 error 监听(win32)。
-5. **PORT ③(LOW)** `5ea80c8d80` 同类:`executePreparedToolCall` 加 `acceptingUpdates` 门,封死迟到 onUpdate 的事件序违约。
-
-五条全是小切片、与现宪法(fail-closed/事件契约)同向,可并一个小修批;PORT ① ② 建议配对差分验收([417] 纪律)。
-
-## 仓内残引扫描(步骤 3)
-
-- `grep -rn "openclaw|vendored" src/ --include="*.ts"`(排除 test):命中集中在 `src/engine/`(agent-harness 11、agent-loop 10、node-execution-env 10、runtask 8 等),**全部为注释性出处标注**(`VENDORED EDIT` provenance / openclaw 行为对照注释)。
-- **实码依赖检查**:`grep "from '.*vendor|require(.*vendor|from '.*openclaw'"` = **0 命中**。无 HIGH。
-
-## npm pack 复核(步骤 4)
-
-`npm pack --dry-run | grep -i vendor` 仅命中 3 个 **docs 文件名**(`docs/audit-2026-06-12-…vendored死路.md`、`docs/audit-2026-06-15/VENDOR-REFACTOR-PLAN.md`、`docs/vendor-history.md`)——均为出处/历史文档,**零代码残引**。PASS。
-
-## 下月 baseline
-
-- **新 baseline:`53d0c4ca50`**(origin/main @ 2026-07-07)。
-- 参照面不变:`packages/agent-core` + `packages/llm-core`(必要时加 `packages/ai` 的 Usage 形状观察,见 e6ec74c254 WATCH)。