Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(examples): experimental pi extension where the agent manages its own context windows (#4941)
t0sakibf8c5e9d3452
diff --git a/examples/pi-experimental-context-management/.gitignore b/examples/pi-experimental-context-management/.gitignorenew file mode 100644index 000000000..d33e9745c--- /dev/null+++ b/examples/pi-experimental-context-management/.gitignore@@ -0,0 +1,5 @@+# The repository root ignores every `lib/` directory (it is a Python build+# artifact there). This extension ships hand-written ESM modules in lib/, so+# re-include that directory here rather than adding another exception to the+# root .gitignore.+!lib/diff --git a/examples/pi-experimental-context-management/CONTEXT-WINDOW.md b/examples/pi-experimental-context-management/CONTEXT-WINDOW.mdnew file mode 100644index 000000000..da91a555e--- /dev/null+++ b/examples/pi-experimental-context-management/CONTEXT-WINDOW.md@@ -0,0 +1,753 @@+# Agent-managed context windows++**EXPERIMENTAL.** This document describes the context-window mode of+`examples/pi-experimental-context-management`: how OpenAI's Codex does it, what+this extension maps onto OpenViking, what actually happens during a reset, and+the exact text the model sees.++Everything below is taken from the code in this directory:+`lib/context-window-core.mjs` (the pure state machine), `context-window.ts`+(the pi/OpenViking adapter), `tools.ts` (the three tools), `index.ts` (event+wiring and the static guidance) and `config.ts` (the `contextWindow` block).++---++## 1. How OpenAI/Codex does it++Codex ships this as `features.context_management.experimental_mode` on GPT-6+Astra. Turning it on enables the `token_budget` feature and sets+`use_history_notes_extension = true`. Instead of compressing the conversation+into a summary, the model keeps its own notes, decides itself when the current+window ends, and can search the messages and tool output of the windows that+already closed.++- **Storage lives on OpenAI's backend** (`alpha/notes/v2/*`,+ `alpha/history/v2/*`), which is why the mode only works for ChatGPT+ Plus/Pro logins.+- **Model-side tools**:+ - the `notes` namespace — `list_files_by_prefix`, `read_file`,+ `search_contents`, `append_to_file`, `write_file` — a private,+ cross-window scratchpad on virtual paths;+ - the `history` namespace — `list_windows`, `list_items`, `read_item`,+ `search_contents` — reads items of earlier windows by window id + item id;+ every non-assistant message carries a trailing `[id: ...]`;+ - `functions.new_context` — **no parameters**, described as "Start a new+ context window. Does not clear, reset, or otherwise affect environment+ state." It only sets a flag; after the current sampling finishes, the+ session is rebuilt as system/developer prompt + world state + the retained+ client developer messages + a `<context_window>` block (current and+ previous window id plus a `thread_hint` pulled from the notes backend,+ ≤ 4000 bytes). **No LLM summarization happens at any point.**+ - `get_context_remaining` — returns `{tokens_left}`.+- **Prompts** (the `token_budget` entry of `models-manager/models.json`):+ a `guidance_message` telling the model to maintain a checkpoint in notes+ (goal / decisions / progress / learnings / next steps / ids of unfinished+ user requests), to plan with `get_context_remaining`, to treat the presence+ of a previous-window id as proof that a reset happened (read the checkpoint+ first, then fill gaps with `history`), and to treat notes/history as internal+ bookkeeping; a `reminder_message_template` fired once when fewer than 6144+ tokens remain ("save notes, then call new_context"); and an+ `auto_compact_fallback_prompt` used when nothing is left, which grants an+ extra 16384-token buffer and forces exactly one notes write followed by+ `new_context`.+- **Compaction path**: in `token_budget` mode `run_compact_task_inner` calls+ `start_new_context_window` — the compaction lifecycle still runs, but the+ summarization step is gone.++## 2. Mapping Codex → this extension++| Codex | Here | Notes |+| --- | --- | --- |+| History backend (`alpha/history/v2`) | The OpenViking session message stream, archived per window to `<session root>/history/archive_NNN/messages.jsonl` | Written by `POST /sessions/{id}/commit` |+| Notes backend (`alpha/notes/v2`) | The `notes` parameter of `new_context` | No separate notes tool in v1 (see limitations) |+| `thread_hint` in the window block | The server-written Working Memory (`.overview.md`) plus the model's own handoff notes | Working Memory has 7 sections: Session Title, Current State, Task & Goals, Key Facts & Decisions, Files & Context, Errors & Corrections, Open Issues |+| `history.list_windows` | `history {"action":"list_windows"}` → `GET /fs/ls?uri=<root>/history` | Window ids come from the core's own `{windowId, archiveId}` ledger, so a window that closed without producing an archive cannot shift them |+| `history.list_items` / `read_item` | `history {"action":"list_items"}` / `{"action":"read_item"}` → `GET /content/read?uri=<archive>/messages.jsonl` | Item ids are the 0-based line index inside that archive: `w2:14` |+| `history.search_contents` | `history {"action":"search_contents"}` → `POST /search/grep` over `<root>/history` | Case-insensitive; hits in `messages.jsonl` are turned into `read_item` pointers |+| `functions.new_context` (no parameters) | `new_context` **with** `reason`, `notes`, `next_steps?` | The parameters replace the missing notes backend |+| `get_context_remaining` → `{tokens_left}` | `get_context_remaining` → tokens left plus window age, turn count, idle gaps, archive readiness and an `advice` line | pi can only estimate tokens, so the report says whether the number is exact or estimated |+| Native window rebuild after sampling | A virtual cut in pi's `context` hook | Nothing is deleted on disk; only the message list of each provider request is rewritten |+| `guidance_message` | `CONTEXT_WINDOW_GUIDANCE`, appended to the system prompt | §5 below |+| `reminder_message_template` | Soft/hard reminders, one of each per window | §5 below |+| `auto_compact_fallback_prompt` | The pi-compaction fallback in `session_before_compact` | §8 below |++**What cannot be mirrored:**++- **No developer role in pi.** The window header can only be a `user` message,+ so it is wrapped in `<openviking-context source="context-window">` and, when+ the first surviving message is already a user message, merged into it to+ avoid two user messages in a row.+- **No exact token count.** `ctx.getContextUsage()` reports the last assistant+ usage plus a chars/4 estimate over the *untransformed* session, so right+ after a reset it is too high; the core keeps its own estimate over the+ transformed list and marks numbers as `estimated` when it uses them.+- **Notes are not private.** Anything mirrored into OpenViking gets indexed and+ becomes searchable, so v1 carries notes as a tool parameter instead of+ building a separate notes namespace.+- **No parameterless `new_context`.** Without a notes backend, the reason and+ notes have to arrive with the call.++## 3. What a reset does at runtime++`new_context` is `executionMode: "sequential"` and its `execute` is awaited, so+the whole pipeline blocks inside the tool call, bounded by one deadline+(`contextWindow.resetDeadlineMs`, default 60s).++1. **Guards.** Refuse if a reset is already running, if the call has no tool+ call id, if the OpenViking session id is unknown, or if the client is not+ connected. Refuse also when a previous commit failed in transport and the+ server is still unreachable.+2. **`sync.syncBranch(branch)`** — pi has already persisted the assistant+ message that issued this call, so the archive reaches exactly the reset+ point. A branch that could not be fully delivered refuses the reset.+3. **`sync.flushBarrier({budgetMs})`** — the disk pending queue must be empty+ (budget: whatever is left of the deadline, clamped to 2–15s). A queue that+ does not drain refuses the reset and reports how many messages are stuck.+4. **Post the handoff note** with `client.addMessage(sid, "assistant", …)`,+ directly rather than through the queue, so it lands *before* the commit and+ is archived into this window. The server's Working Memory prompt writes for+ "the assistant that continues", so it folds the note into Current State /+ Open Issues — the reason ends up in the summary without any server change.+5. **`sync.commit({queueOnFailure:false, keepRecentCount:0})`.**+ `status: "skipped"` (nothing to archive) leaves the window untouched, and so+ does any reply without an `archive_uri` — including one that says+ `accepted`, because there would be no archive id to name and the wait below+ would poll an empty URI until the deadline. A refusal carries the commit's+ `trace_id` when the server sent one, the transport's otherwise.+ Every refusal from here on first posts a one-line+ `[Context Window Handoff] … RETRACTED` message, because the handoff note is+ already in the live session and would otherwise be archived as a window+ boundary that never happened. (OpenViking has no delete for a session+ message, so this is a repair, not a rollback.)+6. **Point of no return.** Once the commit returns an `archive_uri` the+ OpenViking session is empty, so every path below must open a window.+ `archiveId = basename(archive_uri)`; the core polls+ `GET /content/read?uri=<archive_uri>/.overview.md` every+ `archivePollMs` until the deadline (404 while commit phase 2 runs, 200 with+ the Working Memory as the body), checking `GET /tasks/{task_id}` on the+ second attempt and then every fifth. A `failed` or `cancelled` task ends the+ wait immediately; a `completed` one gets three more polls and then ends it+ too, because a commit whose summary came out empty never writes+ `.overview.md` at all and would otherwise burn the whole deadline on every+ reset. Timeout, task failure and `signal.aborted` all still open the window,+ with a degraded header.+7. **Open the window**: freeze `headerText`, `windowIndex += 1`, record+ `anchorToolCallId`, `archiveId`, `overviewReady`, the sibling tool names and+ the current sync watermark, then `pi.appendEntry("ov-context-window", state)`+ and update the status bar.+8. **The cut** happens in the `context` hook of the *next* sampling — which is+ the one right after this tool batch. `computeCutRange` finds the toolResult+ whose `toolCallId` is the anchor, walks back to the assistant message that+ issued it, and drops the whole contiguous run of toolResults it belongs to+ (so a parallel batch never leaves an orphan `tool_result`, which providers+ reject). Everything before that is dropped as well; a stale+ `[context-reminder]` message at the head of the kept segment is dropped too.+ The frozen header goes in front.+9. **Degraded follow-up**: at every `turn_end` a window with+ `overviewReady === false` reads `.overview.md` once more, up to+ `overviewRefreshMaxAttempts` times. Success rebuilds the header once (one+ cache miss) and re-persists; exhausting the attempts marks the Working+ Memory `unavailable` and rebuilds the header with that wording.++**The reset tool's own result is inside the discarded range.** On success the+model never sees the text `new_context` returned — everything it needs has to+be in the window header. Only a refusal (nothing was cut) is actually read.++**Anchor missing → boundary released.** If the anchor is not in the branch any+more (a fork, `/tree`, a native pi compaction), the transform returns the+messages untouched, logs once and disarms. That is the single invariant that+keeps a failure mode of "no reset" rather than "corrupted request". Only the+`context` hook may release it that way: the status line runs the same cut+through `observeMessages`, which records the metrics and leaves the anchor+alone (§4.2).++## 4. Exact prompt texts++### 4.1 Static guidance (appended to the system prompt every turn, `index.ts`)++```text+<context-window-management>+You manage your own context window in this session. When the conversation grows it is not summarized behind your back: you decide when the current window ends, and OpenViking archives it so you can read it back afterwards.++Three tools do this:+- new_context — archive the current window and continue in a fresh one. OpenViking generates a Working Memory of the archived window, and your next window opens with that Working Memory, your handoff notes and the user's most recent request.+- history — read windows that were already archived: list_windows, list_items, read_item, search_contents. Closing a window loses nothing; it only stops being in front of you.+- get_context_remaining — how much room is left, how long this window has been open, and how long it has been since the user's last message.++Start a new window when:+- a phase of the work is finished and its details no longer matter for what comes next;+- the user switches to an unrelated topic or a different area of the code;+- the user comes back after a long idle gap with something new;+- the status line or get_context_remaining says the window is filling up — act when their advice line asks you to, and never ignore a [context-reminder]. If you wait until the window overflows, the harness compacts the conversation for you and your notes are never written.++Do not start a new window:+- in the middle of an edit sequence you have not verified;+- immediately after a reset;+- to get away from a problem you have not solved — the new window carries the same problem with less information.++Write the notes before you call new_context: the goal, the decisions and why you made them, what is finished, what is in flight, exact file paths and identifiers, and the next steps. Write them for someone who has not seen this conversation, because that is exactly what your next window is. Call new_context alone — tool results from the same batch are discarded together with the old window.++If new_context answers with "Context window NOT reset", nothing was archived and nothing was removed from your context: read the reason it gives, keep working in the current window, and do not call it again until that reason is gone.++In a new window, read the <openviking-context source="context-window"> block first: it carries the Working Memory, your notes and the request that is still pending. Use history for anything it does not cover, and never ask the user to repeat something an archived window already holds.+</context-window-management>+```++Followed by one tool-list line:++```text+OpenViking tools: viking_search, viking_read, viking_browse, viking_remember, viking_forget, viking_add_resource. Context window tools: new_context, history, get_context_remaining.+```++Unlike Codex, the model is *not* asked to hide this machinery from the user —+the demo is meant to be visible. No percentage is written into the guidance on+purpose: both thresholds are clamped at runtime under pi's own auto-compaction+line (§6), so a hardcoded "70%" would be a lie on a small-window model, where+the reminders fire at 49%. The status line, the reminders and+`get_context_remaining` carry the numbers that actually apply.++### 4.2 Status line (one per user prompt, `customType: "ov-context-status"`)++```text+[context-status] window w2 · 6 turns · ~38.4k/262k tokens (15%) · 47m since your previous message+```++With an estimated token count the percentage carries a marker:++```text+[context-status] window w2 · 1 turn · ~38.4k/262k tokens (15%, estimated) · 12s since your previous message+```++After an idle gap longer than `idleGapMinutes` a second line is appended:++```text+NOTE: 47 minutes passed since the previous user message. If this request starts unrelated work, consider new_context before you begin.+```++The gap it reports is `sinceLastUserMs` — the time since the newest genuine user+message in the branch, which at `before_agent_start` is still the *previous*+prompt, i.e. the gap the user just came back from. (`get_context_remaining`+reports the gap *before* that message separately; it is not what gates this+NOTE.)++It is emitted from `before_agent_start`, so it appears **once per user prompt**,+not once per sampling: it does not update while a tool loop runs.++Its numbers come from the session branch, not from the last `context` hook:+`messagesFromBranch(ctx.sessionManager.getBranch())` rebuilds the list pi would+send and `core.observeMessages()` runs the same cut over it to refresh+`turnsInWindow`, the token estimate and the user timestamps. The `context` hook+is the only other place those are recorded, and it has not run yet on the first+prompt of a process — a resumed session (`pi -c`) would otherwise open with+`window w2 · 0 turns` and no idle gap however long the window had already been+running. `observeMessages` is `transformContext` minus the right to release the+boundary: a status readout must never disarm a window over a list pi has not+finished writing. Nothing is persisted and no request is made, so the line is+identical whether or not OpenViking answers.++### 4.3 Reminders (at most one of each per window, `customType: "ov-context-reminder"`)++Soft (`softPercent`, default 70):++```text+[context-reminder] Context window w2 is about 70% full (~184k/262k tokens). Finish or checkpoint the step you are on, then call new_context with complete notes: goal, decisions and why, what is done, what is in flight, exact paths and identifiers, next steps. If the window overflows first, the harness compacts it for you and your notes are never written.+```++Hard (`hardPercent`, default 85, clamped one point below pi's own+auto-compaction line):++```text+[context-reminder] Context window w2 is about 85% full (~223k/262k tokens). Save your handoff notes and make exactly one call to new_context now. If the window overflows first, the harness compacts it for you and your notes are never written.+```++Delivery is `pi.sendMessage(..., {deliverAs: toolResults.length ? "steer" : "nextTurn"})`+from `turn_end`. No reminder is evaluated while `awaitingFirstObservation` is+set (between a reset and the first assistant response of the new window),+otherwise the stale 87% of the closed window would trigger an immediate second+reset.++### 4.4 Handoff note (archived as the last assistant message)++```text+[Context Window Handoff] w2 -> w3+Reason: REASON+Handoff notes:+NOTES+Next steps:+1. a+2. b+```++`Next steps:` is omitted when `next_steps` is empty; an empty `reason` renders+as `(none given)` and empty notes as `(none)`.++### 4.5 Window header — Working Memory ready++```text+<openviking-context source="context-window">+<context_window id="w3" previous="w2" archive="archive_002" opened="2026-09-10T06:41:12Z">+This is a fresh context window. The earlier conversation of this session was archived to OpenViking and is no longer in context. Files, the working directory, running processes and tools are unchanged.++Reason you gave: REASON++Your handoff notes:+<handoff-notes>NOTES</handoff-notes>++Next steps you planned:+1. step one+2. step two++The user's most recent message in the previous window was:+<pending-request>PENDING</pending-request>++Working Memory of the archived window, generated by OpenViking:+<working-memory archive="archive_002">WORKING MEMORY</working-memory>++2 other tool results were discarded with the same batch; re-run them if needed. Tools: bash, read.++To recover anything not covered above: history {"action":"list_windows"} / {"action":"list_items","window":"w2"} / {"action":"read_item","item":"w2:<index from list_items>"} / {"action":"search_contents","query":"..."}.+Continue from the notes above. If the pending request is not finished, resume it now.+</context_window>+</openviking-context>+```++Sections are omitted when empty: no `Reason you gave` without a reason, no+`<handoff-notes>` without notes, no `Next steps you planned` without steps, no+`<pending-request>` when the window carries no user message (or when+`pendingRequestBudget` is 0), and the sibling-tool line only when other tool+results were discarded with the same batch (singular wording: `1 other tool+result was discarded …`). Notes, pending request and Working Memory are+truncated to their token budgets and then get a `\n...(truncated)` marker.++One more line appears only when the sync manager lost messages for good (a+non-retryable rejection, or a queue entry whose retries ran out): `N messages of+this session were rejected by OpenViking and are missing from the archive, so+history cannot show them.` (singular wording: `1 message of this session was+rejected by OpenViking and is missing …, so history cannot show it.`) The+barrier cannot catch those — they are counted as accepted so the watermark can+move past them — so the header names them instead of letting `history` quietly+under-report the window.++### 4.6 Window header — Working Memory still pending++The Working Memory paragraph is replaced by:++```text+Working Memory for archive_002 is not ready yet: OpenViking is still summarizing it. Rely on your handoff notes above and use history to read the archived messages directly.+<working-memory status="stale" archive="archive_001" describes="an earlier window, not the archive above">OLD WORKING MEMORY</working-memory>+```++The stale block carries the archive it actually describes — the *previous* one —+never the archive named in the line above it, which is precisely the one that has+no Working Memory yet. When the previous archive id is unknown (a restore that+predates it) the `archive` attribute is left out rather than guessed. The block+only appears when a previous window's Working Memory exists — on the first reset+of a session there is none, and no empty block is written.++### 4.7 Window header — Working Memory unavailable++```text+Working Memory for archive_001 is unavailable: OpenViking could not summarize it. Rely on your handoff notes above and use history to read the archived messages directly.+```++Reached when the archive task reports `failed` or `cancelled`, when it reports+`completed` without ever writing `.overview.md`, or when+`overviewRefreshMaxAttempts` non-blocking retries are exhausted.++## 5. Tool reference++### `new_context`++Description (verbatim from `tools.ts`):++> Start a new context window. Does not clear, reset, or otherwise affect+> environment state. The conversation so far is archived to OpenViking (which+> generates a Working Memory of it) and your next window starts with that+> Working Memory, your handoff notes and the user's last request. Call it alone+> — tool results from the same batch are discarded with the old window — and+> read the `<openviking-context source="context-window">` block that follows. If+> instead this result says "Context window NOT reset", nothing was archived and+> nothing was removed from your context: read the reason, keep working in the+> current window, and do not call new_context again until that reason is gone.++Every non-success text starts with the same marker, `Context window NOT reset`,+so the rule is checkable: the refusals, the cancellation and the "a reset is+already in progress" answer all open on it.++| Parameter | Type | Required | Meaning |+| --- | --- | --- | --- |+| `reason` | string | yes | One sentence: why this context window should end now |+| `notes` | string | yes | Handoff notes: goal, decisions and why, what is done, what is in flight, exact paths and identifiers, next steps |+| `next_steps` | string[] | no | Ordered next steps for the new window |++`executionMode: "sequential"`. It never sets `terminate`: a refusal has to leave+the agent running, and a success is consumed by the next `context` hook.+Progress while waiting for the archive is reported through `onUpdate` as+`waiting for the Working Memory of archive_002 (attempt 3)`.++### `history`++| Parameter | Type | Used by | Meaning |+| --- | --- | --- | --- |+| `action` | `"list_windows" \| "list_items" \| "read_item" \| "search_contents"` | all | What to do |+| `window` | string | list_items, read_item | `"w2"` or `"archive_002"` |+| `item` | string | read_item | `"w2:14"`, or `"14"` together with `window` |+| `query` | string | search_contents | Text or regular expression |+| `offset` | number | list_items | First item index, default 0 |+| `limit` | number | list_items | How many items, default 40, capped at 200 |++`list_windows` lists archives newest-id-last with their directory abstract+(`(Working Memory not ready)` until commit phase 2 finishes) and appends the+open window as `(current)`. When the listing request itself fails (403, 5xx,+timeout) the tool says the archives are unreadable instead of reporting zero+archived windows — the model is told elsewhere to trust an empty history and not+ask the user, which would be exactly wrong for an unreachable server. An archive+whose `messages.jsonl` cannot be read is reported the same way: as a read+failure with a pointer at `search_contents`, not as "still being archived"+(phase 1 writes that file synchronously, so waiting never helps). `list_items` renders one line per message,+`[id: w2:14] role timestamp first 200 chars`. `read_item` returns one+message clipped to `contextWindow.historyItemMaxChars`. `search_contents` greps+every archive case-insensitively, shows at most 20 matches grouped by window,+and turns each `messages.jsonl` hit into a `read_item` pointer (line number − 1+is the item index, because the file holds one message per line). Every line of+the file produces exactly one item, so that arithmetic holds: a line the client+cannot parse keeps its slot as an `(unreadable archive line)` placeholder and a+blank one as `(blank archive line)`, rather than shifting every pointer after+it. The only thing dropped is the empty string after a trailing final newline,+which is not a line of its own.++One tool with an `action` enum rather than four tools: pi's tool namespace is+flat, so four `history_*` tools would cost four slots in every request.++### `get_context_remaining`++No parameters. Read-only; renders the `statusSnapshot`:++```text+tokens_left: 224k+used: ~38.4k / 262k (15%)+window: w2, opened 12m ago+turns in this window: 6+since the user's last message: 47m+gap before that message: 3m+archives: 1 (latest archive_001, Working Memory ready)+accuracy: exact+advice: no action needed+```++`accuracy` is `estimated` when the number comes from the core's own estimate+(right after a reset, or when pi reports `tokens === null`). `advice` is one of+`no action needed`, `past the soft threshold: update your notes and reset at the+next stopping point`, `save your notes and call new_context now`.++The six `viking_*` tools (`viking_search`, `viking_read`, `viking_browse`,+`viking_remember`, `viking_forget`, `viking_add_resource`) come from the+non-experimental extension, with two corrections: `viking_add_resource` lost its+`reason` parameter (it was never sent anywhere), and a `viking_remember` whose+write fails now says the fact was *not* stored instead of claiming it was queued+— this extension has no queue on that path. `viking_archive_expand` is gone —+`history` replaces it.++## 6. Configuration (`contextWindow` block)++| Key | Default | Range | Effect |+| --- | --- | --- | --- |+| `resetDeadlineMs` | 60000 | 5000–600000 | Whole-reset budget: sync, barrier, commit and the wait for `.overview.md` |+| `archivePollMs` | 2000 | 250–30000 | Delay between `.overview.md` polls |+| `overviewRefreshMaxAttempts` | 20 | 0–200 | Non-blocking `turn_end` retries for a degraded window |+| `overviewBudget` | 3000 | 100–50000 | Token budget for the Working Memory block in the header |+| `notesBudget` | 1500 | 100–20000 | Token budget for the handoff notes in the header |+| `pendingRequestBudget` | 400 | 0–8000 | Token budget for the carried-over user message |+| `softPercent` | 70 | 10–99 | Usage that earns the soft reminder |+| `hardPercent` | 85 | 10–99 | Usage that earns the hard reminder; raised to `softPercent` if configured lower |+| `idleGapMinutes` | 30 | 0–1440 | Idle gap after which the status line adds its NOTE line |+| `statusEveryTurn` | true | boolean | Emit the status line after every user prompt |+| `historyItemMaxChars` | 8000 | 500–100000 | Per-item cap for `history read_item` |+| `recentResetGuardMs` | 60000 | 0–600000 | How long after a reset `session_before_compact` returns the current header instead of archiving again |++Every number is rounded and clamped on load; an out-of-range value is pulled to+the nearest bound and a non-numeric one falls back to the default. Unknown keys+inside `contextWindow` are dropped, and a `contextWindow` that is not an object+is ignored entirely.++Two environment variables override the block for one run:+`OPENVIKING_CONTEXT_STATUS_EVERY_TURN` (`0/1`, `true/false`, `on/off`,+`yes/no`) and `OPENVIKING_CONTEXT_RESET_DEADLINE_MS` (clamped like the file+value).++Both thresholds are additionally clamped at runtime to one point below pi's own+auto-compaction line, `1 - reserveTokens/contextWindow`, read from+`compaction.reserveTokens` in `<cwd>/.pi/settings.json` and+`~/.pi/agent/settings.json` (default 16384). On a 32k model that line sits near+50%, so without the clamp the hard reminder would never fire before pi compacted+and the notes would never be written.++## 7. Persisted state++One `pi.appendEntry("ov-context-window", …)` per window open, per Working+Memory upgrade and at shutdown. `restore()` takes the newest entry that belongs+to this OpenViking session and ignores malformed ones and entries of other+sessions.++```json+{+ "version": 1,+ "ovSessionId": "pi-<piSessionId>",+ "windowIndex": 3,+ "anchorToolCallId": "call_…",+ "openedAt": 1789012345678,+ "headerText": "<openviking-context source=\"context-window\">…",+ "reason": "…",+ "notes": "…",+ "nextSteps": [],+ "pendingRequest": "…",+ "archiveId": "archive_002",+ "archiveUri": "viking://user/<uid>/sessions/pi-…/history/archive_002",+ "taskId": "…",+ "archives": [{ "windowId": "w1", "archiveId": "archive_001", "archiveUri": "viking://…/archive_001" }],+ "previousArchiveId": "archive_001",+ "undeliveredCount": 0,+ "overviewReady": true,+ "overviewUnavailable": false,+ "overviewAttempts": 0,+ "previousOverview": "…",+ "siblingToolNames": [],+ "syncedEntryCount": 137,+ "lastResetAt": 1789012345678,+ "lastResetBy": "agent"+}+```++`archives` is the `{windowId, archiveId}` ledger `history` resolves window ids+through, appended on every successful commit (agent reset and pi-compaction+fallback alike) and capped at the last 100 entries. `previousArchiveId` is what+the stale Working Memory block is tagged with, and `undeliveredCount` is how+many messages OpenViking rejected for good.++`lastResetBy` is `agent`, `pi-compaction` or `external`. In-memory only, never+persisted: the `resetting` mutex, `remindersSent`, `awaitingFirstObservation`,+`lastWindowTokens`, `turnsInWindow`, `overviewText`. A fresh session starts at+`windowIndex = 1` (w1, not persisted); the first reset opens w2.++Because `headerText` and the anchor are persisted, `pi -c` reproduces the cut+byte for byte in the next process.++## 8. Failure matrix++| Situation | Cut? | What the model gets |+| --- | --- | --- |+| OpenViking unreachable, or no OV session id | no | `Context window NOT reset: OpenViking is unreachable, so this window cannot be archived. Nothing changed; keep working; the harness will compact for you if the window fills up.` |+| Branch not fully delivered to OpenViking | no | `… the conversation so far could not be fully delivered to OpenViking. …` |+| Pending queue did not drain | no | `… the archive barrier did not clear — N captured message(s) are still queued. …` |+| Deadline exhausted before the handoff note | no | `… the reset deadline was exhausted while syncing this window to OpenViking. …` |+| Handoff note rejected | no | `… the handoff note could not be written to OpenViking. …` |+| Commit threw in transport | no | `… the archive commit failed in transport; the archive may or may not exist, so nothing was cut. …` — remembered, so the next attempt re-checks connectivity first |+| Commit refused, or accepted without an `archive_uri` | no | `… OpenViking refused the archive commit (trace …). …` — the handoff note is retracted |+| Commit `skipped` / `no_messages` | no | `Context window NOT reset: OpenViking had nothing to archive for this window. Keep working; call new_context again once there is something worth archiving.` |+| Aborted before the commit (Esc) | no | `Context window NOT reset: the reset was cancelled before anything was archived. Nothing changed; keep working.` — the handoff note is retracted if it was already written |+| Another reset already running | no | `Context window NOT reset: a reset is already in progress. …` |+| Commit succeeded, Working Memory slow / aborted / deadline hit | **yes** | Window opens with the `status="pending"` header variant |+| Commit succeeded, archive task `failed` or retries exhausted | **yes** | Window opens with the `unavailable` header variant |+| Commit succeeded, something after it threw | **yes** | Window opens through the recovery path with a `pending` header and an explicit error in the tool result |+| Anchor no longer in the branch at transform time | n/a | Messages pass through untouched; the boundary is released and logged once |++Every refusal that happens after the handoff note was written posts a+`[Context Window Handoff] … RETRACTED` line, so the next archive does not carry+a boundary that never happened. A failed retraction is not fatal: the orphan+note stays, and the Working Memory of the next window may read one window+boundary too many.++The rule behind the table: **fail closed before the commit, fail open after+it.** Before the commit nothing was archived, so keeping the context is the+safe answer. After it the OpenViking session is empty+(`keep_recent_count: 0`), so refusing would leave the model holding the old+conversation while believing its history is still live.++## 9. Prompt-cache rules++- `headerText` is built **once** per reset and frozen. Every later provider+ request repeats the same bytes, so the prefix stays cacheable.+- The static guidance and the tool-list line are constant for the whole+ session, so appending them to the system prompt moves no cache boundary.+- The status line and the reminders are persistent custom messages appended+ after a user message, not rewritten in place.+- A degraded window is upgraded at most once (`overviewReady` false → true, or+ → `unavailable`): exactly one cache miss per window, never a poll-driven+ rewrite.+- `pi -c` rebuilds the identical header from the persisted entry, so a resumed+ session can keep the cache.+- The one deliberate exception is `absorbExternalCompaction`, which drops the+ anchor entirely — pi already cut natively at that point.++## 10. pi-compaction fallback++If the model never resets and pi's own threshold hits first,+`session_before_compact` takes over (`ContextWindowCore.handleBeforeCompact`):++1. If our own header exists, the last reset was less than 60s ago+ (`recentResetGuardMs`) and nothing new has been synced since, return the+ current header as the summary **without committing again** — this catches a+ provider hiccup that made pi estimate from the untransformed list.+2. Otherwise: `syncBranch(branchEntries)` → `flushBarrier` → post a handoff note+ with `reason = "automatic: pi compaction threshold"` and, in place of notes,+ an explicit "no handoff notes were written for this window" line → `commit({keepRecentCount: 0})` →+ wait for `.overview.md` under the same deadline. The model's previous notes+ are *not* reused: they were written for the window that opened here, and both+ the archive and the new header would present them as this boundary's handoff.+ `notes` is cleared with `nextSteps`, which is also what keeps the reminders'+ "your notes are never written" honest. Return `{compaction: {summary: headerText,+ firstKeptEntryId, tokensBefore, details: {source: "openviking", reason:+ "pi-compaction"}}}`.+3. `firstKeptEntryId` is picked so pi can never resurrect messages the header+ already declares archived: use `preparation.firstKeptEntryId` when it sits+ after the anchoring tool batch, otherwise the first entry after that batch,+ otherwise the sentinel `"ov-context-window-reset"` (matching no entry, so pi+ builds a summary-only context).+4. Any failure returns `undefined` and pi writes its own summary.+5. After a successful takeover the virtual anchor is cleared — pi has performed+ a native cut — and `lastResetBy` becomes `pi-compaction`.+6. A compaction produced by anyone else (`session_compact` without+ `fromExtension`) calls `absorbExternalCompaction`: the anchor is dropped,+ the window index advances and `lastResetBy` becomes `external`, which also+ stops the guard in step 1 from reusing a header that no longer describes+ what is in context.++`session_before_compact` is skipped only while the extension is bypassed. With+OpenViking unreachable the handler still runs, because step 1 needs no network+and is what stops a stale usage estimate from compacting a window that opened a+moment ago; the core then refuses to commit on its own (`io.connected()` is+false) and returns `undefined`, so an offline pi falls back to its own+summarizer.++## 11. Known limitations++- **`GET /sessions/{id}/archives/{archive_id}` is blocked** (403 `ApiBlocked`)+ on the target gateway, so archive readiness is detected by reading+ `<archive_uri>/.overview.md` and, as a secondary signal, `GET /tasks/{id}`.+ `GET /sessions/{id}/context` is not used for waiting — right after a commit it+ still returns the previous overview.+- **No `viking://~` alias.** The server rejects it with `Invalid scope '~'`.+ URIs come from `GET /sessions/{id}`'s `uri` field (cached) or from the+ commit's `archive_uri`; the fallback is the legacy `viking://session/{id}`.+- **`ctx.getContextUsage()` is stale for one turn after a reset.** It counts+ the untransformed session, so the core ignores it while+ `awaitingFirstObservation` is set and reports its own estimate as+ `estimated`. It is also `null` right after a native pi compaction.+- **Tool-count pressure.** Nine tools ship here (six `viking_*` plus three+ window tools). On models with small tool budgets that is a real cost, which+ is why `history` is one tool with an `action` enum rather than four.+- **Notes are not private.** They travel into the OpenViking archive inside the+ handoff message, get summarized into Working Memory and are searchable by+ `history search_contents` and ordinary memory search — unlike the Codex notes+ backend. Do not treat them as a hidden scratchpad.+- **Status line granularity.** It is emitted once per user prompt, so during a+ long tool loop the numbers the model sees are from the start of the turn.+ `get_context_remaining` is the up-to-date reading.+- **Sibling tool results are lost.** Calling `new_context` alongside other tools+ discards their results (the header says so and names them), so they must be+ re-run if they mattered.+- **Windows are per-session.** Window ids belong to this OpenViking session; a+ restored state belonging to another session is dropped. They come from the+ core's own `{windowId, archiveId}` ledger, so a window closed by a compaction+ that produced no archive keeps its number without appearing in `history` —+ `list_windows` can therefore show gaps (`w1`, `w3`, `w4 (current)`), and an+ archive the ledger does not know (written before the state existed) falls back+ to positional numbering.+- **The first prompt of a restored window gets no recall block.** When the cut+ leaves a user message at the head of the window, the frozen header is merged+ into it, and `injectRecall`'s `<openviking-context` guard then treats the whole+ message as already injected. This is visible on `pi -c` right after a reset:+ that one prompt is answered without recall, and the next user message gets it+ again. The header itself carries the Working Memory, so nothing is lost that+ the window does not already have.++## 12. Manual demo++1. Disable the non-experimental extension first — they both register `viking_*`+ and both write the same OpenViking session. Set `"enabled": false` in+ `~/.pi/agent/extensions/openviking/config.json`, or drop it from+ `settings.json`'s `packages`. (If you forget, this extension notices a+ `viking_search` registered from another directory — on startup and again on+ every event boundary, since the other one registers late — and stands down+ with a warning, unless a window is already open, in which case it warns and+ keeps going rather than handing the model back an archived conversation.)+2. `pi install /abs/path/to/examples/pi-experimental-context-management`+3. Start `pi` and talk about topic A for a few turns. Watch the footer segment+ (`OV ✓ · w1 · 12% · a— · pi-…`) and the `[context-status]` line under each+ prompt.+4. Switch to an unrelated topic B. The model should call `new_context` on its+ own; the footer flips to `w2` and the archive id appears.+5. Ask about a detail of topic A that is not in the notes and watch it reach+ for `history`.+6. Come back after more than `idleGapMinutes` and check that the status line+ adds its NOTE line.+7. `/viking window` prints the current window, archive, Working Memory state+ and advice; `/viking` alone prints connection and session.+8. Re-enable the other extension when you are done.++`OPENVIKING_DEBUG_LOG=/tmp/ov-pi-window.log` writes one JSON Lines record per+event, including `context-window: opened w2 from archive_001 (working memory+ready, waited 34211ms)`.++## 13. End-to-end gate++`scripts/e2e-window.mjs` (with the `scripts/e2e-window.sh` wrapper) drives a+real pi binary against a real OpenViking server and a real OpenAI-compatible+LLM, in a throwaway agent directory that has only this extension installed. It+is a manual gate, not part of CI.++| Variable | Required | Meaning |+| --- | --- | --- |+| `OPENVIKING_URL` | yes | OpenViking server base URL |+| `OPENVIKING_API_KEY` | yes | OpenViking API key |+| `E2E_LLM_API_KEY` | yes | API key of the OpenAI-compatible LLM endpoint |+| `E2E_LLM_BASE_URL` | yes | LLM base URL. No default: a private relay must not end up hardcoded in the repo |+| `E2E_LLM_MODEL` | yes | Model id served by that endpoint |+| `E2E_LLM_API` | no | pi provider api type, e.g. `openai-completions` |+| `E2E_LLM_REASONING` | no | `off` (default), `minimal`, `low`, `medium`, `high`, `xhigh`. Anything but `off` marks the model as reasoning-capable, sets pi's `defaultThinkingLevel` and, for a custom relay, turns on `compat.supportsReasoningEffort` so the request carries `reasoning_effort` |+| `PI_BIN` | no | Path to the pi binary; defaults to `which pi` |+| `E2E_KEEP_TMP` | no | `1` keeps the temporary workspace on success |+| `E2E_KEEP_OV_SESSION` | no | `1` leaves the OpenViking sessions in place so the archives stay readable afterwards; you clean them up |+| `E2E_WINDOW_FAILCLOSED` | no | `1` runs only the fail-closed scenario, `both` runs it after the main one. The script points pi at a dead port itself; `OPENVIKING_URL` / `OPENVIKING_API_KEY` stay required because the gate also checks the OpenViking side |+| `E2E_WINDOW_LONG` | no | `1` runs only the long-context scenario, `both` adds it. The workspace is seeded with this extension's own sources — 22 files, around 105k tokens of material — and the agent is asked to inventory them one file at a time. The prompt never mentions the context tools: the point is whether the agent reaches for them once the window fills. Slow (25-40 minutes) and dependent on model judgement, so the judgement checks warn while harness behaviour still fails the gate |+| `E2E_WINDOW_LONG_MIN_PERCENT` | no | Share of the window the long run should reach before resetting; default `40`. Measured from the provider payloads, because the per-prompt `[context-status]` line undersamples a tool-heavy turn |+| `E2E_WINDOW_LONG_SOFT_PERCENT` | no | Where the soft reminder fires in the long run; default `45` |+| `E2E_WINDOW_LONG_TURN_TIMEOUT_MS` | no | Per-turn timeout for the long run; default 25 minutes |++A passing long run, recorded on 2026-09-11 against Volcengine's Doubao 2.1 Pro+(`doubao-seed-2-1-pro-260628`) on Ark with `reasoning_effort: high`: 96 provider+requests, a peak of 47% of a 128k window, three resets the agent chose itself,+and 22 of 22 files inventoried across four windows. The transcripts are in+[`demo-evidence/`](demo-evidence/README.md).++**Never write an API key into a file.** Pass both keys through the environment+of the run only:++```bash+OPENVIKING_URL=... OPENVIKING_API_KEY=... \+E2E_LLM_API_KEY=... E2E_LLM_BASE_URL=... E2E_LLM_MODEL=... \+ ./scripts/e2e-window.sh+```++The gate drives three pi runs — a first prompt that plants a codename plus+padding, a `pi -c` continuation that instructs one `new_context` call, and a+second `pi -c` that asks for the codename back — and asserts on the captured+provider payloads that the post-reset request starts with a user message+opening on `<openviking-context source="context-window">`, carries `id="w2"`+and the codename from the notes, no longer contains the padding or the+`new_context` call and result, and leaves no orphan `tool_result`; plus, on the+OpenViking side, that `.overview.md` exists, `messages.jsonl` contains the+`[Context Window Handoff]` note and `[tool-result …]` entries, and a grep for+the codename hits.++## 14. Unit tests++```bash+node --test examples/pi-experimental-context-management/tests/*.test.mjs+```++`tests/context-window-core.test.mjs` covers the cut algorithm, the header+variants, the reset pipeline and its failure modes, the reminders, restore and+the compaction fallback; `tests/context-window-adapter.test.mjs` covers the io+binding; `tests/client-archives.test.mjs` the archive endpoints. Node strips TS+types, so the tests import the `.ts` modules directly.diff --git a/examples/pi-experimental-context-management/README.md b/examples/pi-experimental-context-management/README.mdnew file mode 100644index 000000000..b8d26d7c4--- /dev/null+++ b/examples/pi-experimental-context-management/README.md@@ -0,0 +1,175 @@+# pi × OpenViking — experimental context management++> **EXPERIMENTAL.** A demo extension, not a supported product. It changes what+> the model sees on every provider request. Do not point it at a session you+> cannot afford to lose, and do not load it next to the `openviking` extension.++## What this is++A fork of [`examples/pi-coding-agent-extension`](../pi-coding-agent-extension)+in which takeover mode is replaced by **agent-managed context windows** — a+pi-side take on Codex's `features.context_management.experimental_mode`.++The model decides when the current window is done and calls `new_context`. The+extension archives the conversation to OpenViking, waits for the server to write+a Working Memory of it, and then cuts everything up to that tool call out of the+next provider request, putting a frozen window header in front: the model's own+handoff notes, the reason it gave, the user's last request and the Working+Memory. Nothing is summarized by an LLM, and nothing is deleted — closed windows+are readable again through the `history` tool.++Everything else the upstream extension does — turn sync, recall before every+prompt, profile injection, the `viking_*` tools — still works.++Full design, exact prompt texts, failure matrix and the e2e gate:+[CONTEXT-WINDOW.md](./CONTEXT-WINDOW.md).++## Install++```bash+pi install /abs/path/to/examples/pi-experimental-context-management+```++**Disable the `openviking` extension first.** Both register the same `viking_*`+tools and both sync the same OpenViking session, so loading them together+duplicates every tool and gives one session two writers. Set+`"enabled": false` in `~/.pi/agent/extensions/openviking/config.json`, or drop+it from `settings.json`'s `packages`. As a backstop, this extension looks for a+`viking_search` registered from a directory other than its own — at startup and+again on every event boundary, because the other extension registers its tools+only after an awaited health check — and stands down with a warning when it+finds one. Once a window is open the stand-down is skipped (dropping the cut+would hand the model back a conversation it was told is archived); it warns+instead.++Credentials resolve exactly as upstream: `OPENVIKING_*` environment variables →+`~/.openviking/ovcli.conf` → `ov.conf`. No new config file.++## Quick config++`config.json` keeps the upstream fields (minus `captureMode` — capture here is+always faithful — and minus `commitTokenThreshold` / `resumeContextBudget`,+which nothing in this fork reads any more) and adds one nested `contextWindow`+block:++```json+{+ "captureToolResults": true,+ "contextWindow": {+ "resetDeadlineMs": 60000,+ "softPercent": 70,+ "hardPercent": 85,+ "idleGapMinutes": 30,+ "statusEveryTurn": true+ }+}+```++`resetDeadlineMs` bounds the blocking `new_context` call end to end (sync,+barrier, commit, and the wait for the server-side Working Memory — measured at+25–55s on the reference server, so 60s is the default). `softPercent` /+`hardPercent` are the one-shot reminder thresholds, clamped at runtime under+pi's own auto-compaction line. `statusEveryTurn` emits the one-line context+status after every user prompt. Two environment variables override the block+for one run: `OPENVIKING_CONTEXT_STATUS_EVERY_TURN` and+`OPENVIKING_CONTEXT_RESET_DEADLINE_MS`.++The full table, with ranges and clamping rules, is in+[CONTEXT-WINDOW.md §6](./CONTEXT-WINDOW.md#6-configuration-contextwindow-block).++## Tools++| Tool | Parameters | What it does |+| --- | --- | --- |+| `new_context` | `reason`, `notes`, `next_steps?` | Archives the current window to OpenViking and opens a fresh one. Blocks until the archive exists. Call it alone |+| `history` | `action`, `window?`, `item?`, `query?`, `offset?`, `limit?` | Reads closed windows: `list_windows`, `list_items`, `read_item`, `search_contents` |+| `get_context_remaining` | — | Tokens left, window age, turns, idle gaps, archive readiness, one advice line |+| `viking_search` | `query`, `scope?`, `limit?` | Semantic search over the OpenViking knowledge base |+| `viking_read` | `uri`, `level` | Read a `viking://` URI at `abstract` / `overview` / `full` detail |+| `viking_browse` | `action`, `uri?` | `list` or `stat` the store like a filesystem |+| `viking_remember` | `content`, `category?` | Store a fact in the session for memory extraction |+| `viking_forget` | `uri?`, `query?` | Delete a memory by URI or strongest match |+| `viking_add_resource` | `url` | Ingest an HTTP URL into OpenViking |++`viking_archive_expand` is gone — it read `viking://session/{id}`, a namespace+the server does not serve, and `history` replaces it.++## What differs from the upstream extension++- **Agent-managed windows instead of takeover**: no `takeover.ts`, no boundary+ state machine, no threshold-driven commit inside `syncBranch`. Archives are+ produced only by `new_context` and by the pi-compaction fallback.+- **Tool output reaches the archive.** `normalizeRole` recognises pi's+ `toolResult` messages and captures them as `[tool-result <toolName>] …`,+ bounded by `captureToolMaxChars`; `captureToolResults` defaults to true. The+ upstream adapter dropped them, which would have made `history` a false+ promise.+- **Capture is always faithful** — the archive is the only way back to a closed+ window, so nothing is filtered but plugin chatter and slash commands.+- **No recall injection ledger**: replaying historical recall blocks needed+ `SessionManager.buildContextEntries()`, which pi 0.80.3 does not expose.+ `injectRecall` prepends this turn's block to the newest user message only and+ skips any message that already carries an `<openviking-context` block — which+ is also what keeps it away from the frozen window header.+- **`sync.flushForTakeover()` is now `sync.flushBarrier({budgetMs})`**, so a+ reset can cap how long it waits for the pending queue to drain. The sync+ manager also counts messages OpenViking rejected for good; a window opened+ while that count is non-zero says so in its header, because those messages are+ missing from the archive that `history` reads.++## Layout++| Path | What it is |+| --- | --- |+| `index.ts` | Extension entry: event handlers, coexistence guard, static guidance, `/viking` command |+| `client.ts` | OpenViking HTTP client, including the archive read/list/grep helpers |+| `sync.ts` | Session sync, disk pending queue, `flushBarrier`, `commit` |+| `recall.ts` | Per-prompt recall search and injection |+| `config.ts`, `config.json` | Config, the `contextWindow` block, credential resolution |+| `tools.ts` | Six `viking_*` tools plus `new_context` / `history` / `get_context_remaining` |+| `context-window.ts` | Adapter binding the core to pi, the client and the sync manager |+| `lib/context-window-core.mjs` | Pure, harness-agnostic window state machine |+| `lib/text-budget.mjs` | Token estimation / truncation helpers |+| `lib/capture-adapter.mjs` | Branch entries → OpenViking message payloads |+| `lib/uri-guard-adapter.mjs` | Blocks builtin file tools on `viking://` URIs |+| `lib/pi-settings.mjs` | Reads pi's `compaction.reserveTokens` |+| `shared/` | Copied from `examples/memory-plugin-shared/lib` — do not edit (see "Not wired into the repo" below) |+| `scripts/` | The manual e2e gate (`e2e-window.mjs` with the `e2e-window.sh` wrapper), the `e2e-probe.ts` payload recorder and the setup wizard |+| `demo-evidence/` | A redacted snapshot of two real runs: transcripts, provider payloads either side of each reset, and the OpenViking archives pulled back off the server |++## Tests++```bash+node --test examples/pi-experimental-context-management/tests/*.test.mjs+```++These are not in the CI glob yet (see below), so run them locally. The+end-to-end gate is manual and needs live credentials — see+[CONTEXT-WINDOW.md §13](./CONTEXT-WINDOW.md#13-end-to-end-gate).++## Not wired into the repo++This directory is deliberately self-contained: nothing outside it changes. Two+repo-level hooks are therefore missing, and a maintainer who wants to promote+this out of experimental status has to add them:++- **CI does not run these tests.** Add+ `examples/pi-experimental-context-management/tests/*.test.mjs` to the+ `plugin-tests` glob list in `.github/workflows/pr.yml`.+- **`shared/` is not refreshed by the sync script.** Add a `TARGETS` entry for+ `examples/pi-experimental-context-management/shared` (with `PI_SHARED_FILES`)+ in `examples/memory-plugin-shared/sync.mjs`. Until then the copies here are+ frozen at the commit that added them and will drift as the shared modules+ change.++The root `.gitignore` ignores every `lib/` directory, so this extension carries+its own `.gitignore` with `!lib/` instead of adding another exception there.++## Links++- [CONTEXT-WINDOW.md](./CONTEXT-WINDOW.md) — design, prompts, failure matrix+- [examples/pi-coding-agent-extension](../pi-coding-agent-extension) — the+ stable extension this forks+- [docs/en/agent-integrations/11-pi.md](../../docs/en/agent-integrations/11-pi.md)+ · [docs/zh/agent-integrations/11-pi.md](../../docs/zh/agent-integrations/11-pi.md)+ — the pi integration docs for the stable extension; they do not cover this onediff --git a/examples/pi-experimental-context-management/client.ts b/examples/pi-experimental-context-management/client.tsnew file mode 100644index 000000000..1219ccded--- /dev/null+++ b/examples/pi-experimental-context-management/client.ts@@ -0,0 +1,856 @@+import type { OVConfig } from "./config.js";++// --- OV API Response Shapes ---+// All OV responses wrap in: { status: "ok"|"error", result: T, error?: {...}, ... }+// This client normalizes to { ok, result } internally.++export interface OVSearchResult {+ uri: string;+ context_type: string; // "memory" | "resource" | "skill"+ score: number;+ abstract: string;+ overview: string | null;+ level: number; // 0=L0, 1=L1, 2=L2+ category: string;+ match_reason: string;+}++export interface OVDirEntry {+ uri: string;+ name: string;+ isDir: boolean;+ size: number;+ mode: number;+ modTime: string;+ abstract: string;+}++export interface OVStatInfo {+ name: string;+ size: number;+ mode: number;+ modTime: string;+ isDir: boolean;+ isLocked: boolean;+ uri?: string;+ count?: number; // directories only+}++export interface OVSessionMeta {+ session_id: string;+ message_count: number;+ total_message_count?: number;+ commit_count: number;+ pending_tokens?: number;+ memories_extracted?: Record<string, number>;+ last_commit_at?: string;+ /** Canonical session root, e.g. `viking://user/default/sessions/pi-abc`. */+ uri?: string;+}++export interface OVSessionContext {+ latest_archive_overview: string | null;+ pre_archive_abstracts: any[];+ messages: any[];+ estimatedTokens: number;+ stats: {+ totalArchives: number;+ includedArchives: number;+ droppedArchives: number;+ failedArchives: number;+ activeTokens: number;+ archiveTokens: number;+ };+}++export interface OVCommitResult {+ /**+ * `accepted` = phase 1 wrote `history/archive_NNN/messages.jsonl` and a+ * background task is generating the Working Memory; `skipped` = nothing to+ * archive (see `reason`, e.g. `no_messages`).+ */+ status?: "accepted" | "skipped" | string;+ /** Number of messages archived (server also uses a boolean in some builds). */+ archived?: number | boolean;+ reason?: string;+ task_id?: string;+ /** `null` on a `skipped` commit — the server sends the key either way. */+ archive_uri?: string | null;+ trace_id?: string;+}++/** One message of `history/archive_NNN/messages.jsonl`. */+export interface OVArchiveMessage {+ id: string;+ role: string;+ /**+ * Parts rendered to one string: `text` parts verbatim, `tool` parts as+ * `[tool <name>] <input> <output>`, `context` parts as `[context <uri>]`.+ * A part the renderer does not understand never silently disappears.+ */+ text: string;+ parts: any[];+ created_at: string;+}++/** One `history/archive_NNN` directory of a session. */+export interface OVArchiveEntry {+ archiveId: string;+ uri: string;+ modTime: string;+ abstract: string;+}++/** One grep hit inside a session archive. */+export interface OVArchiveGrepMatch {+ archiveId: string;+ /** File inside the archive, e.g. `messages.jsonl` or `.overview.md`. */+ file: string;+ line: number;+ content: string;+}++export interface OVTaskStatus {+ status: string;+ stage?: string;+ error?: string;+}++export interface OVCommitResponse {+ result: OVCommitResult | null;+ traceId?: string;+ error?: any;+ status?: number;+}++export interface OVResponse<T> {+ ok: boolean;+ result: T | null;+ error?: any;+ status?: number;+ traceId?: string;+}++export class OVClient {+ private baseUrl: string;+ private apiKey: string;+ private account: string;+ private user: string;+ private peerId: string;+ connected: boolean = false;++ private resolvedSpaces: Map<string, string> = new Map();+ /** Canonical session roots, keyed by session id. Only successes are cached. */+ private sessionRoots: Map<string, string> = new Map();++ private static RESERVED_USER = new Set(["memories"]);+ private static RESERVED_AGENT = new Set(["memories", "skills", "instructions", "workspaces"]);++ /** Read-only access to config (for value access across modules). */+ readonly cfg: OVConfig;++ constructor(config: OVConfig) {+ this.cfg = config;+ this.baseUrl = config.endpoint.replace(/\/+$/, "");+ this.apiKey = config.apiKey;+ this.account = config.account;+ this.user = config.user;+ this.peerId = config.peerId;+ }++ private headers(): Record<string, string> {+ const h: Record<string, string> = { "Content-Type": "application/json" };+ if (this.apiKey) h["Authorization"] = `Bearer ${this.apiKey}`;+ if (this.account) h["X-OpenViking-Account"] = this.account;+ if (this.user) h["X-OpenViking-User"] = this.user;+ if (this.peerId) h["X-OpenViking-Actor-Peer"] = this.peerId;+ if (this.cfg.userAgent) h["User-Agent"] = this.cfg.userAgent;+ return h;+ }++ /** Core fetch wrapper. Returns { ok, result } after parsing OV's { status, result } envelope. */+ async fetchJSON<T>(path: string, init?: RequestInit, timeoutMs = 10000): Promise<OVResponse<T>> {+ const controller = new AbortController();+ // Cleared in `finally`: when fetch rejects the timer would otherwise keep+ // the event loop alive for the full timeout.+ const timer = setTimeout(() => controller.abort(), timeoutMs);+ try {+ const resp = await fetch(`${this.baseUrl}${path}`, {+ ...init,+ headers: { ...this.headers(), ...(init?.headers as Record<string, string> || {}) },+ signal: controller.signal,+ });+ const body = await resp.json().catch(() => ({}));+ const traceId = body?.result?.trace_id || body?.error?.trace_id || body?.trace_id || undefined;+ if (!resp.ok || body.status === "error") {+ return {+ ok: false,+ result: null,+ status: resp.status,+ error: body.error || { message: `HTTP ${resp.status}` },+ traceId,+ };+ }+ return { ok: true, result: (body.result ?? body) as T, traceId };+ } catch (err: any) {+ return { ok: false, result: null, status: 0, error: { message: err?.message || String(err) } };+ } finally {+ clearTimeout(timer);+ }+ }++ // ========== Health ==========++ async health(): Promise<boolean> {+ const res = await this.fetchJSON<any>("/health", undefined, 5000);+ this.connected = res.ok;+ return res.ok;+ }++ // ========== Sessions ==========++ /** POST /api/v1/sessions — create or reuse session */+ async createSession(sessionId: string): Promise<boolean> {+ const res = await this.fetchJSON<any>("/api/v1/sessions", {+ method: "POST",+ body: JSON.stringify({ session_id: sessionId }),+ });+ return res.ok;+ }++ /** GET /api/v1/sessions/{id} — session metadata */+ async getSession(sessionId: string, autoCreate = false): Promise<OVSessionMeta | null> {+ const q = autoCreate ? "?auto_create=true" : "";+ const res = await this.fetchJSON<OVSessionMeta>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}${q}`,+ undefined, 5000,+ );+ return res.ok ? res.result : null;+ }++ /** GET /api/v1/sessions/{id}/context — assembled context with archive overview */+ async getSessionContext(sessionId: string, tokenBudget = 128000): Promise<OVSessionContext | null> {+ const res = await this.fetchJSON<OVSessionContext>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/context?token_budget=${tokenBudget}`,+ undefined, 10000,+ );+ return res.ok ? res.result : null;+ }++ /** POST /api/v1/sessions/{id}/messages — add a message (simple text mode) */+ async addMessage(sessionId: string, role: string, content: string): Promise<boolean> {+ const res = await this.fetchJSON<any>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,+ { method: "POST", body: JSON.stringify({ role, content }) },+ 10000,+ );+ return res.ok;+ }++ /** POST /api/v1/sessions/{id}/messages — add a message with parts */+ async addMessageParts(sessionId: string, role: string, parts: any[]): Promise<boolean> {+ const res = await this.fetchJSON<any>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,+ { method: "POST", body: JSON.stringify({ role, parts }) },+ 10000,+ );+ return res.ok;+ }++ async addMessagePayload(sessionId: string, payload: any): Promise<boolean> {+ const res = await this.fetchJSON<any>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,+ { method: "POST", body: JSON.stringify(payload) },+ 10000,+ );+ return res.ok;+ }++ /** POST /api/v1/sessions/{id}/commit — commit session for archiving + extraction */+ async commitSessionResponse(+ sessionId: string,+ keepRecentCount = this.cfg.commitKeepRecentCount,+ ): Promise<OVCommitResponse> {+ const res = await this.fetchJSON<OVCommitResult>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,+ { method: "POST", body: JSON.stringify({ keep_recent_count: keepRecentCount }) },+ 30000,+ );+ if (res.ok && res.result && !res.result.trace_id && res.traceId) {+ res.result.trace_id = res.traceId;+ }+ return {+ result: res.ok ? res.result : null,+ traceId: res.traceId,+ error: res.error,+ status: res.status,+ };+ }++ async commitSession(+ sessionId: string,+ keepRecentCount = this.cfg.commitKeepRecentCount,+ ): Promise<OVCommitResult | null> {+ return (await this.commitSessionResponse(sessionId, keepRecentCount)).result;+ }++ /** DELETE /api/v1/sessions/{id} */+ async deleteSession(sessionId: string): Promise<boolean> {+ const res = await this.fetchJSON<any>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}`,+ { method: "DELETE" },+ 10000,+ );+ return res.ok;+ }++ // ========== Session archives ==========+ //+ // `GET /api/v1/sessions/{id}/archives/{archive_id}` is blocked (403 ApiBlocked)+ // on the target gateway, so everything here goes through the generic+ // filesystem / content / grep routes against the session root URI.+ //+ // Every method in this section is failure-tolerant by contract: it returns+ // null (single value) or [] (list) instead of throwing, so callers can treat+ // "OpenViking did not answer" the same as "nothing there".++ /**+ * Session root URI, e.g. `viking://user/default/sessions/pi-abc`.+ *+ * Reads the canonical `uri` from `GET /api/v1/sessions/{id}` and caches it.+ * When the server does not answer (or answers without a `viking://` uri) this+ * falls back to the legacy alias `viking://session/{id}`, which the target+ * server still accepts. The fallback is deliberately NOT cached so a later+ * call can still pick up the canonical URI. Note the `viking://~` alias is+ * rejected by the server ("Invalid scope '~'") and is never produced here.+ */+ async sessionRootUri(sessionId: string): Promise<string> {+ const id = String(sessionId ?? "");+ const cached = this.sessionRoots.get(id);+ if (cached) return cached;+ try {+ const meta = await this.getSession(id);+ const uri = typeof meta?.uri === "string" ? stripTrailingSlash(meta.uri.trim()) : "";+ if (uri.startsWith("viking://")) {+ this.sessionRoots.set(id, uri);+ return uri;+ }+ } catch {+ // fall through to the legacy alias+ }+ return `viking://session/${id}`;+ }++ /** Strip `/history/archive_NNN` off a commit's `archive_uri` to get the session root. */+ static archiveUriToRoot(archiveUri: string): string {+ return archiveUriToRoot(archiveUri);+ }++ /** Instance alias of {@link OVClient.archiveUriToRoot}. */+ archiveUriToRoot(archiveUri: string): string {+ return archiveUriToRoot(archiveUri);+ }++ /**+ * Working Memory of one archive: `GET /content/read?uri=<archive>/.overview.md`.+ *+ * Returns null while commit phase 2 is still running (the server answers 404+ * NOT_FOUND until then) and on any other failure. The server stores this+ * sidecar as OKF Markdown — `---\n<yaml>\n---\n\n<body>\n` — and+ * `content/read` only strips that for memory URIs, not for session archives,+ * so the frontmatter is removed here and callers get the Working Memory body.+ *+ * A file that is present but has no body counts as "not ready" (null), so a+ * caller polling for the Working Memory cannot be fooled by an empty write.+ */+ async readArchiveOverview(archiveUri: string): Promise<string | null> {+ const base = stripTrailingSlash(String(archiveUri ?? "").trim());+ if (!base) return null;+ const res = await this.fetchJSON<string>(+ `/api/v1/content/read?uri=${encodeURIComponent(`${base}/.overview.md`)}`,+ undefined, 15000,+ );+ if (!res.ok || typeof res.result !== "string") return null;+ const body = stripFrontmatter(res.result);+ return body.trim() ? body : null;+ }++ /**+ * Messages of one archive: `GET /content/read?uri=<archive>/messages.jsonl`.+ *+ * Readable right after commit phase 1. A line that is malformed or blank+ * becomes a placeholder item rather than failing the read or shifting the+ * ones after it. Returns null when the file cannot be read at all.+ */+ async readArchiveMessages(archiveUri: string): Promise<OVArchiveMessage[] | null> {+ const base = stripTrailingSlash(String(archiveUri ?? "").trim());+ if (!base) return null;+ const res = await this.fetchJSON<string>(+ `/api/v1/content/read?uri=${encodeURIComponent(`${base}/messages.jsonl`)}`,+ undefined, 15000,+ );+ if (!res.ok || typeof res.result !== "string") return null;++ // Every line of the file has to produce exactly one item, because+ // `search_contents` turns a grep hit's line number into an item index+ // (`line - 1`). The only thing dropped is the empty string left behind by a+ // trailing final newline, which is not a line of its own.+ const lines = res.result.split("\n");+ if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();++ const out: OVArchiveMessage[] = [];+ for (const rawLine of lines) {+ const line = rawLine.trim();+ let obj: any = null;+ if (line) {+ try {+ obj = JSON.parse(line);+ } catch {+ obj = null; // a truncated or non-JSON line must not lose the rest+ }+ }+ if (!obj || typeof obj !== "object" || Array.isArray(obj)) {+ out.push({+ id: "",+ role: line ? "unreadable" : "blank",+ text: line ? "(unreadable archive line)" : "(blank archive line)",+ parts: [],+ created_at: "",+ });+ continue;+ }+ const parts = Array.isArray(obj.parts) ? obj.parts : [];+ out.push({+ id: obj.id == null ? "" : String(obj.id),+ role: obj.role == null ? "" : String(obj.role),+ text: renderMessageText(parts, obj.content),+ parts,+ created_at: obj.created_at == null ? "" : String(obj.created_at),+ });+ }+ return out;+ }++ /**+ * Archive directories of a session, newest first.+ * `GET /fs/ls?uri=<root>/history&sort_by=name&sort_order=desc`.+ *+ * Returns `null` when the listing request itself failed (401/403/5xx/timeout)+ * and `[]` only when the session genuinely has no archives. The two must stay+ * distinguishable: `history` tells the model to trust an empty history and+ * not ask the user, which would be exactly wrong for an unreachable server.+ */+ async listSessionArchives(sessionId: string): Promise<OVArchiveEntry[] | null> {+ const root = await this.sessionRootUri(sessionId);+ const res = await this.fetchJSON<any[]>(+ `/api/v1/fs/ls?uri=${encodeURIComponent(`${root}/history`)}&sort_by=name&sort_order=desc`,+ undefined, 10000,+ );+ // A missing history directory is an empty history, not a failure.+ if (!res.ok) return isNotFound(res) ? [] : null;+ if (!Array.isArray(res.result)) return null;++ const rows: OVArchiveEntry[] = [];+ for (const e of res.result) {+ // The agent-format listing has no `name`, so the URI basename leads.+ const uri = stripTrailingSlash(typeof e?.uri === "string" ? e.uri : "");+ const archiveId = uriBasename(uri) || (typeof e?.name === "string" ? e.name : "");+ if (!ARCHIVE_ID_RE.test(archiveId)) continue;+ if (e?.isDir === false) continue; // an archive is always a directory+ rows.push({+ archiveId,+ uri,+ modTime: typeof e?.modTime === "string" ? e.modTime : "",+ abstract: typeof e?.abstract === "string" ? e.abstract : "",+ });+ }+ // Do not rely on the server honouring sort_order: archive ids are numbered,+ // so order them here as well.+ rows.sort((a, b) => archiveIndex(b.archiveId) - archiveIndex(a.archiveId));+ return rows;+ }++ /**+ * `POST /search/grep` over `<root>/history` (or one archive).+ *+ * `pattern` is a REGULAR EXPRESSION by default; pass `{ literal: true }` to+ * search for the text verbatim (the pattern is regex-escaped then).+ */+ async grepSessionArchives(+ sessionId: string,+ pattern: string,+ opts?: { archiveId?: string; caseInsensitive?: boolean; nodeLimit?: number; literal?: boolean },+ ): Promise<OVArchiveGrepMatch[]> {+ const raw = String(pattern ?? "");+ if (!raw) return [];+ const root = await this.sessionRootUri(sessionId);+ const archiveId = opts?.archiveId && ARCHIVE_ID_RE.test(opts.archiveId) ? opts.archiveId : "";+ const uri = archiveId ? `${root}/history/${archiveId}` : `${root}/history`;+ const nodeLimit = Number.isFinite(opts?.nodeLimit as number)+ ? Math.max(1, Math.min(4096, Math.floor(opts!.nodeLimit as number)))+ : 256;++ const res = await this.fetchJSON<any>("/api/v1/search/grep", {+ method: "POST",+ body: JSON.stringify({+ uri,+ pattern: opts?.literal ? escapeRegExp(raw) : raw,+ case_insensitive: opts?.caseInsensitive !== false,+ node_limit: nodeLimit,+ }),+ }, 15000);+ if (!res.ok || !res.result) return [];++ const matches = Array.isArray(res.result?.matches)+ ? res.result.matches+ : Array.isArray(res.result) ? res.result : [];+ const out: OVArchiveGrepMatch[] = [];+ for (const m of matches) {+ if (!m || typeof m !== "object") continue;+ const matchUri = stripTrailingSlash(typeof m.uri === "string" ? m.uri : "");+ const line = Number(m.line);+ out.push({+ archiveId: archiveIdFromUri(matchUri) || archiveId,+ file: archiveFileFromUri(matchUri),+ line: Number.isFinite(line) ? line : 0,+ content: typeof m.content === "string" ? m.content : "",+ });+ }+ return out;+ }++ /** `GET /api/v1/tasks/{id}` — commit phase 2 progress (`pending|running|completed|failed`). */+ async getTask(taskId: string): Promise<OVTaskStatus | null> {+ const id = String(taskId ?? "").trim();+ if (!id) return null;+ const res = await this.fetchJSON<any>(+ `/api/v1/tasks/${encodeURIComponent(id)}`,+ undefined, 10000,+ );+ if (!res.ok || !res.result || typeof res.result !== "object") return null;+ const r = res.result as any;+ const out: OVTaskStatus = { status: String(r.status ?? r.state ?? "") };+ if (typeof r.stage === "string" && r.stage) out.stage = r.stage;+ const err = r.error ?? r.error_message ?? r.message;+ if (err) out.error = typeof err === "string" ? err : safeStringify(err);+ return out;+ }++ // ========== Search ==========++ /** POST /api/v1/search/find — basic vector search */+ async find(+ query: string,+ opts?: { targetUri?: string; topK?: number; scoreThreshold?: number },+ ): Promise<OVSearchResult[]> {+ const body: Record<string, unknown> = { query };+ if (opts?.targetUri) body.target_uri = opts.targetUri;+ if (opts?.topK) body.limit = opts.topK;+ if (opts?.scoreThreshold) body.score_threshold = opts.scoreThreshold;++ const res = await this.fetchJSON<any>("/api/v1/search/find", {+ method: "POST", body: JSON.stringify(body),+ }, 10000);+ if (!res.ok || !res.result) return [];++ // OV returns { memories: [...], resources: [...], skills: [...], total }+ const all: OVSearchResult[] = [];+ for (const bucket of ["memories", "resources", "skills"]) {+ const items = res.result[bucket];+ if (Array.isArray(items)) {+ for (const m of items) {+ all.push({+ uri: m.uri ?? "",+ context_type: m.context_type ?? (bucket === "memories" ? "memory" : bucket === "skills" ? "skill" : "resource"),+ score: m.score ?? 0,+ abstract: m.abstract ?? "",+ overview: m.overview ?? null,+ level: m.level ?? 0,+ category: m.category ?? "",+ match_reason: m.match_reason ?? "",+ });+ }+ }+ }+ return all;+ }++ // ========== Content ==========++ /** GET /api/v1/content/abstract — L0 summary */+ async abstract(uri: string): Promise<string | null> {+ const res = await this.fetchJSON<string>(+ `/api/v1/content/abstract?uri=${encodeURIComponent(uri)}`,+ undefined, 10000,+ );+ return res.ok ? res.result : null;+ }++ /** GET /api/v1/content/overview — L1 overview (directories only) */+ async overview(uri: string): Promise<string | null> {+ const res = await this.fetchJSON<string>(+ `/api/v1/content/overview?uri=${encodeURIComponent(uri)}`,+ undefined, 10000,+ );+ return res.ok ? res.result : null;+ }++ /** GET /api/v1/content/read — L2 full content (files only) */+ async readContent(uri: string): Promise<string | null> {+ const res = await this.fetchJSON<string>(+ `/api/v1/content/read?uri=${encodeURIComponent(uri)}`,+ undefined, 10000,+ );+ return res.ok ? res.result : null;+ }++ // ========== Filesystem ==========++ /** GET /api/v1/fs/ls — list directory */+ async ls(uri: string): Promise<OVDirEntry[]> {+ const res = await this.fetchJSON<any[]>(+ `/api/v1/fs/ls?uri=${encodeURIComponent(uri)}`,+ undefined, 10000,+ );+ if (!res.ok || !Array.isArray(res.result)) return [];+ return res.result.map(e => ({+ uri: e.uri ?? "",+ name: e.name ?? uriBasename(e.uri ?? ""),+ isDir: e.isDir ?? false,+ size: e.size ?? 0,+ mode: e.mode ?? 0,+ modTime: e.modTime ?? "",+ abstract: e.abstract ?? "",+ }));+ }++ /** GET /api/v1/fs/stat — file/directory metadata */+ async stat(uri: string): Promise<OVStatInfo | null> {+ const res = await this.fetchJSON<OVStatInfo>(+ `/api/v1/fs/stat?uri=${encodeURIComponent(uri)}`,+ undefined, 10000,+ );+ return res.ok ? res.result : null;+ }++ /** DELETE /api/v1/fs — remove file or directory */+ async delete(uri: string, recursive = false): Promise<boolean> {+ const res = await this.fetchJSON<any>(+ `/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=${recursive}`,+ { method: "DELETE" },+ 10000,+ );+ return res.ok;+ }++ // ========== Resources ==========++ /** POST /api/v1/resources — ingest a URL or file path */+ async addResource(+ path: string, opts?: { to?: string },+ ): Promise<{ root_uri: string } | null> {+ const body: Record<string, unknown> = { path };+ if (opts?.to) body.to = opts.to;+ const res = await this.fetchJSON<{ root_uri: string }>(+ "/api/v1/resources",+ { method: "POST", body: JSON.stringify(body) },+ 30000,+ );+ return res.ok ? res.result : null;+ }++ // ========== URI Space Resolution ==========++ async resolveScopeSpace(scope: "user" | "agent"): Promise<string> {+ const cached = this.resolvedSpaces.get(scope);+ if (cached) return cached;++ // Probe system status for user identity fallback+ let fallbackSpace = "default";+ const statusRes = await this.fetchJSON<any>("/api/v1/system/status", undefined, 5000);+ if (statusRes.ok && typeof statusRes.result?.user === "string" && statusRes.result.user.trim()) {+ fallbackSpace = statusRes.result.user.trim();+ }++ // List scope root for actual namespaces+ const reserved = scope === "user" ? OVClient.RESERVED_USER : OVClient.RESERVED_AGENT;+ const entries = await this.ls(`viking://${scope}/`);+ const spaces = entries+ .filter(e => e.isDir && !e.name.startsWith(".") && !reserved.has(e.name))+ .map(e => e.name);++ if (spaces.length > 0) {+ // Prefer the fallback space if it exists, then "default", then first available+ let chosen = spaces[0];+ if (spaces.includes(fallbackSpace)) chosen = fallbackSpace;+ else if (spaces.includes("default")) chosen = "default";+ this.resolvedSpaces.set(scope, chosen);+ return chosen;+ }++ this.resolvedSpaces.set(scope, fallbackSpace);+ return fallbackSpace;+ }++ async resolveTargetUri(targetUri: string): Promise<string> {+ const trimmed = targetUri.trim().replace(/\/+$/, "");+ const m = trimmed.match(/^viking:\/\/(user|agent)(?:\/(.*))?$/);+ if (!m) return trimmed;+ const scope = m[1] as "user" | "agent";+ const rawRest = (m[2] ?? "").trim();+ if (!rawRest) return trimmed;+ const parts = rawRest.split("/").filter(Boolean);+ if (parts.length === 0) return trimmed;++ const reserved = scope === "user" ? OVClient.RESERVED_USER : OVClient.RESERVED_AGENT;+ if (!reserved.has(parts[0])) return trimmed; // already has space++ const space = await this.resolveScopeSpace(scope);+ return `viking://${scope}/${space}/${parts.join("/")}`;+ }+}++function uriBasename(uri: string): string {+ const cleaned = uri.replace(/\/+$/, "");+ const last = cleaned.lastIndexOf("/");+ return last >= 0 ? cleaned.slice(last + 1) : cleaned;+}++const ARCHIVE_ID_RE = /^archive_\d+$/;++/**+ * "The path is not there" as opposed to "the request failed". A session that+ * never committed has no `history` directory, which is an empty archive list,+ * not an unreachable server.+ */+function isNotFound(res: { status?: number; error?: any }): boolean {+ if (res.status === 404) return true;+ const code = String(res.error?.code ?? res.error?.message ?? "");+ return /NOT_?FOUND/i.test(code);+}++function stripTrailingSlash(uri: string): string {+ return uri.replace(/\/+$/, "");+}++/** `viking://…/sessions/x/history/archive_003` → `viking://…/sessions/x`. */+export function archiveUriToRoot(archiveUri: string): string {+ const cleaned = stripTrailingSlash(String(archiveUri ?? "").trim());+ return cleaned.replace(/\/history\/archive_\d+(?:\/.*)?$/, "");+}++/** First `archive_NNN` segment of a URI, "" when there is none. */+export function archiveIdFromUri(uri: string): string {+ for (const seg of stripTrailingSlash(String(uri ?? "")).split("/")) {+ if (ARCHIVE_ID_RE.test(seg)) return seg;+ }+ return "";+}++/** Path inside the archive directory, e.g. `messages.jsonl` / `.overview.md`. */+function archiveFileFromUri(uri: string): string {+ const segs = stripTrailingSlash(String(uri ?? "")).split("/");+ const at = segs.findIndex(s => ARCHIVE_ID_RE.test(s));+ if (at >= 0) return segs.slice(at + 1).join("/");+ return segs.length ? segs[segs.length - 1] : "";+}++function archiveIndex(archiveId: string): number {+ const n = Number.parseInt(archiveId.replace(/^archive_/, ""), 10);+ return Number.isFinite(n) ? n : -1;+}++function escapeRegExp(text: string): string {+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");+}++/**+ * Drop a leading `---` … `---` YAML frontmatter block, if the text opens with+ * one, together with the blank line the server writes after it (its sidecars+ * are rendered as `---\n<yaml>\n---\n\n<body>\n`).+ */+function stripFrontmatter(text: string): string {+ const m = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);+ if (!m) return text;+ return text.slice(m[0].length).replace(/^(?:[ \t]*\r?\n)+/, "");+}++function safeStringify(value: unknown): string {+ try {+ return JSON.stringify(value) ?? String(value);+ } catch {+ return String(value);+ }+}++function renderValue(value: unknown): string {+ if (value == null) return "";+ return typeof value === "string" ? value : safeStringify(value);+}++/**+ * Render one `tool` part.+ *+ * The server serializes a tool part as `{type:"tool", tool_id, tool_name,+ * tool_uri, skill_uri, tool_status, tool_input?, tool_output?, …}` (see+ * `openviking/message/message.py::_part_to_dict`) — a call carries only+ * `tool_input`, a result carries `tool_output`. Older/foreign shapes+ * (`output` / `result` / `input` / `arguments`) are still accepted.+ *+ * The `[tool <name>]` label is emitted even when both sides are empty: a+ * message whose only part is a tool call must not read back as blank, which is+ * the whole promise of the `history` tool.+ */+function renderToolPart(part: any): string {+ const rawName = part.tool_name ?? part.toolName ?? part.name ?? "";+ const name = String(rawName ?? "").trim() || "unknown";+ const input = renderValue(part.tool_input ?? part.input ?? part.arguments ?? part.args);+ let output = renderValue(part.tool_output ?? part.output ?? part.result);+ if (!output && typeof part.content === "string") output = part.content;+ if (!output && typeof part.text === "string") output = part.text;+ // Large outputs are stored outside the message; point at them instead of+ // rendering an empty result.+ if (!output && typeof part.tool_output_ref === "string" && part.tool_output_ref) {+ output = `<output stored at ${part.tool_output_ref}>`;+ }++ const chunks: string[] = [];+ if (input) chunks.push(input);+ if (output) chunks.push(output);+ return chunks.length ? `[tool ${name}] ${chunks.join(" ")}` : `[tool ${name}]`;+}++/** Render one archived part; unknown shapes render to "" and are dropped. */+function renderPart(part: any): string {+ if (part == null) return "";+ if (typeof part === "string") return part;+ if (typeof part !== "object") return "";++ const type = typeof part.type === "string" ? part.type : "";+ const isTool = type.includes("tool")+ || part.tool_name != null || part.toolName != null+ || part.tool_output != null || part.tool_input != null;+ if (isTool) return renderToolPart(part);++ if (type === "context") {+ const uri = typeof part.uri === "string" ? part.uri : "";+ const abstract = typeof part.abstract === "string" ? part.abstract.trim() : "";+ if (!uri && !abstract) return "";+ return abstract ? `[context ${uri}] ${abstract}` : `[context ${uri}]`;+ }+ if (type === "image") return "[image]";++ if (typeof part.text === "string") return part.text;+ if (typeof part.content === "string") return part.content;+ return "";+}++function renderMessageText(parts: any[], content?: unknown): string {+ const chunks: string[] = [];+ for (const part of parts) {+ const rendered = renderPart(part);+ if (rendered) chunks.push(rendered);+ }+ if (chunks.length === 0 && typeof content === "string") return content;+ return chunks.join("\n");+}diff --git a/examples/pi-experimental-context-management/config.json b/examples/pi-experimental-context-management/config.jsonnew file mode 100644index 000000000..014bff59c--- /dev/null+++ b/examples/pi-experimental-context-management/config.json@@ -0,0 +1,31 @@+{+ "enabled": true,+ "syncTurns": true,+ "recallTokenBudget": 2000,+ "recallMaxContentChars": 500,+ "recallPreferAbstract": true,+ "scoreThreshold": 0.35,+ "minQueryLength": 3,+ "profileTokenBudget": 10000,+ "commitKeepRecentCount": 10,+ "captureToolResults": true,+ "captureMaxLength": 24000,+ "captureToolMaxChars": 1000000,+ "captureAssistantTurns": true,+ "bypassPatterns": [],+ "logLevel": "error",+ "contextWindow": {+ "resetDeadlineMs": 60000,+ "archivePollMs": 2000,+ "overviewRefreshMaxAttempts": 20,+ "overviewBudget": 3000,+ "notesBudget": 1500,+ "pendingRequestBudget": 400,+ "softPercent": 70,+ "hardPercent": 85,+ "idleGapMinutes": 30,+ "statusEveryTurn": true,+ "historyItemMaxChars": 8000,+ "recentResetGuardMs": 60000+ }+}diff --git a/examples/pi-experimental-context-management/config.ts b/examples/pi-experimental-context-management/config.tsnew file mode 100644index 000000000..5092e58d3--- /dev/null+++ b/examples/pi-experimental-context-management/config.ts@@ -0,0 +1,272 @@+import { readFileSync, existsSync } from "node:fs";+import { join, dirname } from "node:path";+import { fileURLToPath } from "node:url";+import { buildUserAgent, resolveOpenVikingCredentials } from "./shared/credentials.mjs";+import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs";++/** Hand-maintained: this extension ships no manifest to read a version from. */+export const EXTENSION_VERSION = "0.1.0";++/**+ * Agent-driven context windows. Every number is clamped on load: these bound+ * a blocking tool call and the size of the frozen window header, so an absurd+ * value in `config.json` must not be able to hang a reset or blow the header+ * past the budget the model reads it under.+ */+export interface OVContextWindowConfig {+ /** Total budget for one reset: sync, barrier, commit and archive wait. */+ resetDeadlineMs: number;+ /** Delay between `.overview.md` polls while Phase 2 runs. */+ archivePollMs: number;+ /** Non-blocking retries at `turn_end` when a window opened without its overview. */+ overviewRefreshMaxAttempts: number;+ /** Token budget for the Working Memory block in the window header. */+ overviewBudget: number;+ /** Token budget for the agent's handoff notes in the window header. */+ notesBudget: number;+ /** Token budget for the last user message carried into the new window. */+ pendingRequestBudget: number;+ /** Context usage that earns one soft "checkpoint soon" reminder. */+ softPercent: number;+ /** Context usage that earns one hard "reset now" reminder; never below `softPercent`. */+ hardPercent: number;+ /** Idle gap after which the status line suggests considering a new window. */+ idleGapMinutes: number;+ /** Append a one-line context status after every user prompt. */+ statusEveryTurn: boolean;+ /** Per-item cap for `history` reads out of an archived `messages.jsonl`. */+ historyItemMaxChars: number;+ /**+ * How long after a reset `session_before_compact` refuses to archive again.+ * A provider hiccup can make pi estimate from the untransformed list and+ * compact a window that just opened; inside this guard the current header is+ * returned as the summary instead.+ */+ recentResetGuardMs: number;+}++export interface OVConfig {+ enabled: boolean;+ endpoint: string;+ apiKey: string;+ account: string;+ user: string;+ peerId: string;+ userAgent: string;+ harness: string;+ workspacePeer: boolean;+ recallPeerScope: "actor" | "all";+ recallQueryExpansion: "auto" | "off";+ recallQueryExpansionConfigured: boolean;+ syncTurns: boolean;+ recallTokenBudget: number;+ recallMaxContentChars: number;+ recallPreferAbstract: boolean;+ recallLimit: number;+ recallLimitConfigured: boolean;+ scoreThreshold: number;+ minQueryLength: number;+ profileTokenBudget: number;+ commitKeepRecentCount: number;+ /**+ * Fixed on in this fork: the archive is the model's only way back to a+ * closed context window, so capture stays faithful to what was said.+ */+ faithfulCapture: true;+ captureToolResults: boolean;+ captureMaxLength: number;+ captureToolMaxChars: number;+ captureAssistantTurns: boolean;+ bypassPatterns: string[];+ logLevel: "silent" | "error" | "info";+ debugLogPath: string;+ contextWindow: OVContextWindowConfig;+}++const DEFAULT_CONFIG: OVConfig = {+ enabled: true,+ endpoint: "http://127.0.0.1:1933",+ apiKey: "",+ account: "",+ user: "",+ peerId: "",+ userAgent: "",+ harness: "pi",+ workspacePeer: true,+ recallPeerScope: "all",+ // Server-side query expansion costs a model call before retrieval starts, so+ // it has to be switchable from the client that pays the latency.+ recallQueryExpansion: "auto",+ recallQueryExpansionConfigured: false,+ syncTurns: true,+ recallTokenBudget: 2000,+ recallMaxContentChars: 500,+ recallPreferAbstract: true,+ recallLimit: 10,+ recallLimitConfigured: false,+ scoreThreshold: 0.35,+ minQueryLength: 3,+ profileTokenBudget: 10000,+ commitKeepRecentCount: 10,+ faithfulCapture: true,+ // The `history` tool promises the archive can be read back, so tool output+ // has to reach OpenViking — unlike the non-experimental extension.+ captureToolResults: true,+ captureMaxLength: 24000,+ captureToolMaxChars: 1000000,+ captureAssistantTurns: true,+ bypassPatterns: [],+ logLevel: "error",+ debugLogPath: "",+ contextWindow: {+ resetDeadlineMs: 60000,+ archivePollMs: 2000,+ overviewRefreshMaxAttempts: 20,+ overviewBudget: 3000,+ notesBudget: 1500,+ pendingRequestBudget: 400,+ softPercent: 70,+ hardPercent: 85,+ idleGapMinutes: 30,+ statusEveryTurn: true,+ historyItemMaxChars: 8000,+ recentResetGuardMs: 60000,+ },+};++export function loadConfigFromModuleUrl(moduleUrl: string): OVConfig {+ return loadConfig(dirname(fileURLToPath(moduleUrl)));+}++export function loadConfig(extensionDir: string): OVConfig {+ const configPath = join(extensionDir, "config.json");+ let file: any = {};+ try {+ if (existsSync(configPath)) file = JSON.parse(readFileSync(configPath, "utf8"));+ } catch {+ file = {};+ }++ const creds = resolveOpenVikingCredentials();+ // Nested block: keys are picked one by one, so an unknown key in+ // `contextWindow` is ignored instead of landing in the config.+ const cw = file.contextWindow && typeof file.contextWindow === "object" ? file.contextWindow : {};+ const cwDefaults = DEFAULT_CONFIG.contextWindow;+ const config: OVConfig = {+ ...DEFAULT_CONFIG,+ ...file,+ endpoint: creds.baseUrl,+ apiKey: creds.apiKey,+ account: creds.account,+ user: creds.user,+ peerId: creds.peerId || (typeof file.peerId === "string" ? file.peerId : DEFAULT_CONFIG.peerId),+ userAgent: buildUserAgent("pi", EXTENSION_VERSION),+ harness: "pi",+ recallLimitConfigured: Object.prototype.hasOwnProperty.call(file, "recallLimit"),+ recallQueryExpansionConfigured: Object.prototype.hasOwnProperty.call(file, "recallQueryExpansion"),+ recallTokenBudget: file.recallTokenBudget ?? file.recallBudget ?? DEFAULT_CONFIG.recallTokenBudget,+ scoreThreshold: file.scoreThreshold ?? file.recallScoreThreshold ?? DEFAULT_CONFIG.scoreThreshold,+ minQueryLength: file.minQueryLength ?? file.recallMinQueryLength ?? DEFAULT_CONFIG.minQueryLength,+ profileTokenBudget: file.profileTokenBudget ?? file.profileBudget ?? DEFAULT_CONFIG.profileTokenBudget,+ faithfulCapture: true,+ contextWindow: {+ resetDeadlineMs: cw.resetDeadlineMs ?? cwDefaults.resetDeadlineMs,+ archivePollMs: cw.archivePollMs ?? cwDefaults.archivePollMs,+ overviewRefreshMaxAttempts: cw.overviewRefreshMaxAttempts ?? cwDefaults.overviewRefreshMaxAttempts,+ overviewBudget: cw.overviewBudget ?? cwDefaults.overviewBudget,+ notesBudget: cw.notesBudget ?? cwDefaults.notesBudget,+ pendingRequestBudget: cw.pendingRequestBudget ?? cwDefaults.pendingRequestBudget,+ softPercent: cw.softPercent ?? cwDefaults.softPercent,+ hardPercent: cw.hardPercent ?? cwDefaults.hardPercent,+ idleGapMinutes: cw.idleGapMinutes ?? cwDefaults.idleGapMinutes,+ statusEveryTurn: cw.statusEveryTurn ?? cwDefaults.statusEveryTurn,+ historyItemMaxChars: cw.historyItemMaxChars ?? cwDefaults.historyItemMaxChars,+ recentResetGuardMs: cw.recentResetGuardMs ?? cwDefaults.recentResetGuardMs,+ },+ };++ if (process.env.OPENVIKING_URL || process.env.OPENVIKING_BASE_URL) config.endpoint = creds.baseUrl;+ if (process.env.OPENVIKING_API_KEY || process.env.OPENVIKING_BEARER_TOKEN) config.apiKey = creds.apiKey;+ if (process.env.OPENVIKING_ACCOUNT) config.account = creds.account;+ if (process.env.OPENVIKING_USER) config.user = creds.user;+ if (process.env.OPENVIKING_PEER_ID) config.peerId = creds.peerId;+ if (process.env.OPENVIKING_WORKSPACE_PEER !== undefined) {+ config.workspacePeer = envBool(process.env.OPENVIKING_WORKSPACE_PEER, config.workspacePeer);+ }+ if (process.env.OPENVIKING_RECALL_PEER_SCOPE) {+ config.recallPeerScope = process.env.OPENVIKING_RECALL_PEER_SCOPE === "actor" ? "actor" : "all";+ }+ if (process.env.OPENVIKING_RECALL_LIMIT) {+ config.recallLimit = Number(process.env.OPENVIKING_RECALL_LIMIT);+ config.recallLimitConfigured = true;+ }+ if (process.env.OPENVIKING_RECALL_QUERY_EXPANSION) {+ config.recallQueryExpansion = process.env.OPENVIKING_RECALL_QUERY_EXPANSION === "off" ? "off" : "auto";+ config.recallQueryExpansionConfigured = true;+ }+ // OPENVIKING_DEBUG_LOG is the shared spelling; OV_DEBUG_LOG is pi's older+ // name, kept working so existing setups still log.+ const debugLogEnv = process.env.OPENVIKING_DEBUG_LOG || process.env.OV_DEBUG_LOG;+ if (debugLogEnv) config.debugLogPath = debugLogEnv;+ if (process.env.OPENVIKING_CONTEXT_STATUS_EVERY_TURN !== undefined) {+ config.contextWindow.statusEveryTurn = envBool(+ process.env.OPENVIKING_CONTEXT_STATUS_EVERY_TURN,+ config.contextWindow.statusEveryTurn,+ );+ }+ if (process.env.OPENVIKING_CONTEXT_RESET_DEADLINE_MS) {+ config.contextWindow.resetDeadlineMs = Number(process.env.OPENVIKING_CONTEXT_RESET_DEADLINE_MS);+ }++ config.recallLimit = clampInt(config.recallLimit, 1, 50, DEFAULT_CONFIG.recallLimit);+ config.recallMaxContentChars = clampInt(config.recallMaxContentChars, 100, 5000, DEFAULT_CONFIG.recallMaxContentChars);+ config.recallTokenBudget = clampInt(config.recallTokenBudget, 200, 50000, DEFAULT_CONFIG.recallTokenBudget);+ config.scoreThreshold = clampNumber(config.scoreThreshold, 0, 1, DEFAULT_CONFIG.scoreThreshold);+ config.minQueryLength = clampInt(config.minQueryLength, 1, 64, DEFAULT_CONFIG.minQueryLength);+ config.profileTokenBudget = clampInt(config.profileTokenBudget, 500, 50000, DEFAULT_CONFIG.profileTokenBudget);+ config.commitKeepRecentCount = clampInt(config.commitKeepRecentCount, 0, 1000, DEFAULT_CONFIG.commitKeepRecentCount);+ config.captureToolResults = config.captureToolResults !== false;+ config.captureMaxLength = clampInt(config.captureMaxLength, 200, 100000, DEFAULT_CONFIG.captureMaxLength);+ config.captureToolMaxChars = clampInt(config.captureToolMaxChars, 200, 1000000, DEFAULT_CONFIG.captureToolMaxChars);+ const window = config.contextWindow;+ window.resetDeadlineMs = clampInt(window.resetDeadlineMs, 5000, 600000, cwDefaults.resetDeadlineMs);+ window.archivePollMs = clampInt(window.archivePollMs, 250, 30000, cwDefaults.archivePollMs);+ window.overviewRefreshMaxAttempts = clampInt(window.overviewRefreshMaxAttempts, 0, 200, cwDefaults.overviewRefreshMaxAttempts);+ window.overviewBudget = clampInt(window.overviewBudget, 100, 50000, cwDefaults.overviewBudget);+ window.notesBudget = clampInt(window.notesBudget, 100, 20000, cwDefaults.notesBudget);+ window.pendingRequestBudget = clampInt(window.pendingRequestBudget, 0, 8000, cwDefaults.pendingRequestBudget);+ window.softPercent = clampInt(window.softPercent, 10, 99, cwDefaults.softPercent);+ window.hardPercent = clampInt(window.hardPercent, 10, 99, cwDefaults.hardPercent);+ // The hard reminder is the last one before the harness compacts on its own,+ // so it can never fire before the soft one.+ if (window.hardPercent < window.softPercent) window.hardPercent = window.softPercent;+ window.idleGapMinutes = clampInt(window.idleGapMinutes, 0, 1440, cwDefaults.idleGapMinutes);+ window.historyItemMaxChars = clampInt(window.historyItemMaxChars, 500, 100000, cwDefaults.historyItemMaxChars);+ window.recentResetGuardMs = clampInt(window.recentResetGuardMs, 0, 600000, cwDefaults.recentResetGuardMs);+ window.statusEveryTurn = envBool(String(window.statusEveryTurn), cwDefaults.statusEveryTurn);+ config.recallPeerScope = config.recallPeerScope === "actor" ? "actor" : "all";+ config.recallQueryExpansion = config.recallQueryExpansion === "off" ? "off" : "auto";+ if (!Array.isArray(config.bypassPatterns)) config.bypassPatterns = [];+ config.debugLogPath = typeof config.debugLogPath === "string" ? config.debugLogPath.trim() : "";+ config.peerId = resolveEffectivePeerId({ cfg: config as any, cwd: process.cwd() }).peerId;+ return config;+}++function envBool(value: string, fallback: boolean): boolean {+ const lower = String(value || "").trim().toLowerCase();+ if (lower === "0" || lower === "false" || lower === "no" || lower === "off") return false;+ if (lower === "1" || lower === "true" || lower === "yes" || lower === "on") return true;+ return fallback;+}++function clampInt(value: unknown, min: number, max: number, fallback: number): number {+ const next = Math.round(Number(value));+ if (!Number.isFinite(next)) return fallback;+ return Math.max(min, Math.min(max, next));+}++function clampNumber(value: unknown, min: number, max: number, fallback: number): number {+ const next = Number(value);+ if (!Number.isFinite(next)) return fallback;+ return Math.max(min, Math.min(max, next));+}diff --git a/examples/pi-experimental-context-management/context-window.ts b/examples/pi-experimental-context-management/context-window.tsnew file mode 100644index 000000000..45f93d6b9--- /dev/null+++ b/examples/pi-experimental-context-management/context-window.ts@@ -0,0 +1,182 @@+/**+ * Adapter: binds the pure `ContextWindowCore` to pi, the OpenViking client and+ * the sync manager. The core owns every decision; everything with an effect —+ * network, disk, pi APIs, the clock — arrives through this io object, which is+ * what makes the state machine testable without either side.+ */+import type { OVClient } from "./client.js";+import type { OVConfig } from "./config.js";+import type { SyncManager } from "./sync.js";+import { createRequire } from "node:module";+import { ContextWindowCore } from "./lib/context-window-core.mjs";+import { DEFAULT_RESERVE_TOKENS, readReserveTokens } from "./lib/pi-settings.mjs";+import { listPending } from "./shared/pending-queue.mjs";++/** Queued `addMessage` entries this OV session still owes the server. */+function countUndeliveredForSession(pendingEntries: any[], sid: string): number {+ if (!sid) return 0;+ let count = 0;+ for (const item of Array.isArray(pendingEntries) ? pendingEntries : []) {+ const entry =+ item && typeof item === "object" && item.entry && typeof item.entry === "object"+ ? item.entry+ : item;+ if (entry?.type === "addMessage" && entry.sessionId === sid) count++;+ }+ return count;+}++/** `sleep` that gives up as soon as the tool call is aborted. */+function abortableSleep(ms: number, signal?: AbortSignal | null): Promise<void> {+ const delay = Math.max(0, Math.floor(Number(ms) || 0));+ return new Promise<void>((resolve) => {+ if (signal?.aborted) {+ resolve();+ return;+ }+ let onAbort: (() => void) | null = null;+ const timer = setTimeout(() => {+ if (onAbort && signal) signal.removeEventListener("abort", onAbort);+ resolve();+ }, delay);+ if (signal) {+ onAbort = () => {+ clearTimeout(timer);+ resolve();+ };+ signal.addEventListener("abort", onAbort, { once: true });+ }+ });+}++export function createContextWindowManager(opts: {+ pi: any;+ client: OVClient;+ sync: SyncManager;+ config: OVConfig;+ logger?: { log?: (stage: string, data?: unknown) => void };+}): ContextWindowCore {+ const { pi, client, sync, config } = opts;++ // The core asks for the pending count synchronously (it only reports it in a+ // refusal message), so the number is refreshed whenever the barrier is asked+ // about and cached in between.+ let pendingCache = 0;+ const refreshPendingCache = async (): Promise<number> => {+ const sid = sync.sessionId;+ if (!sid) {+ pendingCache = 0;+ return 0;+ }+ try {+ pendingCache = countUndeliveredForSession(await listPending(), sid);+ } catch {+ pendingCache = 0;+ }+ return pendingCache;+ };++ return new ContextWindowCore({+ config: config.contextWindow,+ io: {+ syncBranch: (branch: any[]) => sync.syncBranch(branch),++ flush: async ({ budgetMs }: { budgetMs: number }) => {+ const ok = await sync.flushBarrier({ budgetMs });+ // Refresh here rather than in pendingCount(): this is the one moment+ // the core needs an accurate number, and it is already awaiting.+ if (ok) pendingCache = 0;+ else await refreshPendingCache();+ return ok;+ },++ // Direct write, never the queue: a handoff note that lands after the+ // commit would be archived into the *next* window instead of this one.+ postHandoff: async (text: string) => {+ const sid = sync.sessionId;+ if (!sid) return false;+ try {+ return await client.addMessage(sid, "assistant", text);+ } catch {+ return false;+ }+ },++ // `queueOnFailure:false` for the same reason: a queued commit would fire+ // later, splitting a window the model still believes it is inside.+ commit: async ({ keepRecentCount }: { keepRecentCount?: number } = {}) => {+ try {+ return await sync.commit({+ queueOnFailure: false,+ keepRecentCount: keepRecentCount ?? 0,+ });+ } catch {+ return null;+ }+ },++ readArchiveOverview: async (archiveUri: string) => {+ try {+ return await client.readArchiveOverview(archiveUri);+ } catch {+ return null;+ }+ },++ getTask: async (taskId: string) => {+ try {+ return await client.getTask(taskId);+ } catch {+ return null;+ }+ },++ persistEntry: (customType: string, data: any) => {+ if (typeof pi?.appendEntry === "function") pi.appendEntry(customType, data);+ },++ getWatermark: () => sync.syncedCount,+ pendingCount: () => pendingCache,+ droppedCount: () => sync.droppedCount,+ commitTraceId: () => sync.commitTraceId,+ now: () => Date.now(),+ sleep: (ms: number, signal?: AbortSignal | null) => abortableSleep(ms, signal),+ log: (message: string) => {+ opts.logger?.log?.("window", message);+ },+ connected: () => client.connected,+ sessionId: () => sync.sessionId,+ },+ });+}++/**+ * pi's `compaction.reserveTokens`, read from `<cwd>/.pi/settings.json` then+ * `~/.pi/agent/settings.json` (pi merges project over global). Used to clamp+ * the reminder thresholds under pi's own auto-compaction line.+ *+ * Best effort: any failure yields pi's own default, 16384.+ */+export function readPiReserveTokens(cwd?: string): number {+ let configDirName = ".pi";+ try {+ // Present since pi 0.80; the literal fallback keeps this working when the+ // package cannot be resolved from here (tests, a standalone checkout).+ const mod = createRequire(import.meta.url)("@earendil-works/pi-coding-agent");+ if (typeof mod?.CONFIG_DIR_NAME === "string" && mod.CONFIG_DIR_NAME) {+ configDirName = mod.CONFIG_DIR_NAME;+ }+ } catch {+ // keep ".pi"+ }+ try {+ return readReserveTokens({+ cwd: cwd ?? process.cwd(),+ configDirName,+ // pi's own override for the agent directory (`ENV_AGENT_DIR`).+ agentDir: process.env.PI_CODING_AGENT_DIR || "",+ });+ } catch {+ return DEFAULT_RESERVE_TOKENS;+ }+}diff --git a/examples/pi-experimental-context-management/demo-evidence/README.md b/examples/pi-experimental-context-management/demo-evidence/README.mdnew file mode 100644index 000000000..a4fc0a1a2--- /dev/null+++ b/examples/pi-experimental-context-management/demo-evidence/README.md@@ -0,0 +1,35 @@+# Demo evidence++`pi-ctxwin-demo.zip` is a redacted snapshot of the sandbox this extension was+demonstrated in, captured on 2026-09-11 against a live OpenViking server and+Volcengine's Doubao 2.1 Pro (`doubao-seed-2-1-pro-260628`) on Ark, with+`reasoning_effort: high`. It is here as evidence for the numbers quoted in the+docs: unpack it and read the transcripts rather than taking them on trust.++ unzip pi-ctxwin-demo.zip && cd pi-ctxwin-demo && $EDITOR README.md++Two runs are included.++**`demo-long/`** — the interesting one. The agent is given 22 source files+(411 KB, about 105k tokens if read in full) and asked to inventory them one by+one. The context tools are never mentioned in the prompt. Over 96 provider+requests it fills its window to 47% of 128k, resets, fills it again, and resets+twice more, finishing 22 of 22 files across four windows. `pressure-timeline.txt`+plots every request with the resets marked; `context-tool-calls.json` has the+reasons the agent gave, one of which reads "Context window reached ~45% (soft+reminder). 8 of 22 files inventoried so far; need a fresh window to finish the+remaining 14 files."++**`demo/`** — the short scripted gate, where the reset is instructed rather than+chosen, so the mechanics are easy to follow: the request before the cut, the+request after it, the same frozen header surviving a process restart, and the+OpenViking archive with the handoff message inside it.++Both folders carry the pi session file, the extension debug log, the provider+payloads either side of each reset, and the archives pulled back off the server+(Working Memory, raw messages, a grep result).++Reproduce either run with `scripts/e2e-window.sh`; see the extension README.+`REDACTIONS.md` inside the archive lists exactly what changed: the secrets file+is absent, the operator's username is replaced, and the private proxy the runs+went through is named as the official Ark endpoint it forwards to.diff --git a/examples/pi-experimental-context-management/demo-evidence/pi-ctxwin-demo.zip b/examples/pi-experimental-context-management/demo-evidence/pi-ctxwin-demo.zipnew file mode 100644index 000000000..7110648c9Binary files /dev/null and b/examples/pi-experimental-context-management/demo-evidence/pi-ctxwin-demo.zip differdiff --git a/examples/pi-experimental-context-management/index.ts b/examples/pi-experimental-context-management/index.tsnew file mode 100644index 000000000..47b7e931d--- /dev/null+++ b/examples/pi-experimental-context-management/index.ts@@ -0,0 +1,620 @@+/**+ * Pi OpenViking Extension — EXPERIMENTAL context management+ *+ * A fork of examples/pi-coding-agent-extension whose takeover mode is replaced+ * by agent-driven context windows: the model decides when a window ends, calls+ * `new_context`, and the extension archives the conversation to OpenViking and+ * cuts it out of the next provider request, leaving a frozen window header with+ * the Working Memory and the model's own handoff notes. `history` reads the+ * archived windows back, `get_context_remaining` reports the pressure. Turns+ * still sync to an OpenViking session and recall is still injected into the+ * newest user message.+ *+ * Do not load this together with the openviking extension — they would both+ * register `viking_*` tools and both sync the same OV session. As a backstop+ * this one stands down as soon as it sees a `viking_search` registered from+ * another extension's directory, which is re-checked on every event boundary+ * because that extension registers its tools only after a network round trip.+ */+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";+import { dirname } from "node:path";+import { fileURLToPath } from "node:url";+import { createLogger } from "./shared/debug-log.mjs";+import { loadConfigFromModuleUrl, type OVConfig } from "./config.js";+import { OVClient } from "./client.js";+import { RecallManager } from "./recall.js";+import { SyncManager } from "./sync.js";+import { buildProfileBlock } from "./shared/profile-inject.mjs";+import { guardVikingUriToolCall } from "./lib/uri-guard-adapter.mjs";+import { registerContextWindowTools, registerTools } from "./tools.js";+import { createContextWindowManager, readPiReserveTokens } from "./context-window.js";+import {+ buildStatusLine,+ messagesFromBranch,+ reminderText,+ REMINDER_CUSTOM_TYPE,+ STATUS_CUSTOM_TYPE,+} from "./lib/context-window-core.mjs";++/** The tool whose presence means the non-experimental extension is loaded. */+const COEXISTENCE_PROBE_TOOL = "viking_search";++/**+ * Static system-prompt guidance (plan §5). Identical for the whole session, so+ * it is appended once per turn without moving any prompt-cache boundary.+ * Unlike Codex we do not ask the model to hide this machinery from the user —+ * the demo is supposed to be visible.+ */+const CONTEXT_WINDOW_GUIDANCE = `<context-window-management>+You manage your own context window in this session. When the conversation grows it is not summarized behind your back: you decide when the current window ends, and OpenViking archives it so you can read it back afterwards.++Three tools do this:+- new_context — archive the current window and continue in a fresh one. OpenViking generates a Working Memory of the archived window, and your next window opens with that Working Memory, your handoff notes and the user's most recent request.+- history — read windows that were already archived: list_windows, list_items, read_item, search_contents. Closing a window loses nothing; it only stops being in front of you.+- get_context_remaining — how much room is left, how long this window has been open, and how long it has been since the user's last message.++Start a new window when:+- a phase of the work is finished and its details no longer matter for what comes next;+- the user switches to an unrelated topic or a different area of the code;+- the user comes back after a long idle gap with something new;+- the status line or get_context_remaining says the window is filling up — act when their advice line asks you to, and never ignore a [context-reminder]. If you wait until the window overflows, the harness compacts the conversation for you and your notes are never written.++Do not start a new window:+- in the middle of an edit sequence you have not verified;+- immediately after a reset;+- to get away from a problem you have not solved — the new window carries the same problem with less information.++Write the notes before you call new_context: the goal, the decisions and why you made them, what is finished, what is in flight, exact file paths and identifiers, and the next steps. Write them for someone who has not seen this conversation, because that is exactly what your next window is. Call new_context alone — tool results from the same batch are discarded together with the old window.++If new_context answers with "Context window NOT reset", nothing was archived and nothing was removed from your context: read the reason it gives, keep working in the current window, and do not call it again until that reason is gone.++In a new window, read the <openviking-context source="context-window"> block first: it carries the Working Memory, your notes and the request that is still pending. Use history for anything it does not cover, and never ask the user to repeat something an archived window already holds.+</context-window-management>`;++const TOOL_LIST_LINE =+ "OpenViking tools: viking_search, viking_read, viking_browse, viking_remember, viking_forget, viking_add_resource. " ++ "Context window tools: new_context, history, get_context_remaining.";++export default async function (pi: ExtensionAPI) {+ // --- Load config ---+ const config = loadConfigFromModuleUrl(import.meta.url);+ if (!config.enabled) return;++ // --- Initialize modules ---+ const client = new OVClient(config);+ const sync = new SyncManager(client, config);+ const recall = new RecallManager(client, config, () => sync.sessionId);+ const logger = createLogger("pi", {+ debug: Boolean(config.debugLogPath),+ debugLogPath: config.debugLogPath,+ });+ const windows = createContextWindowManager({ pi, client, sync, config, logger });++ // Session state+ let connected = false;+ let bypassed = false;+ let profileBlock = "";+ let toolsRegistered = false;+ /** The offline half of start() — session id, window restore, tools. */+ let offlineInitDone = false;+ let started = false;+ let startPromise: Promise<void> | null = null;+ /**+ * The message list the `context` hook last produced. `get_context_remaining`+ * needs the *transformed* list: the untransformed one still holds the closed+ * windows and would report the session, not the window.+ */+ let lastTransformed: any[] | undefined;+ const reserveTokens = readPiReserveTokens(process.cwd());++ /**+ * The message list a status readout is built from, with the window metrics+ * refreshed against it.+ *+ * `turnsInWindow`, the window token estimate and the last-user timestamps are+ * only recorded by `transformContext`, which runs in the `context` hook — and+ * that hook has not fired yet when the first prompt of a process reaches+ * `before_agent_start`. After `pi -c` the line would then describe a restored+ * window as "0 turns" with no idle gap, however many turns it already had in+ * the previous process. Rebuilding the list from the branch fixes that, and+ * keeps the count current on later prompts too: the branch already holds the+ * assistant message the previous turn's last `context` hook could not see.+ *+ * The branch is what pi builds the next provider request from anyway, so the+ * cut here only repeats the one the `context` hook will make. `observeMessages`+ * rather than `transformContext`: it touches the in-memory metrics and nothing+ * else — no persist, no network, and no right to release the boundary from a+ * list pi may not have finished writing.+ */+ const statusMessages = (ctx: any): any[] | undefined => {+ let branch: any[] | undefined;+ try {+ branch = ctx?.sessionManager?.getBranch?.();+ } catch {+ return lastTransformed;+ }+ if (!Array.isArray(branch) || branch.length === 0) return lastTransformed;+ try {+ return windows.observeMessages(messagesFromBranch(branch) as any[]);+ } catch (error) {+ logger.logError("status-metrics", error);+ return lastTransformed;+ }+ };++ /** This extension's own directory, to tell our tools from a peer's. */+ const ownDir = dirname(fileURLToPath(import.meta.url));++ /**+ * True when a *different* extension owns `viking_search`.+ *+ * A one-shot probe at startup cannot work: the other extension registers its+ * tools only after an awaited health check, so at the moment our own start()+ * begins the tool is provably not there yet. So the probe compares the+ * registering extension's `sourceInfo.path` with ours and is re-run on every+ * event boundary — pi's tool registry is keyed by name, so once the peer+ * registers, `viking_search` carries its path and not ours.+ */+ const peerOwnsToolSurface = (): boolean => {+ try {+ const tools = (pi as any).getAllTools?.();+ if (!Array.isArray(tools)) return false;+ for (const tool of tools) {+ if (tool?.name !== COEXISTENCE_PROBE_TOOL) continue;+ const path = String(tool?.sourceInfo?.path ?? tool?.sourceInfo?.baseDir ?? "");+ // No sourceInfo (an older pi, or a synthetic tool): fall back to "any+ // viking_search we did not register ourselves is a peer's".+ if (!path) return !toolsRegistered;+ if (path !== ownDir && !path.startsWith(ownDir + "/")) return true;+ }+ return false;+ } catch {+ return false;+ }+ };++ let peerWarned = false;++ /**+ * Stand down when the other OpenViking extension turns up. Two writers on one+ * OV session double every captured message and race on the archive boundary.+ *+ * Only safe while nothing irreversible has happened: once a window is open,+ * the model's context depends on our cut, and dropping it would hand back a+ * conversation we already told the model was archived. In that case the+ * conflict is reported and this extension keeps going.+ */+ const standDownIfPeerActive = (ctx: any): boolean => {+ if (bypassed) return true;+ if (!peerOwnsToolSurface()) return false;+ if (windows.armed || windows.state.windowIndex > 1 || sync.syncedCount > 0) {+ if (!peerWarned) {+ peerWarned = true;+ ctx?.ui?.notify?.(+ "OpenViking: another OpenViking extension is active and both are writing this session — disable one",+ "warning",+ );+ logger.log("coexistence", { standDown: false, reason: "window already open" });+ }+ return false;+ }+ bypassed = true;+ started = true;+ connected = false;+ if (!peerWarned) {+ peerWarned = true;+ ctx?.ui?.notify?.(+ "OpenViking experimental extension disabled: another OpenViking extension is already active",+ "warning",+ );+ }+ logger.log("coexistence", { standDown: true });+ return true;+ };++ // ================================================================+ // Event Handlers+ // ================================================================++ const start = async (ctx: any): Promise<void> => {+ if (started) return;+ if (startPromise) return startPromise;++ startPromise = (async () => {+ // Coexistence guard, before any registration. It runs again on every+ // event boundary because the peer registers its tools asynchronously.+ if (standDownIfPeerActive(ctx)) return;++ // Bypass check+ const cwd = process.cwd();+ for (const pattern of config.bypassPatterns) {+ if (matchBypass(cwd, pattern)) {+ bypassed = true;+ started = true;+ return;+ }+ }++ // Everything up to the health check is offline and must run even when OV+ // is down: `pi -c` otherwise replays a whole archived window back to the+ // model together with the tool result that claims it was archived.+ const piSessionId = ctx.sessionManager.getSessionId();+ if (!offlineInitDone) {+ // Derives "pi-<piSessionId>" locally; no request, so it cannot fail.+ await sync.ensureSession(piSessionId);++ const branch = ctx.sessionManager.getBranch?.() ?? [];+ const restored = windows.restore(branch);+ sync.restoreWatermark(Math.max(restored.syncedEntryCount ?? 0, sync.syncedCount));++ registerTools(pi, client, sync);+ registerContextWindowTools(pi, client, sync, windows, config, {+ getMessages: () => lastTransformed,+ reserveTokens,+ });+ toolsRegistered = true;+ offlineInitDone = true;+ }++ // Health check+ connected = await client.health();+ if (!connected) {+ if (config.logLevel === "info") {+ ctx.ui.notify("OpenViking: server not reachable", "warning");+ }+ return;+ }++ await sync.replayPending();++ // Profile injection+ profileBlock = await buildSessionProfileBlock(client, config);++ updateStatus(ctx, connected, windows, sync.sessionId);++ started = true;+ if (config.logLevel === "info") {+ ctx.ui.notify(`OpenViking connected (${piSessionId.slice(0, 8)}...)`, "info");+ }+ })().finally(() => {+ startPromise = null;+ });++ return startPromise;+ };++ // --- session_start ---+ pi.on("session_start", async (event, ctx) => {+ // Fire-and-forget: the OV chain (health check, session ensure, profile+ // build) costs ~2s against the remote server; blocking session_start on it+ // delays every pi startup. start() is memoized via startPromise, so+ // before_agent_start awaits the same in-flight chain before the first+ // provider request — the first turn still gets profile + recall.+ void start(ctx).catch((error) => {+ logger.logError("session_start", error);+ });+ });++ // --- before_agent_start ---+ pi.on("before_agent_start", async (event, ctx) => {+ // session_start doesn't fire for pi -c continuations.+ await start(ctx);+ // Re-checked here because the peer extension registers its tools from its+ // own awaited start(), which may only have finished after ours began.+ if (standDownIfPeerActive(ctx) || bypassed) return;++ // Queue recall for the context hook. Pi renders the user message before+ // that hook, so recall latency does not delay the message appearing.+ if (connected) recall.queueSearch(event.prompt);++ // Compose system prompt additions. The window guidance and the tool list+ // describe tools that are registered whether or not OV answers, so they go+ // in either way; only the profile block depends on the server.+ const parts: string[] = [];+ if (profileBlock) parts.push(profileBlock);+ parts.push(CONTEXT_WINDOW_GUIDANCE);+ parts.push(TOOL_LIST_LINE);++ const result: any = { systemPrompt: event.systemPrompt + "\n\n" + parts.join("\n\n") };++ // One status line per user prompt (not per sampling). It is derived from+ // local state only, so an unreachable server still gets the agent its+ // window id, its token pressure and the idle gap.+ if (config.contextWindow.statusEveryTurn) {+ const snapshot = windows.statusSnapshot({+ usage: (ctx as any).getContextUsage?.(),+ now: Date.now(),+ messages: statusMessages(ctx),+ reserveTokens,+ });+ result.message = {+ customType: STATUS_CUSTOM_TYPE,+ content: buildStatusLine({+ windowId: snapshot.windowId,+ turnsInWindow: snapshot.turnsInWindow,+ usedTokens: snapshot.usedTokens,+ contextWindow: snapshot.contextWindow,+ estimated: snapshot.estimated,+ sinceLastUserMs: snapshot.sinceLastUserMs,+ idleGapMs: snapshot.idleGapMs,+ idleGapMinutes: config.contextWindow.idleGapMinutes,+ }),+ display: true,+ };+ }++ return result;+ });++ // --- context ---+ pi.on("context", async (event, ctx) => {+ if (bypassed) return;++ // The window cut runs first and does not depend on the server: the anchor+ // is in the branch, and dropping it because OV is down would hand the model+ // an archived window back together with the tool result that archived it.+ const transformed = windows.transformContext(event.messages as any[]);+ lastTransformed = transformed;+ if (!connected) return { messages: transformed };++ // Everything after the cut is wrapped: pi keeps the *untransformed* list+ // when a context handler throws (runner.js emits the error and moves on),+ // so an exception in recall would undo the window cut and hand the model an+ // archived window back together with the tool result that archived it.+ try {+ // Keep recall synchronous with the provider request so the current prompt+ // still receives current-query memory, without blocking user-message UI.+ await recall.searchPending();+ const messages = recall.injectRecall(transformed);+ lastTransformed = messages;+ return { messages };+ } catch (error) {+ logger.logError("recall", error);+ return { messages: transformed };+ }+ });++ // --- tool_call ---+ pi.on("tool_call", async (event, _ctx) => {+ const decision = guardVikingUriToolCall(event);+ if (!decision) return;+ return decision;+ });++ // --- turn_end ---+ pi.on("turn_end", async (event, ctx) => {+ if (standDownIfPeerActive(ctx) || bypassed) return;++ if (connected && config.syncTurns) {+ const branch = ctx.sessionManager.getBranch();+ const result = await sync.syncBranch(branch);+ logger.log("turn_end", { added: result.added, tokens: result.tokens });+ }++ // Re-arm the reminders only for an assistant response that belongs to the+ // *current* window and actually produced usage. The turn a reset happens in+ // ends here too, and its assistant message is the pre-reset one: pi still+ // reports the whole session as used (the virtual cut never touches its+ // message state), so clearing the guard now would fire a "you are at 95%,+ // call new_context" reminder one line after the window opened — and burn+ // the level for the rest of the window. An undated message counts as+ // current, the same direction the core takes: pi stamps every real message.+ //+ // A provider error or an Esc ends the turn with a message pi stamps *now*+ // but whose usage it refuses to trust (getContextUsage skips assistants+ // with stopReason "error"/"aborted"), so such a turn must not re-arm+ // either: the reported number would still be the closed window's.+ const turnMessage = (event as any).message;+ const stopReason = String(turnMessage?.stopReason ?? "");+ const turnAssistantAt = Number(turnMessage?.timestamp);+ const lastResetAt = Number(windows.state.lastResetAt) || 0;+ const usableResponse = stopReason !== "aborted" && stopReason !== "error";+ if (usableResponse && (!Number.isFinite(turnAssistantAt) || turnAssistantAt >= lastResetAt)) {+ windows.observeAssistantResponse();+ }++ const usage = (ctx as any).getContextUsage?.();+ const level = windows.dueReminder({+ usage,+ contextWindow: usage?.contextWindow ?? 0,+ reserveTokens,+ });+ if (level) {+ const { used } = windows.usedTokens(usage);+ try {+ (pi as any).sendMessage?.(+ {+ customType: REMINDER_CUSTOM_TYPE,+ content: reminderText(level, {+ windowId: windows.windowId,+ usedTokens: used,+ contextWindow: usage?.contextWindow ?? 0,+ }),+ display: true,+ },+ // Mid-batch the reminder has to jump the queue; at the end of a turn+ // the next sampling picks it up on its own.+ { deliverAs: event.toolResults?.length ? "steer" : "nextTurn" },+ );+ } catch (error) {+ logger.logError("reminder", error);+ }+ }++ // One non-blocking retry per turn for a window that opened before its+ // Working Memory was generated.+ if (connected) await windows.refreshPendingOverview();++ updateStatus(ctx, connected, windows, sync.sessionId);+ });++ // --- session_before_compact ---+ pi.on("session_before_compact", async (event, ctx) => {+ if (bypassed) return;+ // Called even with OpenViking down: the core's recent-reset guard needs no+ // network, and it is what stops a stale usage estimate right after a reset+ // from compacting a window that just opened. The core refuses to commit on+ // its own when `io.connected()` is false, so an offline pi still falls back+ // to its own summarizer.+ //+ // Takes over pi's compaction: archive to OpenViking and hand pi our window+ // header as the summary. Returns undefined on any failure, which leaves+ // pi's own summarizer in charge.+ return await windows.handleBeforeCompact({+ preparation: (event as any).preparation,+ branchEntries: (event as any).branchEntries ?? ctx.sessionManager.getBranch?.() ?? [],+ });+ });++ // --- session_compact ---+ pi.on("session_compact", async (event, _ctx) => {+ if (bypassed) return;+ // A compaction we did not produce already cut the history natively, so the+ // virtual anchor is stale and the header no longer describes what is in+ // context.+ if (!(event as any).fromExtension) windows.absorbExternalCompaction("pi compaction");+ });++ // --- session_shutdown ---+ pi.on("session_shutdown", async (_event, _ctx) => {+ if (bypassed) return;++ // Persist the window state with the final watermark. No forced commit:+ // archive boundaries belong to the reset path, and a commit on exit would+ // split a window the next process still owns.+ await windows.shutdown();+ await sync.shutdown();+ });++ // --- agent_end ---+ pi.on("agent_end", async (_event, _ctx) => {+ recall.invalidate();+ });++ // ================================================================+ // Commands+ // ================================================================++ pi.registerCommand("viking", {+ description:+ "OpenViking status and manual operations: 'commit' to force a sync, 'window' for the context window status.",+ handler: async (args, ctx) => {+ const command = args?.trim() ?? "";++ if (command === "window") {+ const snapshot = windows.statusSnapshot({+ usage: (ctx as any).getContextUsage?.(),+ now: Date.now(),+ messages: statusMessages(ctx),+ reserveTokens,+ });+ ctx.ui.notify(+ buildStatusLine({+ windowId: snapshot.windowId,+ turnsInWindow: snapshot.turnsInWindow,+ usedTokens: snapshot.usedTokens,+ contextWindow: snapshot.contextWindow,+ estimated: snapshot.estimated,+ sinceLastUserMs: snapshot.sinceLastUserMs,+ idleGapMs: snapshot.idleGapMs,+ idleGapMinutes: config.contextWindow.idleGapMinutes,+ }) ++ `\narchive: ${snapshot.archiveId || "none"}` ++ ` · working memory ${snapshot.overviewReady ? "ready" : "not ready"}` ++ ` · ${snapshot.advice}`,+ "info",+ );+ return;+ }++ if (!connected) {+ ctx.ui.notify("OpenViking: not connected", "warning");+ return;+ }++ if (command === "commit") {+ await sync.shutdown();+ const commitResult = await sync.commit();+ if (commitResult !== null) {+ ctx.ui.notify(+ "OpenViking: committed successfully" ++ (commitResult?.trace_id ? ` (trace_id=${commitResult.trace_id})` : ""),+ "info",+ );+ } else {+ ctx.ui.notify("OpenViking: commit failed", "error");+ }+ return;+ }++ // Status+ const sid = sync.sessionId ?? "none";+ ctx.ui.notify(+ `OpenViking: ${connected ? "connected" : "disconnected"} | session: ${sid.slice(0, 12)}... | window: ${windows.windowId}`,+ "info",+ );+ },+ });+}++// ================================================================+// Helper Functions+// ================================================================++/** Simple bypass pattern matching (prefix and glob). */+function matchBypass(cwd: string, pattern: string): boolean {+ if (pattern.startsWith("*")) {+ return cwd.endsWith(pattern.slice(1));+ }+ if (pattern.endsWith("*")) {+ return cwd.startsWith(pattern.slice(0, -1));+ }+ return cwd === pattern || cwd.startsWith(pattern + "/");+}++/** Build the <openviking-context> profile block. */+async function buildSessionProfileBlock(+ client: OVClient, config: OVConfig,+): Promise<string> {+ try {+ const profile = await buildProfileBlock(+ (path: string, init?: any, options?: any) => client.fetchJSON(path, init, 10000),+ config.profileTokenBudget,+ config.peerId,+ );+ if (!profile?.block) return "";+ return [+ '<openviking-context source="session-start">',+ profile.block,+ "</openviking-context>",+ ].join("\n");+ } catch {+ return "";+ }+}++/** Status bar: connection, current window, pressure, latest archive, session. */+function updateStatus(+ ctx: any,+ connected: boolean,+ windows: { statusSnapshot: (opts?: any) => any },+ sessionId: string | null,+): void {+ const setter = ctx?.ui?.setStatus;+ if (typeof setter !== "function") return;+ let snapshot: any;+ try {+ snapshot = windows.statusSnapshot({ usage: ctx?.getContextUsage?.(), now: Date.now() });+ } catch {+ return;+ }+ const archive = snapshot.archiveId ? snapshot.archiveId.replace(/^archive_/, "a") : "a—";+ const status =+ `${connected ? "OV ✓" : "OV ✗"} · ${snapshot.windowId} · ${snapshot.percent}% · ${archive}` ++ ` · ${sessionId ? sessionId.slice(0, 12) : "none"}`;+ try {+ setter("openviking", status);+ } catch {+ // Best effort; pi API shape may vary across fast-moving versions.+ }+}diff --git a/examples/pi-experimental-context-management/lib/capture-adapter.d.mts b/examples/pi-experimental-context-management/lib/capture-adapter.d.mtsnew file mode 100644index 000000000..b502604de--- /dev/null+++ b/examples/pi-experimental-context-management/lib/capture-adapter.d.mts@@ -0,0 +1,10 @@+export function extractBranchCapturePayloads(+ branch: any[],+ syncedEntryCount?: number,+ cfg?: Record<string, any>,+): {+ payloads: any[];+ nextEntryCount: number;+ observedEntryCount: number;+ resetWatermark: boolean;+};diff --git a/examples/pi-experimental-context-management/lib/capture-adapter.mjs b/examples/pi-experimental-context-management/lib/capture-adapter.mjsnew file mode 100644index 000000000..fd4b1c914--- /dev/null+++ b/examples/pi-experimental-context-management/lib/capture-adapter.mjs@@ -0,0 +1,134 @@+import {+ extractPartsFromPayload,+ extractTextFromPayload,+ sanitizeCapturedText,+ truncateCaptureText,+} from "../shared/capture-utils.mjs";+import { flattenContent } from "./text-budget.mjs";++/**+ * pi delivers tool output as its own message whose role is "toolResult".+ * The non-experimental extension does not recognise it, which is why tool+ * output never reached the archive; here the `history` tool promises the+ * archive can be read back, so it has to.+ */+const TOOL_RESULT_ROLES = new Set(["toolresult", "tool_result", "tool"]);++function rawRole(payload) {+ return String(payload?.role ?? payload?.type ?? payload?.kind ?? "").toLowerCase();+}++function normalizeRole(role) {+ const value = String(role || "").toLowerCase();+ if (value === "user") return "user";+ if (value === "assistant") return "assistant";+ // OpenViking sessions have no tool role: tool output is archived as a user+ // turn, which is also how the server's extraction prompts read it.+ if (TOOL_RESULT_ROLES.has(value)) return "user";+ if (value === "tool_call" || value === "toolcall") return "assistant";+ return "";+}++function entryPayload(entry) {+ if (!entry || typeof entry !== "object") return null;+ if (entry.type === "message" && entry.message && typeof entry.message === "object") {+ return entry.message;+ }+ if (entry.message && typeof entry.message === "object") return entry.message;+ return entry;+}++/**+ * Capture is faithful in this extension: what the model said is what the+ * archive holds, because a closed context window can only be recovered from+ * the archive. Only plugin chatter and slash commands are dropped.+ */+function faithfulDecision(rawText, cfg) {+ const sanitized = sanitizeCapturedText(rawText);+ if (!sanitized) return { shouldCapture: false, reason: "empty", text: "" };+ const capped = truncateCaptureText(sanitized, cfg.captureMaxLength || 24000);+ const compact = String(capped || "").replace(/\s+/g, " ").trim();+ if (/^\[openviking-memory\]/i.test(compact)) {+ return { shouldCapture: false, reason: "plugin_status", text: "" };+ }+ if (/^\/[a-z0-9_-]{1,64}\b/i.test(compact)) {+ return { shouldCapture: false, reason: "slash_command", text: "" };+ }+ return { shouldCapture: true, reason: "faithful", text: capped };+}++function toolResultName(payload) {+ const name = payload?.toolName ?? payload?.tool_name ?? payload?.name ?? "";+ const value = String(name || "").trim();+ return value || "unknown";+}++function toolResultText(payload, cfg) {+ const direct = flattenContent(payload) || extractTextFromPayload(payload, {+ toolMaxChars: cfg.captureToolMaxChars,+ });+ const sanitized = sanitizeCapturedText(direct);+ if (!sanitized) return "";+ const body = truncateCaptureText(sanitized, cfg.captureToolMaxChars || 1000000);+ if (!body) return "";+ return `[tool-result ${toolResultName(payload)}] ${body}`;+}++export function extractBranchCapturePayloads(branch, syncedEntryCount = 0, cfg = {}) {+ const entries = Array.isArray(branch) ? branch : [];+ const previousCount = Math.max(0, Number(syncedEntryCount) || 0);+ const resetWatermark = entries.length < previousCount;+ const start = resetWatermark ? 0 : Math.min(previousCount, entries.length);+ const payloads = [];++ for (const entry of entries.slice(start)) {+ const payload = entryPayload(entry);+ if (!payload) continue;++ const raw = rawRole(payload);+ const role = normalizeRole(raw);+ if (!role) continue;++ if (TOOL_RESULT_ROLES.has(raw)) {+ if (cfg.captureToolResults === false) continue;+ const text = toolResultText(payload, cfg);+ if (!text) continue;+ const body = { role, parts: [{ type: "text", text }] };+ if (cfg.peerId) body.peer_id = cfg.peerId;+ payloads.push(body);+ continue;+ }++ if (role === "assistant" && cfg.captureAssistantTurns === false) continue;++ const rawText = extractTextFromPayload(payload, { toolMaxChars: cfg.captureToolMaxChars });+ const parts = extractPartsFromPayload(payload, { toolMaxChars: cfg.captureToolMaxChars });+ const decision = faithfulDecision(rawText, cfg);+ const structuredParts = parts.filter((part) => part?.type !== "text");+ if (!decision.shouldCapture && structuredParts.length === 0) continue;++ // decision.text is derived from rawText, which renders tool I/O as+ // "[tool-result ...]" lines. For a tool-only payload that would resend the+ // same output the tool part already carries, so only keep it when the+ // payload really had text of its own.+ const hasTextPart = parts.some((part) => part?.type === "text");+ const bodyParts = [+ ...(hasTextPart && decision.shouldCapture && decision.text+ ? [{ type: "text", text: decision.text }]+ : []),+ ...structuredParts,+ ];+ const body = bodyParts.length > 0+ ? { role, parts: bodyParts }+ : { role, content: decision.text };+ if (cfg.peerId) body.peer_id = cfg.peerId;+ payloads.push(body);+ }++ return {+ payloads,+ nextEntryCount: entries.length,+ observedEntryCount: entries.length,+ resetWatermark,+ };+}diff --git a/examples/pi-experimental-context-management/lib/context-window-core.d.mts b/examples/pi-experimental-context-management/lib/context-window-core.d.mtsnew file mode 100644index 000000000..92f00852a--- /dev/null+++ b/examples/pi-experimental-context-management/lib/context-window-core.d.mts@@ -0,0 +1,335 @@+export const WINDOW_ENTRY_TYPE: "ov-context-window";+export const WINDOW_HEADER_OPEN: '<openviking-context source="context-window">';+export const WINDOW_HEADER_CLOSE: "</openviking-context>";+export const STATUS_CUSTOM_TYPE: "ov-context-status";+export const REMINDER_CUSTOM_TYPE: "ov-context-reminder";+export const HANDOFF_MARKER: "[Context Window Handoff]";+export const STATUS_MARKER: "[context-status]";+export const REMINDER_MARKER: "[context-reminder]";+export const COMPACTION_SENTINEL: "ov-context-window-reset";++export interface WindowMessage {+ role: string;+ content?: unknown;+ timestamp?: number;+ toolCallId?: string;+ toolName?: string;+ customType?: string;+ [key: string]: any;+}++export interface WindowConfig {+ resetDeadlineMs: number;+ archivePollMs: number;+ overviewRefreshMaxAttempts: number;+ overviewBudget: number;+ notesBudget: number;+ pendingRequestBudget: number;+ softPercent: number;+ hardPercent: number;+ idleGapMinutes: number;+ statusEveryTurn: boolean;+ historyItemMaxChars: number;+ recentResetGuardMs: number;+}++export function windowConfig(raw?: Partial<WindowConfig> & Record<string, any>): WindowConfig;++export interface CutRange {+ assistantIndex: number;+ resultIndex: number;+ cutEndIndex: number;+ droppedToolResults: number;+ siblingToolNames: string[];+}++export function computeCutRange(messages: WindowMessage[], anchorToolCallId: string): CutRange | null;++export function applyWindowCut(+ messages: WindowMessage[],+ opts: { anchorToolCallId: string; headerText: string; headerTimestamp?: number },+): { messages: WindowMessage[]; applied: boolean; droppedCount: number };++export function buildHandoffMessage(opts: {+ windowId: string;+ nextWindowId: string;+ reason?: string;+ notes?: string;+ nextSteps?: string[];+}): string;++export type OverviewState = "ready" | "pending" | "unavailable";++export function buildWindowHeader(opts: {+ windowId: string;+ previousWindowId?: string;+ archiveId?: string;+ archiveUri?: string;+ openedAt?: number;+ reason?: string;+ notes?: string;+ nextSteps?: string[];+ pendingRequest?: string;+ overview?: string;+ overviewState?: OverviewState;+ previousOverview?: string;+ /** Archive the stale Working Memory block actually belongs to. */+ previousArchiveId?: string;+ /** Messages OpenViking rejected for good; named in the header when > 0. */+ undeliveredCount?: number;+ siblingToolNames?: string[];+ config?: Partial<WindowConfig> & Record<string, any>;+}): string;++export function buildStatusLine(opts: {+ windowId: string;+ turnsInWindow?: number;+ usedTokens?: number;+ contextWindow?: number;+ estimated?: boolean;+ sinceLastUserMs?: number | null;+ /**+ * Gap the user just came back from. This is what gates the idle NOTE;+ * `idleGapMs` is only a fallback for a caller that has nothing else.+ */+ idleGapMs?: number | null;+ idleGapMinutes?: number;+}): string;++export function reminderText(+ level: "soft" | "hard",+ opts: { windowId: string; usedTokens?: number; contextWindow?: number },+): string;++/**+ * Token estimate for one pi message, including toolCall arguments and thinking+ * blocks (which carry no `text` field and would otherwise score as zero).+ */+export function messageTokens(msg: WindowMessage): number;++/**+ * Clamp the soft/hard reminder thresholds under pi's own auto-compaction line+ * (`contextTokens > contextWindow - reserveTokens`). Pass `reserveTokens: 0`+ * (or omit it) to leave the configured thresholds untouched.+ */+export function effectiveThresholds(opts?: {+ softPercent?: number;+ hardPercent?: number;+ contextWindow?: number;+ reserveTokens?: number;+}): { softPercent: number; hardPercent: number };++export function formatTokens(n: number): string;+export function formatDuration(ms: number): string;+export function lastUserTimestamps(messages: WindowMessage[]): number[];+export function lastUserTextFromBranch(branch: any[]): string;+/**+ * Branch entries → the message list `buildSessionContext()` would produce+ * (messages, custom messages, branch summaries, compaction handling). Used+ * where no `context` hook has run yet in this process.+ */+export function messagesFromBranch(entries: any[]): WindowMessage[];+export function siblingToolNamesFromBranch(branch: any[], anchorToolCallId: string): string[];++export interface ArchiveRef {+ windowId: string;+ archiveId: string;+ archiveUri: string;+}++export interface WindowPersistedState {+ version: number;+ ovSessionId: string | null;+ windowIndex: number;+ anchorToolCallId: string | null;+ openedAt: number;+ headerText: string;+ reason: string;+ notes: string;+ nextSteps: string[];+ pendingRequest: string;+ archiveId: string;+ archiveUri: string;+ taskId: string;+ /** Every archive of this session, oldest first (bounded to the last 100). */+ archives: ArchiveRef[];+ /** Archive of the window before the current one. */+ previousArchiveId: string;+ /** Messages OpenViking rejected for good; they are missing from the archive. */+ undeliveredCount: number;+ overviewReady: boolean;+ /** The archive will never get a Working Memory (task failed / budget spent). */+ overviewUnavailable: boolean;+ overviewAttempts: number;+ /** Working Memory of the *previous* window, truncated to `overviewBudget`. */+ previousOverview: string;+ siblingToolNames: string[];+ syncedEntryCount: number;+ lastResetAt: number;+ lastResetBy: string;+}++export interface WindowCommitResult {+ status?: string;+ reason?: string;+ task_id?: string;+ archive_uri?: string;+ trace_id?: string;+ [key: string]: any;+}++export interface ContextWindowIo {+ syncBranch?: (branch: any[]) => Promise<{ added: number; tokens: number; allDelivered: boolean }> | { added: number; tokens: number; allDelivered: boolean };+ flush?: (opts: { budgetMs: number }) => Promise<boolean> | boolean;+ postHandoff?: (text: string) => Promise<boolean> | boolean;+ commit?: (opts: { keepRecentCount: number }) => Promise<WindowCommitResult | null> | WindowCommitResult | null;+ readArchiveOverview?: (archiveUri: string) => Promise<string | null> | string | null;+ getTask?: (taskId: string) => Promise<{ status?: string } | null> | { status?: string } | null;+ persistEntry?: (customType: string, data: WindowPersistedState) => void;+ getWatermark?: () => number;+ now?: () => number;+ sleep?: (ms: number, signal?: AbortSignal | null) => Promise<void>;+ log?: (message: string) => void;+ connected?: () => boolean;+ sessionId?: () => string | null;+ pendingCount?: () => number;+ /** Messages this session lost for good (non-retryable rejections, dropped queue entries). */+ droppedCount?: () => number;+ /** trace_id of the last commit response, reported in a commit refusal. */+ commitTraceId?: () => string;+}++/**+ * A commit that threw after the request was sent: the archive may or may not+ * exist, so the next reset re-checks connectivity before it syncs again.+ */+export interface CommitTransportError {+ at: number;+ message: string;+}++export interface ResetOutcome {+ ok: boolean;+ kind: "reset" | "refused" | "noop";+ text: string;+ details: Record<string, any>;+}++export interface StatusSnapshot {+ windowId: string;+ turnsInWindow: number;+ usedTokens: number;+ contextWindow: number;+ percent: number;+ tokensLeft: number | null;+ estimated: boolean;+ sinceLastUserMs: number | null;+ idleGapMs: number | null;+ archiveId: string;+ /** Archives this session produced (not derived from the window index). */+ archiveCount: number;+ archives: ArchiveRef[];+ undeliveredCount: number;+ overviewReady: boolean;+ windowAgeMs: number | null;+ /** Effective thresholds for this snapshot (clamped when reserveTokens is known). */+ softPercent: number;+ hardPercent: number;+ advice: string;+}++export interface BeforeCompactResult {+ compaction: {+ summary: string;+ firstKeptEntryId: any;+ tokensBefore: number;+ details: { source: string; reason: string };+ };+}++export class ContextWindowCore {+ constructor(opts?: { config?: Partial<WindowConfig> & Record<string, any>; io?: ContextWindowIo });+ config: WindowConfig;+ get windowId(): string;+ get armed(): boolean;+ get state(): WindowPersistedState & {+ windowId: string;+ armed: boolean;+ resetting: boolean;+ remindersSent: { soft: boolean; hard: boolean };+ awaitingFirstObservation: boolean;+ lastWindowTokens: number;+ turnsInWindow: number;+ lastCommitError: CommitTransportError | null;+ };+ /** True while a restore is still waiting for the OpenViking session id. */+ pendingSessionCheck: boolean;+ /** Archives of this session, oldest first, with the window each belongs to. */+ archives: ArchiveRef[];+ lastCommitError: CommitTransportError | null;+ persistedState(): WindowPersistedState;+ restore(entries: any[]): this["state"];+ /**+ * Settle a restore that ran before `io.sessionId()` was known. Returns false+ * (and drops the window) when the entry belongs to another session. Idempotent.+ */+ validateSession(): boolean;+ persist(): void;+ shutdown(): Promise<void>;+ transformContext(messages: WindowMessage[]): WindowMessage[];+ /**+ * `transformContext` without the right to release the boundary: the cut and+ * the window metrics for a caller that only describes the window (the status+ * line, built from the session branch before any `context` hook has run).+ */+ observeMessages(messages: WindowMessage[]): WindowMessage[];+ /**+ * Refresh `lastWindowTokens` / `turnsInWindow` from a message list.+ * With `headerIndex < 0` only assistant messages newer than the last reset count.+ */+ recordWindowMetrics(messages: WindowMessage[], headerIndex: number): void;+ observeAssistantResponse(): void;+ /** Release the boundary and clear the window metrics. */+ disarm(reason: string): void;+ /** Flush budget for one barrier: clamped to [2s, 15s] of the remaining deadline. */+ flushBudget(deadline: number): number;+ requestReset(opts: {+ reason?: string;+ notes?: string;+ nextSteps?: string[];+ toolCallId: string;+ branch?: any[];+ signal?: AbortSignal | null;+ onProgress?: (message: string) => void;+ siblingToolNames?: string[];+ }): Promise<ResetOutcome>;+ refreshPendingOverview(): Promise<boolean>;+ markOverviewUnavailable(): void;+ /** Remember which window an archive belongs to. Idempotent per archive id. */+ recordArchive(windowId: string, archiveId: string, archiveUri?: string): void;+ /** Post a one-line retraction for a handoff note whose reset then failed. */+ retractHandoff(): Promise<void>;+ rebuildHeader(opts: { overviewState?: OverviewState; previousWindowId?: string }): string;+ /** Reported usage when it is trustworthy, the local estimate otherwise. */+ usedTokens(usage?: { tokens?: number | null } | null): { used: number; estimated: boolean };+ /** Effective soft/hard percentages for a given window size and pi reserve. */+ thresholdsFor(contextWindow: number, reserveTokens?: number): { softPercent: number; hardPercent: number };+ dueReminder(opts?: {+ usage?: { tokens?: number | null; contextWindow?: number } | null;+ contextWindow?: number;+ /** pi settings `compaction.reserveTokens` (default 16384); 0 disables the clamp. */+ reserveTokens?: number;+ }): "soft" | "hard" | null;+ statusSnapshot(opts?: {+ usage?: { tokens?: number | null; contextWindow?: number } | null;+ now?: number | null;+ messages?: WindowMessage[];+ reserveTokens?: number;+ }): StatusSnapshot;+ handleBeforeCompact(opts: {+ preparation?: { firstKeptEntryId?: any; tokensBefore?: number };+ branchEntries?: any[];+ }): Promise<BeforeCompactResult | undefined>;+ pickFirstKeptEntryId(preparation?: { firstKeptEntryId?: any }, branchEntries?: any[]): any;+ absorbExternalCompaction(reason?: string): void;+}diff --git a/examples/pi-experimental-context-management/lib/context-window-core.mjs b/examples/pi-experimental-context-management/lib/context-window-core.mjsnew file mode 100644index 000000000..015b7bfd8--- /dev/null+++ b/examples/pi-experimental-context-management/lib/context-window-core.mjs@@ -0,0 +1,2031 @@+/**+ * Pure, harness-agnostic core of the "agent manages its own context window"+ * mode (a pi port of Codex `features.context_management.experimental_mode`).+ *+ * Nothing in this file imports pi or touches the network: every side effect+ * goes through the injected `io` object, exactly like the takeover core of+ * examples/pi-coding-agent-extension. That keeps the whole reset state machine+ * unit-testable and portable to other harnesses (dsh).+ *+ * The reset itself is a *virtual* cut: the `context` hook replaces the message+ * list of a single provider request with `[window header, ...messages after the+ * anchoring tool call]`. Nothing is deleted from the session on disk.+ */++import { estimateTokens, flattenContent, truncateToTokens } from "./text-budget.mjs";++/** Custom session entry that carries the window state across processes. */+export const WINDOW_ENTRY_TYPE = "ov-context-window";+/** The window header opens with this exact string (recall's idempotency guard). */+export const WINDOW_HEADER_OPEN = '<openviking-context source="context-window">';+/** …and closes with this one, so a merged user message can be split off again. */+export const WINDOW_HEADER_CLOSE = "</openviking-context>";+/** customType of the per-prompt status line. */+export const STATUS_CUSTOM_TYPE = "ov-context-status";+/** customType of the one-shot soft/hard reminders. */+export const REMINDER_CUSTOM_TYPE = "ov-context-reminder";+/** First line of the handoff message archived as the last assistant message. */+export const HANDOFF_MARKER = "[Context Window Handoff]";+/** First token of the per-prompt status line. */+export const STATUS_MARKER = "[context-status]";+/** First token of a soft/hard reminder. */+export const REMINDER_MARKER = "[context-reminder]";+/**+ * `firstKeptEntryId` used when the anchoring tool batch is the tail of the+ * branch: it matches no entry, so pi builds a summary-only context.+ */+export const COMPACTION_SENTINEL = "ov-context-window-reset";++const HEADER_INTRO =+ "This is a fresh context window. The earlier conversation of this session was archived to " ++ "OpenViking and is no longer in context. Files, the working directory, running processes and " ++ "tools are unchanged.";++const TRUNCATION_MARKER = "\n...(truncated)";++/**+ * Handoff notes for a window pi compacted before the model called+ * `new_context`. The model wrote none for this boundary, and reusing the notes+ * of the previous one would archive them as if it had.+ */+const AUTO_COMPACT_NOTES =+ "(none — the harness compacted this window before new_context was called, " ++ "so no handoff notes were written for it)";++const FAIL_CLOSED_TAIL =+ "Nothing changed; keep working; the harness will compact for you if the window fills up.";++const DEFAULTS = {+ resetDeadlineMs: 60000,+ archivePollMs: 2000,+ overviewRefreshMaxAttempts: 20,+ overviewBudget: 3000,+ notesBudget: 1500,+ pendingRequestBudget: 400,+ softPercent: 70,+ hardPercent: 85,+ idleGapMinutes: 30,+ statusEveryTurn: true,+ historyItemMaxChars: 8000,+ recentResetGuardMs: 60000,+};++function clampInt(value, fallback, min, max) {+ const raw = Number(value);+ const base = Number.isFinite(raw) ? Math.floor(raw) : fallback;+ return Math.min(max, Math.max(min, base));+}++/**+ * Normalize + clamp the `contextWindow.*` config block. Idempotent: feeding an+ * already normalized object back in returns the same values.+ */+export function windowConfig(raw = {}) {+ const outer = raw && typeof raw === "object" ? raw : {};+ const nested = outer.contextWindow && typeof outer.contextWindow === "object" ? outer.contextWindow : null;+ const src = nested ? { ...outer, ...nested } : outer;++ const softPercent = clampInt(src.softPercent, DEFAULTS.softPercent, 10, 99);+ const hardPercent = Math.max(softPercent, clampInt(src.hardPercent, DEFAULTS.hardPercent, 10, 99));++ return {+ resetDeadlineMs: clampInt(src.resetDeadlineMs, DEFAULTS.resetDeadlineMs, 5000, 600000),+ archivePollMs: clampInt(src.archivePollMs, DEFAULTS.archivePollMs, 250, 30000),+ overviewRefreshMaxAttempts: clampInt(src.overviewRefreshMaxAttempts, DEFAULTS.overviewRefreshMaxAttempts, 0, 200),+ overviewBudget: clampInt(src.overviewBudget, DEFAULTS.overviewBudget, 100, 50000),+ notesBudget: clampInt(src.notesBudget, DEFAULTS.notesBudget, 100, 20000),+ pendingRequestBudget: clampInt(src.pendingRequestBudget, DEFAULTS.pendingRequestBudget, 0, 8000),+ softPercent,+ hardPercent,+ idleGapMinutes: clampInt(src.idleGapMinutes, DEFAULTS.idleGapMinutes, 0, 1440),+ statusEveryTurn: src.statusEveryTurn !== false,+ historyItemMaxChars: clampInt(src.historyItemMaxChars, DEFAULTS.historyItemMaxChars, 500, 100000),+ recentResetGuardMs: clampInt(src.recentResetGuardMs, DEFAULTS.recentResetGuardMs, 0, 600000),+ };+}++// --------------------------------------------------------------------------+// Cut+// --------------------------------------------------------------------------++function isToolResult(msg) {+ return !!msg && msg.role === "toolResult";+}++function toolCallBlocks(msg) {+ if (!msg || msg.role !== "assistant") return [];+ const content = msg.content;+ if (!Array.isArray(content)) return [];+ return content.filter((block) => block && typeof block === "object" && block.type === "toolCall");+}++function blockToolName(block) {+ if (!block || typeof block !== "object") return "";+ return String(block.name || block.toolName || block.tool_name || "");+}++/**+ * Locate the message range a reset must drop.+ *+ * `resultIndex` is the toolResult of the `new_context` call itself; the whole+ * contiguous run of toolResults it belongs to is dropped so that a parallel+ * batch never leaves an orphan tool_result behind (providers reject those).+ */+export function computeCutRange(messages, anchorToolCallId) {+ const list = Array.isArray(messages) ? messages : [];+ const anchor = String(anchorToolCallId || "");+ if (!anchor) return null;++ let resultIndex = -1;+ for (let i = list.length - 1; i >= 0; i--) {+ const msg = list[i];+ if (isToolResult(msg) && String(msg.toolCallId || "") === anchor) {+ resultIndex = i;+ break;+ }+ }+ if (resultIndex < 0) return null;++ let assistantIndex = -1;+ for (let i = resultIndex - 1; i >= 0; i--) {+ const blocks = toolCallBlocks(list[i]);+ if (blocks.some((block) => String(block.id || block.toolCallId || "") === anchor)) {+ assistantIndex = i;+ break;+ }+ }++ let start = resultIndex;+ if (assistantIndex >= 0 && isToolResult(list[assistantIndex + 1])) start = assistantIndex + 1;++ let cutEndIndex = start;+ while (isToolResult(list[cutEndIndex + 1])) cutEndIndex++;+ if (cutEndIndex < resultIndex) {+ // Non-contiguous batch (should not happen in pi): fall back to the anchor.+ start = resultIndex;+ cutEndIndex = resultIndex;+ while (isToolResult(list[cutEndIndex + 1])) cutEndIndex++;+ }++ const siblingToolNames = [];+ let droppedToolResults = 0;+ for (let i = start; i <= cutEndIndex; i++) {+ if (!isToolResult(list[i])) continue;+ droppedToolResults++;+ if (String(list[i].toolCallId || "") === anchor) continue;+ siblingToolNames.push(String(list[i].toolName || list[i].tool_name || ""));+ }+ if (siblingToolNames.length === 0 && assistantIndex >= 0) {+ for (const block of toolCallBlocks(list[assistantIndex])) {+ if (String(block.id || block.toolCallId || "") === anchor) continue;+ siblingToolNames.push(blockToolName(block));+ }+ }++ return {+ assistantIndex,+ resultIndex,+ cutEndIndex,+ droppedToolResults,+ siblingToolNames: siblingToolNames.filter(Boolean),+ };+}++function cloneMessage(msg) {+ try {+ return structuredClone(msg);+ } catch {+ return JSON.parse(JSON.stringify(msg));+ }+}++function mergeHeaderIntoUser(msg, headerText) {+ const copy = cloneMessage(msg);+ if (typeof copy.content === "string") {+ copy.content = `${headerText}\n\n${copy.content}`;+ return copy;+ }+ if (Array.isArray(copy.content)) {+ const idx = copy.content.findIndex((block) => block && typeof block === "object" && typeof block.text === "string");+ if (idx >= 0) {+ copy.content[idx] = { ...copy.content[idx], text: `${headerText}\n\n${copy.content[idx].text}` };+ } else {+ copy.content.unshift({ type: "text", text: headerText });+ }+ return copy;+ }+ copy.content = headerText;+ return copy;+}++/**+ * A pressure reminder is about the window that just ended, so it must never+ * survive into the new one: leaving it in front would tell a brand new window+ * that it is already 87% full and push the model straight into a second reset.+ *+ * The `context` hook runs on pi's *AgentMessage* list, before `convertToLlm`+ * rewrites custom messages to `user` (agent-loop.js: transformContext →+ * convertToLlm), so what a reminder actually looks like here is+ * `{role:"custom", customType:"ov-context-reminder"}`. Both shapes are matched:+ * the custom one is what pi emits, the user one is what a converted copy looks+ * like.+ */+function isReminderCarrier(msg) {+ return !!msg && (msg.role === "user" || msg.role === "custom");+}++function isStaleReminder(msg) {+ if (!isReminderCarrier(msg)) return false;+ if (messageCustomType(msg) === REMINDER_CUSTOM_TYPE) return true;+ return flattenContent(msg).trimStart().startsWith(REMINDER_MARKER);+}++/**+ * Apply the virtual cut. Pure: the input array and its objects are never+ * mutated (only the merged first kept message is cloned and rewritten).+ */+export function applyWindowCut(messages, opts = {}) {+ const list = Array.isArray(messages) ? messages : [];+ const headerText = String(opts.headerText || "");+ const range = computeCutRange(list, opts.anchorToolCallId);+ if (!range || !headerText) return { messages: list, applied: false, droppedCount: 0 };++ let keptStart = range.cutEndIndex + 1;+ while (keptStart < list.length && isStaleReminder(list[keptStart])) keptStart++;+ const kept = list.slice(keptStart);+ const droppedCount = keptStart;++ if (kept.length > 0 && kept[0] && kept[0].role === "user") {+ const merged = mergeHeaderIntoUser(kept[0], headerText);+ return { messages: [merged, ...kept.slice(1)], applied: true, droppedCount };+ }++ const header = { role: "user", content: headerText };+ const ts = Number(opts.headerTimestamp);+ if (Number.isFinite(ts)) header.timestamp = ts;+ return { messages: [header, ...kept], applied: true, droppedCount };+}++// --------------------------------------------------------------------------+// Text builders+// --------------------------------------------------------------------------++function normalizeSteps(value) {+ if (!Array.isArray(value)) return [];+ return value.map((step) => String(step || "").trim()).filter(Boolean);+}++function normalizeNames(value) {+ if (!Array.isArray(value)) return [];+ return value.map((name) => String(name || "").trim()).filter(Boolean);+}++/** How many `{windowId, archiveId}` pairs the persisted entry carries. */+const ARCHIVE_HISTORY_LIMIT = 100;++function normalizeArchives(value) {+ if (!Array.isArray(value)) return [];+ const out = [];+ for (const row of value) {+ if (!row || typeof row !== "object" || Array.isArray(row)) continue;+ const windowId = String(row.windowId || "").trim();+ const archiveId = String(row.archiveId || "").trim();+ if (!windowId || !archiveId) continue;+ out.push({ windowId, archiveId, archiveUri: String(row.archiveUri || "").trim() });+ }+ return out.slice(-ARCHIVE_HISTORY_LIMIT);+}++function truncateWithMarker(text, budget) {+ const raw = String(text || "").trim();+ const limit = Math.max(0, Math.floor(Number(budget) || 0));+ if (!raw || limit <= 0) return "";+ const cut = truncateToTokens(raw, limit);+ return cut === raw ? raw : `${cut}${TRUNCATION_MARKER}`;+}++/**+ * The assistant message appended to the OpenViking session right before the+ * commit, so the server-side Working Memory prompt folds reason + notes into+ * Current State / Open Issues without any server change.+ */+export function buildHandoffMessage(opts = {}) {+ const windowId = String(opts.windowId || "w?");+ const nextWindowId = String(opts.nextWindowId || "w?");+ const reason = String(opts.reason || "").trim() || "(none given)";+ const notes = String(opts.notes || "").trim() || "(none)";+ const steps = normalizeSteps(opts.nextSteps);++ const lines = [+ `${HANDOFF_MARKER} ${windowId} -> ${nextWindowId}`,+ `Reason: ${reason}`,+ "Handoff notes:",+ notes,+ ];+ if (steps.length > 0) {+ lines.push("Next steps:");+ steps.forEach((step, i) => lines.push(`${i + 1}. ${step}`));+ }+ return lines.join("\n");+}++function isoSecond(ms) {+ const value = Number(ms);+ if (!Number.isFinite(value) || value <= 0) return "";+ try {+ return new Date(value).toISOString().replace(/\.\d{3}Z$/, "Z");+ } catch {+ return "";+ }+}++/**+ * The frozen window header (plan §3). Generated exactly once per reset so that+ * every later provider request repeats the same bytes and the prompt cache+ * survives.+ */+export function buildWindowHeader(opts = {}) {+ const cfg = windowConfig(opts.config || {});+ const windowId = String(opts.windowId || "w?");+ const previousWindowId = String(opts.previousWindowId || "");+ const archiveId = String(opts.archiveId || "");+ const opened = isoSecond(opts.openedAt);++ const attrs = [`id="${windowId}"`];+ if (previousWindowId) attrs.push(`previous="${previousWindowId}"`);+ if (archiveId) attrs.push(`archive="${archiveId}"`);+ if (opened) attrs.push(`opened="${opened}"`);++ const lines = [WINDOW_HEADER_OPEN, `<context_window ${attrs.join(" ")}>`, HEADER_INTRO];++ const reason = String(opts.reason || "").trim();+ if (reason) {+ lines.push("", `Reason you gave: ${reason}`);+ }++ const notes = truncateWithMarker(opts.notes, cfg.notesBudget);+ if (notes) {+ lines.push("", "Your handoff notes:", `<handoff-notes>${notes}</handoff-notes>`);+ }++ const steps = normalizeSteps(opts.nextSteps);+ if (steps.length > 0) {+ lines.push("", "Next steps you planned:");+ steps.forEach((step, i) => lines.push(`${i + 1}. ${step}`));+ }++ const pending = truncateWithMarker(opts.pendingRequest, cfg.pendingRequestBudget);+ if (pending) {+ lines.push(+ "",+ "The user's most recent message in the previous window was:",+ `<pending-request>${pending}</pending-request>`,+ );+ }++ const overview = truncateWithMarker(opts.overview, cfg.overviewBudget);+ const archiveLabel = archiveId || "the archived window";+ let state = opts.overviewState === "ready" || opts.overviewState === "unavailable" ? opts.overviewState : "pending";+ if (state === "ready" && !overview) state = "pending";++ lines.push("");+ if (state === "ready") {+ lines.push(+ "Working Memory of the archived window, generated by OpenViking:",+ `<working-memory archive="${archiveId}">${overview}</working-memory>`,+ );+ } else if (state === "unavailable") {+ lines.push(+ `Working Memory for ${archiveLabel} is unavailable: OpenViking could not summarize it. ` ++ "Rely on your handoff notes above and use history to read the archived messages directly.",+ );+ } else {+ lines.push(+ `Working Memory for ${archiveLabel} is not ready yet: OpenViking is still summarizing it. ` ++ "Rely on your handoff notes above and use history to read the archived messages directly.",+ );+ const previousOverview = truncateWithMarker(opts.previousOverview, cfg.overviewBudget);+ if (previousOverview) {+ // This block is the Working Memory of an *earlier* window, never of the+ // archive named one line above — tagging it with `archiveId` would+ // present a summary as belonging to the archive that has none.+ const staleArchive = String(opts.previousArchiveId || "").trim();+ const attrs = ['status="stale"'];+ if (staleArchive) attrs.push(`archive="${staleArchive}"`);+ attrs.push('describes="an earlier window, not the archive above"');+ lines.push(`<working-memory ${attrs.join(" ")}>${previousOverview}</working-memory>`);+ }+ }++ const siblings = normalizeNames(opts.siblingToolNames);+ if (siblings.length > 0) {+ const singular = siblings.length === 1;+ lines.push(+ "",+ `${siblings.length} other tool result${singular ? " was" : "s were"} discarded with the same batch; ` ++ `re-run ${singular ? "it" : "them"} if needed. Tools: ${siblings.join(", ")}.`,+ );+ }++ const undelivered = Math.max(0, Math.floor(Number(opts.undeliveredCount) || 0));+ if (undelivered > 0) {+ const singular = undelivered === 1;+ lines.push(+ "",+ `${undelivered} message${singular ? "" : "s"} of this session ${singular ? "was" : "were"} ` ++ `rejected by OpenViking and ${singular ? "is" : "are"} missing from the archive, ` ++ `so history cannot show ${singular ? "it" : "them"}.`,+ );+ }++ const previousLabel = previousWindowId || windowId;+ lines.push(+ "",+ 'To recover anything not covered above: history {"action":"list_windows"} / ' ++ `{"action":"list_items","window":"${previousLabel}"} / ` ++ // A literal index would usually be out of range; list_items is what hands+ // out the real ones.+ `{"action":"read_item","item":"${previousLabel}:<index from list_items>"} / ` ++ '{"action":"search_contents","query":"..."}.',+ "Continue from the notes above. If the pending request is not finished, resume it now.",+ "</context_window>",+ "</openviking-context>",+ );++ return lines.join("\n");+}++/** "38k", "38.4k", "262k", "512". */+export function formatTokens(n) {+ const value = Number(n);+ if (!Number.isFinite(value) || value <= 0) return "0";+ const rounded = Math.round(value);+ if (rounded < 1000) return String(rounded);+ const k = rounded / 1000;+ if (k < 100) {+ const text = k.toFixed(1);+ return `${text.endsWith(".0") ? text.slice(0, -2) : text}k`;+ }+ return `${Math.round(k)}k`;+}++/** "12s", "3m", "47m", "1h 12m", "2d 3h". */+export function formatDuration(ms) {+ const value = Number(ms);+ if (!Number.isFinite(value) || value <= 0) return "0s";+ const seconds = Math.round(value / 1000);+ if (seconds < 60) return `${seconds}s`;+ const minutes = Math.round(seconds / 60);+ if (minutes < 60) return `${minutes}m`;+ const hours = Math.floor(minutes / 60);+ const restMinutes = minutes % 60;+ if (hours < 24) return restMinutes > 0 ? `${hours}h ${restMinutes}m` : `${hours}h`;+ const days = Math.floor(hours / 24);+ const restHours = hours % 24;+ return restHours > 0 ? `${days}d ${restHours}h` : `${days}d`;+}++/**+ * pi auto-compacts as soon as `contextTokens > contextWindow - reserveTokens`+ * (compaction.js `shouldCompact`, reserveTokens default 16384). On a small model+ * that line sits at 50% of a 32k window, far below our 85% default, so the hard+ * reminder would never fire before pi compacted and the agent's notes would+ * never be written. Clamp both thresholds one point under it.+ */+export function effectiveThresholds({ softPercent, hardPercent, contextWindow, reserveTokens } = {}) {+ let soft = Math.max(1, Math.floor(Number(softPercent) || 0));+ let hard = Math.max(soft, Math.floor(Number(hardPercent) || 0));++ const total = Math.floor(Number(contextWindow) || 0);+ const reserve = Math.floor(Number(reserveTokens) || 0);+ if (total > 0 && reserve > 0 && reserve < total) {+ const line = Math.max(1, Math.floor(((total - reserve) / total) * 100) - 1);+ hard = Math.min(hard, line);+ soft = Math.min(soft, hard);+ }+ return { softPercent: soft, hardPercent: hard };+}++function percentOf(used, total) {+ const u = Number(used) || 0;+ const t = Number(total) || 0;+ if (t <= 0 || u <= 0) return 0;+ return Math.min(100, Math.round((u / t) * 100));+}++/**+ * One line appended after every user prompt (persistent custom message, so the+ * bytes stay stable and the prompt cache is not broken).+ */+export function buildStatusLine(opts = {}) {+ const windowId = String(opts.windowId || "w1");+ const turns = Math.max(0, Math.floor(Number(opts.turnsInWindow) || 0));+ const used = Math.max(0, Math.floor(Number(opts.usedTokens) || 0));+ const contextWindow = Math.max(0, Math.floor(Number(opts.contextWindow) || 0));+ const pct = percentOf(used, contextWindow);++ const parts = [+ `${STATUS_MARKER} window ${windowId}`,+ `${turns} turn${turns === 1 ? "" : "s"}`,+ `~${formatTokens(used)}/${formatTokens(contextWindow)} tokens (${pct}%${opts.estimated ? ", estimated" : ""})`,+ ];++ const since = Number(opts.sinceLastUserMs);+ if (Number.isFinite(since) && since > 0) {+ parts.push(`${formatDuration(since)} since your previous message`);+ }++ const lines = [parts.join(" · ")];++ // The NOTE is about the gap the user just came back from, which is+ // `sinceLastUserMs` — the status line is built in `before_agent_start`, where+ // the newest genuine user message is still the *previous* prompt.+ // `idleGapMs` (the gap before that message) is only a fallback for a caller+ // that has nothing else; it is what `get_context_remaining` reports on its+ // own line.+ const gapMs = Number.isFinite(since) && since > 0 ? since : Number(opts.idleGapMs);+ const idleGapMinutes = Math.max(0, Math.floor(Number(opts.idleGapMinutes) || 0));+ if (idleGapMinutes > 0 && Number.isFinite(gapMs) && gapMs > idleGapMinutes * 60000) {+ const minutes = Math.round(gapMs / 60000);+ lines.push(+ `NOTE: ${minutes} minutes passed since the previous user message. ` ++ "If this request starts unrelated work, consider new_context before you begin.",+ );+ }++ return lines.join("\n");+}++/** One-shot soft / hard pressure reminders (plan §5). */+export function reminderText(level, opts = {}) {+ const windowId = String(opts.windowId || "w1");+ const used = Math.max(0, Math.floor(Number(opts.usedTokens) || 0));+ const contextWindow = Math.max(0, Math.floor(Number(opts.contextWindow) || 0));+ const usage = `about ${percentOf(used, contextWindow)}% full (~${formatTokens(used)}/${formatTokens(contextWindow)} tokens)`;++ if (level === "hard") {+ return (+ `${REMINDER_MARKER} Context window ${windowId} is ${usage}. ` ++ "Save your handoff notes and make exactly one call to new_context now. " ++ "If the window overflows first, the harness compacts it for you and your notes are never written."+ );+ }+ return (+ `${REMINDER_MARKER} Context window ${windowId} is ${usage}. ` ++ "Finish or checkpoint the step you are on, then call new_context with complete notes: " ++ "goal, decisions and why, what is done, what is in flight, exact paths and identifiers, next steps. " ++ "If the window overflows first, the harness compacts it for you and your notes are never written."+ );+}++function messageCustomType(msg) {+ if (!msg || typeof msg !== "object") return "";+ return String(msg.customType || msg.custom_type || "");+}++/**+ * Strip a leading frozen window header. `applyWindowCut` merges the header into+ * the first kept user message, so "starts with the header" alone does not make a+ * message ours — only a message that is *nothing but* the header is.+ */+function withoutWindowHeader(text) {+ const raw = String(text || "").trimStart();+ if (!raw.startsWith(WINDOW_HEADER_OPEN)) return raw;+ const end = raw.indexOf(WINDOW_HEADER_CLOSE);+ if (end < 0) return "";+ return raw.slice(end + WINDOW_HEADER_CLOSE.length).trimStart();+}++function isSyntheticUserMessage(msg) {+ const customType = messageCustomType(msg);+ if (customType === STATUS_CUSTOM_TYPE || customType === REMINDER_CUSTOM_TYPE) return true;+ const raw = flattenContent(msg).trimStart();+ const hadHeader = raw.startsWith(WINDOW_HEADER_OPEN);+ const text = hadHeader ? withoutWindowHeader(raw) : raw;+ if (hadHeader && !text) return true;+ return text.startsWith(STATUS_MARKER) || text.startsWith(REMINDER_MARKER) || text.startsWith(HANDOFF_MARKER);+}++/**+ * Timestamps of the two newest messages the human actually typed, newest+ * first. Everything this extension injects is skipped.+ */+export function lastUserTimestamps(messages) {+ const list = Array.isArray(messages) ? messages : [];+ const found = [];+ for (let i = list.length - 1; i >= 0 && found.length < 2; i--) {+ const msg = list[i];+ if (!msg || msg.role !== "user") continue;+ if (isSyntheticUserMessage(msg)) continue;+ const ts = Number(msg.timestamp);+ if (!Number.isFinite(ts)) continue;+ found.push(ts);+ }+ return found;+}++/** Last text the human typed, taken from a pi branch (entries or messages). */+export function lastUserTextFromBranch(branch) {+ const list = Array.isArray(branch) ? branch : [];+ for (let i = list.length - 1; i >= 0; i--) {+ const msg = entryMessage(list[i]);+ if (!msg || msg.role !== "user") continue;+ if (isSyntheticUserMessage(msg)) continue;+ const text = withoutWindowHeader(flattenContent(msg)).trim();+ if (text) return text;+ }+ return "";+}++function entryMessage(entry) {+ if (!entry || typeof entry !== "object") return null;+ if (entry.message && typeof entry.message === "object") return entry.message;+ if (typeof entry.role === "string") return entry;+ return null;+}++function entryId(entry) {+ if (!entry || typeof entry !== "object") return null;+ if (entry.id !== undefined && entry.id !== null) return entry.id;+ if (entry.entryId !== undefined && entry.entryId !== null) return entry.entryId;+ return null;+}++/** pi stamps session entries with an ISO string; its messages carry epoch ms. */+function entryTimestamp(entry) {+ const raw = entry?.timestamp;+ if (typeof raw === "number") return Number.isFinite(raw) ? raw : 0;+ const parsed = Date.parse(String(raw ?? ""));+ return Number.isFinite(parsed) ? parsed : 0;+}++function appendBranchMessage(out, entry) {+ if (!entry || typeof entry !== "object") return;+ if (entry.type === "message") {+ if (entry.message && typeof entry.message === "object") out.push(entry.message);+ return;+ }+ if (entry.type === "custom_message") {+ out.push({+ role: "custom",+ customType: entry.customType,+ content: entry.content,+ display: entry.display,+ details: entry.details,+ timestamp: entryTimestamp(entry),+ });+ return;+ }+ if (entry.type === "branch_summary" && entry.summary) {+ out.push({+ role: "branchSummary",+ summary: entry.summary,+ fromId: entry.fromId,+ timestamp: entryTimestamp(entry),+ });+ }+}++/**+ * The provider-visible message list of a pi branch — the same list+ * `SessionManager.buildSessionContext()` would build from those entries:+ * `message` entries contribute their message, `custom_message` entries a+ * `{role:"custom"}` message, and a compaction replaces everything before its+ * `firstKeptEntryId` with the summary. Every other entry type (this+ * extension's own window state, model or thinking-level changes, labels)+ * carries no message.+ *+ * `before_agent_start` runs before the `context` hook ever fires in a process,+ * so this is the only message list a status line built there can work from —+ * without it the first prompt after `pi -c` reports a window with no turns and+ * no idle gap.+ */+export function messagesFromBranch(entries) {+ const list = Array.isArray(entries) ? entries : [];+ let compactionIndex = -1;+ for (let i = list.length - 1; i >= 0; i--) {+ if (list[i]?.type === "compaction") {+ compactionIndex = i;+ break;+ }+ }++ const out = [];+ if (compactionIndex < 0) {+ for (const entry of list) appendBranchMessage(out, entry);+ return out;+ }++ const compaction = list[compactionIndex];+ out.push({+ role: "compactionSummary",+ summary: compaction.summary,+ tokensBefore: compaction.tokensBefore,+ timestamp: entryTimestamp(compaction),+ });+ let kept = false;+ for (let i = 0; i < compactionIndex; i++) {+ if (entryId(list[i]) === compaction.firstKeptEntryId) kept = true;+ if (kept) appendBranchMessage(out, list[i]);+ }+ for (let i = compactionIndex + 1; i < list.length; i++) appendBranchMessage(out, list[i]);+ return out;+}++/**+ * Sibling tool names for the header: the other tool calls issued in the same+ * assistant message as the anchoring `new_context` call. At reset time the+ * toolResults do not exist yet, so this reads the assistant message instead.+ */+export function siblingToolNamesFromBranch(branch, anchorToolCallId) {+ const anchor = String(anchorToolCallId || "");+ if (!anchor) return [];+ const list = Array.isArray(branch) ? branch : [];+ for (let i = list.length - 1; i >= 0; i--) {+ const msg = entryMessage(list[i]);+ const blocks = toolCallBlocks(msg);+ if (blocks.length === 0) continue;+ if (!blocks.some((block) => String(block.id || block.toolCallId || "") === anchor)) continue;+ return blocks+ .filter((block) => String(block.id || block.toolCallId || "") !== anchor)+ .map(blockToolName)+ .filter(Boolean);+ }+ return [];+}++function safeJson(value) {+ if (value === undefined || value === null) return "";+ if (typeof value === "string") return value;+ try {+ return JSON.stringify(value) || "";+ } catch {+ return "";+ }+}++/**+ * Token estimate for one pi message.+ *+ * `flattenContent` only sees `text`, so a bare `estimateTokens(flattenContent(m))`+ * scores an assistant message that writes a 40k-character file through a toolCall+ * block as ~2 tokens. The window estimate is the *only* signal when pi reports+ * `usage.tokens === null` (right after a native compaction), so tool-call+ * arguments and thinking blocks have to be counted too.+ */+export function messageTokens(msg) {+ if (!msg || typeof msg !== "object") return 0;+ let total = estimateTokens(flattenContent(msg));+ const content = msg.content;+ if (!Array.isArray(content)) return total;+ for (const block of content) {+ if (!block || typeof block !== "object") continue;+ if (block.type === "toolCall") {+ total += estimateTokens(blockToolName(block));+ total += estimateTokens(safeJson(block.arguments ?? block.input ?? block.parameters));+ } else if (typeof block.thinking === "string") {+ total += estimateTokens(block.thinking);+ }+ }+ return total;+}++function basename(uri) {+ const value = String(uri || "");+ if (!value) return "";+ const parts = value.split("/").filter(Boolean);+ return parts.length > 0 ? parts[parts.length - 1] : "";+}++// --------------------------------------------------------------------------+// Core+// --------------------------------------------------------------------------++export class ContextWindowCore {+ constructor({ config = {}, io = {} } = {}) {+ this.config = windowConfig(config);+ this.io = {+ syncBranch: io.syncBranch || (async () => ({ added: 0, tokens: 0, allDelivered: true })),+ flush: io.flush || (async () => true),+ postHandoff: io.postHandoff || (async () => false),+ commit: io.commit || (async () => null),+ readArchiveOverview: io.readArchiveOverview || (async () => null),+ getTask: io.getTask || (async () => null),+ persistEntry: io.persistEntry || (() => {}),+ getWatermark: io.getWatermark || (() => 0),+ now: io.now || (() => Date.now()),+ sleep: io.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),+ log: io.log || (() => {}),+ connected: io.connected || (() => true),+ sessionId: io.sessionId || (() => null),+ pendingCount: io.pendingCount || (() => 0),+ /** Messages the server rejected for good; they are missing from the archive. */+ droppedCount: io.droppedCount || (() => 0),+ /** trace_id of the last commit response, for a refusal the model can report. */+ commitTraceId: io.commitTraceId || (() => ""),+ };++ // Persisted state (plan §10).+ this.version = 1;+ this.ovSessionId = null;+ this.windowIndex = 1;+ this.anchorToolCallId = null;+ this.openedAt = 0;+ this.headerText = "";+ this.reason = "";+ this.notes = "";+ this.nextSteps = [];+ this.pendingRequest = "";+ this.archiveId = "";+ this.archiveUri = "";+ this.taskId = "";+ /**+ * Every archive this session produced, oldest first:+ * `{windowId, archiveId, archiveUri}`. `history` resolves window ids+ * through this map instead of numbering the server's archive list+ * positionally — a window that closed without producing an archive (an+ * external compaction) would otherwise shift every id by one.+ */+ this.archives = [];+ /** Archive of the window before the current one, for the stale WM block. */+ this.previousArchiveId = "";+ /** Messages OpenViking rejected for good; they are missing from the archive. */+ this.undeliveredCount = 0;+ this.overviewReady = false;+ this.overviewUnavailable = false;+ this.overviewAttempts = 0;+ // Persisted (truncated) so a window that opened with a stale Working Memory+ // block keeps it across `pi -c` instead of rendering a header without it.+ this.previousOverview = "";+ this.siblingToolNames = [];+ this.syncedEntryCount = 0;+ this.lastResetAt = 0;+ this.lastResetBy = "";++ // In-memory only.+ this.resetting = false;+ this.remindersSent = { soft: false, hard: false };+ this.awaitingFirstObservation = false;+ this.lastWindowTokens = 0;+ this.turnsInWindow = 0;+ this.overviewText = "";+ this.disarmLogged = false;+ this.lastPersisted = "";+ /**+ * Set when `restore()` adopted a window while the OpenViking session id was+ * still unknown; `validateSession()` settles it once the id exists.+ */+ this.pendingSessionCheck = false;+ /**+ * `{at, message}` of the last `io.commit` that threw. A throw after the+ * request left the process is indistinguishable from a request that never+ * arrived, so the archive may or may not exist.+ */+ this.lastCommitError = null;+ }++ get windowId() {+ return `w${this.windowIndex}`;+ }++ get armed() {+ return !!this.anchorToolCallId;+ }++ get state() {+ return {+ ...this.persistedState(),+ windowId: this.windowId,+ armed: this.armed,+ resetting: this.resetting,+ remindersSent: { ...this.remindersSent },+ awaitingFirstObservation: this.awaitingFirstObservation,+ lastWindowTokens: this.lastWindowTokens,+ turnsInWindow: this.turnsInWindow,+ lastCommitError: this.lastCommitError ? { ...this.lastCommitError } : null,+ };+ }++ persistedState() {+ return {+ version: 1,+ ovSessionId: this.ovSessionId,+ windowIndex: this.windowIndex,+ anchorToolCallId: this.anchorToolCallId,+ openedAt: this.openedAt,+ headerText: this.headerText,+ reason: this.reason,+ notes: this.notes,+ nextSteps: [...this.nextSteps],+ pendingRequest: this.pendingRequest,+ archiveId: this.archiveId,+ archiveUri: this.archiveUri,+ taskId: this.taskId,+ // Bounded: only the tail matters and the entry has to stay small.+ archives: this.archives.slice(-ARCHIVE_HISTORY_LIMIT).map((a) => ({ ...a })),+ previousArchiveId: this.previousArchiveId,+ undeliveredCount: this.undeliveredCount,+ overviewReady: this.overviewReady,+ overviewUnavailable: this.overviewUnavailable,+ overviewAttempts: this.overviewAttempts,+ // Truncated without the "(truncated)" marker: the entry only has to be+ // small, the frozen `headerText` already carries the rendered block.+ previousOverview: truncateToTokens(this.previousOverview || "", this.config.overviewBudget),+ siblingToolNames: [...this.siblingToolNames],+ syncedEntryCount: this.syncedEntryCount,+ lastResetAt: this.lastResetAt,+ lastResetBy: this.lastResetBy,+ };+ }++ // ---- persistence ------------------------------------------------------++ restore(entries) {+ const list = Array.isArray(entries) ? entries : [];+ const sid = this.safeSessionId();+ for (let i = list.length - 1; i >= 0; i--) {+ const entry = list[i];+ const isWindowEntry =+ (entry?.type === "custom" && entry.customType === WINDOW_ENTRY_TYPE) ||+ entry?.customType === WINDOW_ENTRY_TYPE ||+ entry?.type === WINDOW_ENTRY_TYPE;+ const data = isWindowEntry ? entry.data : null;+ if (!data || typeof data !== "object" || Array.isArray(data)) continue;+ if (sid && data.ovSessionId && String(data.ovSessionId) !== sid) continue;++ this.ovSessionId = typeof data.ovSessionId === "string" ? data.ovSessionId : null;+ this.windowIndex = Math.max(1, Math.floor(Number(data.windowIndex) || 1));+ this.anchorToolCallId = data.anchorToolCallId ? String(data.anchorToolCallId) : null;+ this.openedAt = Math.max(0, Math.floor(Number(data.openedAt) || 0));+ this.headerText = typeof data.headerText === "string" ? data.headerText : "";+ this.reason = typeof data.reason === "string" ? data.reason : "";+ this.notes = typeof data.notes === "string" ? data.notes : "";+ this.nextSteps = normalizeSteps(data.nextSteps);+ this.pendingRequest = typeof data.pendingRequest === "string" ? data.pendingRequest : "";+ this.archiveId = typeof data.archiveId === "string" ? data.archiveId : "";+ this.archiveUri = typeof data.archiveUri === "string" ? data.archiveUri : "";+ this.taskId = typeof data.taskId === "string" ? data.taskId : "";+ this.archives = normalizeArchives(data.archives);+ this.previousArchiveId = typeof data.previousArchiveId === "string" ? data.previousArchiveId : "";+ this.undeliveredCount = Math.max(0, Math.floor(Number(data.undeliveredCount) || 0));+ this.overviewReady = data.overviewReady === true;+ this.overviewUnavailable = data.overviewUnavailable === true;+ this.overviewAttempts = Math.max(0, Math.floor(Number(data.overviewAttempts) || 0));+ this.previousOverview = typeof data.previousOverview === "string" ? data.previousOverview : "";+ this.siblingToolNames = normalizeNames(data.siblingToolNames);+ this.syncedEntryCount = Math.max(0, Math.floor(Number(data.syncedEntryCount) || 0));+ this.lastResetAt = Math.max(0, Math.floor(Number(data.lastResetAt) || 0));+ this.lastResetBy = typeof data.lastResetBy === "string" ? data.lastResetBy : "";+ this.lastPersisted = JSON.stringify(this.persistedState());+ // The adapter often restores before the OpenViking session id is known+ // (the sync manager derives it from pi's session id, which arrives with+ // the first event). Remember that the ownership check is still owed.+ this.pendingSessionCheck = !sid && !!this.ovSessionId;+ this.log(+ `context-window: restored ${this.windowId}` ++ (this.armed ? ` anchored at ${this.anchorToolCallId}` : " (not armed)"),+ );+ return this.state;+ }+ return this.state;+ }++ /**+ * Settle a restore that happened before `io.sessionId()` was known: if the+ * window belonged to a different OpenViking session, drop it. Safe to call on+ * every context transform — it does nothing once the check is settled.+ */+ validateSession() {+ if (!this.pendingSessionCheck) return true;+ const sid = this.safeSessionId();+ if (!sid) return true;+ this.pendingSessionCheck = false;+ if (!this.ovSessionId || this.ovSessionId === sid) {+ this.ovSessionId = sid;+ return true;+ }+ this.disarm(`restored window belongs to ${this.ovSessionId}, this session is ${sid}; window dropped`);+ this.windowIndex = 1;+ this.headerText = "";+ this.archiveId = "";+ this.archiveUri = "";+ this.taskId = "";+ this.previousOverview = "";+ this.overviewReady = false;+ this.overviewUnavailable = false;+ this.ovSessionId = sid;+ this.lastPersisted = "";+ return false;+ }++ persist() {+ try {+ const state = this.persistedState();+ const key = JSON.stringify(state);+ if (key === this.lastPersisted) return;+ this.io.persistEntry(WINDOW_ENTRY_TYPE, state);+ this.lastPersisted = key;+ } catch {+ // Best effort: a missed entry only means the next process sees full history.+ }+ }++ async shutdown() {+ this.syncedEntryCount = this.safeWatermark();+ this.persist();+ }++ // ---- context transform ------------------------------------------------++ transformContext(messages) {+ return this.cutAndRecord(messages, true);+ }++ /**+ * The same cut and the same metrics, but without the right to release the+ * boundary — for a caller that only wants to describe the window (the status+ * line, built in `before_agent_start` from the session branch).+ *+ * Only the hook that actually feeds the provider may disarm: a list that is+ * missing the anchor because pi has not finished writing it would otherwise+ * release the boundary from a status readout, and the next request would hand+ * the model back a window it was told is archived.+ */+ observeMessages(messages) {+ return this.cutAndRecord(messages, false);+ }++ cutAndRecord(messages, mayDisarm) {+ const list = Array.isArray(messages) ? messages : [];+ // Opportunistic: by the time a context is built the session id always+ // exists, so a window restored from another session is dropped here at the+ // latest, even if the adapter never called `validateSession()` itself.+ this.validateSession();+ if (!this.armed || !this.headerText) {+ this.recordWindowMetrics(list, -1);+ return list;+ }++ const cut = applyWindowCut(list, {+ anchorToolCallId: this.anchorToolCallId,+ headerText: this.headerText,+ headerTimestamp: this.openedAt,+ });+ if (!cut.applied) {+ if (mayDisarm) this.disarm("anchor missing, boundary released");+ this.recordWindowMetrics(list, -1);+ return list;+ }++ this.recordWindowMetrics(cut.messages, 0);+ return cut.messages;+ }++ /**+ * Refresh `lastWindowTokens` / `turnsInWindow` from the message list that is+ * actually going to the provider.+ *+ * With a header at `headerIndex` the turn count is simply "assistants after+ * it". Without one (`headerIndex < 0`, i.e. the anchor was lost) the list is+ * the *whole* session again, so counting every assistant message would tell+ * the model that a window opened a minute ago is dozens of turns old. Fall+ * back to the timestamp of the last reset instead.+ */+ recordWindowMetrics(messages, headerIndex) {+ const list = Array.isArray(messages) ? messages : [];+ const since = headerIndex < 0 && this.lastResetAt > 0 ? this.lastResetAt : 0;+ let tokens = 0;+ let assistants = 0;+ for (let i = 0; i < list.length; i++) {+ const msg = list[i];+ tokens += messageTokens(msg);+ if (i <= headerIndex) continue;+ if (msg?.role !== "assistant") continue;+ if (since > 0) {+ const ts = Number(msg.timestamp);+ // An undated message is counted: pi always stamps them, so this only+ // happens for synthetic ones, and over-counting is the safe direction.+ if (Number.isFinite(ts) && ts < since) continue;+ }+ assistants++;+ }+ this.lastWindowTokens = tokens;+ this.turnsInWindow = assistants;+ if (assistants > 0) this.awaitingFirstObservation = false;+ }++ observeAssistantResponse() {+ this.awaitingFirstObservation = false;+ }++ /**+ * Release the virtual boundary. The window metrics described the cut window,+ * so they are reset too: keeping them would let the status line report "12+ * turns" for a window that no longer exists.+ */+ disarm(reason) {+ if (!this.disarmLogged) {+ this.log(`context-window: ${reason}`);+ this.disarmLogged = true;+ }+ this.anchorToolCallId = null;+ this.awaitingFirstObservation = false;+ this.turnsInWindow = 0;+ this.lastWindowTokens = 0;+ }++ // ---- reset ------------------------------------------------------------++ /**+ * The blocking reset pipeline (plan §2). Never throws: every failure comes+ * back as `{ok:false}` with text the model reads (fail-closed — a refusal+ * means nothing was cut, so no history is lost).+ */+ async requestReset(opts = {}) {+ const reason = String(opts.reason || "").trim();+ const notes = String(opts.notes || "").trim();+ const nextSteps = normalizeSteps(opts.nextSteps);+ const toolCallId = String(opts.toolCallId || "");+ const branch = Array.isArray(opts.branch) ? opts.branch : [];+ const signal = opts.signal || null;+ const onProgress = typeof opts.onProgress === "function" ? opts.onProgress : () => {};++ if (this.resetting) {+ return {+ ok: false,+ kind: "noop",+ text:+ "Context window NOT reset: a reset is already in progress. " ++ "Nothing changed; keep working and do not call new_context again.",+ details: { stage: "busy" },+ };+ }++ const startedAt = this.io.now();+ const deadline = startedAt + this.config.resetDeadlineMs;+ /** Set to `{archiveUri, archiveId, taskId}` once the archive exists. */+ let committed = null;+ /** True once the handoff note is in the live session and may need retracting. */+ let handoffPosted = false;+ this.resetting = true;+ try {+ if (!toolCallId) {+ return this.refuse("this call has no tool call id to anchor the new window to", { stage: "anchor" });+ }+ if (signal?.aborted) return this.cancelled("aborted-early");+ const connected = this.io.connected();+ if (this.lastCommitError) {+ // A previous commit threw *after* the request went out, so we never+ // learned whether the server archived the session. Re-checking+ // connectivity is all we can do; if it is back we try again, which may+ // produce an empty second archive (commit answers `skipped`) — the+ // failure mode we accept, because the alternative is a window that can+ // never be reset again.+ if (!connected) {+ return this.refuse(+ "the previous archive commit failed in transport and OpenViking is still unreachable",+ { stage: "commit-transport", error: this.lastCommitError.message },+ );+ }+ this.log("context-window: retrying after an unresolved commit transport error");+ this.lastCommitError = null;+ }+ if (!connected || !this.safeSessionId()) {+ return this.refuse("OpenViking is unreachable, so this window cannot be archived", {+ stage: "connectivity",+ });+ }++ const synced = await this.io.syncBranch(branch);+ if (synced && synced.allDelivered === false) {+ return this.refuse(+ "the conversation so far could not be fully delivered to OpenViking",+ { stage: "sync", added: Number(synced.added) || 0 },+ );+ }++ if (signal?.aborted) return this.cancelled("aborted-before-flush");++ const flushed = await this.io.flush({ budgetMs: this.flushBudget(deadline) });+ if (!flushed) {+ const pending = Math.max(0, Math.floor(Number(this.io.pendingCount()) || 0));+ const detail = pending > 0 ? `${pending} captured message(s) are still queued` : "captured messages are still queued";+ return this.refuse(`the archive barrier did not clear — ${detail}`, { stage: "flush", pending });+ }++ // Both the abort and the deadline are checked *before* the handoff note+ // is written, because a refusal after it leaves a+ // "[Context Window Handoff]" message in the live OpenViking session for a+ // window that never closed. The paths that can still refuse after the+ // write retract it (`refuseAfterHandoff`), which is a repair, not a+ // rollback: OpenViking has no delete for a session message.+ if (signal?.aborted) return this.cancelled("aborted-before-handoff");+ if (this.io.now() >= deadline) {+ return this.refuse(+ "the reset deadline was exhausted while syncing this window to OpenViking",+ { stage: "deadline", deadlineMs: this.config.resetDeadlineMs },+ );+ }++ const nextWindowId = `w${this.windowIndex + 1}`;+ const handoff = buildHandoffMessage({+ windowId: this.windowId,+ nextWindowId,+ reason,+ notes,+ nextSteps,+ });+ const posted = await this.io.postHandoff(handoff);+ if (!posted) {+ return this.refuse("the handoff note could not be written to OpenViking", { stage: "handoff" });+ }+ // From here on the live OpenViking session already carries a+ // "[Context Window Handoff]" message for a window that has not closed+ // yet, so every refusal below has to retract it first — otherwise the+ // next archive would contain two handoffs and the Working Memory prompt+ // would read a window boundary that never happened.+ handoffPosted = true;++ if (signal?.aborted) return await this.cancelledAfterHandoff("aborted-before-commit");++ let commit;+ try {+ commit = await this.io.commit({ keepRecentCount: 0 });+ } catch (err) {+ // A throw here is ambiguous by construction: the request may have been+ // rejected before it left the process, or it may have archived the+ // session and lost the response. We fail closed (nothing is cut) and+ // remember it, so the next attempt at least re-checks connectivity+ // before it syncs and flushes again.+ this.lastCommitError = { at: this.safeNow(), message: String(err?.message || err) };+ this.log(`context-window: commit transport error; the archive may or may not exist (${this.lastCommitError.message})`);+ return await this.refuseAfterHandoff(+ "the archive commit failed in transport; the archive may or may not exist, so nothing was cut",+ { stage: "commit-transport", error: this.lastCommitError.message },+ );+ }+ if (!commit || typeof commit !== "object") {+ return await this.refuseAfterHandoff("OpenViking refused the archive commit", {+ stage: "commit",+ traceId: this.safeCommitTraceId(),+ });+ }+ const status = String(commit.status || "");+ // No `archive_uri` means there is no archive to point the model at, and+ // waiting for the Working Memory of an empty URI would burn the whole+ // deadline — so it refuses even when the status says `accepted`.+ if (status === "skipped" || !commit.archive_uri) {+ if (status === "skipped") {+ await this.retractHandoff();+ return {+ ok: false,+ kind: "noop",+ text:+ "Context window NOT reset: OpenViking had nothing to archive for this window. " ++ "Keep working; call new_context again once there is something worth archiving.",+ details: { stage: "commit", status, reason: commit.reason || "" },+ };+ }+ return await this.refuseAfterHandoff("OpenViking refused the archive commit", {+ stage: "commit",+ status,+ traceId: commit.trace_id || this.safeCommitTraceId(),+ });+ }++ // ---- past the point of no return: the archive exists -------------+ // Everything below MUST end in an open window. The commit emptied the+ // OpenViking session (keep_recent_count 0), so answering "NOT reset —+ // nothing changed" here would leave the model carrying the old context+ // while believing its history is still live.+ const archiveUri = String(commit.archive_uri || "");+ const archiveId = basename(archiveUri);+ const taskId = String(commit.task_id || "");+ // `baseWindowIndex` lets the recovery path below re-derive the window ids+ // even if the throw happened halfway through the assignments.+ committed = {+ archiveUri,+ archiveId,+ taskId,+ baseWindowIndex: this.windowIndex,+ previousOverview: this.overviewText,+ };++ let wait;+ try {+ wait = await this.waitForOverview({ archiveUri, archiveId, taskId, deadline, signal, onProgress });+ } catch {+ // An abort-aware io.sleep may reject; the window still has to open.+ wait = { state: "pending", overview: "", attempts: 0 };+ }++ const previousWindowId = this.windowId;+ const previousOverview = this.overviewText;++ this.windowIndex += 1;+ this.anchorToolCallId = toolCallId;+ this.openedAt = this.io.now();+ this.reason = reason;+ this.notes = notes;+ this.nextSteps = nextSteps;+ this.pendingRequest = lastUserTextFromBranch(branch);+ this.previousArchiveId = this.archiveId;+ this.recordArchive(previousWindowId, archiveId, archiveUri);+ this.undeliveredCount = this.safeDroppedCount();+ this.archiveId = archiveId;+ this.archiveUri = archiveUri;+ this.taskId = taskId;+ this.overviewReady = wait.state === "ready";+ this.overviewUnavailable = wait.state === "unavailable";+ this.overviewAttempts = 0;+ this.siblingToolNames = normalizeNames(+ opts.siblingToolNames || siblingToolNamesFromBranch(branch, toolCallId),+ );+ this.previousOverview = previousOverview;+ this.overviewText = wait.overview;+ this.headerText = this.rebuildHeader({ overviewState: wait.state, previousWindowId });+ this.previousWindowId = previousWindowId;+ this.remindersSent = { soft: false, hard: false };+ this.awaitingFirstObservation = true;+ this.disarmLogged = false;+ this.lastResetAt = this.io.now();+ this.lastResetBy = "agent";+ this.ovSessionId = this.safeSessionId();+ this.syncedEntryCount = this.safeWatermark();+ this.persist();+ this.log(+ `context-window: opened ${this.windowId} from ${archiveId || "(no archive)"} ` ++ `(working memory ${wait.state}, waited ${this.io.now() - startedAt}ms)`,+ );++ const memory =+ wait.state === "ready"+ ? "ready and included in the new window"+ : wait.state === "unavailable"+ ? "unavailable; the window header points at history instead"+ : "still being generated; the window header points at history instead";++ return {+ ok: true,+ kind: "reset",+ text:+ `Context window ${this.windowId} is open. ${previousWindowId} was archived to OpenViking as ` ++ `${archiveId || "an archive"}. Working Memory is ${memory}. ` ++ "This tool result is not part of the new window: the next sampling starts from the window header, " ++ "which carries your reason, your handoff notes and whatever Working Memory exists. Continue from there.",+ details: {+ windowId: this.windowId,+ previousWindowId,+ archiveId,+ archiveUri,+ taskId,+ overviewState: wait.state,+ attempts: wait.attempts,+ waitedMs: this.io.now() - startedAt,+ },+ };+ } catch (err) {+ if (committed) {+ const recovered = this.recoverAfterCommit(committed, err, {+ toolCallId,+ reason,+ notes,+ nextSteps,+ branch,+ siblingToolNames: opts.siblingToolNames,+ startedAt,+ });+ if (recovered) return recovered;+ }+ if (handoffPosted && !committed) await this.retractHandoff();+ return this.refuse(`the reset failed unexpectedly (${err?.message || err})`, { stage: "error" });+ } finally {+ this.resetting = false;+ }+ }++ /**+ * Last-resort open: the commit landed but something after it threw. Open the+ * window anyway with an `unavailable` Working Memory so the model at least+ * gets its own notes and the pointer to `history`.+ */+ recoverAfterCommit(committed, err, ctx) {+ try {+ const base = Math.max(1, Math.floor(Number(committed.baseWindowIndex) || 1));+ const previousWindowId = `w${base}`;+ const previousOverview = committed.previousOverview || "";+ this.windowIndex = base + 1;+ this.anchorToolCallId = ctx.toolCallId;+ this.openedAt = this.safeNow();+ this.reason = ctx.reason;+ this.notes = ctx.notes;+ this.nextSteps = ctx.nextSteps;+ try {+ this.pendingRequest = lastUserTextFromBranch(ctx.branch);+ } catch {+ this.pendingRequest = "";+ }+ this.previousArchiveId = this.archiveId;+ this.recordArchive(previousWindowId, committed.archiveId, committed.archiveUri);+ this.undeliveredCount = this.safeDroppedCount();+ this.archiveId = committed.archiveId;+ this.archiveUri = committed.archiveUri;+ this.taskId = committed.taskId;+ this.overviewReady = false;+ this.overviewUnavailable = false;+ this.overviewAttempts = 0;+ this.previousOverview = previousOverview;+ this.overviewText = "";+ try {+ this.siblingToolNames = normalizeNames(+ ctx.siblingToolNames || siblingToolNamesFromBranch(ctx.branch, ctx.toolCallId),+ );+ } catch {+ this.siblingToolNames = [];+ }+ this.headerText = this.rebuildHeader({ overviewState: "pending", previousWindowId });+ this.previousWindowId = previousWindowId;+ this.remindersSent = { soft: false, hard: false };+ this.awaitingFirstObservation = true;+ this.disarmLogged = false;+ this.lastResetAt = this.safeNow();+ this.lastResetBy = "agent";+ this.ovSessionId = this.safeSessionId();+ this.syncedEntryCount = this.safeWatermark();+ this.persist();+ this.log(+ `context-window: opened ${this.windowId} from ${committed.archiveId || "(no archive)"} ` ++ `after a post-commit failure (${err?.message || err})`,+ );+ return {+ ok: true,+ kind: "reset",+ text:+ `Context window ${this.windowId} is open. ${previousWindowId} was archived to OpenViking as ` ++ `${committed.archiveId || "an archive"}, but the wait for its Working Memory failed ` ++ `(${err?.message || err}). Work from your own handoff notes in the window header and use ` ++ "history to read the archived messages. This tool result is not part of the new window.",+ details: {+ windowId: this.windowId,+ previousWindowId,+ archiveId: committed.archiveId,+ archiveUri: committed.archiveUri,+ taskId: committed.taskId,+ overviewState: "pending",+ attempts: 0,+ error: String(err?.message || err),+ waitedMs: this.safeNow() - ctx.startedAt,+ },+ };+ } catch {+ return null;+ }+ }++ /**+ * Budget for one flush barrier: never more than 15s of the reset deadline,+ * but never less than 2s either — a barrier called with a nearly empty budget+ * reports "not delivered" for a queue that would have drained in a moment.+ */+ flushBudget(deadline) {+ const remaining = Number(deadline) - this.io.now();+ return Math.max(2000, Math.min(15000, Number.isFinite(remaining) ? remaining : 0));+ }++ /** Cancelled before anything irreversible happened. */+ cancelled(stage) {+ return {+ ok: false,+ kind: "noop",+ // Every non-success text starts with the same marker so the model has one+ // string to key off: "Context window NOT reset".+ text:+ "Context window NOT reset: the reset was cancelled before anything was archived. " ++ "Nothing changed; keep working.",+ details: { stage },+ };+ }++ /**+ * Retract the handoff note that is already in the live OpenViking session.+ * Best effort and never fatal: it is a second message, not a deletion, and+ * the Working Memory prompt reads it as "that boundary did not happen".+ */+ async retractHandoff() {+ try {+ await this.io.postHandoff(+ `${HANDOFF_MARKER} RETRACTED — the reset of ${this.windowId} failed, this window is still open. ` ++ "Ignore the handoff note above; it does not mark a window boundary.",+ );+ } catch {+ // The refusal itself is what matters; a failed retraction only leaves the+ // orphan note behind.+ }+ }++ async refuseAfterHandoff(cause, details = {}) {+ await this.retractHandoff();+ return this.refuse(cause, details);+ }++ async cancelledAfterHandoff(stage) {+ await this.retractHandoff();+ return this.cancelled(stage);+ }++ refuse(cause, details = {}) {+ const trace = details.traceId ? ` (trace ${details.traceId})` : "";+ return {+ ok: false,+ kind: "refused",+ text: `Context window NOT reset: ${cause}${trace}. ${FAIL_CLOSED_TAIL}`,+ details,+ };+ }++ /**+ * Poll `<archive_uri>/.overview.md` until it exists (the only readable+ * readiness signal — the archives route is blocked on the gateway).+ */+ async waitForOverview({ archiveUri, archiveId, taskId, deadline, signal, onProgress }) {+ let attempts = 0;+ let state = "pending";+ let overview = "";+ /**+ * Polls left after the archive task reached a terminal state without a+ * Working Memory; -1 while the task is still running. A commit whose phase 2+ * finishes with an empty summary never writes `.overview.md` at all+ * (session.py skips the write), and the task ends as `completed` — without+ * this the wait would burn the entire deadline on every single reset.+ */+ let graceLeft = -1;++ while (true) {+ if (signal?.aborted) {+ state = "pending";+ break;+ }++ attempts++;+ let text = null;+ try {+ text = await this.io.readArchiveOverview(archiveUri);+ } catch {+ text = null;+ }+ if (typeof text === "string" && text.trim()) {+ overview = text.trim();+ state = "ready";+ break;+ }++ if (taskId && graceLeft < 0 && (attempts === 2 || attempts % 5 === 0)) {+ let task = null;+ try {+ task = await this.io.getTask(taskId);+ } catch {+ task = null;+ }+ const status = task ? String(task.status || "") : "";+ if (status === "failed" || status === "cancelled") {+ state = "unavailable";+ break;+ }+ if (status === "completed") {+ // Phase 2 is over. Either the write is a moment behind this read, or+ // there is no Working Memory to wait for at all.+ graceLeft = 2;+ }+ } else if (graceLeft > 0) {+ graceLeft -= 1;+ } else if (graceLeft === 0) {+ state = "unavailable";+ this.log(`context-window: ${archiveId} finished without a Working Memory`);+ break;+ }++ const remaining = deadline - this.io.now();+ if (remaining <= 0) {+ state = "pending";+ break;+ }+ try {+ onProgress?.(`waiting for the Working Memory of ${archiveId} (attempt ${attempts})`);+ } catch {+ // progress reporting must never break the reset+ }+ await this.io.sleep(Math.min(this.config.archivePollMs, remaining), signal);+ }++ return { state, overview, attempts };+ }++ rebuildHeader({ overviewState, previousWindowId }) {+ return buildWindowHeader({+ windowId: this.windowId,+ previousWindowId: previousWindowId || this.previousWindowId || `w${Math.max(1, this.windowIndex - 1)}`,+ archiveId: this.archiveId,+ archiveUri: this.archiveUri,+ openedAt: this.openedAt,+ reason: this.reason,+ notes: this.notes,+ nextSteps: this.nextSteps,+ pendingRequest: this.pendingRequest,+ overview: this.overviewText,+ overviewState,+ previousOverview: this.previousOverview,+ previousArchiveId: this.previousArchiveId,+ undeliveredCount: this.undeliveredCount,+ siblingToolNames: this.siblingToolNames,+ config: this.config,+ });+ }++ /** Remember which window a fresh archive belongs to (plan §10, carry-over 2). */+ recordArchive(windowId, archiveId, archiveUri) {+ const id = String(archiveId || "").trim();+ if (!id) return;+ const row = { windowId: String(windowId || this.windowId), archiveId: id, archiveUri: String(archiveUri || "") };+ const existing = this.archives.findIndex((a) => a.archiveId === id);+ if (existing >= 0) this.archives[existing] = row;+ else this.archives.push(row);+ if (this.archives.length > ARCHIVE_HISTORY_LIMIT) {+ this.archives = this.archives.slice(-ARCHIVE_HISTORY_LIMIT);+ }+ }++ /**+ * Non-blocking follow-up for a degraded window: one `.overview.md` read per+ * turn until it lands (then the header is rebuilt once — a single cache miss)+ * or the attempt budget runs out.+ */+ async refreshPendingOverview() {+ if (!this.armed || this.overviewReady || this.overviewUnavailable) return false;+ if (!this.archiveUri) return false;++ if (this.overviewAttempts >= this.config.overviewRefreshMaxAttempts) {+ this.markOverviewUnavailable();+ return false;+ }++ this.overviewAttempts += 1;+ let text = null;+ try {+ text = await this.io.readArchiveOverview(this.archiveUri);+ } catch {+ text = null;+ }++ if (typeof text === "string" && text.trim()) {+ this.overviewText = text.trim();+ this.overviewReady = true;+ this.headerText = this.rebuildHeader({ overviewState: "ready" });+ this.persist();+ this.log(`context-window: working memory attached to ${this.windowId}`);+ return true;+ }++ if (this.overviewAttempts >= this.config.overviewRefreshMaxAttempts) {+ this.markOverviewUnavailable();+ }+ return false;+ }++ markOverviewUnavailable() {+ if (this.overviewUnavailable) return;+ this.overviewUnavailable = true;+ this.headerText = this.rebuildHeader({ overviewState: "unavailable" });+ this.persist();+ this.log(`context-window: working memory unavailable for ${this.archiveId || this.windowId}`);+ }++ // ---- signals ----------------------------------------------------------++ usedTokens(usage) {+ let used = Math.max(0, Math.floor(Number(this.lastWindowTokens) || 0));+ let estimated = true;+ const reported = usage && usage.tokens !== null && usage.tokens !== undefined ? Number(usage.tokens) : NaN;+ if (!this.awaitingFirstObservation && Number.isFinite(reported)) {+ used = Math.max(used, Math.floor(reported));+ estimated = false;+ }+ return { used, estimated };+ }++ /**+ * Soft/hard percentages for this call, clamped under pi's own auto-compaction+ * line when the caller knows `reserveTokens` (settings `compaction.reserveTokens`).+ */+ thresholdsFor(contextWindow, reserveTokens) {+ return effectiveThresholds({+ softPercent: this.config.softPercent,+ hardPercent: this.config.hardPercent,+ contextWindow,+ reserveTokens,+ });+ }++ dueReminder({ usage = null, contextWindow = 0, reserveTokens = 0 } = {}) {+ if (this.awaitingFirstObservation) return null;+ const total = Math.max(0, Math.floor(Number(contextWindow) || Number(usage?.contextWindow) || 0));+ if (total <= 0) return null;+ const { used } = this.usedTokens(usage);+ if (used <= 0) return null;++ const limits = this.thresholdsFor(total, reserveTokens);+ const pct = (used / total) * 100;+ if (pct >= limits.hardPercent && !this.remindersSent.hard) {+ this.remindersSent.hard = true;+ this.remindersSent.soft = true;+ return "hard";+ }+ if (pct >= limits.softPercent && !this.remindersSent.soft) {+ this.remindersSent.soft = true;+ return "soft";+ }+ return null;+ }++ statusSnapshot({ usage = null, now = null, messages = [], reserveTokens = 0 } = {}) {+ const nowMs = Number.isFinite(Number(now)) ? Number(now) : this.io.now();+ const stamps = lastUserTimestamps(messages);+ const sinceLastUserMs = stamps.length > 0 ? Math.max(0, nowMs - stamps[0]) : null;+ const idleGapMs = stamps.length >= 2 ? Math.max(0, stamps[0] - stamps[1]) : null;++ const contextWindow = Math.max(0, Math.floor(Number(usage?.contextWindow) || 0));+ const { used, estimated } = this.usedTokens(usage);+ const percent = percentOf(used, contextWindow);+ const tokensLeft = contextWindow > 0 ? Math.max(0, contextWindow - used) : null;++ const limits = this.thresholdsFor(contextWindow, reserveTokens);+ let advice = "no action needed";+ if (percent >= limits.hardPercent) advice = "save your notes and call new_context now";+ else if (percent >= limits.softPercent) {+ advice = "past the soft threshold: update your notes and reset at the next stopping point";+ }++ return {+ windowId: this.windowId,+ turnsInWindow: this.turnsInWindow,+ usedTokens: used,+ contextWindow,+ percent,+ tokensLeft,+ estimated,+ sinceLastUserMs,+ idleGapMs,+ archiveId: this.archiveId,+ // The real number of archives this session produced. Deriving it from the+ // window index would over-count: a window closed by an external+ // compaction advances the index without producing one.+ archiveCount: this.archives.length,+ archives: this.archives.map((a) => ({ ...a })),+ undeliveredCount: this.undeliveredCount,+ overviewReady: this.overviewReady,+ windowAgeMs: this.openedAt > 0 ? Math.max(0, nowMs - this.openedAt) : null,+ softPercent: limits.softPercent,+ hardPercent: limits.hardPercent,+ advice,+ };+ }++ // ---- pi compaction fallback ------------------------------------------++ /**+ * `session_before_compact`. Either takes over pi's compaction with an+ * OpenViking archive + our window header as the summary, or (right after a+ * reset) short-circuits it so a stale usage estimate cannot double-archive.+ */+ async handleBeforeCompact({ preparation = {}, branchEntries = [] } = {}) {+ const prep = preparation && typeof preparation === "object" ? preparation : {};+ const entries = Array.isArray(branchEntries) ? branchEntries : [];+ const tokensBefore = Number(prep.tokensBefore) || 0;++ const sinceReset = this.lastResetAt > 0 ? this.io.now() - this.lastResetAt : Infinity;+ const noNewSync = this.safeWatermark() <= this.syncedEntryCount;+ // After an *external* compaction our header describes an archive that no+ // longer covers what pi is about to drop, so it must not be reused as the+ // summary — let pi write its own instead.+ const ourHeader = this.headerText && this.lastResetBy !== "external";+ if (ourHeader && sinceReset < this.config.recentResetGuardMs && noNewSync) {+ this.log(`context-window: compaction suppressed, ${this.windowId} was opened ${sinceReset}ms ago`);+ return {+ compaction: {+ summary: this.headerText,+ firstKeptEntryId: this.pickFirstKeptEntryId(prep, entries),+ tokensBefore,+ details: { source: "openviking", reason: "recent-reset-guard" },+ },+ };+ }++ if (this.resetting) return undefined;+ this.resetting = true;+ try {+ if (!this.io.connected() || !this.safeSessionId()) return undefined;+ const deadline = this.io.now() + this.config.resetDeadlineMs;++ // pi hands us the branch it is about to compact; whatever of it the+ // capture path has not delivered yet must reach the archive first, or the+ // window header would claim messages that were never archived.+ const synced = await this.io.syncBranch(entries);+ if (synced && synced.allDelivered === false) return undefined;++ if (!(await this.io.flush({ budgetMs: this.flushBudget(deadline) }))) return undefined;++ const previousWindowId = this.windowId;+ const reason = "automatic: pi compaction threshold";+ // Not `this.notes`: those were written for the window that *opened* here,+ // and repeating them would present them as this window's handoff.+ const posted = await this.io.postHandoff(+ buildHandoffMessage({+ windowId: previousWindowId,+ nextWindowId: `w${this.windowIndex + 1}`,+ reason,+ notes: AUTO_COMPACT_NOTES,+ nextSteps: [],+ }),+ );+ if (!posted) return undefined;++ const commit = await this.io.commit({ keepRecentCount: 0 });+ if (!commit || typeof commit !== "object" || !commit.archive_uri) {+ await this.retractHandoff();+ return undefined;+ }++ const archiveUri = String(commit.archive_uri || "");+ const archiveId = basename(archiveUri);+ const taskId = String(commit.task_id || "");+ const wait = await this.waitForOverview({+ archiveUri,+ archiveId,+ taskId,+ deadline,+ signal: null,+ onProgress: null,+ });++ const firstKeptEntryId = this.pickFirstKeptEntryId(prep, entries);+ const previousOverview = this.overviewText;++ this.windowIndex += 1;+ // pi performs a native cut here, so the virtual anchor must go.+ this.anchorToolCallId = null;+ this.openedAt = this.io.now();+ this.reason = reason;+ // The notes belonged to the window that just closed, so they are not this+ // window's handoff; the header would otherwise label them as such.+ this.notes = "";+ this.nextSteps = [];+ this.pendingRequest = lastUserTextFromBranch(entries);+ this.previousArchiveId = this.archiveId;+ this.recordArchive(previousWindowId, archiveId, archiveUri);+ this.undeliveredCount = this.safeDroppedCount();+ this.archiveId = archiveId;+ this.archiveUri = archiveUri;+ this.taskId = taskId;+ this.overviewReady = wait.state === "ready";+ this.overviewUnavailable = wait.state === "unavailable";+ this.overviewAttempts = 0;+ this.siblingToolNames = [];+ this.previousOverview = previousOverview;+ this.overviewText = wait.overview;+ this.headerText = this.rebuildHeader({ overviewState: wait.state, previousWindowId });+ this.previousWindowId = previousWindowId;+ this.remindersSent = { soft: false, hard: false };+ this.awaitingFirstObservation = true;+ this.disarmLogged = false;+ this.lastResetAt = this.io.now();+ this.lastResetBy = "pi-compaction";+ this.ovSessionId = this.safeSessionId();+ this.syncedEntryCount = this.safeWatermark();+ this.persist();+ this.log(`context-window: pi compaction opened ${this.windowId} from ${archiveId || "(no archive)"}`);++ return {+ compaction: {+ summary: this.headerText,+ firstKeptEntryId,+ tokensBefore,+ details: { source: "openviking", reason: "pi-compaction" },+ },+ };+ } catch {+ return undefined;+ } finally {+ this.resetting = false;+ }+ }++ /**+ * Never hand pi a `firstKeptEntryId` that would resurrect messages the window+ * header already declares archived.+ */+ pickFirstKeptEntryId(preparation = {}, branchEntries = []) {+ const fallback = preparation?.firstKeptEntryId;+ if (!this.anchorToolCallId) return fallback;++ const entries = Array.isArray(branchEntries) ? branchEntries : [];+ let anchorIndex = -1;+ for (let i = entries.length - 1; i >= 0; i--) {+ const msg = entryMessage(entries[i]);+ if (isToolResult(msg) && String(msg.toolCallId || "") === this.anchorToolCallId) {+ anchorIndex = i;+ break;+ }+ }+ if (anchorIndex < 0) return fallback;++ let runEnd = anchorIndex;+ while (isToolResult(entryMessage(entries[runEnd + 1]))) runEnd++;++ if (fallback !== undefined && fallback !== null) {+ const prepIndex = entries.findIndex((entry) => entryId(entry) === fallback);+ if (prepIndex > runEnd) return fallback;+ }++ const next = entries[runEnd + 1];+ const nextId = entryId(next);+ if (nextId !== null && nextId !== undefined) return nextId;+ return COMPACTION_SENTINEL;+ }++ /**+ * pi (or another extension) compacted without us: drop the virtual cut.+ *+ * The window index still advances — the model's context really did change,+ * and the reminders have to re-arm for what is effectively a new window — but+ * no archive is produced, so this window id never appears in `this.archives`+ * and `history` never lists it. That is why window ids are resolved through+ * the recorded map rather than by numbering the server's archive list.+ */+ absorbExternalCompaction(reason = "external compaction") {+ this.anchorToolCallId = null;+ this.windowIndex += 1;+ this.openedAt = this.io.now();+ this.remindersSent = { soft: false, hard: false };+ this.awaitingFirstObservation = true;+ this.disarmLogged = false;+ this.lastResetAt = this.io.now();+ this.lastResetBy = "external";+ this.syncedEntryCount = this.safeWatermark();+ this.persist();+ this.log(`context-window: absorbed external compaction (${reason}), now ${this.windowId}`);+ }++ // ---- helpers ----------------------------------------------------------++ safeSessionId() {+ try {+ const sid = this.io.sessionId();+ return sid ? String(sid) : null;+ } catch {+ return null;+ }+ }++ safeNow() {+ try {+ const value = Number(this.io.now());+ return Number.isFinite(value) ? value : Date.now();+ } catch {+ return Date.now();+ }+ }++ safeDroppedCount() {+ try {+ const value = Number(this.io.droppedCount());+ return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : this.undeliveredCount;+ } catch {+ return this.undeliveredCount;+ }+ }++ safeCommitTraceId() {+ try {+ const value = this.io.commitTraceId();+ return value ? String(value) : "";+ } catch {+ return "";+ }+ }++ safeWatermark() {+ try {+ const value = Number(this.io.getWatermark());+ return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : this.syncedEntryCount;+ } catch {+ return this.syncedEntryCount;+ }+ }++ log(message) {+ try {+ this.io.log(message);+ } catch {+ // Logging must never affect pi's context path.+ }+ }+}diff --git a/examples/pi-experimental-context-management/lib/pi-settings.mjs b/examples/pi-experimental-context-management/lib/pi-settings.mjsnew file mode 100644index 000000000..8b383e5a8--- /dev/null+++ b/examples/pi-experimental-context-management/lib/pi-settings.mjs@@ -0,0 +1,101 @@+/**+ * Reading pi's own `settings.json`, without importing pi.+ *+ * The only value the context-window mode needs from it is+ * `compaction.reserveTokens`: pi auto-compacts as soon as+ * `contextTokens > contextWindow - reserveTokens`, so the hard reminder has to+ * be clamped under that line or the agent's notes are never written.+ *+ * pi merges the project file over the global one (`SettingsManager`), so the+ * project value wins here as well. Everything is best effort — a missing or+ * malformed file yields the pi default (16384).+ */+import { readFileSync } from "node:fs";+import { join } from "node:path";++/** pi's own default when `compaction.reserveTokens` is unset. */+export const DEFAULT_RESERVE_TOKENS = 16384;++/**+ * `compaction.reserveTokens` of one parsed settings object, or null when the+ * object does not carry a usable value.+ */+export function reserveTokensFromSettings(settings) {+ if (!settings || typeof settings !== "object" || Array.isArray(settings)) return null;+ const compaction = settings.compaction;+ if (!compaction || typeof compaction !== "object" || Array.isArray(compaction)) return null;+ const value = Number(compaction.reserveTokens);+ if (!Number.isFinite(value) || value < 0) return null;+ return Math.floor(value);+}++/**+ * First usable `compaction.reserveTokens` across the given file contents, in+ * order (project file first), else {@link DEFAULT_RESERVE_TOKENS}.+ *+ * `contents` holds raw file text or null for "file missing"; parse errors are+ * treated as "missing" so one broken file cannot hide the other one.+ */+export function pickReserveTokens(contents) {+ for (const raw of Array.isArray(contents) ? contents : []) {+ if (typeof raw !== "string" || !raw.trim()) continue;+ let parsed;+ try {+ parsed = JSON.parse(raw);+ } catch {+ continue;+ }+ const value = reserveTokensFromSettings(parsed);+ if (value !== null) return value;+ }+ return DEFAULT_RESERVE_TOKENS;+}++/**+ * The settings files pi reads, project first.+ *+ * `agentDir` mirrors pi's `PI_CODING_AGENT_DIR` override; without it the global+ * file sits at `~/<configDir>/agent/settings.json`, the same place `getAgentDir()`+ * points at.+ */+export function settingsPaths(opts = {}) {+ const cwd = String(opts.cwd || process.cwd());+ const configDirName = String(opts.configDirName || ".pi");+ const homeDir = String(opts.homeDir || process.env.HOME || "");+ const agentDir = String(opts.agentDir || "");+ const paths = [join(cwd, configDirName, "settings.json")];+ if (agentDir) paths.push(join(agentDir, "settings.json"));+ else if (homeDir) paths.push(join(homeDir, configDirName, "agent", "settings.json"));+ return paths;+}++/**+ * `compaction.reserveTokens` from `<cwd>/<configDir>/settings.json`, else+ * `~/<configDir>/agent/settings.json`, else {@link DEFAULT_RESERVE_TOKENS}.+ *+ * `readFile` is injected so the resolution order is testable without touching+ * the real filesystem.+ */+export function readReserveTokens(opts = {}) {+ const read =+ typeof opts.readFile === "function"+ ? opts.readFile+ : (path) => {+ try {+ return readFileSync(path, "utf8");+ } catch {+ return null;+ }+ };+ const contents = [];+ for (const path of settingsPaths(opts)) {+ let raw = null;+ try {+ raw = read(path);+ } catch {+ raw = null;+ }+ contents.push(typeof raw === "string" ? raw : null);+ }+ return pickReserveTokens(contents);+}diff --git a/examples/pi-experimental-context-management/lib/text-budget.d.mts b/examples/pi-experimental-context-management/lib/text-budget.d.mtsnew file mode 100644index 000000000..fa48face7--- /dev/null+++ b/examples/pi-experimental-context-management/lib/text-budget.d.mts@@ -0,0 +1,16 @@+export const CONTEXT_BLOCK_MARKER: "<openviking-context";++export interface BudgetMessage {+ role?: string;+ content?: unknown;+ timestamp?: number;+ [key: string]: any;+}++export function flattenContent(msg: BudgetMessage): string;+export function fingerprintMessage(msg: BudgetMessage): string;+export function isUserTurnStart(msg: BudgetMessage): boolean;+export function countUserTurns(messages: BudgetMessage[]): number;+export function estimateTokens(text: string): number;+export function truncateToTokens(text: string, budget: number): string;+export function estimatePayloadTokens(payload: any): number;diff --git a/examples/pi-experimental-context-management/lib/text-budget.mjs b/examples/pi-experimental-context-management/lib/text-budget.mjsnew file mode 100644index 000000000..450b853c0--- /dev/null+++ b/examples/pi-experimental-context-management/lib/text-budget.mjs@@ -0,0 +1,107 @@+/**+ * Pure text/token helpers shared by the context-window core and the sync+ * manager. Extracted verbatim from the takeover core of+ * examples/pi-coding-agent-extension so this extension carries no takeover+ * state machine.+ */++/**+ * Every user message this extension synthesizes (recall block, window header)+ * opens with this marker, so turn counting can tell an injected message apart+ * from something the human typed.+ */+export const CONTEXT_BLOCK_MARKER = "<openviking-context";++function flattenValue(value) {+ if (typeof value === "string") return value;+ if (Array.isArray(value)) return value.map(flattenValue).filter(Boolean).join("");+ if (!value || typeof value !== "object") return "";+ if (typeof value.text === "string") return value.text;+ if (typeof value.input_text === "string") return value.input_text;+ if (typeof value.output_text === "string") return value.output_text;+ if (typeof value.content === "string") return value.content;+ if (Array.isArray(value.content)) return flattenValue(value.content);+ return "";+}++export function flattenContent(msg) {+ if (!msg || typeof msg !== "object") return "";+ return flattenValue(msg.content);+}++export function fingerprintMessage(msg) {+ const text = flattenContent(msg);+ return `${msg?.role || ""}:${text.length}:${text.slice(0, 200)}`;+}++export function isUserTurnStart(msg) {+ if (!msg || msg.role !== "user") return false;+ return !flattenContent(msg).startsWith(CONTEXT_BLOCK_MARKER);+}++export function countUserTurns(messages) {+ let count = 0;+ for (const msg of Array.isArray(messages) ? messages : []) {+ if (isUserTurnStart(msg)) count++;+ }+ return count;+}++export function estimateTokens(text) {+ const value = String(text || "");+ if (!value) return 0;+ let cjk = 0;+ let other = 0;+ for (const ch of value) {+ if (ch.codePointAt(0) >= 0x3000) cjk++;+ else other++;+ }+ return Math.ceil(cjk * 1.5 + other / 4);+}++export function truncateToTokens(text, budget) {+ const value = String(text || "");+ const limit = Math.max(0, Math.floor(Number(budget) || 0));+ if (!value || limit <= 0) return "";+ if (estimateTokens(value) <= limit) return value;++ let lo = 0;+ let hi = value.length;+ while (lo < hi) {+ const mid = Math.ceil((lo + hi) / 2);+ if (estimateTokens(value.slice(0, mid)) <= limit) lo = mid;+ else hi = mid - 1;+ }+ return value.slice(0, lo);+}++function partText(part) {+ if (!part || typeof part !== "object") return "";+ if (typeof part.text === "string") return part.text;+ if (part.type === "tool") {+ const payload = {+ name: part.tool_name,+ input: part.tool_input,+ output: part.tool_output,+ status: part.tool_status,+ };+ try {+ return JSON.stringify(payload);+ } catch {+ return String(part.tool_name || part.tool_output || "");+ }+ }+ return flattenValue(part);+}++export function estimatePayloadTokens(payload) {+ if (!payload || typeof payload !== "object") return 0;+ if (typeof payload.content === "string") return estimateTokens(payload.content);+ if (Array.isArray(payload.parts)) {+ return estimateTokens(payload.parts.map(partText).filter(Boolean).join("\n\n"));+ }+ if (Array.isArray(payload.content)) {+ return estimateTokens(payload.content.map(partText).filter(Boolean).join("\n\n"));+ }+ return 0;+}diff --git a/examples/pi-experimental-context-management/lib/uri-guard-adapter.d.mts b/examples/pi-experimental-context-management/lib/uri-guard-adapter.d.mtsnew file mode 100644index 000000000..f19a7b460--- /dev/null+++ b/examples/pi-experimental-context-management/lib/uri-guard-adapter.d.mts@@ -0,0 +1 @@+export function guardVikingUriToolCall(event: any): { block: true; reason: string } | null;diff --git a/examples/pi-experimental-context-management/lib/uri-guard-adapter.mjs b/examples/pi-experimental-context-management/lib/uri-guard-adapter.mjsnew file mode 100644index 000000000..e1bd58c36--- /dev/null+++ b/examples/pi-experimental-context-management/lib/uri-guard-adapter.mjs@@ -0,0 +1,42 @@+import { buildGuardMessage, findVikingUri, normalizeToolName } from "../shared/uri-guard.mjs";++const VIKING_URI_TOOL_HINTS = {+ read: {+ tool: "viking_read",+ example: (uri) => `viking_read(uri="${uri}", level="overview")`,+ },+ grep: {+ tool: "viking_search",+ example: (uri, input = {}) => `viking_search(query="${String(input.pattern ?? "").replaceAll('"', '\\"')}", scope="${uri}")`,+ },+ find: {+ tool: "viking_browse",+ example: (uri) => `viking_browse(action="list", uri="${uri}")`,+ },+ ls: {+ tool: "viking_browse",+ example: (uri) => `viking_browse(action="list", uri="${uri}")`,+ },+ bash: {+ tool: "viking_read or viking_search",+ example: (uri) => `viking_read(uri="${uri}", level="overview")`,+ },+};++export function guardVikingUriToolCall(event) {+ const toolName = normalizeToolName(event?.toolName ?? event?.tool_name ?? event?.name);+ const hint = VIKING_URI_TOOL_HINTS[toolName];+ if (!hint) return null;++ const input = event?.input ?? event?.args ?? event?.params ?? {};+ const uri = findVikingUri(input);+ if (!uri) return null;++ return {+ block: true,+ reason: buildGuardMessage(uri, {+ tool: hint.tool,+ example: hint.example(uri, input),+ }),+ };+}diff --git a/examples/pi-experimental-context-management/recall.ts b/examples/pi-experimental-context-management/recall.tsnew file mode 100644index 000000000..71edae3c4--- /dev/null+++ b/examples/pi-experimental-context-management/recall.ts@@ -0,0 +1,119 @@+import type { OVClient } from "./client.js";+import type { OVConfig } from "./config.js";+import { buildRecallBlock } from "./shared/recall-core.mjs";++export interface RecallCache {+ block: string | null;+ promptText: string; // the query this cache is for+}++export class RecallManager {+ private client: OVClient;+ private config: OVConfig;+ private cache: RecallCache = { block: null, promptText: "" };+ private pendingPrompt = "";+ // Read lazily: the session manager that owns this id is constructed after the+ // recall manager, and the id only exists once a session has been opened.+ private sessionId: () => string | null;++ constructor(+ client: OVClient,+ config: OVConfig,+ sessionId: () => string | null = () => null,+ ) {+ this.client = client;+ this.config = config;+ this.sessionId = sessionId;+ }++ queueSearch(userQuery: string): void {+ this.pendingPrompt = userQuery;+ }++ async searchPending(): Promise<string | null> {+ if (!this.pendingPrompt) return this.cache.block;++ const userQuery = this.pendingPrompt;+ this.pendingPrompt = "";+ if (userQuery.trim().length < this.config.minQueryLength) {+ this.cache = { block: null, promptText: userQuery };+ return null;+ }++ const block = await buildRecallBlock(+ // 10s is this extension's own budget for a bare retrieval; when the+ // request also spends a server fuse the helper hands down a longer+ // deadline, and ignoring it would abort a request still inside its fuse.+ (path: string, init?: any, options?: any) =>+ this.client.fetchJSON(path, init, options?.timeoutMs ?? 10000),+ this.config as any,+ userQuery,+ {+ actorPeerId: this.config.peerId,+ // Passing the OV session id is what turns on server-side query+ // expansion and the cross-turn dedup ledger.+ sessionId: this.sessionId() ?? "",+ },+ );+ this.cache = { block, promptText: userQuery };+ return block;+ }++ // --- Injection ---++ /**+ * Prepend this turn's recall block to the newest user message of the+ * deep-copied provider view.+ *+ * No injection ledger here: replaying historical blocks needed pi entry ids+ * from SessionManager.buildContextEntries(), which pi 0.80.3 does not+ * expose. The `<openviking-context` guard is what keeps the prefix stable —+ * an already-injected message (a recall block from an earlier copy, or a+ * frozen context-window header) is never rewritten.+ */+ injectRecall(messages: any[]): any[] {+ const block = this.cache.block;+ if (!block) return messages;++ // Locate the newest user message; everything before it is history.+ let lastUserIndex = -1;+ for (let i = messages.length - 1; i >= 0; i--) {+ if (messages[i].role === "user") {+ lastUserIndex = i;+ break;+ }+ }+ if (lastUserIndex === -1) return messages;++ const newest = messages[lastUserIndex];+ // Idempotency: never stack a second block onto an already-injected copy.+ if (textOf(newest).includes("<openviking-context")) return messages;++ prependBlock(newest, block);+ return messages;+ }++ invalidate(): void {+ this.cache = { block: null, promptText: "" };+ this.pendingPrompt = "";+ }+}++function textOf(msg: any): string {+ return typeof msg.content === "string"+ ? msg.content+ : Array.isArray(msg.content)+ ? msg.content.filter((b: any) => b.type === "text").map((b: any) => b.text).join("")+ : "";+}++function prependBlock(msg: any, block: string): void {+ if (typeof msg.content === "string") {+ msg.content = block + "\n" + msg.content;+ } else if (Array.isArray(msg.content)) {+ const textBlocks = msg.content.filter((b: any) => b.type === "text");+ if (textBlocks.length > 0) {+ (textBlocks[0] as any).text = block + "\n" + (textBlocks[0] as any).text;+ }+ }+}diff --git a/examples/pi-experimental-context-management/scripts/e2e-probe.ts b/examples/pi-experimental-context-management/scripts/e2e-probe.tsnew file mode 100644index 000000000..605fafb17--- /dev/null+++ b/examples/pi-experimental-context-management/scripts/e2e-probe.ts@@ -0,0 +1,42 @@+/**+ * Probe extension for live e2e runs.+ *+ * Loaded next to the OpenViking extension to capture the exact provider+ * payload pi sends after context hooks have run.+ */+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";+import { mkdirSync, writeFileSync } from "node:fs";+import { join } from "node:path";++export default function (pi: ExtensionAPI) {+ const outDir = process.env.OV_E2E_OUT;+ if (!outDir) return;+ mkdirSync(outDir, { recursive: true });++ const turn = process.env.OV_E2E_TURN ?? "0";+ let n = 0;++ const writeSessionId = (ctx: { sessionManager?: { getSessionId?: () => string } }) => {+ try {+ const id = ctx.sessionManager?.getSessionId?.();+ if (id) writeFileSync(join(outDir, "session-id.txt"), id);+ } catch {+ // Best effort.+ }+ };++ pi.on("session_start", async (_event, ctx) => writeSessionId(ctx));+ pi.on("before_agent_start", async (_event, ctx) => writeSessionId(ctx));++ pi.on("before_provider_request", async (event, _ctx) => {+ n++;+ try {+ writeFileSync(+ join(outDir, `payload-t${turn}-${String(n).padStart(2, "0")}.json`),+ JSON.stringify(event.payload, null, 2),+ );+ } catch {+ // Best effort.+ }+ });+}diff --git a/examples/pi-experimental-context-management/scripts/e2e-window.mjs b/examples/pi-experimental-context-management/scripts/e2e-window.mjsnew file mode 100755index 000000000..350737047--- /dev/null+++ b/examples/pi-experimental-context-management/scripts/e2e-window.mjs@@ -0,0 +1,1147 @@+#!/usr/bin/env node+/**+ * Live e2e gate for the agent-driven context window.+ *+ * Manual by design: it drives a real pi binary, a real OpenViking server and a+ * real OpenAI-compatible LLM relay, and asserts the whole reset pipeline —+ * archive to OpenViking, virtual cut of the provider payload, frozen window+ * header, cross-process restore, fail-closed refusal.+ *+ * Scenario (plan "端到端"):+ * T1 `pi -p` remember ZEPHYR-9942 + the deploy window, padded with PAD1.+ * T2 `pi -c` instruct the model to call new_context alone with a fixed+ * reason and notes carrying the codename and the next step,+ * then reply READY in the new window.+ * T3 `pi -c` ask for the codename (a fresh process, so the window state+ * has to survive in the session file).+ *+ * Required env:+ * OPENVIKING_URL+ * OPENVIKING_API_KEY+ * E2E_LLM_API_KEY LLM provider API key (never written to disk)+ *+ * Optional env:+ * PI_BIN path to the pi binary; defaults to `which pi`+ * E2E_LLM_BASE_URL base URL of an OpenAI- or Anthropic-compatible+ * endpoint; required, no default, so a private relay+ * never ends up hardcoded here+ * E2E_LLM_MODEL model id served by that endpoint; required+ * E2E_LLM_API pi provider api type; default openai-completions+ * E2E_LLM_REASONING thinking level for the model: off (default),+ * minimal, low, medium, high or xhigh. Anything but+ * off marks the model as reasoning-capable and sets+ * pi's defaultThinkingLevel, so an OpenAI-compatible+ * relay receives reasoning_effort.+ * E2E_KEEP_TMP=1 keep the temp workspaces even on success+ * E2E_KEEP_OV_SESSION=1 do not delete the OpenViking sessions afterwards,+ * so the archives stay readable on the server (for+ * demos; the sessions are yours to clean up)+ * E2E_WINDOW_LONG=1 run ONLY the long-context scenario: the agent+ * inventories a real code tree until context+ * pressure makes it reset on its own, with no+ * instruction to call the tool. `=both` adds it to+ * the other scenarios. Slow (10-20 min) and it+ * depends on model judgement, so the judgement+ * checks warn rather than fail.+ * E2E_WINDOW_FAILCLOSED=1 run ONLY the fail-closed variant: OPENVIKING_URL+ * is pointed at a closed port and the gate asserts+ * that nothing was cut. `=both` runs both scenarios.+ *+ * Exit codes: 0 all checks passed, 1 a check failed, 2 bad environment.+ */+import { spawnSync } from "node:child_process";+import {+ copyFileSync,+ cpSync,+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ statSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { basename, dirname, join } from "node:path";+import { fileURLToPath } from "node:url";++// The gate asserts on the extension's own markers, so it imports them instead+// of copying the strings: a rename in the core has to break the gate loudly.+import {+ HANDOFF_MARKER,+ STATUS_CUSTOM_TYPE,+ WINDOW_ENTRY_TYPE,+ WINDOW_HEADER_OPEN,+} from "../lib/context-window-core.mjs";++const EXT_SRC = dirname(dirname(fileURLToPath(import.meta.url)));++const OV_URL = process.env.OPENVIKING_URL;+const OV_KEY = process.env.OPENVIKING_API_KEY;+const LLM_KEY = process.env.E2E_LLM_API_KEY;+const LLM_BASE = process.env.E2E_LLM_BASE_URL;+const LLM_MODEL = process.env.E2E_LLM_MODEL;+const LLM_API = process.env.E2E_LLM_API ?? "openai-completions";+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];+const LLM_REASONING = (process.env.E2E_LLM_REASONING ?? "off").trim() || "off";+const KEEP_OV_SESSION = (process.env.E2E_KEEP_OV_SESSION ?? "") === "1";+const FAILCLOSED_MODE = (process.env.E2E_WINDOW_FAILCLOSED ?? "").trim();+const LONG_MODE = (process.env.E2E_WINDOW_LONG ?? "").trim();+const RUN_FAILCLOSED = FAILCLOSED_MODE === "1" || FAILCLOSED_MODE === "both";+const RUN_LONG = LONG_MODE === "1" || LONG_MODE === "both";+const RUN_MAIN = FAILCLOSED_MODE !== "1" && LONG_MODE !== "1";+/** Context share the long scenario must reach before the agent resets. */+const LONG_MIN_PERCENT = Number(process.env.E2E_WINDOW_LONG_MIN_PERCENT ?? 40);+/** Where the soft reminder fires: high enough that the run is a real workload. */+const LONG_SOFT_PERCENT = Number(process.env.E2E_WINDOW_LONG_SOFT_PERCENT ?? 45);+/** What models.json tells pi the window is; used to turn payload size into a share. */+const LONG_CONTEXT_WINDOW = 128000;++/** A port nothing listens on: the fail-closed variant's "OpenViking is down". */+const DEAD_OV_URL = "http://127.0.0.1:9";++const PROVIDER_ID = "e2e-relay";+const RESET_TOOL = "new_context";+const CODENAME = "ZEPHYR-9942";+const DEPLOY_WINDOW = "Friday 03:00 UTC";+const RELEASE_FILE = "release.md";+/** Only present in release.md, so answering with it proves the file was read. */+const RELEASE_OWNER = "dana-okonkwo";+const RESET_REASON = "phase one complete, starting phase two";+/** The part of the reason we require verbatim in the archive and the entry. */+const REASON_MARKER = "phase one complete";+const NEXT_STEP_MARKER = "rollout checklist";+const PAD1 = `PADDING-T1 ${"lorem ipsum dolor sit amet consectetur ".repeat(60)}`;++// ============================================================================+// Environment validation (runs before anything is created, so a bad env is a+// clean exit 2 and the script stays dry-runnable).+// ============================================================================++function which(cmd) {+ const res = spawnSync("which", [cmd], { encoding: "utf8" });+ return res.status === 0 ? res.stdout.trim() : "";+}++const PI_BIN = process.env.PI_BIN || which("pi");++for (const [key, value] of [+ ["OPENVIKING_URL", OV_URL],+ ["OPENVIKING_API_KEY", OV_KEY],+ ["E2E_LLM_API_KEY", LLM_KEY],+ ["E2E_LLM_BASE_URL", LLM_BASE],+ ["E2E_LLM_MODEL", LLM_MODEL],+ ["PI_BIN or pi on PATH", PI_BIN],+]) {+ if (!value) {+ console.error(`e2e-window: missing required ${key}`);+ process.exit(2);+ }+}+if (!existsSync(PI_BIN)) {+ console.error(`e2e-window: pi binary not found: ${PI_BIN}`);+ process.exit(2);+}+if (!THINKING_LEVELS.includes(LLM_REASONING)) {+ console.error(+ `e2e-window: E2E_LLM_REASONING must be one of ${THINKING_LEVELS.join(", ")}, got "${LLM_REASONING}"`,+ );+ process.exit(2);+}+if (LONG_MODE && !["1", "both"].includes(LONG_MODE)) {+ console.error(`e2e-window: E2E_WINDOW_LONG must be "1" or "both", got "${LONG_MODE}"`);+ process.exit(2);+}+if (FAILCLOSED_MODE && !["1", "both"].includes(FAILCLOSED_MODE)) {+ console.error(`e2e-window: E2E_WINDOW_FAILCLOSED must be "1" or "both", got "${FAILCLOSED_MODE}"`);+ process.exit(2);+}++// ============================================================================+// Reporting+// ============================================================================++let failures = 0;+let warnings = 0;+const pass = (msg) => console.log(` PASS ${msg}`);+const fail = (msg) => {+ failures++;+ console.error(` FAIL ${msg}`);+};+const warn = (msg) => {+ warnings++;+ console.log(` WARN ${msg}`);+};+const check = (cond, msg) => (cond ? pass(msg) : fail(msg));+const section = (title) => console.log(`\ne2e-window: --- ${title} ---`);++// ============================================================================+// Workspace+// ============================================================================++/**+ * A private pi installation: its own agent dir (models.json + settings.json),+ * its own copy of the extension, its own session dir and project cwd. Nothing+ * touches the user's ~/.pi.+ */+function makeWorkspace(label, { windowConfig = {}, seedSourceTree = false } = {}) {+ const root = mkdtempSync(join(tmpdir(), `ov-pi-window-${label}-`));+ const ws = {+ label,+ root,+ agentDir: join(root, "agent"),+ // Deliberately outside the agent dir: pi is told to load it with `-e`, and+ // a copy under <agentDir>/extensions could be picked up a second time.+ extDir: join(root, "ext"),+ outDir: join(root, "out"),+ projDir: join(root, "proj"),+ sessionDir: join(root, "sessions"),+ };+ for (const dir of [ws.agentDir, ws.extDir, ws.outDir, ws.projDir, ws.sessionDir]) {+ mkdirSync(dir, { recursive: true });+ }++ writeFileSync(+ join(ws.agentDir, "models.json"),+ JSON.stringify(+ {+ providers: {+ [PROVIDER_ID]: {+ name: "OpenViking e2e relay",+ baseUrl: LLM_BASE,+ api: LLM_API,+ apiKey: "$E2E_LLM_API_KEY",+ ...(LLM_API === "openai-completions"+ ? { authHeader: true, headers: { "x-session-id": "ov-pi-e2e-window" } }+ : {}),+ models: [+ {+ id: LLM_MODEL,+ name: "OpenViking e2e model",+ reasoning: LLM_REASONING !== "off",+ // A custom relay is not recognised by pi-ai's URL-based+ // auto-detection, so reasoning_effort has to be enabled here.+ ...(LLM_REASONING !== "off" && LLM_API === "openai-completions"+ ? { compat: { supportsReasoningEffort: true, thinkingFormat: "openai" } }+ : {}),+ input: ["text"],+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },+ contextWindow: 128000,+ maxTokens: 8192,+ },+ ],+ },+ },+ },+ null,+ 2,+ ),+ );+ writeFileSync(+ join(ws.agentDir, "settings.json"),+ JSON.stringify(+ {+ defaultProjectTrust: "always",+ ...(LLM_REASONING !== "off" ? { defaultThinkingLevel: LLM_REASONING } : {}),+ },+ null,+ 2,+ ),+ );++ // The extension itself: sources plus lib/shared/scripts, with a config that+ // is generous about the archive deadline (phase 2 takes 25-55s on the target+ // server) and eager about the reminders, so a short gate still exercises the+ // thresholds.+ for (const name of readdirSync(EXT_SRC)) {+ if (name === "config.json") continue;+ const src = join(EXT_SRC, name);+ const dst = join(ws.extDir, basename(name));+ if (name.endsWith(".ts") || name === "README.md") {+ copyFileSync(src, dst);+ } else if (["lib", "shared", "scripts"].includes(name)) {+ cpSync(src, dst, { recursive: true });+ }+ }+ writeFileSync(+ join(ws.extDir, "config.json"),+ JSON.stringify(+ {+ enabled: true,+ syncTurns: true,+ logLevel: "info",+ contextWindow: {+ resetDeadlineMs: 120000,+ archivePollMs: 3000,+ softPercent: 60,+ hardPercent: 75,+ statusEveryTurn: true,+ ...windowConfig,+ },+ },+ null,+ 2,+ ),+ );++ // The long scenario needs enough real material that reading it through does+ // not fit in one window. The extension's own sources are the closest thing to+ // hand: about 60k tokens of TypeScript and ESM, already in the repo.+ if (seedSourceTree) {+ const srcDir = join(ws.projDir, "src");+ mkdirSync(srcDir, { recursive: true });+ let bytes = 0;+ for (const name of readdirSync(EXT_SRC)) {+ const from = join(EXT_SRC, name);+ if (name.endsWith(".ts")) {+ copyFileSync(from, join(srcDir, name));+ bytes += statSync(from).size;+ } else if (name === "lib" || name === "tests") {+ for (const child of readdirSync(from)) {+ if (!child.endsWith(".mjs")) continue;+ copyFileSync(join(from, child), join(srcDir, child));+ bytes += statSync(join(from, child)).size;+ }+ }+ }+ const files = readdirSync(srcDir).sort();+ writeFileSync(+ join(ws.projDir, "TASK.md"),+ [+ "# Source inventory task",+ "",+ `There are ${files.length} files under src/ (~${Math.round(bytes / 1024)} KB).`,+ "Work through them in alphabetical order:",+ "",+ ...files.map((f) => `- [ ] src/${f}`),+ "",+ ].join("\n"),+ );+ console.log(+ `e2e-window: [${label}] seeded ${files.length} source files, ` ++ `${Math.round(bytes / 1024)} KB (~${Math.round(bytes / 4000)}k tokens if fully read)`,+ );+ }++ // A file for T1 to read: the gate asserts that tool OUTPUT reaches the+ // archive, so the first turn must produce a tool result rather than relying+ // on the model deciding to use a tool on its own.+ writeFileSync(+ join(ws.projDir, RELEASE_FILE),+ [+ "# Release checklist",+ "",+ `- codename: ${CODENAME}`,+ `- deploy window: ${DEPLOY_WINDOW}`,+ `- owner: ${RELEASE_OWNER}`,+ "- status: phase one in progress",+ "",+ ].join("\n"),+ );++ console.log(`e2e-window: [${label}] workspace ${root}`);+ return ws;+}++/** Run one pi turn in a workspace and capture stdout/stderr. */+function runTurn(ws, turn, prompt, { continueSession = false, ovUrl = OV_URL, timeoutMs = 600_000 } = {}) {+ console.log(`\ne2e-window: [${ws.label}] --- turn ${turn} ---`);+ const args = [+ "--provider", PROVIDER_ID,+ "--model", LLM_MODEL,+ "--mode", "text",+ "-p",+ "-ne",+ "-e", join(ws.extDir, "index.ts"),+ "-e", join(ws.extDir, "scripts", "e2e-probe.ts"),+ "--approve",+ "--no-context-files",+ "--no-skills",+ "--no-prompt-templates",+ "--session-dir", ws.sessionDir,+ "--offline",+ ...(continueSession ? ["-c"] : []),+ prompt,+ ];+ const res = spawnSync(PI_BIN, args, {+ cwd: ws.projDir,+ env: {+ ...process.env,+ PI_CODING_AGENT_DIR: ws.agentDir,+ OPENVIKING_URL: ovUrl,+ OPENVIKING_API_KEY: OV_KEY,+ E2E_LLM_API_KEY: LLM_KEY,+ OV_E2E_OUT: ws.outDir,+ OV_E2E_TURN: String(turn),+ OPENVIKING_DEBUG_LOG: join(ws.outDir, "ov-pi.log"),+ },+ timeout: timeoutMs,+ encoding: "utf8",+ });+ const out = `${res.stdout ?? ""}`;+ const err = `${res.stderr ?? ""}`;+ if (res.status !== 0) {+ fail(+ `[${ws.label}] turn ${turn}: pi exited ${res.status}\n` ++ `stdout:\n${out.slice(-2000)}\nstderr:\n${err.slice(-2000)}`,+ );+ } else {+ console.log(out.trim().slice(-800));+ }+ return { out, err, status: res.status, transcript: `${out}\n${err}` };+}++// ============================================================================+// OpenViking HTTP+// ============================================================================++async function ovFetch(path, init, baseUrl = OV_URL) {+ try {+ const resp = await fetch(`${baseUrl}${path}`, {+ ...init,+ headers: {+ Authorization: `Bearer ${OV_KEY}`,+ "Content-Type": "application/json",+ ...(init?.headers ?? {}),+ },+ });+ const body = await resp.json().catch(() => ({}));+ return { ok: resp.ok && body?.status !== "error", status: resp.status, body };+ } catch (error) {+ return { ok: false, status: 0, body: {}, error: String(error?.message ?? error) };+ }+}++const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));++/** `viking://…/sessions/<sid>` — canonical root, legacy alias as the fallback. */+async function sessionRootUri(ovSessionId) {+ const res = await ovFetch(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}`);+ const uri = typeof res.body?.result?.uri === "string" ? res.body.result.uri.trim() : "";+ if (uri.startsWith("viking://")) return uri.replace(/\/+$/, "");+ return `viking://session/${ovSessionId}`;+}++/** Archive directories under `<root>/history`, newest first. */+async function listArchives(rootUri) {+ const res = await ovFetch(+ `/api/v1/fs/ls?uri=${encodeURIComponent(`${rootUri}/history`)}&sort_by=name&sort_order=desc`,+ );+ const rows = Array.isArray(res.body?.result) ? res.body.result : [];+ const archives = [];+ for (const row of rows) {+ const uri = String(row?.uri ?? "").replace(/\/+$/, "");+ const id = uri.split("/").pop() || String(row?.name ?? "");+ if (!/^archive_\d+$/.test(id)) continue;+ archives.push({ archiveId: id, uri: uri || `${rootUri}/history/${id}` });+ }+ archives.sort((a, b) => Number(b.archiveId.slice(8)) - Number(a.archiveId.slice(8)));+ return archives;+}++/** `GET /content/read?uri=<archive>/<file>` — raw text, plus the HTTP status. */+async function readArchiveFile(archiveUri, file) {+ const res = await ovFetch(+ `/api/v1/content/read?uri=${encodeURIComponent(`${archiveUri}/${file}`)}`,+ );+ return { status: res.status, ok: res.ok, text: typeof res.body?.result === "string" ? res.body.result : "" };+}++/** Poll `.overview.md` until phase 2 has written it (25-55s on the target server). */+async function waitForOverview(archiveUri, budgetMs = 150_000) {+ const startedAt = Date.now();+ let last = { status: 0, ok: false, text: "" };+ while (Date.now() - startedAt < budgetMs) {+ last = await readArchiveFile(archiveUri, ".overview.md");+ if (last.status === 200 && last.text.trim()) break;+ await sleep(5000);+ }+ return { ...last, waitedMs: Date.now() - startedAt };+}++// ============================================================================+// Provider payload helpers+// ============================================================================++function payloadsFor(ws, turn) {+ return readdirSync(ws.outDir)+ .filter((f) => f.startsWith(`payload-t${turn}-`) && f.endsWith(".json"))+ .sort()+ .map((f) => {+ const raw = readFileSync(join(ws.outDir, f), "utf8");+ let payload = null;+ try {+ payload = JSON.parse(raw);+ } catch {+ payload = null;+ }+ return { file: f, raw, payload };+ });+}++const asArray = (value) => (Array.isArray(value) ? value : []);+const contentBlocks = (msg) => (Array.isArray(msg?.content) ? msg.content : []);++/** Text of a message under either provider shape. */+function messageText(msg) {+ if (typeof msg?.content === "string") return msg.content;+ return contentBlocks(msg)+ .filter((b) => b && (b.type === "text" || b.type === "input_text") && typeof b.text === "string")+ .map((b) => b.text)+ .join("\n");+}++function messagesOf(entry) {+ return asArray(entry?.payload?.messages);+}++/** The first message the model actually reads (system/developer are framing). */+function firstNonSystem(messages) {+ return messages.find((m) => m?.role !== "system" && m?.role !== "developer") ?? null;+}++/** `{id, name}` for every tool call in a message, both provider shapes. */+function toolCallsOf(msg) {+ const calls = [];+ for (const call of asArray(msg?.tool_calls)) {+ calls.push({ id: String(call?.id ?? ""), name: String(call?.function?.name ?? call?.name ?? "") });+ }+ for (const block of contentBlocks(msg)) {+ if (block?.type === "tool_use") calls.push({ id: String(block?.id ?? ""), name: String(block?.name ?? "") });+ }+ return calls;+}++/** `{id}` for every tool result in a message, both provider shapes. */+function toolResultsOf(msg) {+ const results = [];+ // openai-completions: a dedicated {role:"tool", tool_call_id} message.+ if (msg?.role === "tool") results.push({ id: String(msg?.tool_call_id ?? "") });+ // anthropic-messages: tool_result blocks carried on a user message.+ for (const block of contentBlocks(msg)) {+ if (block?.type === "tool_result") results.push({ id: String(block?.tool_use_id ?? "") });+ }+ return results;+}++/**+ * Orphan detection for both wire shapes.+ *+ * A tool result whose call was cut away — or a call whose result was cut away —+ * is rejected outright by the provider, and it is exactly what a sloppy cut+ * produces, so it is the single most important structural assertion here.+ */+function assertNoOrphanToolResults(messages, label) {+ const issued = new Set();+ const answered = new Set();+ const orphanResults = [];+ for (const msg of messages) {+ for (const call of toolCallsOf(msg)) {+ if (call.id) issued.add(call.id);+ }+ for (const result of toolResultsOf(msg)) {+ if (!result.id || !issued.has(result.id)) {+ orphanResults.push(result.id || "(missing id)");+ } else {+ answered.add(result.id);+ }+ }+ }+ const danglingCalls = [...issued].filter((id) => !answered.has(id));++ check(+ orphanResults.length === 0,+ `${label}: no orphan tool results${orphanResults.length ? ` (orphans: ${orphanResults.join(", ")})` : ""}`,+ );+ check(+ danglingCalls.length === 0,+ `${label}: no tool calls left without a result${danglingCalls.length ? ` (dangling: ${danglingCalls.join(", ")})` : ""}`,+ );+ return { orphanResults, danglingCalls };+}++/** Does any non-system message call `new_context` (or answer such a call)? */+function mentionsResetToolCall(messages) {+ const resetIds = new Set();+ let found = false;+ for (const msg of messages) {+ for (const call of toolCallsOf(msg)) {+ if (call.name === RESET_TOOL) {+ found = true;+ if (call.id) resetIds.add(call.id);+ }+ }+ for (const result of toolResultsOf(msg)) {+ if (result.id && resetIds.has(result.id)) found = true;+ }+ }+ return found;+}++function lastAssistant(messages) {+ for (let i = messages.length - 1; i >= 0; i--) {+ if (messages[i]?.role === "assistant") return messages[i];+ }+ return null;+}++// ============================================================================+// Session file helpers+// ============================================================================++function readSessionEntries(ws) {+ const files = readdirSync(ws.sessionDir)+ .filter((f) => f.endsWith(".jsonl"))+ .sort();+ if (files.length === 0) return { file: "", entries: [] };+ const file = join(ws.sessionDir, files[files.length - 1]);+ const entries = [];+ for (const line of readFileSync(file, "utf8").split("\n")) {+ const trimmed = line.trim();+ if (!trimmed) continue;+ try {+ entries.push(JSON.parse(trimmed));+ } catch {+ // A partially flushed tail must not lose the entries before it.+ }+ }+ return { file, entries };+}++// ============================================================================+// Prompts+// ============================================================================++const T1_PROMPT =+ `Read the file ${RELEASE_FILE} in the working directory with the read tool, then tell me who owns ` ++ `the release. Also remember for the rest of this session: the release codename is ${CODENAME}, ` ++ `and the deploy window is ${DEPLOY_WINDOW}. Keep the answer to one short sentence. ${PAD1}`;++const T2_PROMPT =+ "Phase one is complete. Do exactly this, nothing else. " ++ `Make a single tool call to ${RESET_TOOL}, alone in its own turn, with no other tool call beside it. ` ++ `Use reason exactly: "${RESET_REASON}". ` ++ `In notes, state the release codename ${CODENAME}, the deploy window ${DEPLOY_WINDOW}, ` ++ `and that the next step is to write the phase two ${NEXT_STEP_MARKER}. ` ++ "After the new context window opens, reply with exactly: READY";++const T3_PROMPT = "What is the release codename I gave you earlier? Answer with just the codename.";++/**+ * The long scenario never mentions the context tools: the point is that the+ * agent reaches for them on its own once the window fills up. The work is+ * deliberately bigger than one window, and the running file means progress is+ * visible even across a reset.+ */+const LONG_T1_PROMPT =+ "Read TASK.md, then work through every file it lists, in order. For each file: read it with the " ++ "read tool, and append one entry to INVENTORY.md with the file name, what it is responsible for, " ++ "its main exports, and anything that looks risky. Tick the file off in TASK.md as you go. " ++ "Append after each file rather than holding everything until the end, and keep going until every " ++ "file is covered. Do not summarise the files you have not read yet.";++const LONG_T2_PROMPT =+ "Continue the inventory exactly where you left off: read TASK.md and INVENTORY.md first to see " ++ "what is already done, then carry on until every file is ticked off.";++const LONG_T3_PROMPT =+ "In the very first file you inventoried, what did you write down as its main responsibility, and " ++ "what was the first thing that file imports? Answer in two short lines.";++// ============================================================================+// Scenario: the main gate+// ============================================================================++async function runMainScenario() {+ const ws = makeWorkspace("main");+ const t1 = runTurn(ws, 1, T1_PROMPT);+ const t2 = runTurn(ws, 2, T2_PROMPT, { continueSession: true });+ const t3 = runTurn(ws, 3, T3_PROMPT, { continueSession: true });++ section("pi runs");+ check(+ t1.status === 0 && t2.status === 0 && t3.status === 0,+ `all three pi runs exited 0 (got ${t1.status}/${t2.status}/${t3.status})`,+ );++ // ---- T2 payloads: the cut ------------------------------------------------+ section("T2 provider payloads");+ const p2 = payloadsFor(ws, 2);+ check(p2.length >= 2, `T2 produced >=2 provider payloads (got ${p2.length})`);++ const postIndex = p2.findIndex((entry) => {+ const first = firstNonSystem(messagesOf(entry));+ return first?.role === "user" && messageText(first).startsWith(WINDOW_HEADER_OPEN);+ });+ check(postIndex >= 0, "T2 has a post-cut payload that starts with the window header");++ if (postIndex > 0) {+ const pre = p2[postIndex - 1];+ const post = p2[postIndex];+ const preMessages = messagesOf(pre);+ const postMessages = messagesOf(post);+ const header = messageText(firstNonSystem(postMessages));++ const preCall = lastAssistant(preMessages);+ if (preCall && toolCallsOf(preCall).some((c) => c.name === RESET_TOOL)) {+ pass(`pre-cut payload (${pre.file}) ends with an assistant ${RESET_TOOL} tool call`);+ } else {+ // The happy path is one sampling per turn: the model emits the+ // new_context call as its very first response, so the request that+ // elicited it cannot contain it yet. That is correct behaviour, not a+ // regression — but the pre-cut payload must still be the *old* window.+ warn(+ `pre-cut payload (${pre.file}) has no assistant ${RESET_TOOL} call: the model called it on ` ++ "its first sampling of the turn, so no captured request contains the call",+ );+ check(pre.raw.includes(PAD1), "pre-cut payload is the uncut window (still carries PAD1)");+ check(+ !messageText(firstNonSystem(preMessages)).startsWith(WINDOW_HEADER_OPEN),+ "pre-cut payload does not already start with a window header",+ );+ }++ check(header.includes('id="w2"'), 'window header is the second window (id="w2")');+ check(header.includes(CODENAME), `window header carries the codename ${CODENAME} from the notes`);+ check(!post.raw.includes(PAD1), "post-cut payload no longer contains the T1 padding");+ check(+ postMessages.length < preMessages.length,+ `post-cut payload has fewer messages (${postMessages.length} < ${preMessages.length})`,+ );+ assertNoOrphanToolResults(preMessages, "pre-cut payload");+ assertNoOrphanToolResults(postMessages, "post-cut payload");+ check(+ !mentionsResetToolCall(postMessages),+ `post-cut payload contains neither the ${RESET_TOOL} call nor its result`,+ );+ } else if (postIndex === 0) {+ fail("the very first T2 payload already carries the window header; no cut was observed in T2");+ }++ // ---- T3 payloads: the window survived the process boundary ---------------+ section("T3 provider payloads");+ const p3 = payloadsFor(ws, 3);+ check(p3.length > 0, `T3 produced a provider payload (got ${p3.length})`);+ if (p3.length > 0) {+ const last = p3[p3.length - 1];+ const first = firstNonSystem(messagesOf(last));+ check(+ first?.role === "user" && messageText(first).startsWith(WINDOW_HEADER_OPEN),+ "T3 payload still starts with the frozen window header (restored in a new process)",+ );+ check(!last.raw.includes(PAD1), "T3 payload still does not contain the T1 padding");+ }++ if (t3.out.includes(CODENAME)) pass(`T3 answer contains ${CODENAME}`);+ else warn(`T3 answer did not contain ${CODENAME}; inspect the window header and Working Memory`);++ // ---- Session file: window entry + status line ----------------------------+ section("pi session file");+ const { file: sessionFile, entries } = readSessionEntries(ws);+ check(Boolean(sessionFile), `session JSONL found (${sessionFile || "none"})`);+ const windowEntries = entries.filter(+ (e) => e?.type === "custom" && e?.customType === WINDOW_ENTRY_TYPE && e?.data,+ );+ const armedEntries = windowEntries.filter((e) => String(e.data?.archiveId ?? ""));+ const distinctWindows = new Set(armedEntries.map((e) => `${e.data.windowIndex}:${e.data.archiveId}`));+ check(+ distinctWindows.size === 1,+ `exactly one ${WINDOW_ENTRY_TYPE} window recorded (distinct windows: ${distinctWindows.size}, ` ++ `raw entries: ${windowEntries.length})`,+ );+ if (windowEntries.length > armedEntries.length + 1 || armedEntries.length > 1) {+ // Every persist() that sees a changed watermark writes another entry; only+ // a *second window* is a defect.+ warn(+ `${windowEntries.length} ${WINDOW_ENTRY_TYPE} entries in the session file ` ++ `(${armedEntries.length} armed): re-persists of the same window are expected`,+ );+ }+ const windowState = armedEntries.length > 0 ? armedEntries[armedEntries.length - 1].data : null;+ check(+ Boolean(windowState) && String(windowState.reason ?? "").includes(REASON_MARKER),+ `window entry records the reason (got "${String(windowState?.reason ?? "").slice(0, 80)}")`,+ );+ check(+ Boolean(windowState) && /^archive_\d+$/.test(String(windowState.archiveId ?? "")),+ `window entry records an archive id (got "${windowState?.archiveId ?? ""}")`,+ );+ const statusEntries = entries.filter(+ (e) =>+ (e?.type === "custom_message" || e?.type === "custom") && e?.customType === STATUS_CUSTOM_TYPE,+ );+ check(statusEntries.length >= 1, `session file has >=1 ${STATUS_CUSTOM_TYPE} message (got ${statusEntries.length})`);++ // ---- Debug log -----------------------------------------------------------+ section("debug log");+ const logPath = join(ws.outDir, "ov-pi.log");+ if (existsSync(logPath)) {+ const log = readFileSync(logPath, "utf8");+ check(log.includes("context-window: opened w2"), 'debug log records "context-window: opened w2"');+ } else {+ fail(`no debug log at ${logPath}`);+ }++ // ---- OpenViking ----------------------------------------------------------+ section("OpenViking archive");+ const sessionIdFile = join(ws.outDir, "session-id.txt");+ let ovSessionId = null;+ if (!existsSync(sessionIdFile)) {+ fail("probe did not record a pi session id");+ } else {+ ovSessionId = `pi-${readFileSync(sessionIdFile, "utf8").trim()}`;+ const rootUri = await sessionRootUri(ovSessionId);+ console.log(`e2e-window: OV session ${ovSessionId} root ${rootUri}`);++ const archives = await listArchives(rootUri);+ check(archives.length >= 1, `session has >=1 archive under <root>/history (got ${archives.length})`);++ if (archives.length > 0) {+ const archive = archives[0];+ if (windowState?.archiveId) {+ check(+ archive.archiveId === windowState.archiveId,+ `newest archive matches the window entry (${archive.archiveId} vs ${windowState.archiveId})`,+ );+ }++ const overview = await waitForOverview(archive.uri);+ check(+ overview.status === 200 && overview.text.trim().length > 0,+ `GET content/read ${archive.archiveId}/.overview.md is 200 with a body ` ++ `(status ${overview.status}, waited ${overview.waitedMs}ms)`,+ );++ const messages = await readArchiveFile(archive.uri, "messages.jsonl");+ check(messages.status === 200 && messages.text.length > 0, `${archive.archiveId}/messages.jsonl is readable`);+ check(messages.text.includes(HANDOFF_MARKER), `messages.jsonl contains "${HANDOFF_MARKER}"`);+ check(messages.text.includes(REASON_MARKER), `messages.jsonl contains the reason "${REASON_MARKER}"`);+ check(messages.text.includes("[tool-result"), 'messages.jsonl contains a "[tool-result" entry (tool output reached the archive)');++ const grep = await ovFetch("/api/v1/search/grep", {+ method: "POST",+ body: JSON.stringify({+ uri: `${rootUri}/history`,+ pattern: "ZEPHYR",+ case_insensitive: true,+ }),+ });+ const matches = asArray(grep.body?.result?.matches);+ check(matches.length >= 1, `grep "ZEPHYR" over <root>/history has >=1 match (got ${matches.length})`);+ }++ if (KEEP_OV_SESSION) {+ console.log(+ `e2e-window: keeping OV session ${ovSessionId} (E2E_KEEP_OV_SESSION=1); ` ++ `archives stay under <session root>/history — delete it yourself when done`,+ );+ } else {+ const del = await ovFetch(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}`, { method: "DELETE" });+ console.log(+ `e2e-window: cleanup OV session ${ovSessionId}: ${del.ok ? "deleted" : "FAILED; delete it manually"}`,+ );+ }+ }++ return ws;+}++// ============================================================================+// Scenario: fail-closed+// ============================================================================++/**+ * Highest context share the extension's own status line reported, and the+ * biggest provider request seen. Both are evidence that the window really did+ * fill up before the agent reset it.+ */+function contextPressureSeen(ws, entries) {+ let peakPercent = 0;+ let peakTokens = "";+ for (const entry of entries) {+ if (entry?.customType !== STATUS_CUSTOM_TYPE) continue;+ const text = typeof entry.content === "string" ? entry.content : "";+ const match = text.match(/~([\d.]+k?)\/(\S+)\s+tokens\s+\((\d+)%\)/);+ if (!match) continue;+ const percent = Number(match[3]);+ if (percent > peakPercent) {+ peakPercent = percent;+ peakTokens = `${match[1]}/${match[2]}`;+ }+ }+ let peakBytes = 0;+ let peakPayload = "";+ for (const turn of [1, 2, 3]) {+ for (const entry of payloadsFor(ws, turn)) {+ const bytes = messagesOf(entry).reduce((sum, m) => sum + JSON.stringify(m).length, 0);+ if (bytes > peakBytes) {+ peakBytes = bytes;+ peakPayload = entry.file;+ }+ }+ }+ // chars/4 is the same estimate the extension itself uses for non-CJK text.+ const peakEstimatedTokens = Math.round(peakBytes / 4);+ const peakEstimatedPercent = Math.round((peakEstimatedTokens / LONG_CONTEXT_WINDOW) * 100);+ return {+ peakPercent,+ peakTokens,+ peakBytes,+ peakPayload,+ peakEstimatedTokens,+ peakEstimatedPercent,+ };+}++/**+ * The OpenViking side of a scenario that does not control when the reset+ * happens: assert the archive exists and carries the handoff, without assuming+ * a particular reason string.+ */+async function checkOpenVikingSide(ws, { requireHandoff }) {+ section("long: OpenViking archive");+ const sessionIdFile = join(ws.outDir, "session-id.txt");+ if (!existsSync(sessionIdFile)) {+ fail("probe did not record a pi session id");+ return;+ }+ const ovSessionId = `pi-${readFileSync(sessionIdFile, "utf8").trim()}`;+ const rootUri = await sessionRootUri(ovSessionId);+ console.log(`e2e-window: OV session ${ovSessionId} root ${rootUri}`);++ const archives = await listArchives(rootUri);+ if (!requireHandoff && archives.length === 0) {+ warn("no archive: the agent never reset, so nothing was committed");+ } else {+ check(archives.length >= 1, `session has >=1 archive under <root>/history (got ${archives.length})`);+ }++ if (archives.length > 0) {+ const newest = archives[0];+ const overview = await waitForOverview(newest.uri);+ check(+ overview.status === 200 && overview.text.trim().length > 0,+ `${newest.archiveId}/.overview.md is readable, Working Memory generated ` ++ `(status ${overview.status}, waited ${overview.waitedMs}ms)`,+ );+ const messages = await readArchiveFile(newest.uri, "messages.jsonl");+ check(+ messages.status === 200 && messages.text.length > 0,+ `${newest.archiveId}/messages.jsonl is readable`,+ );+ if (messages.text) {+ check(messages.text.includes(HANDOFF_MARKER), `messages.jsonl contains "${HANDOFF_MARKER}"`);+ check(+ messages.text.includes("[tool-result"),+ 'messages.jsonl contains a "[tool-result" entry (tool output reached the archive)',+ );+ }+ }++ if (KEEP_OV_SESSION) {+ console.log(+ `e2e-window: keeping OV session ${ovSessionId} (E2E_KEEP_OV_SESSION=1); ` ++ "delete it yourself when done",+ );+ } else {+ const del = await ovFetch(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}`, { method: "DELETE" });+ console.log(+ `e2e-window: cleanup OV session ${ovSessionId}: ${del.ok ? "deleted" : "FAILED; delete it manually"}`,+ );+ }+}++// ============================================================================+// Scenario: long context, the agent resets under pressure on its own+// ============================================================================++async function runLongScenario() {+ const ws = makeWorkspace("long", {+ seedSourceTree: true,+ // Soft reminder well before pi's own compaction line, so the agent has room+ // to finish the file it is on, write notes and reset deliberately.+ windowConfig: { softPercent: LONG_SOFT_PERCENT, hardPercent: 70 },+ });+ // Reading 400 KB of source with reasoning on is slow: a turn that gets killed+ // mid-inventory looks like a product failure in the transcript when it is+ // only the harness giving up.+ const turnTimeoutMs = Number(process.env.E2E_WINDOW_LONG_TURN_TIMEOUT_MS ?? 1_500_000);+ const t1 = runTurn(ws, 1, LONG_T1_PROMPT, { timeoutMs: turnTimeoutMs });+ const t2 = runTurn(ws, 2, LONG_T2_PROMPT, { continueSession: true, timeoutMs: turnTimeoutMs });+ const t3 = runTurn(ws, 3, LONG_T3_PROMPT, { continueSession: true, timeoutMs: turnTimeoutMs });++ section("long: pi runs");+ check(+ t1.status === 0 && t2.status === 0 && t3.status === 0,+ `all three pi runs exited 0 (got ${t1.status}/${t2.status}/${t3.status})`,+ );++ const { file: sessionFile, entries } = readSessionEntries(ws);+ check(Boolean(sessionFile), "session JSONL found");++ section("long: context pressure");+ const pressure = contextPressureSeen(ws, entries);+ const { peakPercent, peakTokens, peakBytes, peakPayload, peakEstimatedTokens, peakEstimatedPercent } =+ pressure;+ console.log(+ `e2e-window: biggest provider request ${peakPayload} ${Math.round(peakBytes / 1024)} KB ` ++ `(~${Math.round(peakEstimatedTokens / 1000)}k tokens, ${peakEstimatedPercent}% of ` ++ `${Math.round(LONG_CONTEXT_WINDOW / 1000)}k)`,+ );+ console.log(+ `e2e-window: highest [context-status] line seen: ${peakPercent}% (${peakTokens || "none"}) — ` ++ "that line is emitted once per user prompt, so it undersamples a long tool-heavy turn",+ );+ // The payload is what actually went to the model; the status line is a sample.+ const reached = Math.max(peakPercent, peakEstimatedPercent);+ if (reached >= LONG_MIN_PERCENT) {+ pass(`context reached ${reached}% of the window (>= ${LONG_MIN_PERCENT}%)`);+ } else {+ warn(+ `context only reached ${reached}% (< ${LONG_MIN_PERCENT}%): the model stopped reading ` ++ "early, so this run does not exercise the pressure path",+ );+ }++ section("long: the agent's own decision");+ const resets = [];+ for (const entry of entries) {+ for (const msg of [entry?.message].filter(Boolean)) {+ for (const block of asArray(msg.content)) {+ if (block?.type === "toolCall" && block?.name === RESET_TOOL) {+ resets.push(block.arguments ?? {});+ }+ }+ }+ }+ const windowEntries = entries.filter((e) => e?.customType === WINDOW_ENTRY_TYPE);+ const armed = windowEntries.filter((e) => e?.data?.anchorToolCallId);+ if (resets.length === 0) {+ warn("the agent never called new_context: nothing was instructed, so this is model judgement");+ } else {+ pass(`the agent called ${RESET_TOOL} ${resets.length}x without being told to`);+ console.log(`e2e-window: reason: ${JSON.stringify(resets[0]?.reason ?? "")}`);+ console.log(`e2e-window: notes: ${JSON.stringify(String(resets[0]?.notes ?? "").slice(0, 300))}`);+ check(+ String(resets[0]?.notes ?? "").length > 40,+ "the reset carried handoff notes of its own",+ );+ check(armed.length > 0, `a window was armed and persisted (${armed.length} entries)`);+ }++ section("long: the cut");+ if (resets.length === 0) {+ warn("no reset, so there is no cut to check");+ } else {+ const afterCut = [];+ for (const turn of [1, 2, 3]) {+ for (const entry of payloadsFor(ws, turn)) {+ const first = firstNonSystem(messagesOf(entry));+ if (first && messageText(first).startsWith(WINDOW_HEADER_OPEN)) afterCut.push(entry);+ }+ }+ check(afterCut.length > 0, `at least one provider request starts with the window header (${afterCut.length})`);+ for (const entry of afterCut.slice(0, 2)) {+ assertNoOrphanToolResults(messagesOf(entry), `post-cut payload ${entry.file}`);+ }+ const post = afterCut[0];+ if (post) {+ const postBytes = messagesOf(post).reduce((sum, m) => sum + JSON.stringify(m).length, 0);+ check(+ postBytes * 2 < peakBytes,+ `the reset more than halved the request (${Math.round(peakBytes / 1024)} KB -> ` ++ `${Math.round(postBytes / 1024)} KB)`,+ );+ check(+ !mentionsResetToolCall(messagesOf(post)),+ "the reset tool call and its result are gone from the new window",+ );+ }+ }++ section("long: work continued across the boundary");+ const inventory = join(ws.projDir, "INVENTORY.md");+ const taskFile = join(ws.projDir, "TASK.md");+ if (existsSync(inventory)) {+ const body = readFileSync(inventory, "utf8");+ const sourceFiles = readdirSync(join(ws.projDir, "src")).sort();+ const covered = sourceFiles.filter((f) => body.includes(f));+ console.log(`e2e-window: INVENTORY.md covers ${covered.length}/${sourceFiles.length} files`);+ check(covered.length > 0, "the agent produced an inventory");+ if (resets.length > 0 && covered.length <= 1) {+ warn("only one file made it into the inventory: the run stopped too early to show continuity");+ }+ if (existsSync(taskFile)) {+ const ticked = (readFileSync(taskFile, "utf8").match(/- \[x\]/gi) ?? []).length;+ console.log(`e2e-window: TASK.md ticked off ${ticked} files`);+ }+ } else {+ warn("no INVENTORY.md: the agent never started the task");+ }++ await checkOpenVikingSide(ws, { requireHandoff: resets.length > 0 });+ return ws;+}++async function runFailClosedScenario() {+ const ws = makeWorkspace("failclosed");+ console.log(`e2e-window: [failclosed] OPENVIKING_URL=${DEAD_OV_URL}`);+ const f1 = runTurn(ws, 1, T1_PROMPT, { ovUrl: DEAD_OV_URL });+ const f2 = runTurn(ws, 2, T2_PROMPT, { continueSession: true, ovUrl: DEAD_OV_URL });++ section("fail-closed");+ check(f1.status === 0 && f2.status === 0, `both fail-closed pi runs exited 0 (got ${f1.status}/${f2.status})`);++ const payloads = payloadsFor(ws, 2);+ check(payloads.length >= 1, `fail-closed T2 produced a provider payload (got ${payloads.length})`);+ if (payloads.length > 0) {+ const last = payloads[payloads.length - 1];+ check(last.raw.includes(PAD1), "fail-closed: the last payload still contains PAD1 (nothing was cut)");+ const first = firstNonSystem(messagesOf(last));+ check(+ !messageText(first).startsWith(WINDOW_HEADER_OPEN),+ "fail-closed: no window header was injected",+ );+ assertNoOrphanToolResults(messagesOf(last), "fail-closed last payload");+ }++ const logPath = join(ws.outDir, "ov-pi.log");+ const haystack = [+ f2.transcript,+ ...payloads.map((p) => p.raw),+ existsSync(logPath) ? readFileSync(logPath, "utf8") : "",+ ].join("\n");+ check(haystack.includes("NOT reset"), 'fail-closed: the refusal text "NOT reset" reached the model');++ return ws;+}++// ============================================================================+// Main+// ============================================================================++const workspaces = [];+try {+ if (RUN_MAIN) workspaces.push(await runMainScenario());+ if (RUN_LONG) workspaces.push(await runLongScenario());+ if (RUN_FAILCLOSED) workspaces.push(await runFailClosedScenario());+} catch (error) {+ fail(`unexpected error: ${error?.stack || error}`);+}++console.log("");+for (const ws of workspaces) {+ if (failures === 0 && !process.env.E2E_KEEP_TMP) {+ rmSync(ws.root, { recursive: true, force: true });+ } else {+ console.log(`e2e-window: [${ws.label}] workspace kept for inspection: ${ws.root}`);+ }+}++console.log(+ failures === 0+ ? `\ne2e-window: ALL CHECKS PASSED${warnings ? ` (${warnings} warning(s))` : ""}`+ : `\ne2e-window: ${failures} CHECK(S) FAILED${warnings ? `, ${warnings} warning(s)` : ""}`,+);+process.exit(failures === 0 ? 0 : 1);diff --git a/examples/pi-experimental-context-management/scripts/e2e-window.sh b/examples/pi-experimental-context-management/scripts/e2e-window.shnew file mode 100755index 000000000..ab6590afd--- /dev/null+++ b/examples/pi-experimental-context-management/scripts/e2e-window.sh@@ -0,0 +1,16 @@+#!/usr/bin/env bash+# Live acceptance gate for the agent-driven context window:+# real pi + real OpenViking + real LLM relay. Manual, never run in CI.+#+# Required env (documented in e2e-window.mjs):+# OPENVIKING_URL OPENVIKING_API_KEY E2E_LLM_API_KEY+# Optional:+# PI_BIN E2E_LLM_BASE_URL E2E_LLM_MODEL E2E_LLM_API E2E_KEEP_TMP+# E2E_WINDOW_FAILCLOSED=1|both+#+# Usage:+# OPENVIKING_URL=... OPENVIKING_API_KEY=... E2E_LLM_API_KEY=... scripts/e2e-window.sh+# E2E_WINDOW_FAILCLOSED=1 ... scripts/e2e-window.sh # only the fail-closed variant+set -euo pipefail+cd "$(dirname "$0")/.."+exec node scripts/e2e-window.mjs "$@"diff --git a/examples/pi-experimental-context-management/scripts/setup.mjs b/examples/pi-experimental-context-management/scripts/setup.mjsnew file mode 100755index 000000000..dcd93a30e--- /dev/null+++ b/examples/pi-experimental-context-management/scripts/setup.mjs@@ -0,0 +1,8 @@+#!/usr/bin/env node++import { runSetupWizard } from "../shared/setup-wizard.mjs";++runSetupWizard().catch((err) => {+ process.stderr.write(`${err?.stack || err}\n`);+ process.exit(1);+});diff --git a/examples/pi-experimental-context-management/shared/batch-send.d.mts b/examples/pi-experimental-context-management/shared/batch-send.d.mtsnew file mode 100644index 000000000..3e7bb6739--- /dev/null+++ b/examples/pi-experimental-context-management/shared/batch-send.d.mts@@ -0,0 +1,15 @@+export const BATCH_LIMIT: number;+export function sendSessionMessages(+ fetchJSON: (path: string, init?: any) => Promise<{ ok: boolean; status?: number; result?: any; error?: any }>,+ sessionId: string,+ payloads: Array<Record<string, any>>,+ opts?: { enqueueOnRetryable?: boolean; onSent?: (count: number) => void | Promise<void> },+): Promise<{+ sent: number;+ queued: number;+ enqueueFailed: number;+ failed: number;+ retryable: boolean;+ usedBatch: boolean;+ lastError: any;+}>;diff --git a/examples/pi-experimental-context-management/shared/batch-send.mjs b/examples/pi-experimental-context-management/shared/batch-send.mjsnew file mode 100644index 000000000..d7ec355cc--- /dev/null+++ b/examples/pi-experimental-context-management/shared/batch-send.mjs@@ -0,0 +1,121 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+import { enqueue } from "./pending-queue.mjs";+import { isRetryableFailure } from "./retryable.mjs";++export const BATCH_LIMIT = 100;++export function isRetryableSendFailure(res) {+ return isRetryableFailure(res);+}++function makeResult() {+ return {+ sent: 0,+ queued: 0,+ enqueueFailed: 0,+ failed: 0,+ retryable: false,+ usedBatch: true,+ lastError: null,+ };+}++async function enqueueRemainder(sessionId, payloads, startIndex, result, retryable, lastError) {+ result.retryable = retryable;+ result.lastError = lastError ?? null;++ if (!retryable) {+ result.failed += Math.max(0, payloads.length - startIndex);+ return result;+ }++ const baseCreatedAt = Date.now();+ for (let i = startIndex; i < payloads.length; i++) {+ const queued = await enqueue("addMessage", sessionId, payloads[i], {+ createdAt: baseCreatedAt + (i - startIndex),+ });+ if (!queued.ok) {+ // Stop at the first enqueue failure so queued entries stay a contiguous+ // prefix: consumers mark the first sent+queued payloads as captured, so+ // skipping a payload here and queueing a later one would silently drop it.+ result.enqueueFailed += payloads.length - i;+ return result;+ }+ result.queued++;+ }+ return result;+}++async function sendSerial(fetchJSON, sessionId, payloads, startIndex, opts, result) {+ result.usedBatch = false;+ const encodedSid = encodeURIComponent(sessionId);+ for (let i = startIndex; i < payloads.length; i++) {+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages`, {+ method: "POST",+ body: JSON.stringify(payloads[i]),+ });+ if (res?.ok) {+ result.sent++;+ await opts.onSent?.(1);+ continue;+ }++ const retryable = isRetryableSendFailure(res);+ if (opts.enqueueOnRetryable) {+ return enqueueRemainder(sessionId, payloads, i, result, retryable, res?.error ?? res);+ }+ result.retryable = retryable;+ result.lastError = res?.error ?? res ?? null;+ result.failed += payloads.length - i;+ return result;+ }+ return result;+}++/**+ * Send add-message payloads in server-sized batches with serial fallback.+ *+ * @param {Function} fetchJSON - (path, init) => { ok, status, result?, error? }+ * @param {string} sessionId - OpenViking session id+ * @param {Array<object>} payloads - sanitized add-message request bodies+ * @param {object} opts+ * @param {boolean} opts.enqueueOnRetryable - enqueue unsent payloads after a retryable failure+ * @param {Function} opts.onSent - called with the number of messages durably sent after each success+ * @returns {Promise<{sent:number,queued:number,enqueueFailed:number,failed:number,retryable:boolean,usedBatch:boolean,lastError:any}>}+ */+export async function sendSessionMessages(fetchJSON, sessionId, payloads, opts = {}) {+ const result = makeResult();+ const messages = Array.isArray(payloads) ? payloads : [];+ if (messages.length === 0) return result;++ const encodedSid = encodeURIComponent(sessionId);+ for (let start = 0; start < messages.length; start += BATCH_LIMIT) {+ const chunk = messages.slice(start, start + BATCH_LIMIT);+ const res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages/batch`, {+ method: "POST",+ body: JSON.stringify({ messages: chunk }),+ });++ if (res?.ok) {+ result.sent += chunk.length;+ await opts.onSent?.(chunk.length);+ continue;+ }++ const status = Number(res?.status || 0);+ if (status === 404 || status === 405) {+ return sendSerial(fetchJSON, sessionId, messages, start, opts, result);+ }++ const retryable = isRetryableSendFailure(res);+ if (opts.enqueueOnRetryable) {+ return enqueueRemainder(sessionId, messages, start, result, retryable, res?.error ?? res);+ }+ result.retryable = retryable;+ result.lastError = res?.error ?? res ?? null;+ result.failed += messages.length - start;+ return result;+ }++ return result;+}diff --git a/examples/pi-experimental-context-management/shared/capture-utils.d.mts b/examples/pi-experimental-context-management/shared/capture-utils.d.mtsnew file mode 100644index 000000000..70c40abd3--- /dev/null+++ b/examples/pi-experimental-context-management/shared/capture-utils.d.mts@@ -0,0 +1,9 @@+export function extractPartsFromPayload(payload: any, options?: Record<string, any>): any[];+export function extractTextFromPayload(payload: any, options?: Record<string, any>): string;+export function shouldCaptureText(text: string, role: string, cfg?: Record<string, any>): {+ shouldCapture: boolean;+ reason: string;+ text: string;+};+export function sanitizeCapturedText(text: string): string;+export function truncateCaptureText(text: string, maxChars?: number): string;diff --git a/examples/pi-experimental-context-management/shared/capture-utils.mjs b/examples/pi-experimental-context-management/shared/capture-utils.mjsnew file mode 100644index 000000000..22bc1b63c--- /dev/null+++ b/examples/pi-experimental-context-management/shared/capture-utils.mjs@@ -0,0 +1,578 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+import { applyInputFilters, compileInputFilters } from "./input-filters.mjs";++const TEXT_BLOCK_TYPES = new Set(["text", "input_text", "output_text"]);+const TOOL_CALL_TYPES = new Set([+ "tool_call",+ "toolcall",+ "tool_use",+ "tooluse",+ "function_call",+ "functioncall",+]);+const TOOL_RESULT_TYPES = new Set([+ "tool_result",+ "toolresult",+ "tool_output",+ "tooloutput",+ "function_call_output",+ "functioncalloutput",+]);++// Tool output is reported verbatim; the server owns truncation via+// tool_output_externalization (threshold_chars, default 20000). This cap only+// guards against pathological payloads.+const DEFAULT_TOOL_MAX_CHARS = 1000000;++const ACK_RE = /^(?:ok|okay|k|yes|yep|no|nope|thanks|thank you|thx|done|收到|好的|好|嗯|可以|继续|不用|不需要|没了|好了)[.!?。!?\s]*$/i;+const SLASH_COMMAND_RE = /^\/[a-z0-9_-]{1,64}\b/i;+const METADATA_KEYS = [+ "session_id",+ "sessionid",+ "sessionkey",+ "conversation_id",+ "conversationid",+ "channel",+ "sender",+ "user_id",+ "userid",+ "agent_id",+ "agentid",+ "timestamp",+ "timezone",+ "cwd",+ "model",+ "permission_mode",+];++function normalizeType(value) {+ return String(value || "").toLowerCase().replace(/[-\s]/g, "_");+}++function isToolCallBlock(block) {+ const type = normalizeType(block?.type || block?.kind || block?.role);+ return TOOL_CALL_TYPES.has(type) || Boolean(block?.tool_calls) || Boolean(block?.function?.name);+}++function isToolResultBlock(block) {+ const type = normalizeType(block?.type || block?.kind || block?.role);+ return TOOL_RESULT_TYPES.has(type) || type === "tool" || type === "function";+}++function oneLine(text) {+ return String(text || "").replace(/\s+/g, " ").trim();+}++export function truncateCaptureText(text, maxChars = 2000) {+ const value = String(text || "").trim();+ if (!Number.isFinite(maxChars) || maxChars <= 0 || value.length <= maxChars) return value;+ return `${value.slice(0, Math.max(0, maxChars - 20)).trimEnd()}\n[truncated]`;+}++function stringifyCompact(value, maxChars) {+ if (value == null) return "";+ if (typeof value === "string") return truncateCaptureText(value, maxChars);+ try {+ return truncateCaptureText(JSON.stringify(value), maxChars);+ } catch {+ return truncateCaptureText(String(value), maxChars);+ }+}++function parseMaybeJson(value) {+ if (value == null || typeof value !== "string") return value;+ const trimmed = value.trim();+ if (!trimmed) return value;+ try {+ return JSON.parse(trimmed);+ } catch {+ return value;+ }+}++function blockText(block) {+ if (!block || typeof block !== "object") return "";+ if (typeof block.text === "string") return block.text;+ if (typeof block.output_text === "string") return block.output_text;+ if (typeof block.input_text === "string") return block.input_text;+ if (typeof block.content === "string") return block.content;+ return "";+}++function toolName(block) {+ return oneLine(+ block?.name ||+ block?.tool_name ||+ block?.toolName ||+ block?.tool ||+ block?.function?.name ||+ block?.call?.name ||+ "",+ );+}++function toolPayload(block, kind) {+ if (!block || typeof block !== "object") return "";+ if (kind === "call") {+ return block.input ??+ block.state?.input ??+ block.arguments ??+ block.args ??+ block.params ??+ block.function?.arguments ??+ block.command ??+ block.call?.input ??+ block.call?.arguments ??+ "";+ }+ return block.output ??+ block.state?.output ??+ block.result ??+ block.error ??+ block.state?.error ??+ block.data ??+ block.content ??+ block.text ??+ "";+}++function toolId(block) {+ return oneLine(+ block?.call_id ||+ block?.callId ||+ block?.callID ||+ block?.tool_call_id ||+ block?.toolCallId ||+ block?.tool_use_id ||+ block?.toolUseId ||+ block?.function_call_id ||+ block?.functionCallId ||+ block?.id ||+ "",+ );+}++function toolStatus(block, kind) {+ if (kind === "call") return "running";+ if (block?.is_error || block?.isError || block?.state?.isError || block?.error || block?.state?.error) return "error";+ const status = oneLine(block?.status || block?.state?.status || "");+ return status || "completed";+}++function setToolInput(part, payload) {+ const input = parseMaybeJson(payload);+ if (input === "" || input == null) return;+ part.tool_input = typeof input === "object" && !Array.isArray(input)+ ? input+ : { value: input };+}++function buildToolPart(block, kind, { toolMaxChars = DEFAULT_TOOL_MAX_CHARS, toolNameById = {} } = {}) {+ const id = toolId(block);+ const name = toolName(block) || (id ? toolNameById[id] : "");+ const payload = toolPayload(block, kind);+ const part = {+ type: "tool",+ tool_id: id || undefined,+ tool_name: name || undefined,+ tool_status: toolStatus(block, kind),+ };+ if (kind === "call") {+ setToolInput(part, payload);+ } else {+ if (block?.state?.input !== undefined) {+ setToolInput(part, block.state.input);+ }+ part.tool_output = stringifyCompact(payload, toolMaxChars);+ }+ return part;+}++function formatToolBlock(block, kind, maxChars) {+ const name = toolName(block);+ const payload = toolPayload(block, kind);+ const body = oneLine(stringifyCompact(payload, maxChars));+ const label = kind === "call" ? "tool-call" : "tool-result";+ return body+ ? `[${label}${name ? ` ${name}` : ""}] ${body}`+ : `[${label}${name ? ` ${name}` : ""}]`;+}++function blockToText(block, options) {+ if (!block) return "";+ if (typeof block === "string") return block;+ if (Array.isArray(block)) return extractTextFromContent(block, options);+ if (typeof block !== "object") return "";++ if (block.item && typeof block.item === "object") {+ const itemText = blockToText(block.item, options);+ if (itemText) return itemText;+ }++ const type = normalizeType(block.type || block.kind || block.role);+ if (TEXT_BLOCK_TYPES.has(type)) return blockText(block);+ if (isToolCallBlock(block)) return formatToolBlock(block, "call", options.toolMaxChars);+ if (isToolResultBlock(block)) return formatToolBlock(block, "result", options.toolMaxChars);+ if (Array.isArray(block.content)) return extractTextFromContent(block.content, options);+ if (!type) return blockText(block);+ return "";+}++export function extractTextFromContent(content, options = {}) {+ const opts = { toolMaxChars: DEFAULT_TOOL_MAX_CHARS, ...options };+ if (!content) return "";+ if (typeof content === "string") return content;+ if (Array.isArray(content)) {+ return content+ .map((block) => blockToText(block, opts))+ .filter(Boolean)+ .join("\n\n");+ }+ if (typeof content === "object") {+ return blockToText(content, opts) || stringifyCompact(content, opts.toolMaxChars);+ }+ return "";+}++export function extractTextFromPayload(payload, options = {}) {+ if (!payload || typeof payload !== "object") return "";+ const chunks = [];+ const directType = normalizeType(payload.type || payload.kind || payload.role);+ if (TOOL_RESULT_TYPES.has(directType) || directType === "tool" || TOOL_CALL_TYPES.has(directType)) {+ const direct = blockToText(payload, { toolMaxChars: DEFAULT_TOOL_MAX_CHARS, ...options });+ if (direct) return direct;+ }++ if (payload.message && typeof payload.message === "object") {+ const messageText = extractTextFromPayload(payload.message, options);+ if (messageText) chunks.push(messageText);+ } else if (payload.content !== undefined) {+ const contentText = extractTextFromContent(payload.content, options);+ if (contentText) chunks.push(contentText);+ }++ for (const key of ["tool_calls", "toolCalls", "function_call", "functionCall", "tool_call", "toolCall"]) {+ const value = payload[key];+ if (!value) continue;+ const toolText = extractTextFromContent(value, options);+ if (toolText) chunks.push(toolText);+ }++ if (chunks.length === 0) {+ const direct = blockToText(payload, { toolMaxChars: DEFAULT_TOOL_MAX_CHARS, ...options });+ if (direct) chunks.push(direct);+ }++ return chunks.join("\n\n");+}++function collectToolNamesByIdFromEntries(entries) {+ const map = {};+ for (const entry of entries || []) {+ const payload = entry?.payload && typeof entry.payload === "object" ? entry.payload : entry;+ collectToolNamesByIdFromPayload(payload, map);+ }+ return map;+}++function collectToolNamesByIdFromPayload(payload, out) {+ if (!payload || typeof payload !== "object") return;+ if (payload.message && typeof payload.message === "object") {+ collectToolNamesByIdFromPayload(payload.message, out);+ }+ const candidates = [];+ if (Array.isArray(payload.content)) candidates.push(...payload.content);+ for (const key of ["tool_calls", "toolCalls", "function_call", "functionCall", "tool_call", "toolCall"]) {+ const value = payload[key];+ if (!value) continue;+ if (Array.isArray(value)) candidates.push(...value);+ else candidates.push(value);+ }+ if (isToolCallBlock(payload)) candidates.push(payload);+ for (const block of candidates) {+ if (!block || typeof block !== "object") continue;+ if (!isToolCallBlock(block)) continue;+ const id = toolId(block);+ const name = toolName(block);+ if (id && name) out[id] = name;+ }+}++function extractPartsFromContent(content, options = {}) {+ const opts = { toolMaxChars: DEFAULT_TOOL_MAX_CHARS, toolNameById: {}, ...options };+ const parts = [];+ if (!content) return parts;+ if (typeof content === "string") {+ if (content.trim()) parts.push({ type: "text", text: content });+ return parts;+ }+ if (!Array.isArray(content)) {+ const text = blockToText(content, opts);+ if (text.trim()) parts.push({ type: "text", text });+ return parts;+ }+ for (const block of content) {+ if (!block || typeof block !== "object") continue;+ if (isToolCallBlock(block)) {+ parts.push(buildToolPart(block, "call", opts));+ } else if (isToolResultBlock(block)) {+ parts.push(buildToolPart(block, "result", opts));+ } else {+ const text = blockToText(block, opts);+ if (text.trim()) parts.push({ type: "text", text });+ }+ }+ return parts;+}++export function extractPartsFromPayload(payload, options = {}) {+ if (!payload || typeof payload !== "object") return [];+ const opts = { toolMaxChars: DEFAULT_TOOL_MAX_CHARS, toolNameById: {}, ...options };+ if (payload.message && typeof payload.message === "object") {+ return extractPartsFromPayload(payload.message, opts);+ }++ const directType = normalizeType(payload.type || payload.kind || payload.role);+ if (TOOL_CALL_TYPES.has(directType) || isToolCallBlock(payload)) {+ return [buildToolPart(payload, "call", opts)];+ }+ if (TOOL_RESULT_TYPES.has(directType) || directType === "tool" || directType === "function") {+ return [buildToolPart(payload, "result", opts)];+ }++ const parts = [];+ if (payload.content !== undefined) {+ parts.push(...extractPartsFromContent(payload.content, opts));+ }+ for (const key of ["tool_calls", "toolCalls", "function_call", "functionCall", "tool_call", "toolCall"]) {+ const value = payload[key];+ if (!value) continue;+ if (Array.isArray(value)) {+ for (const block of value) parts.push(...extractPartsFromPayload(block, opts));+ } else {+ parts.push(...extractPartsFromPayload(value, opts));+ }+ }+ return parts;+}++/**+ * Prune blank text parts and run `cfg.captureFilters` over the ones that remain.+ *+ * One drop verdict is taken per turn, on the aggregate of its text parts; the+ * individual parts are then rewritten with the substitutions only, so a rule can+ * never both keep and drop the same turn. Tool call/result parts are carried+ * through untouched — filters match conversation text, not tool payloads — but a+ * turn dropped on its text takes its tool parts with it.+ */+export function filterCaptureParts(parts, role, cfg = {}) {+ const kept = [];+ for (const part of parts || []) {+ if (!part) continue;+ if (part.type !== "text") {+ kept.push(part);+ continue;+ }+ const text = typeof part.text === "string" ? part.text.trim() : "";+ if (!text) continue;+ kept.push(text === part.text ? part : { ...part, text });+ }++ const blank = { parts: kept, dropped: false };+ const compiled = compileInputFilters(cfg?.captureFilters);+ if (!compiled.rules.length || kept.length === 0) return blank;++ const textParts = kept.filter((part) => part.type === "text");+ if (textParts.length === 0) return blank;++ const verdict = applyInputFilters(textParts.map((part) => part.text).join("\n\n"), compiled.rules, {+ role,+ });+ if (verdict.dropped) return { parts: [], dropped: true };++ const out = [];+ for (const part of kept) {+ if (part.type !== "text") {+ out.push(part);+ continue;+ }+ const shaped = applyInputFilters(part.text, compiled.rules, { role, substituteOnly: true });+ if (!shaped.text) continue;+ out.push(shaped.text === part.text ? part : { ...part, text: shaped.text });+ }+ return { parts: out, dropped: out.length === 0 };+}++export function extractCaptureTurns(rolloutEntries, cfg = {}) {+ const toolNameById = collectToolNamesByIdFromEntries(rolloutEntries);+ const turns = [];+ for (const entry of rolloutEntries || []) {+ if (!entry || typeof entry !== "object") continue;+ const payload = entry.payload && typeof entry.payload === "object" ? entry.payload : entry;+ const message = payload.message && typeof payload.message === "object" ? payload.message : null;+ const rawRole = message?.role || payload.role || payload.type || payload.kind;+ const role = normalizeCaptureRole(rawRole);+ if (!role) continue;+ if (isAssistantSideCaptureRole(rawRole) && !cfg.captureAssistantTurns) continue;++ const rawText = extractTextFromPayload(payload, { toolMaxChars: cfg.captureToolMaxChars });+ const parts = extractPartsFromPayload(payload, {+ toolMaxChars: cfg.captureToolMaxChars,+ toolNameById,+ });+ const shaped = filterCaptureParts(parts, role, cfg);+ if (shaped.dropped) continue;+ // With parts on the wire the drop decision was already taken above, so the+ // text path only runs the filters for the `content` fallback. That also+ // keeps `turn.text` faithful for callers that scan it for trigger words.+ const decision = shouldCaptureText(rawText, role, cfg, { filters: shaped.parts.length === 0 });+ if (!decision.shouldCapture && shaped.parts.length === 0) continue;+ const text = decision.shouldCapture ? decision.text : "";+ turns.push({ role, text, parts: shaped.parts });+ }+ return turns;+}++export function normalizeCaptureRole(role) {+ const value = normalizeType(role);+ if (value === "user") return "user";+ if (value === "assistant") return "assistant";+ if (value === "tool" || value === "tool_result" || value === "function" || value === "function_call_output") {+ return "user";+ }+ if (value === "tool_call" || value === "function_call") return "assistant";+ return null;+}++export function isAssistantSideCaptureRole(role) {+ const value = normalizeType(role);+ return value === "assistant" ||+ value === "tool" ||+ value === "tool_result" ||+ value === "tool_call" ||+ value === "function" ||+ value === "function_call" ||+ value === "function_call_output";+}++function stripMetadataFences(text) {+ return String(text || "").replace(/```(?:json)?\s*([\s\S]*?)```/gi, (match, body) => {+ const lower = body.toLowerCase();+ let hits = 0;+ for (const key of METADATA_KEYS) {+ const re = new RegExp(`["']?${key}["']?\\s*:`, "i");+ if (re.test(lower)) hits += 1;+ }+ return hits >= 3 ? "" : match;+ });+}++function stripInjectedDigestBlocks(text) {+ const lines = String(text || "").split(/\r?\n/);+ const out = [];+ let skipping = false;+ let skipUntilMcpHint = false;++ for (const line of lines) {+ const trimmed = line.trim();+ if (/^OpenViking session archive digest:/i.test(trimmed)) {+ skipping = true;+ skipUntilMcpHint = true;+ continue;+ }+ if (/^OpenViking memory digest:/i.test(trimmed)) {+ skipping = true;+ skipUntilMcpHint = false;+ continue;+ }+ if (skipping) {+ if (skipUntilMcpHint) {+ if (/^More detail: use the OpenViking MCP /i.test(trimmed)) {+ skipping = false;+ skipUntilMcpHint = false;+ }+ continue;+ }+ if (!trimmed) {+ skipping = false;+ continue;+ }+ if (+ /^(?:[-*]\s+|#{1,6}\s+|More detail:|Use OpenViking MCP|Latest committed archive|Resume continuity|viking:\/\/)/i.test(trimmed) ||+ /^\s{2,}\S/.test(line)+ ) {+ continue;+ }+ skipping = false;+ }+ out.push(line);+ }++ return out.join("\n");+}++export function sanitizeCapturedText(text) {+ let value = String(text || "");+ value = value+ .replace(/\u0000/g, "")+ .replace(/<openviking-context\b[^>]*>[\s\S]*?<\/openviking-context>/gi, " ")+ .replace(/<relevant-memor(?:y|ies)\b[^>]*>[\s\S]*?<\/relevant-memor(?:y|ies)>/gi, " ")+ .replace(/^\s*Sender\s*\([^)]+\)\s*```[\s\S]*?```\s*/gim, " ")+ .replace(/^\s*Conversation (?:metadata|info):\s*```[\s\S]*?```\s*/gim, " ")+ .replace(/^\s*\[?\d{4}-\d{2}-\d{2}[T ][^\]\n]{3,80}\]?\s*/gm, "")+ .replace(/^\s*\d{10,13}\s+/gm, "");+ value = stripMetadataFences(value);+ value = stripInjectedDigestBlocks(value);+ value = value.replace(/^\s*More detail: use the OpenViking MCP .*$/gim, " ");+ return value+ .replace(/[ \t]+\n/g, "\n")+ .replace(/\n{3,}/g, "\n\n")+ .trim();+}++function hasEnoughSignal(text) {+ const cjk = text.match(/[\u3400-\u9fff]/g)?.length || 0;+ const alnum = text.match(/[a-z0-9]/gi)?.length || 0;+ return cjk >= 4 || alnum >= 6 || text.length >= 12;+}++function isPunctuationOnly(text) {+ return !/[a-z0-9\u3400-\u9fff]/i.test(text);+}++export function shouldCaptureText(text, role, cfg = {}, { filters = true } = {}) {+ const maxLength = cfg.captureMaxLength || 24000;+ const sanitized = sanitizeCapturedText(text);+ if (!sanitized) return { shouldCapture: false, reason: "empty", text: "" };++ let capped = truncateCaptureText(sanitized, maxLength);+ if (filters) {+ const compiled = compileInputFilters(cfg?.captureFilters);+ if (compiled.rules.length) {+ const verdict = applyInputFilters(capped, compiled.rules, { role });+ if (verdict.dropped) return { shouldCapture: false, reason: "filtered", text: "" };+ capped = verdict.text;+ if (!capped) return { shouldCapture: false, reason: "empty", text: "" };+ }+ }+ const compact = oneLine(capped);+ const isToolSummary = /^\[tool-(?:call|result)\b/i.test(compact);++ if (!isToolSummary && role === "user" && SLASH_COMMAND_RE.test(compact)) {+ return { shouldCapture: false, reason: "slash_command", text: "" };+ }+ if (!isToolSummary && ACK_RE.test(compact)) {+ return { shouldCapture: false, reason: "ack", text: "" };+ }+ if (!isToolSummary && isPunctuationOnly(compact)) {+ return { shouldCapture: false, reason: "punctuation", text: "" };+ }+ if (!isToolSummary && !hasEnoughSignal(compact)) {+ return { shouldCapture: false, reason: "too_short", text: "" };+ }+ if (/^\[openviking-memory\]/i.test(compact)) {+ return { shouldCapture: false, reason: "plugin_status", text: "" };+ }++ return { shouldCapture: true, reason: "ok", text: capped };+}diff --git a/examples/pi-experimental-context-management/shared/credentials.d.mts b/examples/pi-experimental-context-management/shared/credentials.d.mtsnew file mode 100644index 000000000..aa46700cf--- /dev/null+++ b/examples/pi-experimental-context-management/shared/credentials.d.mts@@ -0,0 +1,14 @@+export function buildUserAgent(harness: string, version?: string): string;++export function readManifestVersion(manifest: string | URL): string;++export function resolveOpenVikingCredentials(env?: Record<string, string | undefined>): {+ credentialSource: string;+ baseUrl: string;+ mcpUrl: string;+ apiKey: string;+ account: string;+ user: string;+ peerId: string;+ hasApiKey: boolean;+};diff --git a/examples/pi-experimental-context-management/shared/credentials.mjs b/examples/pi-experimental-context-management/shared/credentials.mjsnew file mode 100644index 000000000..ba26a84dc--- /dev/null+++ b/examples/pi-experimental-context-management/shared/credentials.mjs@@ -0,0 +1,239 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+import { readFileSync } from "node:fs";+import { homedir } from "node:os";+import { join, resolve as resolvePath } from "node:path";+import { fileURLToPath } from "node:url";++const DEFAULT_OVCLI_CONF_PATH = join(homedir(), ".openviking", "ovcli.conf");+const DEFAULT_OV_CONF_PATH = join(homedir(), ".openviking", "ov.conf");+const DEFAULT_BASE_URL = "http://127.0.0.1:1933";++function str(val, fallback = "") {+ if (typeof val === "string" && val.trim()) return val.trim();+ return fallback;+}++function normalizePath(value) {+ const raw = str(value, "");+ if (!raw) return "";+ if (raw === "~") return homedir();+ if (raw.startsWith("~/")) return resolvePath(join(homedir(), raw.slice(2)));+ return resolvePath(raw);+}++function tryLoadJson(path) {+ if (!path) return null;+ try {+ return JSON.parse(readFileSync(path, "utf-8"));+ } catch {+ return null;+ }+}++/**+ * Build the User-Agent every harness plugin sends on OpenViking-bound requests.+ * Shape is `name/semver` so downstream stats layers can parse it as one token.+ */+export function buildUserAgent(harness, version) {+ return `openviking-memory-${harness}/${str(version, "") || "0.0.0"}`;+}++/**+ * Read a plugin manifest's `version` field. Accepts a path or a URL (so callers+ * can resolve relative to import.meta.url). Returns "" when unreadable so the+ * User-Agent falls back to 0.0.0 instead of throwing inside a short-lived hook.+ */+export function readManifestVersion(manifest) {+ try {+ return str(JSON.parse(readFileSync(manifest, "utf-8")).version, "");+ } catch {+ return "";+ }+}++function looksLikeOvcli(obj) {+ if (!obj || typeof obj !== "object") return false;+ if (obj.server && typeof obj.server === "object") return false;+ return Boolean(+ typeof obj.url === "string" ||+ typeof obj.api_key === "string" ||+ typeof obj.account === "string" ||+ typeof obj.account_id === "string" ||+ typeof obj.user === "string" ||+ typeof obj.user_id === "string" ||+ typeof obj.actor_peer_id === "string",+ );+}++function hasCredentialFields(obj) {+ if (!obj || typeof obj !== "object") return false;+ return [+ "url",+ "api_key",+ "account",+ "account_id",+ "user",+ "user_id",+ "actor_peer_id",+ "peer_id",+ ].some((key) => typeof obj[key] === "string");+}++export function loadCredentialFiles(env = process.env) {+ const cliPathCandidate = normalizePath(env.OPENVIKING_CLI_CONFIG_FILE) || DEFAULT_OVCLI_CONF_PATH;+ const ovPathCandidate = normalizePath(env.OPENVIKING_CONFIG_FILE) || DEFAULT_OV_CONF_PATH;+ const cliPathEnv = Boolean(str(env.OPENVIKING_CLI_CONFIG_FILE, ""));+ const ovPathEnv = Boolean(str(env.OPENVIKING_CONFIG_FILE, ""));++ let cliFile = tryLoadJson(cliPathCandidate);+ let cliPath = cliFile ? cliPathCandidate : "";+ let ovFile = tryLoadJson(ovPathCandidate);+ let ovPath = ovFile ? ovPathCandidate : "";++ // Backward compat: older plugin installs used OPENVIKING_CONFIG_FILE for+ // both ov.conf and ovcli.conf. Preserve that when the file is ovcli-shaped.+ if (ovPathEnv && !cliPathEnv && looksLikeOvcli(ovFile)) {+ cliFile = ovFile;+ cliPath = ovPath;+ ovFile = null;+ ovPath = "";+ }++ return {+ cliFile: cliFile || {},+ cliPath,+ cliPathCandidate,+ ovFile: ovFile || {},+ ovPath,+ };+}++function sourceMode(env) {+ const raw = str(env.OPENVIKING_CREDENTIAL_SOURCE, str(env.OPENVIKING_CREDENTIALS_SOURCE, "auto"))+ .toLowerCase();+ if (raw === "env" || raw === "environment") return "env";+ if (raw === "cli" || raw === "ovcli" || raw === "file" || raw === "config") return "cli";+ return "auto";+}++function hasEnvCredentialFields(env) {+ return Boolean(+ str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, "")) ||+ str(env.OPENVIKING_MCP_URL, "") ||+ str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, "")) ||+ str(env.OPENVIKING_ACCOUNT, "") ||+ str(env.OPENVIKING_USER, "") ||+ str(env.OPENVIKING_PEER_ID, ""),+ );+}++function deriveBaseUrl({ env, cliFile, ovFile, mode, useCli }) {+ const envUrl = str(env.OPENVIKING_URL, str(env.OPENVIKING_BASE_URL, ""));+ const cliUrl = str(cliFile.url, "");++ if (mode !== "cli" && envUrl) return envUrl.replace(/\/+$/, "");+ if (useCli && cliUrl) return cliUrl.replace(/\/+$/, "");+ if (mode !== "env" && cliUrl) return cliUrl.replace(/\/+$/, "");++ const server = ovFile.server || {};+ const ovUrl = str(server.url, "");+ if (ovUrl) return ovUrl.replace(/\/+$/, "");++ const host = str(server.host, "127.0.0.1").replace("0.0.0.0", "127.0.0.1");+ const port = Number.isFinite(Number(server.port)) ? Math.floor(Number(server.port)) : 1933;+ return `http://${host}:${port}`;+}++export function resolveOpenVikingCredentials(env = process.env) {+ const files = loadCredentialFiles(env);+ const mode = sourceMode(env);+ const envHasCredentials = hasEnvCredentialFields(env);+ const useCli = mode === "cli" ||+ (mode === "auto" && !envHasCredentials && files.cliPath && hasCredentialFields(files.cliFile));+ const cx = files.ovFile.codex || {};+ const server = files.ovFile.server || {};++ const baseUrl = deriveBaseUrl({ env, ...files, mode, useCli });++ const apiKey = useCli+ ? str(files.cliFile.api_key, "")+ : (+ str(env.OPENVIKING_BEARER_TOKEN, "") ||+ str(env.OPENVIKING_API_KEY, "") ||+ str(files.cliFile.api_key, "") ||+ str(cx.apiKey, "") ||+ str(server.root_api_key, "")+ );++ const account = useCli+ ? str(files.cliFile.account, str(files.cliFile.account_id, ""))+ : (+ str(env.OPENVIKING_ACCOUNT, "") ||+ str(files.cliFile.account, str(files.cliFile.account_id, "")) ||+ str(cx.accountId, "")+ );++ const user = useCli+ ? str(files.cliFile.user, str(files.cliFile.user_id, ""))+ : (+ str(env.OPENVIKING_USER, "") ||+ str(files.cliFile.user, str(files.cliFile.user_id, "")) ||+ str(cx.userId, "")+ );++ const peerId = useCli+ ? str(files.cliFile.actor_peer_id, str(files.cliFile.peer_id, ""))+ : (+ str(env.OPENVIKING_PEER_ID, "") ||+ str(files.cliFile.actor_peer_id, str(files.cliFile.peer_id, "")) ||+ str(cx.peerId, str(cx.peer_id, ""))+ );++ const explicitMcpUrl = str(env.OPENVIKING_MCP_URL, "");+ const mcpUrl = (mode !== "cli" && explicitMcpUrl) ? explicitMcpUrl : `${baseUrl.replace(/\/+$/, "")}/mcp`;++ // The file that actually supplied the api_key, following the same chain —+ // empty when the key came from the environment or was never found.+ let credentialPath = "";+ if (apiKey) {+ if (useCli) credentialPath = files.cliPath;+ else if (str(env.OPENVIKING_BEARER_TOKEN, str(env.OPENVIKING_API_KEY, ""))) credentialPath = "";+ else if (str(files.cliFile.api_key, "")) credentialPath = files.cliPath;+ else credentialPath = files.ovPath;+ }++ return {+ ...files,+ credentialSource: useCli ? "ovcli" : ((mode === "env" || envHasCredentials) ? "env" : "auto"),+ credentialPath,+ baseUrl,+ mcpUrl,+ apiKey,+ account,+ user,+ peerId,+ hasApiKey: Boolean(apiKey),+ };+}++function main() {+ const cmd = process.argv[2] || "";+ if (cmd === "mcp-url") {+ process.stdout.write(resolveOpenVikingCredentials().mcpUrl);+ return;+ }+ if (cmd === "has-api-key") {+ process.stdout.write(resolveOpenVikingCredentials().hasApiKey ? "1" : "0");+ return;+ }+ if (cmd === "has-peer-id") {+ process.stdout.write(resolveOpenVikingCredentials().peerId ? "1" : "0");+ return;+ }+ process.stderr.write("usage: ov-credentials.mjs <mcp-url|has-api-key|has-peer-id>\n");+ process.exitCode = 2;+}++if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {+ main();+}diff --git a/examples/pi-experimental-context-management/shared/debug-log.d.mts b/examples/pi-experimental-context-management/shared/debug-log.d.mtsnew file mode 100644index 000000000..7c44ca656--- /dev/null+++ b/examples/pi-experimental-context-management/shared/debug-log.d.mts@@ -0,0 +1,7 @@+export declare function createLogger(+ hookName: string,+ overrideCfg?: { debug?: boolean; debugLogPath?: string },+): {+ log(stage: string, data?: unknown): void;+ logError(stage: string, err: unknown): void;+};diff --git a/examples/pi-experimental-context-management/shared/debug-log.mjs b/examples/pi-experimental-context-management/shared/debug-log.mjsnew file mode 100644index 000000000..73855cf6d--- /dev/null+++ b/examples/pi-experimental-context-management/shared/debug-log.mjs@@ -0,0 +1,58 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Shared structured debug logger for OpenViking memory plugin hook scripts.+ *+ * Harness-specific wrappers load config and pass {debug, debugLogPath}. This+ * module stays path-agnostic so it can be vendored into each plugin snapshot.+ */++import { appendFileSync, mkdirSync } from "node:fs";+import { dirname } from "node:path";++function ensureDir(filePath) {+ try {+ mkdirSync(dirname(filePath), { recursive: true });+ } catch { /* best effort */ }+}++function writeLine(filePath, obj) {+ try {+ appendFileSync(filePath, JSON.stringify(obj) + "\n");+ } catch { /* best effort */ }+}++function localISO() {+ const d = new Date();+ const off = d.getTimezoneOffset();+ const sign = off <= 0 ? "+" : "-";+ const abs = Math.abs(off);+ const local = new Date(d.getTime() - off * 60000);+ return local.toISOString().replace(+ "Z",+ `${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`,+ );+}++const noop = () => {};++export function createLogger(hookName, overrideCfg) {+ const c = overrideCfg || {};+ if (!c.debug) return { log: noop, logError: noop };++ const logPath = c.debugLogPath;+ if (!logPath) return { log: noop, logError: noop };+ ensureDir(logPath);++ function log(stage, data) {+ writeLine(logPath, { ts: localISO(), hook: hookName, stage, data });+ }++ function logError(stage, err) {+ const error = err instanceof Error+ ? { message: err.message, stack: err.stack }+ : String(err);+ writeLine(logPath, { ts: localISO(), hook: hookName, stage, error });+ }++ return { log, logError };+}diff --git a/examples/pi-experimental-context-management/shared/input-filters.mjs b/examples/pi-experimental-context-management/shared/input-filters.mjsnew file mode 100644index 000000000..e20bb03a7--- /dev/null+++ b/examples/pi-experimental-context-management/shared/input-filters.mjs@@ -0,0 +1,219 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Ordered, operator-configured regex filters for memory plugin input.+ *+ * Rules are sed-style strings, applied in order to a single piece of text:+ * s/^\s*ultrathink\s+//i substitute (add `g` to replace every match)+ * d|^\s*[/!]| drop the text when the pattern matches+ * k/^\?ov\b/ keep the text only when the pattern matches+ * user:d/^\s*\/clear\b/ apply to one role only+ *+ * A malformed rule becomes an entry in `errors` and is skipped rather than+ * throwing, so a typo in a config file cannot take a hook down.+ */++const OPS = new Set(["s", "d", "k"]);+const SCOPES = ["user", "assistant"];+const ALLOWED_FLAGS = "imsug";++export const INPUT_FILTER_KNOBS = [+ {+ key: "recallQueryFilters",+ env: "OPENVIKING_RECALL_QUERY_FILTERS",+ label: "recall query filters",+ },+ {+ key: "captureFilters",+ env: "OPENVIKING_CAPTURE_FILTERS",+ label: "capture filters",+ },+];++/**+ * Read one delimited field. `\` always consumes the next character, and only+ * `\<delim>` is un-escaped, so `\d` / `\b` / `\x2c` reach RegExp verbatim.+ * Returns the index of the closing delimiter, or -1 when it is missing.+ */+function scanField(source, start, delim) {+ let out = "";+ let i = start;+ while (i < source.length) {+ const c = source[i];+ if (c === "\\") {+ const next = source[i + 1];+ if (next === undefined) {+ out += "\\";+ i += 1;+ continue;+ }+ out += next === delim ? next : "\\" + next;+ i += 2;+ continue;+ }+ if (c === delim) return { value: out, end: i };+ out += c;+ i += 1;+ }+ return { value: out, end: -1 };+}++export function parseInputFilterRule(source) {+ if (typeof source !== "string") {+ return { source: String(source ?? ""), error: "rule must be a string" };+ }+ const raw = source.trim();+ if (!raw) return { source: raw, error: "rule is empty" };++ let scope = "";+ let rest = raw;+ for (const candidate of SCOPES) {+ if (rest.startsWith(`${candidate}:`)) {+ scope = candidate;+ rest = rest.slice(candidate.length + 1);+ break;+ }+ }++ const op = rest[0] || "";+ if (!OPS.has(op)) {+ return {+ source: raw,+ error: `unknown operation "${op}" — expected s (substitute), d (drop) or k (keep)`,+ };+ }+ const delim = rest[1];+ if (delim === undefined) {+ return { source: raw, error: `missing delimiter after "${op}"` };+ }+ if (/[A-Za-z0-9\s\\]/.test(delim)) {+ return {+ source: raw,+ error: `invalid delimiter ${JSON.stringify(delim)} — use punctuation such as / | # or :`,+ };+ }++ const first = scanField(rest, 2, delim);+ const pattern = first.value;+ let replacement = null;+ let flagsRaw = "";+ if (op === "s") {+ if (first.end < 0) {+ return { source: raw, error: `missing ${JSON.stringify(delim)} after the pattern` };+ }+ const second = scanField(rest, first.end + 1, delim);+ if (second.end < 0) {+ return {+ source: raw,+ error: `missing ${JSON.stringify(delim)} after the replacement — write s${delim}pattern${delim}replacement${delim}`,+ };+ }+ replacement = second.value;+ flagsRaw = rest.slice(second.end + 1);+ } else {+ flagsRaw = first.end < 0 ? "" : rest.slice(first.end + 1);+ }++ if (!pattern) return { source: raw, error: "pattern is empty" };++ const flags = new Set();+ for (const flag of flagsRaw) {+ if (!ALLOWED_FLAGS.includes(flag)) {+ return { source: raw, error: `unknown flag "${flag}" — allowed flags are i, m, s, u, g` };+ }+ if (flags.has(flag)) return { source: raw, error: `duplicate flag "${flag}"` };+ flags.add(flag);+ }+ // d/k decide with .test(), which advances lastIndex on a global regex and+ // would then alternate between calls. `g` means nothing there, so drop it.+ if (op !== "s") flags.delete("g");++ let re;+ try {+ re = new RegExp(pattern, [...flags].join(""));+ } catch (err) {+ // V8 already says "Invalid regular expression: <pattern>: <why>"; keep that+ // detail without stuttering the prefix the doctors key off.+ const message = err?.message || String(err);+ return {+ source: raw,+ error: /^invalid regular expression/i.test(message)+ ? `invalid${message.slice("Invalid".length)}`+ : `invalid regular expression: ${message}`,+ };+ }++ return { op, scope, re, replacement, source: raw };+}++export function compileInputFilters(rules) {+ const compiled = [];+ const errors = [];+ const list = Array.isArray(rules) ? rules : [];+ list.forEach((entry, index) => {+ if (typeof entry !== "string") {+ errors.push({ index, source: String(entry ?? ""), message: "rule must be a string" });+ return;+ }+ if (!entry.trim()) return;+ const parsed = parseInputFilterRule(entry);+ if (parsed.error) errors.push({ index, source: parsed.source, message: parsed.error });+ else compiled.push({ ...parsed, index });+ });+ return { rules: compiled, errors };+}++/**+ * Run compiled rules over `text`.+ *+ * `substituteOnly` skips the d/k operations, so a caller that already took one+ * drop decision for a turn can rewrite its individual pieces without taking a+ * second, possibly contradictory one.+ */+export function applyInputFilters(text, compiled, { role = "", substituteOnly = false } = {}) {+ const original = typeof text === "string" ? text : String(text ?? "");+ let current = original;+ for (const rule of Array.isArray(compiled) ? compiled : []) {+ if (rule.scope && rule.scope !== role) continue;+ if (rule.op === "s") {+ current = current.replace(rule.re, rule.replacement);+ continue;+ }+ if (substituteOnly) continue;+ const matched = rule.re.test(current);+ if ((rule.op === "d" && matched) || (rule.op === "k" && !matched)) {+ return { text: "", changed: false, dropped: true, ruleIndex: rule.index, op: rule.op };+ }+ }+ const finalText = current.trim();+ return {+ text: finalText,+ changed: finalText !== original,+ dropped: false,+ ruleIndex: -1,+ op: "",+ };+}++/** Doctor-facing summary of both filter knobs on a resolved plugin config. */+export function describeInputFilters(cfg = {}) {+ return INPUT_FILTER_KNOBS.map(({ key, env, label }) => {+ const configured = Array.isArray(cfg?.[key]) ? cfg[key] : [];+ const compiled = compileInputFilters(configured);+ const ops = { s: 0, d: 0, k: 0 };+ for (const rule of compiled.rules) ops[rule.op] += 1;+ const bits = [];+ if (ops.s) bits.push(`${ops.s} substitute`);+ if (ops.d) bits.push(`${ops.d} drop`);+ if (ops.k) bits.push(`${ops.k} keep-only`);+ const active = compiled.rules.length;+ return {+ key,+ env,+ label,+ total: configured.length,+ active,+ summary: `${active} rule${active === 1 ? "" : "s"}${bits.length ? ` (${bits.join(", ")})` : ""}`,+ errors: compiled.errors,+ };+ });+}diff --git a/examples/pi-experimental-context-management/shared/pending-queue.d.mts b/examples/pi-experimental-context-management/shared/pending-queue.d.mtsnew file mode 100644index 000000000..9051bdcdb--- /dev/null+++ b/examples/pi-experimental-context-management/shared/pending-queue.d.mts@@ -0,0 +1,10 @@+export function enqueue(type: string, sessionId: string, payload: Record<string, any>): Promise<{ ok: boolean; path?: string; error?: string }>;+export function listPending(): Promise<Array<{ filename: string; entry: Record<string, any> }>>;+export function replayPending(+ fetchJSON: (path: string, init?: any) => Promise<{ ok: boolean; status?: number; result?: any; error?: any }>,+ log: (stage: string, data?: any) => void,+): Promise<{ replayed: number; failed: number; skipped: number; deferred: number }>;+export function claimForReplay(filename: string): Promise<string | null>;+export function dequeue(filename: string): Promise<boolean>;+export function incrementRetry(filename: string, entry: Record<string, any>): Promise<boolean>;+export function cleanStale(): Promise<number>;diff --git a/examples/pi-experimental-context-management/shared/pending-queue.mjs b/examples/pi-experimental-context-management/shared/pending-queue.mjsnew file mode 100644index 000000000..38dccb1c8--- /dev/null+++ b/examples/pi-experimental-context-management/shared/pending-queue.mjs@@ -0,0 +1,487 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Local pending queue for offline resilience.+ *+ * When the OpenViking server is temporarily unreachable, write operations+ * (addMessage, commitSession) serialize their payloads to+ * `~/.openviking/pending/` as JSON files. The queue is replayed in small+ * batches, either at session-start (consuming retry budgets, with+ * maxRetries/TTL) or by a long-running drainer that passes+ * `consumeRetries: false` so transient failures stay retryable.+ *+ * Each file contains: { type, sessionId, payload, createdAt, retries, dedupKey }+ *+ * Config (env vars):+ * OPENVIKING_PENDING_DIR pending queue directory+ * (default: ~/.openviking/pending)+ * OPENVIKING_PENDING_MAX_RETRIES max retry attempts per item (default: 3)+ * OPENVIKING_PENDING_TTL_DAYS max age in days before stale cleanup+ * (default: 7)+ * OPENVIKING_PENDING_REPLAY_LIMIT max items replayed per session-start+ * (default: 50)+ */++import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from "node:fs/promises";+import { createHash } from "node:crypto";+import { join } from "node:path";+import { homedir } from "node:os";+import { isRetryableFailure } from "./retryable.mjs";++const DEFAULT_MAX_RETRIES = 3;+const DEFAULT_TTL_DAYS = 7;+const DEFAULT_REPLAY_LIMIT = 50;+const PROCESSING_STALE_MS = 10 * 60 * 1000;+const DEFAULT_PENDING_DIR = () => join(homedir(), ".openviking", "pending");++// Pending queue files may contain raw memory payload / transcript content.+// Use restrictive permissions explicitly so we don't depend on umask.+// - dir: 0o700 (owner: rwx; group/other: none)+// - file: 0o600 (owner: rw; group/other: none)+const PENDING_DIR_MODE = 0o700;+const PENDING_FILE_MODE = 0o600;++/**+ * Ensure the pending directory exists with 0o700 permissions. If the+ * directory was created by a previous version of this code (or by hand)+ * with looser permissions, best-effort chmod it on first use.+ */+async function ensurePendingDir(dir) {+ await mkdir(dir, { recursive: true, mode: PENDING_DIR_MODE });+ try {+ await chmod(dir, PENDING_DIR_MODE);+ } catch {+ // Best effort: chmod may fail on some platforms (e.g. Windows); not fatal.+ }+}++function getPendingDir() {+ return process.env.OPENVIKING_PENDING_DIR || DEFAULT_PENDING_DIR();+}++function getMaxRetries() {+ const v = parseInt(process.env.OPENVIKING_PENDING_MAX_RETRIES || "", 10);+ return Number.isFinite(v) && v >= 0 ? v : DEFAULT_MAX_RETRIES;+}++function getTTLDays() {+ const v = parseInt(process.env.OPENVIKING_PENDING_TTL_DAYS || "", 10);+ return Number.isFinite(v) && v >= 0 ? v : DEFAULT_TTL_DAYS;+}++function getReplayLimit() {+ const v = parseInt(process.env.OPENVIKING_PENDING_REPLAY_LIMIT || "", 10);+ return Number.isFinite(v) && v > 0 ? v : DEFAULT_REPLAY_LIMIT;+}++function stableStringify(value) {+ if (value === null || typeof value !== "object") return JSON.stringify(value);+ if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;+ const keys = Object.keys(value).sort();+ return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;+}++function makeDedupKey(type, sessionId, payload) {+ return createHash("sha256")+ .update(type)+ .update("\n")+ .update(sessionId)+ .update("\n")+ .update(stableStringify(payload))+ .digest("hex");+}++function pendingFilename(dedupKey, retries = 0) {+ return `${dedupKey}_${Math.max(0, Number(retries) || 0)}.json`;+}++function retryFilename(filename, retries) {+ const bare = filename.replace(/\.(json|processing)$/, "");+ const nextBare = /_\d+$/.test(bare)+ ? bare.replace(/_\d+$/, `_${retries}`)+ : `${bare}_${retries}`;+ return `${nextBare}.json`;+}++function processingFilename(filename) {+ return filename.replace(/\.json$/, ".processing");+}++function pendingFromProcessingFilename(filename) {+ return filename.replace(/\.processing$/, ".json");+}++function isRetryableReplayFailure(res) {+ return isRetryableFailure(res);+}++async function readEntry(dir, filename) {+ const raw = await readFile(join(dir, filename), "utf-8");+ return JSON.parse(raw);+}++async function findExistingByDedupKey(dir, dedupKey) {+ let files;+ try {+ files = await readdir(dir);+ } catch {+ return null;+ }++ // Fast path: filenames are `${dedupKey}_${retries}.json` (or+ // .processing). `dedupKey` is a sha256 hex produced by makeDedupKey+ // (no underscores), so `${dedupKey}_` is a unique prefix per key.+ // Filter on prefix BEFORE opening the file to avoid readFile ++ // JSON.parse on every entry in the directory on every enqueue call —+ // the previous implementation was O(n²) in queue size. Worst case here+ // is O(n) readdir entries, but only the (typically single) prefix+ // match actually gets opened and parsed.+ const prefix = `${dedupKey}_`;++ for (const f of files) {+ if (!f.startsWith(prefix)) continue;+ if (!f.endsWith(".json") && !f.endsWith(".processing")) continue;+ try {+ const entry = await readEntry(dir, f);+ if (entry?.dedupKey === dedupKey) return { filename: f, entry };+ } catch {+ // Corrupted file - ignore for dedup lookup.+ }+ }+ return null;+}++async function recoverStaleProcessing(dir) {+ let files;+ try {+ files = await readdir(dir);+ } catch {+ return 0;+ }++ const now = Date.now();+ let recovered = 0;+ for (const f of files) {+ if (!f.endsWith(".processing")) continue;+ const from = join(dir, f);+ try {+ const s = await stat(from);+ if (now - s.mtimeMs < PROCESSING_STALE_MS) continue;+ const to = join(dir, pendingFromProcessingFilename(f));+ await rename(from, to);+ recovered++;+ } catch {+ // Best effort. A concurrent process may have already handled it.+ }+ }+ return recovered;+}++/**+ * Enqueue a failed operation to local disk.+ *+ * @param {string} type - "addMessage" or "commitSession"+ * @param {string} sessionId - OV session ID+ * @param {object} payload - the data that failed to send+ * @param {object} options+ * @param {number} options.createdAt - optional queue timestamp override+ */+export async function enqueue(type, sessionId, payload, options = {}) {+ const dir = getPendingDir();+ const now = Number.isFinite(options.createdAt) ? options.createdAt : Date.now();+ const dedupKey = makeDedupKey(type, sessionId, payload);+ const filename = pendingFilename(dedupKey, 0);+ const entry = {+ type,+ sessionId,+ payload,+ createdAt: now,+ retries: 0,+ dedupKey,+ };++ try {+ await ensurePendingDir(dir);+ } catch (err) {+ return { ok: false, error: err?.message || String(err), dedupKey };+ }++ const existing = await findExistingByDedupKey(dir, dedupKey);+ if (existing) {+ return { ok: true, path: existing.filename, deduped: true, dedupKey };+ }++ try {+ await writeFile(join(dir, filename), JSON.stringify(entry), {+ encoding: "utf-8",+ flag: "wx",+ mode: PENDING_FILE_MODE,+ });+ return { ok: true, path: filename, dedupKey };+ } catch (err) {+ if (err?.code !== "EEXIST") {+ return { ok: false, error: err?.message || String(err), dedupKey };+ }+ }++ const duplicate = await findExistingByDedupKey(dir, dedupKey);+ if (duplicate) {+ return { ok: true, path: duplicate.filename, deduped: true, dedupKey };+ }+ return { ok: false, error: `pending file exists but dedup entry was not readable: ${filename}`, dedupKey };+}++/**+ * List all pending queue entries.+ * Returns array of { filename, entry } sorted by createdAt ascending.+ */+export async function listPending() {+ const dir = getPendingDir();+ let files;+ try {+ await recoverStaleProcessing(dir);+ files = await readdir(dir);+ } catch {+ return [];+ }++ const entries = [];+ for (const f of files) {+ if (!f.endsWith(".json")) continue;+ try {+ const entry = await readEntry(dir, f);+ entries.push({ filename: f, entry });+ } catch {+ // Corrupted file - skip.+ }+ }++ entries.sort((a, b) => (a.entry.createdAt || 0) - (b.entry.createdAt || 0));+ return entries;+}++/**+ * Atomically claim a pending file for replay. Only the process that successfully+ * renames the file may send the HTTP replay.+ */+export async function claimForReplay(filename) {+ if (!filename.endsWith(".json")) return null;+ const dir = getPendingDir();+ const claimed = processingFilename(filename);+ try {+ await rename(join(dir, filename), join(dir, claimed));+ return claimed;+ } catch {+ return null;+ }+}++/**+ * Release a claimed file back to the queue without consuming a retry. The+ * entry keeps its original filename, retry count, and createdAt position, so a+ * later run retries it as if this attempt never happened.+ */+export async function releaseClaim(claimedFilename) {+ if (!claimedFilename.endsWith(".processing")) return null;+ const dir = getPendingDir();+ const restored = pendingFromProcessingFilename(claimedFilename);+ try {+ await rename(join(dir, claimedFilename), join(dir, restored));+ return restored;+ } catch {+ return null;+ }+}++/**+ * Remove a pending entry after successful replay.+ */+export async function dequeue(filename) {+ const dir = getPendingDir();+ try {+ await unlink(join(dir, filename));+ return true;+ } catch {+ return false;+ }+}++/**+ * Increment retry count on a pending entry. Returns false if max retries exceeded.+ */+export async function incrementRetry(filename, entry) {+ const dir = getPendingDir();+ const maxRetries = getMaxRetries();+ entry.retries = (entry.retries || 0) + 1;++ if (entry.retries > maxRetries) {+ try {+ await unlink(join(dir, filename));+ } catch {+ // Best effort.+ }+ return false;+ }++ const newFilename = retryFilename(filename, entry.retries);+ // Atomic write: write to a unique temp file in the same directory, then+ // rename into place. Avoids leaving a half-written JSON if the process+ // crashes mid-write.+ const tmpFilename = `${newFilename}.tmp.${process.pid}.${Date.now()}`;+ try {+ await writeFile(join(dir, tmpFilename), JSON.stringify(entry), {+ encoding: "utf-8",+ flag: "wx",+ mode: PENDING_FILE_MODE,+ });+ await rename(join(dir, tmpFilename), join(dir, newFilename));+ await unlink(join(dir, filename)).catch(() => {});+ return true;+ } catch {+ await unlink(join(dir, tmpFilename)).catch(() => {});+ return false;+ }+}++/**+ * Clean up stale entries older than TTL.+ */+export async function cleanStale() {+ const ttlMs = getTTLDays() * 24 * 60 * 60 * 1000;+ const now = Date.now();+ const pending = await listPending();+ let cleaned = 0;++ for (const { filename, entry } of pending) {+ const age = now - (entry.createdAt || 0);+ if (age > ttlMs) {+ await dequeue(filename);+ cleaned++;+ }+ }+ return cleaned;+}++/**+ * Replay pending entries. Call this during session-start when the server is+ * healthy. Each run processes at most OPENVIKING_PENDING_REPLAY_LIMIT items so+ * a just-recovered server is not hit with an unbounded replay burst.+ *+ * @param {Function} fetchJSON - the configured fetchJSON from makeFetchJSON+ * @param {Function} log - logger function+ * @param {object} [options]+ * @param {boolean} [options.consumeRetries=true] - when false, retryable+ * failures release their claim instead of incrementing the retry count, so+ * a background drainer can keep retrying a transient failure without+ * burning the session-start retry budget. Exhausted and non-retryable+ * entries are deleted exactly as in the default mode.+ * @returns {{ replayed: number, failed: number, skipped: number, deferred: number }}+ */+export async function replayPending(fetchJSON, log, options = {}) {+ const consumeRetries = options.consumeRetries !== false;+ const pending = await listPending();++ if (pending.length === 0) {+ return { replayed: 0, failed: 0, skipped: 0, deferred: 0 };+ }++ const replayLimit = getReplayLimit();+ log("pending-queue", { count: pending.length, replayLimit, action: "replay-start" });++ let replayed = 0;+ let failed = 0;+ let skipped = 0;+ let deferred = 0;+ let processed = 0;++ for (const { filename, entry } of pending) {+ if (processed >= replayLimit) {+ deferred++;+ continue;+ }++ if ((entry.retries || 0) >= getMaxRetries()) {+ await dequeue(filename);+ skipped++;+ continue;+ }++ const claimedFilename = await claimForReplay(filename);+ if (!claimedFilename) {+ skipped++;+ continue;+ }+ processed++;++ let res;+ try {+ const encodedSid = encodeURIComponent(entry.sessionId);+ if (entry.type === "addMessage") {+ res = await fetchJSON(`/api/v1/sessions/${encodedSid}/messages`, {+ method: "POST",+ body: JSON.stringify(entry.payload),+ });+ } else if (entry.type === "commitSession") {+ res = await fetchJSON(`/api/v1/sessions/${encodedSid}/commit`, {+ method: "POST",+ body: JSON.stringify(entry.payload || {}),+ });+ } else {+ await dequeue(claimedFilename);+ skipped++;+ continue;+ }+ } catch {+ res = { ok: false };+ }++ if (entry.type === "commitSession") {+ log("pending-queue", {+ action: "commit-replay",+ sessionId: entry.sessionId,+ ok: Boolean(res?.ok),+ status: res?.result?.status || res?.status,+ trace_id: res?.traceId || res?.result?.trace_id,+ error: res?.ok ? undefined : res?.error?.message || res?.error?.code,+ });+ }++ if (res?.ok) {+ await dequeue(claimedFilename);+ replayed++;+ } else if (!isRetryableReplayFailure(res)) {+ await dequeue(claimedFilename);+ skipped++;+ } else {+ if (consumeRetries) {+ await incrementRetry(claimedFilename, entry);+ } else {+ const released = await releaseClaim(claimedFilename);+ log("pending-queue", {+ action: released ? "replay-deferred" : "release-failed",+ sessionId: entry.sessionId,+ type: entry.type,+ status: res?.result?.status || res?.status,+ retries: entry.retries || 0,+ });+ }+ failed++;+ if (entry.type === "addMessage") {+ deferred += Math.max(0, pending.length - processed);+ break;+ }+ }+ }++ const cleaned = await cleanStale();++ log("pending-queue", {+ action: "replay-done",+ replayed,+ failed,+ skipped,+ deferred,+ cleaned,+ });++ return { replayed, failed, skipped, deferred };+}diff --git a/examples/pi-experimental-context-management/shared/profile-inject.d.mts b/examples/pi-experimental-context-management/shared/profile-inject.d.mtsnew file mode 100644index 000000000..e8c95ef0c--- /dev/null+++ b/examples/pi-experimental-context-management/shared/profile-inject.d.mts@@ -0,0 +1,17 @@+export function buildProfileBlock(+ fetchJSON: (path: string, init?: any, options?: any) => Promise<{ ok: boolean; status?: number; result?: any; error?: any }>,+ totalBudgetTokens: number,+ actorPeerId?: string,+): Promise<null | {+ block: string;+ chars: number;+ tokens: number;+ profileUri: string;+ profileChars: number;+ prefCount: number;+ entCount: number;+ droppedPref: number;+ droppedEnt: number;+}>;++export function estimateTokens(text: string): number;diff --git a/examples/pi-experimental-context-management/shared/profile-inject.mjs b/examples/pi-experimental-context-management/shared/profile-inject.mjsnew file mode 100644index 000000000..3f601844a--- /dev/null+++ b/examples/pi-experimental-context-management/shared/profile-inject.mjs@@ -0,0 +1,294 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Session-start profile injection helper.+ *+ * Builds a <user-profile> + <available-memories> block from+ * viking://user/<space>/memories/profile.md+ * viking://user/<space>/memories/preferences/ (ls with abstracts)+ * viking://user/<space>/memories/entities/ (ls with abstracts)+ *+ * Budget enforced via the CJK-aware estimateTokens() below — codepoint >=+ * 0x3000 counts at 1.5 tokens, else chars/4. The estimator is exported so+ * callers (e.g. session-start.mjs) can log token counts that match what+ * the budget logic actually sees.+ *+ * Returned block is the *inner* content only (no outer <openviking-context>);+ * session-start.mjs composes the outer wrapper so the archive block can sit+ * alongside in a single context envelope.+ */++const USER_RESERVED_DIRS = new Set(["memories"]);+let _userSpaceCache = null;++/**+ * Mirrors auto-recall.mjs resolveScopeSpace for scope="user" (lines 123-147).+ * Duplicated rather than imported to avoid coupling session-start to+ * auto-recall's module-level fetchJSON closure.+ */+async function resolveUserSpace(fetchJSON, actorPeerId = "") {+ if (_userSpaceCache) return _userSpaceCache;++ let fallbackSpace = "default";+ const status = await fetchJSON("/api/v1/system/status");+ if (status.ok && typeof status.result?.user === "string" && status.result.user.trim()) {+ fallbackSpace = status.result.user.trim();+ }++ const lsRes = await fetchJSON(+ `/api/v1/fs/ls?uri=${encodeURIComponent("viking://user")}&output=original`,+ {},+ { actorPeerId },+ );+ if (lsRes.ok && Array.isArray(lsRes.result)) {+ const spaces = lsRes.result+ .filter((e) => e?.isDir)+ .map((e) => (typeof e.name === "string" ? e.name.trim() : ""))+ .filter((n) => n && !n.startsWith(".") && !USER_RESERVED_DIRS.has(n));+ if (spaces.length > 0) {+ if (spaces.includes(fallbackSpace)) { _userSpaceCache = fallbackSpace; return fallbackSpace; }+ if (spaces.includes("default")) { _userSpaceCache = "default"; return "default"; }+ if (spaces.length === 1) { _userSpaceCache = spaces[0]; return spaces[0]; }+ }+ }+ _userSpaceCache = fallbackSpace;+ return fallbackSpace;+}++/**+ * Token estimate that splits CJK from the rest. The rest of the plugin uses a+ * flat chars/4 heuristic, which silently undercounts CJK content by 4-6× and+ * makes a "5000 token budget" really worth ~1k real tokens for Chinese text.+ *+ * Rule:+ * - codepoint >= 0x3000 → CJK / Hiragana / Katakana / Hangul / CJK+ * punctuation / fullwidth ASCII; counted at 1.5 tokens/char (empirical+ * average for cl100k_base on Chinese; Claude's tokenizer is in the same+ * ballpark).+ * - everything else → chars/4 (the standard English-ish heuristic).+ *+ * Single linear pass, no dependencies. Errs on the side of overcounting CJK+ * by ~10-20% in the worst case (some common Chinese phrases compress better+ * than 1.5 tokens/char), which is the safe direction for budget enforcement.+ */+export function estimateTokens(text) {+ if (!text) return 0;+ let cjk = 0;+ for (let i = 0; i < text.length; i++) {+ if (text.charCodeAt(i) >= 0x3000) cjk++;+ }+ const other = text.length - cjk;+ return Math.ceil(cjk * 1.5 + other / 4);+}++/**+ * Convert a token budget to a max-chars budget that respects this content's+ * actual CJK density. Avoids the chars/4 trap where a "5000 token" sub-cap+ * yields 20000 chars of pure-CJK text → 30000 actual tokens (6× over).+ *+ * For an empty/missing string, returns 0.+ */+function tokensToCharsBudget(content, maxTokens) {+ if (!content) return 0;+ let cjk = 0;+ for (let i = 0; i < content.length; i++) {+ if (content.charCodeAt(i) >= 0x3000) cjk++;+ }+ const ratio = cjk / content.length;+ const tokensPerChar = ratio * 1.5 + (1 - ratio) * 0.25;+ return Math.floor(maxTokens / Math.max(tokensPerChar, 0.25));+}++async function readProfile(fetchJSON, profileUri, actorPeerId = "") {+ const res = await fetchJSON(+ `/api/v1/content/read?uri=${encodeURIComponent(profileUri)}`,+ {},+ { actorPeerId },+ );+ if (!res.ok || typeof res.result !== "string") return null;+ const trimmed = res.result.trim();+ return trimmed || null;+}++/**+ * Recursive ls of a memory directory, flattening to .md leaves.+ *+ * Memory layout under preferences/ and entities/ is two-level:+ * <dir>/<owner_name>/<topic>.md+ * so we use the server's recursive=true flag and filter to leaf .md files.+ * `rel_path` (e.g. "zhengxiao.wu/pr_workflow.md") is preserved as display name+ * to keep owner-namespacing visible and unambiguous when multiple owners exist.+ */+async function lsDir(fetchJSON, dirUri, actorPeerId = "") {+ const url = `/api/v1/fs/ls?uri=${encodeURIComponent(dirUri)}&output=agent&recursive=true&abs_limit=512&node_limit=512`;+ const res = await fetchJSON(url, {}, { actorPeerId });+ if (!res.ok || !Array.isArray(res.result)) return [];+ return res.result+ .filter((e) => !e.isDir)+ .map((e) => {+ const rel = typeof e.rel_path === "string" && e.rel_path+ ? e.rel_path+ : (typeof e.name === "string" ? e.name : "");+ return {+ name: rel,+ abstract: typeof e.abstract === "string" ? e.abstract.trim() : "",+ };+ })+ .filter((e) => e.name && e.name.endsWith(".md"))+ .sort((a, b) => a.name.localeCompare(b.name));+}++/**+ * When profile exceeds its sub-cap, keep the head (identity block + first+ * timeline events) and the tail (most-recent events), drop the middle. This+ * preserves both stable identity facts (top of file) and most-recent activity+ * (bottom of file) — only the noisy middle timeline is sacrificed.+ *+ * Layout:+ * <first HEAD_LINES lines>+ * ... [profile middle elided] ...+ * <as many trailing lines as fit in remaining budget>+ *+ * Falls back to head-only truncate when the file is too short to elide+ * meaningfully (<HEAD_LINES + 4 lines) or the budget is too tight to fit+ * both head and a useful tail.+ */+function elideProfile(content, maxTokens) {+ // Compute char budget from token budget using *this* content's CJK density,+ // not chars/4 — otherwise the truncated string can still blow the token cap+ // for CJK-heavy profiles (Copilot review point).+ const maxChars = Math.max(400, tokensToCharsBudget(content, maxTokens));+ if (estimateTokens(content) <= maxTokens) return content;++ const HEAD_LINES = 8;+ const ELLIPSIS = "\n... [profile middle elided] ...\n";+ const lines = content.split("\n");++ const fallbackHeadTruncate = () =>+ content.slice(0, maxChars).trimEnd() + "\n... [profile truncated]";++ if (lines.length <= HEAD_LINES + 4) return fallbackHeadTruncate();++ const head = lines.slice(0, HEAD_LINES).join("\n");+ const reserveForTail = maxChars - head.length - ELLIPSIS.length;+ if (reserveForTail < 200) return fallbackHeadTruncate();++ let tailChars = 0;+ let tailStart = lines.length;+ for (let i = lines.length - 1; i > HEAD_LINES; i--) {+ const lineLen = lines[i].length + 1;+ if (tailChars + lineLen > reserveForTail) break;+ tailChars += lineLen;+ tailStart = i;+ }+ if (tailStart >= lines.length - 1) return fallbackHeadTruncate();++ return `${head}${ELLIPSIS}${lines.slice(tailStart).join("\n")}`;+}++function formatListing(headerUri, entries, budgetTokens) {+ if (entries.length === 0) return { lines: [], used: 0, dropped: 0 };+ // Header is the full directory URI; child lines are relative paths so the+ // agent can reconstruct each leaf's full URI by concatenation while the+ // listing itself stays compact.+ const header = ` ${headerUri}/`;+ const headerTokens = estimateTokens(header);+ // If the header alone busts the budget, emit just a one-line stub instead+ // of silently violating the cap (Copilot review point).+ if (headerTokens > budgetTokens) {+ const stub = ` ${headerUri}/ (${entries.length} entries, budget too tight; use \`memory_recall\`)`;+ return { lines: [stub], used: estimateTokens(stub), dropped: entries.length };+ }+ const lines = [header];+ let used = headerTokens;+ for (let i = 0; i < entries.length; i++) {+ const e = entries[i];+ const desc = e.abstract+ ? ` — ${e.abstract.replace(/\s+/g, " ").slice(0, 200)}`+ : "";+ const line = ` - ${e.name}${desc}`;+ const tokens = estimateTokens(line);+ if (used + tokens > budgetTokens) {+ const remaining = entries.length - i;+ const tail = ` ... +${remaining} more, use \`memory_recall\``;+ const tailTokens = estimateTokens(tail);+ // Only emit the tail if it fits; otherwise the listing closes silently+ // rather than violating the cap to advertise its own truncation.+ if (used + tailTokens <= budgetTokens) {+ lines.push(tail);+ return { lines, used: used + tailTokens, dropped: remaining };+ }+ return { lines, used, dropped: remaining };+ }+ lines.push(line);+ used += tokens;+ }+ return { lines, used, dropped: 0 };+}++/**+ * Build the profile injection block.+ *+ * Returns null when neither profile.md nor either listing has any content.+ * The returned `block` is just the inner <user-profile>/<available-memories>+ * payload — the caller wraps it in <openviking-context source="...">.+ *+ * @param {Function} fetchJSON ov-session.mjs:makeFetchJSON closure+ * @param {number} totalBudgetTokens chars/4 budget, total for the whole block+ * @returns {Promise<null | {+ * block: string, chars: number, tokens: number, profileUri: string,+ * profileChars: number, prefCount: number, entCount: number,+ * droppedPref: number, droppedEnt: number,+ * }>}+ */+export async function buildProfileBlock(fetchJSON, totalBudgetTokens, actorPeerId = "") {+ const space = await resolveUserSpace(fetchJSON, actorPeerId);+ const profileUri = `viking://user/${space}/memories/profile.md`;+ const prefUri = `viking://user/${space}/memories/preferences`;+ const entUri = `viking://user/${space}/memories/entities`;++ const [profile, prefs, ents] = await Promise.all([+ readProfile(fetchJSON, profileUri, actorPeerId),+ lsDir(fetchJSON, prefUri, actorPeerId),+ lsDir(fetchJSON, entUri, actorPeerId),+ ]);++ if (!profile && prefs.length === 0 && ents.length === 0) return null;++ // Profile gets up to half the total budget; listings split the rest.+ // Sub-cap protects against a runaway profile blowing the listing budget.+ const profileBudget = Math.floor(totalBudgetTokens / 2);+ const profileTrunc = profile ? elideProfile(profile, profileBudget) : null;+ const profileTokens = estimateTokens(profileTrunc || "");++ const listingBudget = Math.max(0, totalBudgetTokens - profileTokens);+ const halfListing = Math.floor(listingBudget / 2);+ const prefBlock = formatListing(prefUri, prefs, halfListing);+ const entBudget = Math.max(0, listingBudget - prefBlock.used);+ const entBlock = formatListing(entUri, ents, entBudget);++ const lines = [];+ if (profileTrunc) {+ lines.push(`<user-profile uri="${profileUri}">`);+ lines.push(profileTrunc);+ lines.push(`</user-profile>`);+ }+ if (prefBlock.lines.length > 0 || entBlock.lines.length > 0) {+ lines.push(`<available-memories>`);+ lines.push(...prefBlock.lines);+ lines.push(...entBlock.lines);+ lines.push(`</available-memories>`);+ }++ const block = lines.join("\n");+ return {+ block,+ chars: block.length,+ tokens: estimateTokens(block),+ profileUri,+ profileChars: profile?.length ?? 0,+ prefCount: prefs.length,+ entCount: ents.length,+ droppedPref: prefBlock.dropped,+ droppedEnt: entBlock.dropped,+ };+}diff --git a/examples/pi-experimental-context-management/shared/recall-compress-core.mjs b/examples/pi-experimental-context-management/shared/recall-compress-core.mjsnew file mode 100644index 000000000..1ced4cf4d--- /dev/null+++ b/examples/pi-experimental-context-management/shared/recall-compress-core.mjs@@ -0,0 +1,206 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+import { createHash } from "node:crypto";+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";+import { dirname } from "node:path";++export const NO_RELEVANT_MEMORY = "NO_RELEVANT_MEMORY";+export const DIGEST_HEADER = "OpenViking memory digest:";+const COMPRESS_OK = "ok";+const COMPRESS_EMPTY = "empty";+const COMPRESS_FAILED = "failed";++// Medium-constraint prompt: state the goal and two structural floors, but no hard+// bullet-length contract. Hard per-bullet limits pin the digest to headline+// density; leaving it unconstrained lets small models rewrite long URIs into dead+// links, which the URI repair below cleans up.+export function buildRecallCompressionPrompt({ query, rendered, maxBullets = 6 }) {+ return `You are a memory relevance compressor utility.+Do not use any tools. Do not investigate. Only transform the given text.++User query:+${query}++Retrieved OpenViking context fragments:+${rendered}++Write a memory digest for a coding agent about to answer that query. Keep the+concrete facts (paths, identifiers, decisions, constraints); drop pleasantries+and conversational filler.++Format rules:+- Group related facts by topic, one bullet per topic, at most ${maxBullets} bullets.+- Start every bullet with "- ".+- End every bullet with its source, copied verbatim from the fragments above:+ "来源:viking://..." or "source: viking://...". Never edit, shorten, or invent a URI.+- Output the digest body only. No preamble, no closing remark.++If nothing above is relevant to the query, output exactly: ${NO_RELEVANT_MEMORY}`;+}++function editDistance(a, b) {+ if (a === b) return 0;+ const rows = a.length + 1;+ const cols = b.length + 1;+ let prev = Array.from({ length: cols }, (_, i) => i);+ for (let i = 1; i < rows; i += 1) {+ const cur = [i];+ for (let j = 1; j < cols; j += 1) {+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;+ cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);+ }+ prev = cur;+ }+ return prev[cols - 1];+}++function nearestUri(candidate, validUris) {+ let best = "";+ let bestDistance = Infinity;+ for (const uri of validUris) {+ const distance = editDistance(candidate, uri);+ if (distance < bestDistance) {+ best = uri;+ bestDistance = distance;+ }+ }+ // Only repair near-misses; an unrelated hallucination is dropped instead.+ const tolerance = Math.max(4, Math.floor(candidate.length * 0.25));+ return bestDistance <= tolerance ? best : "";+}++/**+ * Small models occasionally mangle long URIs. Snap every cited URI back onto the+ * set the server actually returned, and drop bullets whose citation cannot be+ * recovered so the digest never carries a dead link.+ */+export function repairDigestUris(digest, validUris = []) {+ const text = String(digest || "");+ if (!text) return "";+ const valid = validUris.map((uri) => String(uri || "").trim()).filter(Boolean);+ if (!valid.length) return text;+ const validSet = new Set(valid);++ const lines = [];+ for (const line of text.split(/\r?\n/)) {+ if (!line.trim().startsWith("- ")) {+ lines.push(line);+ continue;+ }+ let tokenized = line;+ for (const uri of [...valid].sort((a, b) => b.length - a.length)) {+ if (/\s/.test(uri)) tokenized = tokenized.split(uri).join(encodeURI(uri));+ }+ let dropped = false;+ const repaired = tokenized.replace(/viking:\/\/[^\s<>"')\]]+/g, (uri) => {+ let decoded = uri;+ try { decoded = decodeURI(uri); } catch { /* keep the original candidate */ }+ if (validSet.has(decoded)) return decoded;+ const nearest = nearestUri(decoded, valid);+ if (nearest) return nearest;+ dropped = true;+ return uri;+ });+ if (!dropped) lines.push(repaired);+ }+ return lines.join("\n").trim();+}++export function normalizeCompressedContext(raw, maxChars = 4000, maxBullets = 6) {+ const text = String(raw || "").trim();+ if (!text) return null;+ if (text.toUpperCase() === NO_RELEVANT_MEMORY) return "";+ const bullets = text.split(/\r?\n/)+ .map((line) => line.trim())+ .filter((line) => /^[-*]\s+/.test(line) && line.includes("viking://"))+ .slice(0, Math.max(1, maxBullets))+ .map((line) => `- ${line.replace(/^[-*]\s+/, "").slice(0, 500).trim()}`);+ if (!bullets.length) return null;+ return (`${DIGEST_HEADER}\n${bullets.join("\n")}`).slice(0, Math.max(100, maxChars));+}++export function recallDigestCacheKey({+ query = "",+ rendered = "",+ entries = [],+ maxInputChars = 18000,+ maxBullets = 6,+} = {}) {+ const uris = entries.map((entry) => String(entry?.uri || "").trim()).filter(Boolean).sort();+ const source = JSON.stringify({+ version: 2,+ query: String(query),+ rendered: String(rendered).slice(0, maxInputChars),+ uris,+ maxInputChars,+ maxBullets,+ });+ return createHash("sha256").update(source).digest("hex");+}++async function readCache(path) {+ if (!path) return null;+ try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }+}++async function writeCache(path, value) {+ if (!path) return;+ try {+ await mkdir(dirname(path), { recursive: true });+ const tmp = `${path}.tmp`;+ await writeFile(tmp, JSON.stringify(value));+ await rename(tmp, path);+ } catch { /* best effort */ }+}++export async function compressRecallContext({+ query,+ rendered,+ shortContext = rendered,+ entries = [],+ cfg = {},+ runCompressor,+ cachePath = "",+ now = 0,+}) {+ const input = String(rendered || "").trim();+ if (!input) return { status: COMPRESS_EMPTY, context: "" };+ const minChars = Math.max(0, Number(cfg.recallCompressMinInputChars ?? 1500));+ if (input.length < minChars) {+ return { status: COMPRESS_OK, context: String(shortContext ?? input).trim() };+ }++ const maxInputChars = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));+ const maxBullets = Math.max(1, Number(cfg.recallCompressMaxBullets || 6));+ const key = recallDigestCacheKey({+ query,+ rendered: input,+ entries,+ maxInputChars,+ maxBullets,+ });+ const cached = await readCache(cachePath);+ if (cached?.key === key && typeof cached.digest === "string") {+ const digest = normalizeCompressedContext(cached.digest, 4000, maxBullets);+ if (digest) return { status: COMPRESS_OK, context: digest };+ }++ const prompt = buildRecallCompressionPrompt({+ query,+ rendered: input.slice(0, maxInputChars),+ maxBullets,+ });+ const raw = await runCompressor(prompt);+ const normalized = normalizeCompressedContext(raw, 4000, maxBullets);+ if (normalized === null) return { status: COMPRESS_FAILED, context: "" };+ if (!normalized) return { status: COMPRESS_EMPTY, context: "" };++ const validUris = entries.map((entry) => entry?.uri).filter(Boolean);+ const repaired = repairDigestUris(normalized, validUris.length+ ? validUris+ : (input.match(/viking:\/\/[^\s<>"']+/g) || []));+ const digest = normalizeCompressedContext(repaired, 4000, maxBullets);+ if (!digest) return { status: COMPRESS_FAILED, context: "" };++ await writeCache(cachePath, { key, digest, updatedAt: now || 0 });+ return { status: COMPRESS_OK, context: digest };+}diff --git a/examples/pi-experimental-context-management/shared/recall-core.d.mts b/examples/pi-experimental-context-management/shared/recall-core.d.mtsnew file mode 100644index 000000000..e470aa237--- /dev/null+++ b/examples/pi-experimental-context-management/shared/recall-core.d.mts@@ -0,0 +1,13 @@+export function buildRecallBlock(+ fetchJSON: (path: string, init?: any, options?: any) => Promise<{ ok: boolean; status?: number; result?: any; error?: any }>,+ cfg: Record<string, any>,+ query: string,+ options?: {+ actorPeerId?: string;+ sessionId?: string;+ log?: (stage: string, data?: any) => void;+ },+): Promise<string | null>;++export function buildRecallEndpointBody(cfg?: Record<string, any>): Record<string, any>;+export function estimateTokens(text: string): number;diff --git a/examples/pi-experimental-context-management/shared/recall-core.mjs b/examples/pi-experimental-context-management/shared/recall-core.mjsnew file mode 100644index 000000000..72835de8f--- /dev/null+++ b/examples/pi-experimental-context-management/shared/recall-core.mjs@@ -0,0 +1,678 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";+import { homedir } from "node:os";+import { dirname, join } from "node:path";++import { compressRecallContext } from "./recall-compress-core.mjs";++const PREFERENCE_QUERY_RE = /prefer|preference|favorite|favourite|like|偏好|喜欢|爱好|更倾向/i;+const TEMPORAL_QUERY_RE = /when|what time|date|day|month|year|yesterday|today|tomorrow|last|next|什么时候|何时|哪天|几月|几年|昨天|今天|明天/i;+const QUERY_TOKEN_RE = /[a-z0-9一-龥]{2,}/gi;+const STOPWORDS = new Set([+ "what", "when", "where", "which", "who", "whom", "whose", "why", "how", "did", "does",+ "is", "are", "was", "were", "the", "and", "for", "with", "from", "that", "this", "your", "you",+]);+const USER_RESERVED_DIRS = new Set(["memories", "skills"]);+const SOURCES = [+ { type: "memory", uri: "viking://~/memories", bucket: "memories" },+ { type: "skill", uri: "viking://~/skills", bucket: "skills" },+];+const DEFAULT_CONTEXT_LIMIT = 10;+const DEFAULT_CONTEXT_MAX_TOKENS = 1600;+const DEFAULT_REWRITE_MAX_BULLETS = 6;+const CODING_QUOTA_WEIGHTS = {+ events: 1,+ entities: 2,+ preferences: 1,+ experiences: 1,+ resources: 3,+ skills: 2,+};++let userSpaceCache = "";++export function estimateTokens(text) {+ return text ? Math.ceil(String(text).length / 4) : 0;+}++function scaleQuotas(limit, weights) {+ const slots = Math.max(1, Math.floor(Number(limit) || DEFAULT_CONTEXT_LIMIT));+ const order = Object.keys(weights);+ const quotas = Object.fromEntries(order.map((key) => [key, 0]));+ if (slots < order.length) {+ for (const key of order) quotas[key] = 1;+ return quotas;+ }++ for (const key of order) quotas[key] = 1;+ const totalWeight = Object.values(weights).reduce((sum, weight) => sum + weight, 0);+ const ideals = Object.fromEntries(+ order.map((key) => [key, slots * weights[key] / totalWeight]),+ );+ while (order.reduce((sum, key) => sum + quotas[key], 0) < slots) {+ const key = order.reduce((best, candidate) => (+ ideals[candidate] - quotas[candidate] > ideals[best] - quotas[best]+ ? candidate+ : best+ ));+ quotas[key] += 1;+ }+ return quotas;+}++function legacyMemoryQuotas(limit) {+ return {+ ...scaleQuotas(limit, { events: 10, entities: 10, preferences: 3 }),+ experiences: 0,+ };+}++function codingQuotas(limit) {+ return scaleQuotas(limit, CODING_QUOTA_WEIGHTS);+}++export function buildRecallEndpointBody(cfg = {}) {+ const limit = Math.max(Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT), 1);+ const body = {+ query: "",+ quotas: legacyMemoryQuotas(limit),+ max_chars: Math.max(Number(cfg.recallMaxContentChars || 0) * limit, 1000),+ min_score: Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35,+ render: true,+ };+ if (cfg.recallPeerScope === "actor") body.peer_scope = "actor";+ return body;+}++/**+ * Body for the server-side context face. The plugin declares intent (coding+ * purpose, budget, session) and leaves the mechanics — quota ratios, tier+ * degradation, cross-turn dedup — to the server's defaults.+ */+export function buildContextSearchBody(cfg = {}, options = {}) {+ const rewriteMode = String(cfg.recallRewrite || "off").toLowerCase();+ const limit = Math.max(1, Math.floor(Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT)));+ const maxTokens = Math.max(+ 64,+ Math.floor(Number(cfg.recallMaxTokens || DEFAULT_CONTEXT_MAX_TOKENS)),+ );+ const body = {+ query: "",+ mode: "context",+ purpose: "coding",+ score_threshold: Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35,+ };+ const limitConfigured = cfg.recallLimitConfigured === true;+ const maxTokensConfigured = cfg.recallMaxTokensConfigured === true;+ if (limitConfigured) body.quotas = codingQuotas(limit);+ if (maxTokensConfigured) body.max_tokens = maxTokens;+ if (cfg.recallPeerScope === "actor") body.peer_scope = "actor";++ const sessionId = String(options.sessionId || "").trim();+ if (sessionId) {+ body.session_id = sessionId;+ const queryExpansionConfigured = cfg.recallQueryExpansionConfigured === true;+ if (queryExpansionConfigured) {+ body.query_expansion = cfg.recallQueryExpansion === "off" ? "off" : "auto";+ }+ const dedupTurns = Number(cfg.recallDedupTurns);+ const resolvedDedupTurns = Number.isFinite(dedupTurns)+ ? Math.max(0, Math.floor(dedupTurns))+ : 5;+ if (resolvedDedupTurns > 0) body.dedup_turns = resolvedDedupTurns;+ }++ const excludeUris = Array.isArray(options.excludeUris) ? options.excludeUris.slice(0, 200) : [];+ if (excludeUris.length) body.exclude_uris = excludeUris;++ if (rewriteMode === "server") body.rewrite = true;+ else if (rewriteMode === "auto" && !options.localCompressorAvailable) body.rewrite = "auto";+ const rewriteMaxBullets = Math.max(+ 1,+ Math.floor(Number(cfg.recallCompressMaxBullets || DEFAULT_REWRITE_MAX_BULLETS)),+ );+ const rewriteMaxBulletsConfigured = cfg.recallCompressMaxBulletsConfigured === true;+ if (body.rewrite !== undefined && rewriteMaxBulletsConfigured) {+ body.rewrite_max_bullets = rewriteMaxBullets;+ }+ return body;+}++// The server pipeline is serial and each optional stage has its own fuse. A+// request is aborted client-side unless its deadline covers every stage it+// asked for, and aborting discards the whole response rather than just the+// stage that ran long.+//+// session_id -> query expansion (retrieval.recall_intent_timeout_s, 5s)+// always -> retrieval, body reads, budget planning+// rewrite -> digest (retrieval.recall_rewrite_timeout_s, 30s)+//+// Both budgets stay inside the 60s prompt-hook allowance, the rewrite one with+// a quarter to spare.+const EXPANSION_REQUEST_TIMEOUT_MS = 15000;+const SERVER_REWRITE_REQUEST_TIMEOUT_MS = 45000;++/**+ * HTTP deadline for one context request, or undefined to keep the caller's own.+ *+ * Derived from the request body, because the body is what states which server+ * stages will run: reading `cfg` alone cannot tell a bare retrieval from one+ * that also spends the expansion or rewrite fuse.+ */+export function contextRequestTimeoutMs(cfg = {}, body = {}) {+ const wantsRewrite = body.rewrite !== undefined;+ // `query_expansion` defaults to "auto" server-side, so only an explicit "off"+ // takes the expansion fuse back out of the budget.+ const wantsExpansion = Boolean(body.session_id) && body.query_expansion !== "off";+ const configured = Number(cfg.recallContextTimeoutMs);+ if (Number.isFinite(configured) && configured > 0) return Math.max(1000, Math.floor(configured));+ if (!wantsRewrite && !wantsExpansion) return undefined;+ const floor = wantsRewrite ? SERVER_REWRITE_REQUEST_TIMEOUT_MS : EXPANSION_REQUEST_TIMEOUT_MS;+ return Math.max(Number(cfg.timeoutMs) || 0, floor);+}++/**+ * Strip the context-face fields a pre-context server rejects, converting the+ * token budget back to v1's character budget.+ */+export function downgradeToRecallBody(contextBody = {}, cfg = {}) {+ const body = buildRecallEndpointBody(cfg);+ body.query = contextBody.query || "";+ body.max_chars = Math.max(1000, Math.floor(Number(contextBody.max_tokens || 1600) * 4));+ if (contextBody.peer_scope) body.peer_scope = contextBody.peer_scope;+ return body;+}++function clampScore(v) {+ if (typeof v !== "number" || Number.isNaN(v)) return 0;+ return Math.max(0, Math.min(1, v));+}++function buildQueryProfile(query) {+ const text = query.trim();+ const allTokens = text.toLowerCase().match(QUERY_TOKEN_RE) || [];+ return {+ tokens: allTokens.filter((t) => !STOPWORDS.has(t)),+ wantsPreference: PREFERENCE_QUERY_RE.test(text),+ wantsTemporal: TEMPORAL_QUERY_RE.test(text),+ };+}++function lexicalOverlapBoost(tokens, text) {+ if (tokens.length === 0 || !text) return 0;+ const haystack = ` ${text.toLowerCase()} `;+ let matched = 0;+ for (const token of tokens.slice(0, 8)) {+ if (haystack.includes(token)) matched += 1;+ }+ return Math.min(0.2, (matched / Math.min(tokens.length, 4)) * 0.2);+}++function rankItem(item, profile) {+ const base = clampScore(item.score);+ const abstract = (item.abstract || item.overview || "").trim();+ const cat = (item.category || "").toLowerCase();+ const uri = (item.uri || "").toLowerCase();+ const leafBoost = (item.level === 2 || uri.endsWith(".md")) ? 0.12 : 0;+ const eventBoost = profile.wantsTemporal && (cat === "events" || uri.includes("/events/")) ? 0.1 : 0;+ const prefBoost = profile.wantsPreference && (cat === "preferences" || uri.includes("/preferences/")) ? 0.08 : 0;+ const overlapBoost = lexicalOverlapBoost(profile.tokens, `${item.uri} ${abstract}`);+ return base + leafBoost + eventBoost + prefBoost + overlapBoost;+}++function isEventOrCaseItem(item) {+ const cat = (item.category || "").toLowerCase();+ const uri = (item.uri || "").toLowerCase();+ return cat === "events" || cat === "cases" || uri.includes("/events/") || uri.includes("/cases/");+}++function dedupeItems(items) {+ const seen = new Set();+ const out = [];+ for (const item of items) {+ const key = isEventOrCaseItem(item)+ ? `uri:${item.uri}`+ : ((item.abstract || item.overview || "").trim().toLowerCase() || `uri:${item.uri}`);+ if (seen.has(key)) continue;+ seen.add(key);+ out.push(item);+ }+ return out;+}++async function resolveUserSpace(fetchJSON, actorPeerId = "") {+ if (userSpaceCache) return userSpaceCache;++ let fallbackSpace = "default";+ const status = await fetchJSON("/api/v1/system/status");+ if (status.ok && typeof status.result?.user === "string" && status.result.user.trim()) {+ fallbackSpace = status.result.user.trim();+ }++ const lsRes = await fetchJSON(+ `/api/v1/fs/ls?uri=${encodeURIComponent("viking://user")}&output=original`,+ {},+ { actorPeerId },+ );+ if (lsRes.ok && Array.isArray(lsRes.result)) {+ const spaces = lsRes.result+ .filter((e) => e?.isDir)+ .map((e) => (typeof e.name === "string" ? e.name.trim() : ""))+ .filter((n) => n && !n.startsWith(".") && !USER_RESERVED_DIRS.has(n));+ if (spaces.length > 0) {+ if (spaces.includes(fallbackSpace)) { userSpaceCache = fallbackSpace; return fallbackSpace; }+ if (spaces.includes("default")) { userSpaceCache = "default"; return "default"; }+ if (spaces.length === 1) { userSpaceCache = spaces[0]; return spaces[0]; }+ }+ }+ userSpaceCache = fallbackSpace;+ return fallbackSpace;+}++async function resolveTargetUri(fetchJSON, targetUri, actorPeerId = "") {+ const trimmed = targetUri.trim().replace(/\/+$/, "");+ // viking://~ is the home alias: the server expands it to the caller's own user+ // space, so it needs no client-side rewrite.+ if (trimmed === "viking://~" || trimmed.startsWith("viking://~/")) return trimmed;+ // Legacy compat: uid-less viking://user/<reserved> URIs may still sit in plugin+ // configs. Newer servers reject them, so rewrite to an explicit-uid URI here.+ const m = trimmed.match(/^viking:\/\/user(?:\/(.*))?$/);+ if (!m) return trimmed;+ const rawRest = (m[1] ?? "").trim();+ if (!rawRest) return trimmed;+ const parts = rawRest.split("/").filter(Boolean);+ if (parts.length === 0) return trimmed;+ if (!USER_RESERVED_DIRS.has(parts[0])) return trimmed;+ const space = await resolveUserSpace(fetchJSON, actorPeerId);+ return `viking://user/${space}/${parts.join("/")}`;+}++async function searchOneSource(fetchJSON, query, source, limit, actorPeerId = "") {+ const resolvedUri = await resolveTargetUri(fetchJSON, source.uri, actorPeerId);+ const body = { query, target_uri: resolvedUri, limit, score_threshold: 0 };+ const res = await fetchJSON("/api/v1/search/find", {+ method: "POST",+ body: JSON.stringify(body),+ }, { actorPeerId });+ if (!res.ok) return [];+ const items = res.result?.[source.bucket] || [];+ return items.map((item) => ({ ...item, _sourceType: source.type }));+}++async function searchAllSources(fetchJSON, query, perSourceLimit, actorPeerId = "", log = () => {}) {+ const results = await Promise.all(+ SOURCES.map((src) => searchOneSource(fetchJSON, query, src, perSourceLimit, actorPeerId)),+ );+ const all = results.flat();+ log("recall_search_summary", {+ counts: SOURCES.map((src, i) => ({ type: src.type, uri: src.uri, count: results[i].length })),+ total: all.length,+ });+ return all;+}++async function resolveItemContent(fetchJSON, item, cfg, actorPeerId = "") {+ let content;++ if (cfg.recallPreferAbstract && (item.abstract || item.overview || "").trim()) {+ content = (item.abstract || item.overview).trim();+ } else if (item.level === 2) {+ try {+ const res = await fetchJSON(+ `/api/v1/content/read?uri=${encodeURIComponent(item.uri)}`,+ {},+ { actorPeerId },+ );+ const body = res.ok && typeof res.result === "string" ? res.result.trim() : "";+ content = body || (item.abstract || item.overview || "").trim() || item.uri;+ } catch {+ content = (item.abstract || item.overview || "").trim() || item.uri;+ }+ } else {+ content = (item.abstract || item.overview || "").trim() || item.uri;+ }++ const maxChars = Math.max(50, Number(cfg.recallMaxContentChars || 500));+ if (content.length > maxChars) content = `${content.slice(0, maxChars)}...`;+ return content;+}++async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId = "", log = () => {}) {+ if (items.length === 0) return null;++ let budgetRemaining = Math.max(200, Number(cfg.recallTokenBudget || 2000));+ const lines = [+ "<openviking-context>",+ "Relevant context from OpenViking. Use the read MCP tool to expand URIs.",+ ];+ let contentCount = 0;+ let hintCount = 0;++ for (const item of items) {+ const score = (clampScore(item.score) * 100).toFixed(0);+ const uriLine = `- [${item._sourceType} ${score}%] ${item.uri}`;++ if (budgetRemaining > 0) {+ const content = await resolveItemContent(fetchJSON, item, cfg, actorPeerId);+ const contentLine = `- [${item._sourceType} ${score}%] ${content}`;+ const lineTokens = estimateTokens(contentLine);++ if (lineTokens > budgetRemaining && contentCount > 0) {+ lines.push(uriLine);+ hintCount++;+ } else {+ lines.push(contentLine);+ budgetRemaining -= lineTokens;+ contentCount++;+ }+ } else {+ lines.push(uriLine);+ hintCount++;+ }+ }++ lines.push("</openviking-context>");++ const budgetUsed = Math.max(200, Number(cfg.recallTokenBudget || 2000)) - budgetRemaining;+ log("recall_injection_built", {+ contentItems: contentCount,+ hintItems: hintCount,+ budgetUsed,+ budgetTotal: Math.max(200, Number(cfg.recallTokenBudget || 2000)),+ });++ return lines.join("\n");+}++const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;++function stateFile(name) {+ const override = String(process.env.OPENVIKING_STATE_DIR || "").trim();+ return override ? join(override, name) : join(homedir(), ".openviking", "state", name);+}++async function readJsonFile(path) {+ try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }+}++async function writeJsonFile(path, value) {+ try {+ await mkdir(dirname(path), { recursive: true });+ const tmp = `${path}.tmp`;+ await writeFile(tmp, JSON.stringify(value));+ await rename(tmp, path);+ } catch { /* best effort */ }+}++/**+ * Hooks are one-shot processes, so "this server has no context face" has to be+ * remembered on disk or every turn pays for a rejected request.+ */+export async function isContextFaceLegacy(path = stateFile("context-face.json"), now = Date.now()) {+ const cached = await readJsonFile(path);+ return Boolean(cached?.legacyUntil && Number(cached.legacyUntil) > now);+}++export async function markContextFaceLegacy(path = stateFile("context-face.json"), now = Date.now()) {+ await writeJsonFile(path, { legacyUntil: now + LEGACY_CACHE_TTL_MS });+}++/**+ * A `peer_scope` the server rejects is remembered the same way, but unlike the+ * context face this one is not a silent capability probe: dropping the field+ * widens recall from the caller's own peer to the whole user root, so doctor+ * reads this file back and warns.+ */+export function peerScopeMemoPath() {+ return stateFile("peer-scope.json");+}++export async function readPeerScopeDowngrade(path = peerScopeMemoPath(), now = Date.now()) {+ const cached = await readJsonFile(path);+ if (!cached?.legacyUntil || Number(cached.legacyUntil) <= now) return null;+ return cached;+}++export async function markPeerScopeDowngrade(scope, status, path = peerScopeMemoPath(), now = Date.now()) {+ await writeJsonFile(path, {+ legacyUntil: now + LEGACY_CACHE_TTL_MS,+ scope: String(scope || ""),+ status: Number(status) || 0,+ at: now,+ });+}++function looksLikeUnknownField(res) {+ const text = JSON.stringify(res?.error ?? res?.result ?? res?.detail ?? "").toLowerCase();+ return text.includes("extra") || text.includes("mode") || text.includes("unexpected");+}++function wrapContext(body) {+ return [+ "<openviking-context>",+ "Relevant memory from OpenViking. Use the search/read MCP tools to expand URIs.",+ body,+ "</openviking-context>",+ ].join("\n");+}++/**+ * Server-assembled context: the context face when the deployment has it, else+ * the deprecated /recall preset. Returns the injection block, "" when there was+ * nothing relevant, or null when no server-side path was usable at all.+ */+export async function buildServerAssembledBlock(fetchJSON, cfg, query, options = {}) {+ const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";+ const log = options.log || (() => {});++ const block = await recallViaContextFace(fetchJSON, cfg, query, { ...options, actorPeerId }, log);+ if (block !== null) return block;+ return recallViaEndpoint(fetchJSON, cfg, query, actorPeerId, log);+}++/**+ * Raw server-assembled context, or null when the deployment has no context face.+ * Returns `{ rendered, entries, digest, stats }` — callers that need the entries+ * (their own compression, their own envelope) use this instead of the block+ * builders below.+ */+export async function fetchAssembledContext(fetchJSON, cfg, query, options = {}) {+ const actorPeerId = options.actorPeerId || "";+ const log = options.log || (() => {});+ if (await isContextFaceLegacy(options.legacyCachePath)) return null;++ const body = buildContextSearchBody(cfg, options);+ body.query = query;+ const res = await fetchJSON("/api/v1/search/search", {+ method: "POST",+ body: JSON.stringify(body),+ }, { actorPeerId, timeoutMs: contextRequestTimeoutMs(cfg, body) });++ if (!res.ok) {+ const status = res.status || 0;+ if ((status === 400 || status === 422) && looksLikeUnknownField(res)) {+ await markContextFaceLegacy(options.legacyCachePath);+ log("recall_context_face_unsupported", { status });+ } else {+ log("recall_context_face_error", { status });+ }+ return null;+ }++ const result = res.result || {};+ const stats = result.stats || {};+ log("recall_context_assembled", {+ entries: Array.isArray(result.entries) ? result.entries.length : 0,+ usedTokens: stats.used_tokens || 0,+ tiers: stats.tier_counts || {},+ rewrite: stats.rewrite || "off",+ });+ return {+ rendered: String(result.rendered || "").trim(),+ entries: Array.isArray(result.entries) ? result.entries : [],+ digest: String(result.digest || "").trim(),+ stats,+ };+}++/**+ * Entry field compatibility: the context face returns `category`/`text`, while+ * the deprecated /recall v1 shape used `type` plus `content`/`summary`.+ */+export function normalizeContextEntry(entry = {}) {+ return {+ uri: String(entry.uri || "").trim(),+ category: String(entry.category || entry.type || "memory").trim() || "memory",+ detail: String(entry.detail || entry.mode || "").trim(),+ score: Number(entry.score) || 0,+ text: String(+ entry.text || entry.content || entry.summary || entry.abstract || entry.uri || "",+ ).trim(),+ };+}++async function recallViaContextFace(fetchJSON, cfg, query, options, log) {+ const assembled = await fetchAssembledContext(fetchJSON, cfg, query, { ...options, log });+ if (assembled === null) return null;++ const { rendered, entries } = assembled;+ let digest = assembled.digest;+ const mode = String(cfg.recallRewrite || "off").toLowerCase();+ if (String(assembled.stats?.rewrite || "").toLowerCase() === "no_relevant") {+ log("recall_server_compression", { status: "empty" });+ return "";+ }+ const wantsLocal = mode === "client" || (mode === "auto" && !digest);+ if (wantsLocal && rendered && typeof options.runCompressor === "function") {+ try {+ const compression = await compressRecallContext({+ query,+ rendered,+ entries,+ cfg,+ runCompressor: options.runCompressor,+ cachePath: options.digestCachePath || stateFile("recall-digest.json"),+ now: Date.now(),+ });+ log("recall_local_compression", { status: compression.status });+ if (compression.status === "ok") digest = compression.context;+ if (compression.status === "empty") return "";+ } catch (err) {+ log("recall_local_compression_failed", { error: String(err?.message || err) });+ }+ }++ const injected = digest || rendered;+ if (!injected) return "";+ return wrapContext(injected);+}++async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log = () => {}) {+ const body = buildRecallEndpointBody(cfg);+ body.query = query;+ const res = await postRecall(fetchJSON, body, { actorPeerId, log });+ if (!res.ok) {+ log("recall_endpoint_fallback", { status: res.status || 0 });+ return null;+ }+ const rendered = String(res.result?.rendered || "").trim();+ if (!rendered) return "";+ return wrapContext(rendered);+}++export async function postRecall(fetchJSON, body, opts = {}) {+ const actorPeerId = opts.actorPeerId || "";+ const log = opts.log || (() => {});+ const memoPath = opts.peerScopeMemoPath;+ const request = { ...body };++ // A remembered downgrade is still a downgrade: recall runs wider than the+ // caller asked for, so the memo doubles as the doctor's evidence.+ if (request.peer_scope && await readPeerScopeDowngrade(memoPath)) {+ delete request.peer_scope;+ }++ const res = await fetchJSON("/api/v1/search/recall", {+ method: "POST",+ body: JSON.stringify(request),+ }, { actorPeerId });+ if (!request.peer_scope || (res.status !== 400 && res.status !== 422)) {+ return res;+ }+ // Only an unknown-field rejection means "this server predates peer_scope".+ // Retrying every other 400/422 without it silently widens the search from+ // the caller's own peer to the whole user root.+ if (!looksLikeUnknownField(res)) {+ log("recall_peer_scope_error", { status: res.status || 0 });+ return res;+ }++ const downgraded = { ...request };+ delete downgraded.peer_scope;+ await markPeerScopeDowngrade(String(request.peer_scope), res.status || 0, memoPath);+ log("recall_peer_scope_downgrade", { status: res.status || 0 });+ return fetchJSON("/api/v1/search/recall", {+ method: "POST",+ body: JSON.stringify(downgraded),+ }, { actorPeerId });+}++/**+ * Recall, plus whatever is still filed under the peer this workspace used+ * before the identity rule changed.+ *+ * Under the default `peer_scope: "all"` this costs nothing: the server's own+ * sweep of `{user_root}/peers` already reaches the old peer's memories. Under+ * `"actor"` that sweep is off by definition, so the old peer is asked for+ * separately — as itself, which is both cheaper and wider than a bare+ * cross-peer read (that would need the user id, and reaches memories only).+ */+export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {+ const primary = await recallForPeer(fetchJSON, cfg, query, options);++ const legacyPeerId = String(options.legacyPeerId || "").trim();+ const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";+ if (cfg.recallPeerScope !== "actor" || !legacyPeerId || legacyPeerId === actorPeerId) return primary;++ const log = options.log || (() => {});+ const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });+ if (!legacy) return primary;+ log("recall_legacy_peer_hit", { legacyPeerId });+ return primary ? `${primary}\n${legacy}` : legacy;+}++async function recallForPeer(fetchJSON, cfg, query, options = {}) {+ const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";+ const log = options.log || (() => {});+ const trimmed = String(query || "").trim();+ if (!trimmed) return null;++ // Assembly happens server-side when the deployment offers the context face;+ // older servers fall through to /recall, then to raw find.+ const serverBlock = await buildServerAssembledBlock(fetchJSON, cfg, trimmed, {+ ...options,+ actorPeerId,+ log,+ });+ if (serverBlock !== null) return serverBlock || null;++ const recallLimit = Math.max(1, Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT));+ const perSourceLimit = Math.max(recallLimit * 2, 8);+ const raw = await searchAllSources(fetchJSON, trimmed, perSourceLimit, actorPeerId, log);+ if (raw.length === 0) return null;++ const profile = buildQueryProfile(trimmed);+ const scoreThreshold = Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35;+ const filtered = raw.filter((it) => clampScore(it.score) >= scoreThreshold);+ filtered.sort((a, b) => rankItem(b, profile) - rankItem(a, profile));+ const picked = dedupeItems(filtered).slice(0, recallLimit);+ log("recall_picked", {+ rawCount: raw.length,+ filteredCount: filtered.length,+ pickedCount: picked.length,+ items: picked.map((it) => ({ type: it._sourceType, uri: it.uri, score: clampScore(it.score) })),+ });++ if (picked.length === 0) return null;+ return buildFallbackInjectionBlock(fetchJSON, picked, cfg, actorPeerId, log);+}diff --git a/examples/pi-experimental-context-management/shared/retryable.mjs b/examples/pi-experimental-context-management/shared/retryable.mjsnew file mode 100644index 000000000..8be4b14e8--- /dev/null+++ b/examples/pi-experimental-context-management/shared/retryable.mjs@@ -0,0 +1,9 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+export function isRetryableFailure(result) {+ if (!result || result.ok) return false;+ const status = Number(result.status || 0);+ if (!status || status === 408 || status === 429 || status >= 500) {+ return true;+ }+ return status === 409 && result.error?.details?.retryable === true;+}diff --git a/examples/pi-experimental-context-management/shared/session-model.d.mts b/examples/pi-experimental-context-management/shared/session-model.d.mtsnew file mode 100644index 000000000..82a340dbb--- /dev/null+++ b/examples/pi-experimental-context-management/shared/session-model.d.mts@@ -0,0 +1,3 @@+export function deriveHarnessSessionId(prefix: string, sessionId: string, suffix?: string): string;+export function deriveCodexSessionId(codexSessionId: string): string;+export function isBypassed(cfg: Record<string, any>, options?: { sessionId?: string; cwd?: string }): boolean;diff --git a/examples/pi-experimental-context-management/shared/session-model.mjs b/examples/pi-experimental-context-management/shared/session-model.mjsnew file mode 100644index 000000000..b6496a113--- /dev/null+++ b/examples/pi-experimental-context-management/shared/session-model.mjs@@ -0,0 +1,57 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Shared OpenViking session-id helpers for memory plugin harnesses.+ */++/**+ * Glob -> RegExp. Minimal implementation: supports `*`, `**`, and literals.+ */+function globToRe(glob) {+ let re = "^";+ for (let i = 0; i < glob.length; i++) {+ const c = glob[i];+ if (c === "*") {+ if (glob[i + 1] === "*") { re += ".*"; i++; }+ else re += "[^/]*";+ } else if (/[.+?^${}()|[\]\\]/.test(c)) {+ re += "\\" + c;+ } else {+ re += c;+ }+ }+ re += "$";+ return new RegExp(re);+}++export function isBypassed(cfg, { sessionId, cwd } = {}) {+ if (cfg.bypassSession) return true;+ const patterns = cfg.bypassSessionPatterns || [];+ if (patterns.length === 0) return false;+ const haystacks = [sessionId, cwd].filter(Boolean);+ for (const pat of patterns) {+ const re = globToRe(pat);+ if (haystacks.some((h) => re.test(h))) return true;+ }+ return false;+}++function safeId(value, replacement = "_") {+ return String(value || "unknown").replace(/[^A-Za-z0-9._-]/g, replacement);+}++export function deriveHarnessSessionId(prefix, sessionId, suffix = "") {+ if (!prefix || typeof prefix !== "string") {+ throw new Error("deriveHarnessSessionId requires a non-empty prefix");+ }+ if (!sessionId || typeof sessionId !== "string") {+ throw new Error("deriveHarnessSessionId requires a non-empty sessionId");+ }+ const base = `${prefix}${sessionId}`;+ if (!suffix) return base;+ const normalized = String(suffix).replace(/:/g, "-").replace(/[^A-Za-z0-9._-]/g, "-");+ return `${base}__${normalized}`;+}++export function deriveCodexSessionId(codexSessionId) {+ return `cx-${safeId(codexSessionId, "_")}`;+}diff --git a/examples/pi-experimental-context-management/shared/setup-wizard.mjs b/examples/pi-experimental-context-management/shared/setup-wizard.mjsnew file mode 100644index 000000000..a49dbe7db--- /dev/null+++ b/examples/pi-experimental-context-management/shared/setup-wizard.mjs@@ -0,0 +1,114 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Interactive ovcli.conf setup wizard shared by the OpenViking memory plugins.+ *+ * Lets a pure-marketplace install (no installer script) configure the server+ * URL and API key that both the lifecycle hooks and the stdio MCP proxy read:+ *+ * node <plugin>/scripts/setup.mjs+ *+ * Conventions: show current values, keep existing secrets on empty input,+ * merge-write (never drop unknown fields), back up the previous file, 0600.+ */++import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";+import { dirname } from "node:path";+import { createInterface } from "node:readline/promises";+import { loadCredentialFiles } from "./credentials.mjs";++const CLOUD_URL = "https://api.vikingdb.cn-beijing.volces.com/openviking";+const LOCAL_URL = "http://127.0.0.1:1933";++function maskSecret(value) {+ const s = String(value || "");+ if (!s) return "(not set)";+ if (s.length <= 8) return "****";+ return `${s.slice(0, 4)}…${s.slice(-4)} (${s.length} chars)`;+}++function readJsonSafe(path) {+ try {+ return JSON.parse(readFileSync(path, "utf-8"));+ } catch {+ return {};+ }+}++export async function runSetupWizard({+ input = process.stdin,+ output = process.stdout,+ env = process.env,+} = {}) {+ // cliPath is empty until the file exists; first-run writes go to the candidate+ // path (OPENVIKING_CLI_CONFIG_FILE, else ~/.openviking/ovcli.conf).+ const { cliPath, cliPathCandidate } = loadCredentialFiles(env);+ const targetPath = cliPath || cliPathCandidate;+ const current = readJsonSafe(targetPath);+ const rl = createInterface({ input, output });+ const say = (line = "") => output.write(`${line}\n`);++ try {+ say("OpenViking memory plugin setup");+ say(`Config file: ${targetPath}`);+ say("");+ say("Current values:");+ say(` url: ${current.url || "(not set)"}`);+ say(` api_key: ${maskSecret(current.api_key)}`);+ if (current.account) say(` account: ${current.account}`);+ if (current.user) say(` user: ${current.user}`);+ say("");++ const defaultUrl = current.url || LOCAL_URL;+ say("Where do you connect to OpenViking?");+ say(` 1) Self-hosted / local [${LOCAL_URL}]`);+ say(` 2) Volcengine OpenViking Cloud [${CLOUD_URL}]`);+ say(` 3) Custom URL / keep current [${defaultUrl}]`);+ const mode = (await rl.question("Choice [1/2/3, default 3]: ")).trim();+ let url = defaultUrl;+ if (mode === "1") {+ url = LOCAL_URL;+ } else if (mode === "2") {+ url = CLOUD_URL;+ } else {+ const answer = (await rl.question(`Server URL [${defaultUrl}]: `)).trim();+ if (answer) url = answer;+ }++ const keyPrompt = current.api_key+ ? `API key [enter = keep ${maskSecret(current.api_key)}, '-' = clear]: `+ : "API key (leave empty for unauthenticated local mode): ";+ const keyAnswer = await rl.question(keyPrompt);+ let apiKey = current.api_key || "";+ if (keyAnswer === "-") apiKey = "";+ else if (keyAnswer.trim()) apiKey = keyAnswer.trim();+ else if (!current.api_key) apiKey = "";++ const next = { ...current, url, api_key: apiKey };++ say("");+ say("Changes:");+ say(` url: ${current.url || "(not set)"} -> ${next.url}`);+ say(` api_key: ${maskSecret(current.api_key)} -> ${maskSecret(next.api_key)}`);+ const confirm = (await rl.question("Write config? [Y/n] ")).trim().toLowerCase();+ if (confirm === "n" || confirm === "no") {+ say("Aborted; nothing written.");+ return { written: false, path: targetPath };+ }++ mkdirSync(dirname(targetPath), { recursive: true });+ if (existsSync(targetPath)) {+ copyFileSync(targetPath, `${targetPath}.bak.${Date.now()}`);+ }+ writeFileSync(targetPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });+ try {+ chmodSync(targetPath, 0o600);+ } catch {+ /* best effort on platforms without chmod semantics */+ }+ say(`Written: ${targetPath}`);+ say("The stdio MCP proxy and hooks pick this up on the next harness start.");+ return { written: true, path: targetPath };+ } finally {+ rl.close();+ }+}diff --git a/examples/pi-experimental-context-management/shared/uri-guard.mjs b/examples/pi-experimental-context-management/shared/uri-guard.mjsnew file mode 100644index 000000000..cf57bf406--- /dev/null+++ b/examples/pi-experimental-context-management/shared/uri-guard.mjs@@ -0,0 +1,78 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+const DEFAULT_URI_KEYS = [+ "filePath",+ "file_path",+ "filepath",+ "path",+ "uri",+ "target_uri",+ "targetUri",+ "pattern",+];++export function normalizeToolName(value) {+ return String(value || "").trim().toLowerCase();+}++// Arguments that carry file CONTENT rather than a location. The sweep below+// looks past the known path keys so an unusual one (`paths`, a nested target)+// is still caught, but text a tool is asked to WRITE is not a path: a local+// `write` whose body merely mentions viking://user/default/ was denied, and no+// file was created. Skipped by name at any depth.+const DEFAULT_CONTENT_KEYS = [+ "content",+ "contents",+ "text",+ "body",+ "old_string",+ "oldString",+ "new_string",+ "newString",+ "old_str",+ "new_str",+ "file_text",+ "insert_line",+ "replacement",+];++export function findVikingUri(args = {}, keys = DEFAULT_URI_KEYS, contentKeys = DEFAULT_CONTENT_KEYS) {+ if (!args || typeof args !== "object") return null;+ for (const key of keys) {+ const uri = findVikingUriInValue(args[key]);+ if (uri) return uri;+ }+ return findVikingUriInValue(args, new Set(contentKeys));+}++export function findVikingUriInValue(value, skipKeys) {+ if (typeof value === "string") {+ const match = value.match(/\bviking:\/\/[^\s"'`<>)]*/i);+ return match?.[0] || null;+ }+ if (Array.isArray(value)) {+ for (const item of value) {+ const uri = findVikingUriInValue(item, skipKeys);+ if (uri) return uri;+ }+ return null;+ }+ if (value && typeof value === "object") {+ for (const [key, item] of Object.entries(value)) {+ if (skipKeys?.has(key)) continue;+ const uri = findVikingUriInValue(item, skipKeys);+ if (uri) return uri;+ }+ }+ return null;+}++export function buildGuardMessage(uri, hint = {}) {+ const tool = hint.tool || "the OpenViking MCP tools";+ const example = typeof hint.example === "function" ? hint.example(uri) : hint.example;+ const lines = [+ "viking:// URIs are OpenViking virtual paths, not local filesystem paths.",+ `Use ${tool} instead.`,+ ];+ if (example) lines.push(`Example: ${example}`);+ return lines.join("\n");+}diff --git a/examples/pi-experimental-context-management/shared/workspace-identity.mjs b/examples/pi-experimental-context-management/shared/workspace-identity.mjsnew file mode 100644index 000000000..76922cb03--- /dev/null+++ b/examples/pi-experimental-context-management/shared/workspace-identity.mjs@@ -0,0 +1,334 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Workspace identity: where the workspace root is, and what git calls it.+ *+ * Every hook is a fresh Node process and this runs on prompt-level paths, so+ * the derivation is pure filesystem work — no `git` subprocess. That keeps it+ * inside the tightest hook budget (Codex allows SessionEnd 3s against+ * SessionStart's 70s), and it keeps working where git is absent from PATH or+ * would refuse the repo over dubious ownership.+ *+ * The result is cached per cwd under the state dir so the several hooks of one+ * turn pay for the walk once.+ */++import { createHash } from "node:crypto";+import { mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";+import { homedir } from "node:os";+import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";++// The workspace config file names live here, and `workspace-config.mjs`+// re-exports them: the walk below needs the filenames to recognise a directory+// someone marked as a workspace, and it must not pull in the config layer to+// learn them.+export const CONFIG_DIR_NAME = ".openviking";+export const TEAM_FILE = "config.json";+export const LOCAL_FILE = "config.local.json";++const IDENTITY_CACHE_TTL_MS = 60_000;+// 255 is the AGFS path-segment limit; stopping well short leaves room for the+// hash suffix and for anything that later prefixes a peer id.+const MAX_PEER_ID_LENGTH = 100;++export function stateDir(env = process.env) {+ const explicit = String(env.OPENVIKING_STATE_DIR || "").trim();+ if (explicit) return explicit;+ const home = String(env.OPENVIKING_HOME || "").trim();+ const base = home ? home.replace(/^~(?=$|\/)/, homedir()) : join(homedir(), ".openviking");+ return join(base, "state");+}++function shortHash(value) {+ return createHash("sha256").update(String(value)).digest("hex").slice(0, 12);+}++/**+ * Legacy peer sanitation: one byte in, one byte out, no collapsing and no+ * trimming, so a leading `/` still becomes a leading `-`. Kept byte-exact+ * because `peer.source: "cwd"` and the legacy id that dual-read recomputes both+ * depend on it — do not "improve" it.+ */+export function legacySanitize(value) {+ return String(value || "").replace(/[^A-Za-z0-9]/g, "-");+}++/**+ * Readable sanitation for values that were never path-shaped — a normalized+ * remote, a directory name. Mirrors the server's own `_sanitize_component`+ * (`openviking/ingest/peer.py:32`) so both languages agree on the id, then+ * enforces what `validate_identifier_part` additionally requires.+ */+export function sanitizePeerId(value) {+ const raw = String(value || "").trim();+ let cleaned = raw.replace(/[^a-zA-Z0-9_.@-]+/g, "-").replace(/-{2,}/g, "-").replace(/^[-.]+|[-.]+$/g, "");+ if (!cleaned) return "";+ // The server accepts at most one `@` in an identifier part.+ const at = cleaned.indexOf("@");+ if (at !== -1) cleaned = cleaned.slice(0, at + 1) + cleaned.slice(at + 1).replace(/@/g, "-");+ // `ext-` is the server's namespace for base64-encoded external identities,+ // and `__self` its operation-target sentinel. Neither is ours to occupy.+ if (cleaned.startsWith("ext-")) cleaned = `x-${cleaned}`;+ if (cleaned === "__self") cleaned = "self";+ if (cleaned === "." || cleaned === "..") return "";+ if (cleaned.length > MAX_PEER_ID_LENGTH) {+ cleaned = `${cleaned.slice(0, MAX_PEER_ID_LENGTH - 13).replace(/[-.]+$/, "")}-${shortHash(raw)}`;+ }+ return cleaned;+}++/**+ * Normalize a remote URL to `host/path`, lowercased.+ *+ * Both spellings of the same repo converge, and userinfo is dropped — so a+ * remote with an embedded token cannot leak it into a peer id. The cost of+ * case folding is that two repos differing only in case share one namespace on+ * the rare case-sensitive forge.+ */+export function normalizeGitRemote(url) {+ const raw = String(url || "").trim();+ if (!raw) return "";++ // `C:\src\repo` and `C:/src/repo` are one machine's directory, not a shared+ // identity — and the scp pattern would happily read the drive as a host.+ if (/^[A-Za-z]:[\\/]/.test(raw)) return "";++ let host = "";+ let path = "";+ const scp = /^(?:[^@/\\]+@)?([^:/\\]+):(?!\/)(.+)$/.exec(raw);+ if (scp && !/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(raw)) {+ host = scp[1];+ path = scp[2];+ } else {+ let parsed;+ try {+ parsed = new URL(raw);+ } catch {+ return "";+ }+ // A local clone has no stable shared identity — fall through to the path+ // rules instead of minting one from `file://` or a bare directory.+ if (parsed.protocol === "file:" || !parsed.hostname) return "";+ host = parsed.hostname;+ path = parsed.pathname;+ }++ host = host.toLowerCase().replace(/^\[|\]$/g, "");+ path = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "").toLowerCase();+ if (!host || !path) return "";+ return `${host}/${path}`;+}++function readFileOrEmpty(path) {+ try {+ return readFileSync(path, "utf-8");+ } catch {+ return "";+ }+}++/**+ * Read `[remote "origin"] url` out of a git config with a minimal INI parse.+ *+ * `include` / `includeIf` are deliberately not followed: resolving them means+ * more filesystem walking for a value the fallback chain already covers, so an+ * unreadable remote just falls through to the next template.+ */+export function readGitRemoteUrl(commonDir, remote = "origin") {+ const text = readFileOrEmpty(join(commonDir, "config"));+ if (!text) return "";++ let inSection = false;+ for (const line of text.split("\n")) {+ const trimmed = line.trim();+ if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(";")) continue;+ const section = /^\[([^\]]+)\]/.exec(trimmed);+ if (section) {+ const header = section[1].trim();+ // git folds section and key names to lower case but keeps a quoted+ // subsection exact, so `[Remote "origin"]` is the same section and+ // `[remote "Origin"]` is not.+ const quoted = /^remote\s+"(.*)"$/i.exec(header);+ inSection = Boolean(quoted && quoted[1] === remote);+ continue;+ }+ if (!inSection) continue;+ const pair = /^url\s*=\s*(.*)$/i.exec(trimmed);+ // git treats an unquoted `#` or `;` as starting a comment anywhere on the+ // line, so a trailing note is not part of the URL.+ if (pair) return pair[1].split(/[#;]/)[0].trim().replace(/^["']|["']$/g, "");+ }+ return "";+}++function resolveGitDir(root) {+ const dotGit = join(root, ".git");+ let stat;+ try {+ stat = statSync(dotGit);+ } catch {+ return null;+ }+ if (stat.isDirectory()) return { gitDir: dotGit, commonDir: dotGit, kind: "repo" };+ if (!stat.isFile()) return null;++ const pointer = /^gitdir:\s*(.+)$/m.exec(readFileOrEmpty(dotGit));+ if (!pointer) return null;+ const gitDir = resolve(root, pointer[1].trim());++ // `commondir` is the worktree signal, so it is read first — a repository+ // that merely lives under a directory called `modules` is not a submodule.+ const commonRef = readFileOrEmpty(join(gitDir, "commondir")).trim();+ const commonDir = commonRef+ ? (isAbsolute(commonRef) ? commonRef : resolve(gitDir, commonRef))+ : gitDir;++ // A submodule keeps its own remote under the superproject's+ // `.git/modules/<name>`; converging it onto the superproject would merge two+ // repositories that release, and are reviewed, separately. Only the segment+ // right after a `.git` directory means that, which is also why a worktree of+ // a submodule resolves here through its own commondir.+ const kind = /[/\\]\.git[/\\]modules[/\\]/.test(`${commonDir}${sep}`)+ ? "submodule"+ : (commonRef ? "worktree" : "repo");+ return { gitDir, commonDir, kind };+}++/** A directory the user made a workspace on purpose, by giving it a config file. */+function hasWorkspaceMarker(dir) {+ for (const name of [TEAM_FILE, LOCAL_FILE]) {+ try {+ if (statSync(join(dir, CONFIG_DIR_NAME, name)).isFile()) return true;+ } catch { /* not marked here */ }+ }+ return false;+}++const NO_ROOT = Object.freeze({ root: "", rootKind: "", git: null, gitRoot: "" });++/**+ * Walk up from `cwd` to the nearest workspace root.+ *+ * A workspace is a git repository, or a directory someone marked as one by+ * creating `.openviking/config.json` (or `config.local.json`) in it. Nearest+ * wins. Above a marked directory the walk continues to the enclosing+ * repository, if any, so the git-shaped variables still resolve there.+ * Anything else — a scratch folder, a download, an app's per-task directory —+ * is not a workspace and gets no peer of its own.+ *+ * `$HOME` and the filesystem root are never workspace roots: a stray `.git`+ * in either would silently make every unrelated directory one workspace.+ */+export function findWorkspaceRoot(cwd, env = process.env) {+ const start = String(cwd || "").trim();+ if (!start) return NO_ROOT;++ let absolute;+ try {+ // A relative `start` makes `resolve` read process.cwd(), which throws when+ // the directory is gone — the very case the catch below is meant to cover.+ absolute = resolve(start);+ } catch {+ return NO_ROOT;+ }++ // `current` and `stopAt` are compared as strings, so they must be+ // canonicalized together. A `$HOME` reached through a symlink plus an+ // unresolvable cwd would otherwise walk straight past the guard.+ const home = String(env.HOME || "").trim() || homedir();+ let current;+ let stopAt;+ try {+ current = realpathSync(absolute);+ stopAt = realpathSync(home);+ } catch {+ current = absolute;+ stopAt = home;+ }+ const filesystemRoot = parse(current).root;+ if (current === stopAt || current === filesystemRoot) return NO_ROOT;++ let root = "";+ let rootKind = "";+ while (current && current !== filesystemRoot && current !== stopAt) {+ const git = resolveGitDir(current);+ if (git) return { root: root || current, rootKind: rootKind || "git", git, gitRoot: current };+ if (!root && hasWorkspaceMarker(current)) {+ root = current;+ rootKind = "config";+ }+ const parent = dirname(current);+ if (parent === current) break;+ current = parent;+ }+ return root ? { root, rootKind, git: null, gitRoot: "" } : NO_ROOT;+}++function cachePath(cwd, env) {+ return join(stateDir(env), `ws-identity-${shortHash(cwd)}.json`);+}++function readCache(path, now) {+ try {+ const cached = JSON.parse(readFileSync(path, "utf-8"));+ // Bounded on both sides: an entry stamped in the future — a clock that ran+ // fast, or `Infinity` — would otherwise pin a stale identity indefinitely.+ if (typeof cached?.ts !== "number" || cached.ts > now || now - cached.ts > IDENTITY_CACHE_TTL_MS) return null;+ const identity = cached.identity;+ if (identity && typeof identity === "object" && identity.vars && typeof identity.vars === "object") {+ return identity;+ }+ } catch { /* a cold or corrupt cache just costs one walk */ }+ return null;+}++function writeCache(path, identity, now) {+ try {+ mkdirSync(dirname(path), { recursive: true });+ const tmp = `${path}.${process.pid}.tmp`;+ writeFileSync(tmp, JSON.stringify({ ts: now, identity }), { mode: 0o600 });+ renameSync(tmp, path);+ } catch { /* best effort */ }+}++/**+ * Everything the peer templates can substitute, for one cwd.+ *+ * `git_remote` and `dir` are already sanitized; `git_root` and `cwd` carry the+ * legacy byte-for-byte rule, because they are the two that must reproduce a+ * peer minted before any of this existed.+ */+export function resolveWorkspaceIdentity({ cwd = "", env = process.env, cache = true, now = Date.now() } = {}) {+ const key = String(cwd || "");+ const path = cachePath(key, env);+ if (cache) {+ const hit = readCache(path, now);+ if (hit) return hit;+ }++ const { root, rootKind, git, gitRoot } = findWorkspaceRoot(key, env);+ // Only the normalized form is kept. The raw URL may carry a token, and this+ // file outlives the process — writing it here would undo the care+ // `normalizeGitRemote` takes to drop userinfo.+ const remote = git ? normalizeGitRemote(readGitRemoteUrl(git.commonDir)) : "";+ const identity = {+ cwd: key,+ root,+ rootKind,+ isGit: Boolean(git),+ gitKind: git?.kind || "",+ gitCommonDir: git?.commonDir || "",+ gitRoot,+ remote,+ vars: {+ git_remote: sanitizePeerId(remote),+ // The enclosing repository's root, which is not the workspace root when a+ // marker file below it won. Empty outside a repository, so the `git`+ // preset resolves to nothing there rather than to a bare path.+ git_root: git ? legacySanitize(gitRoot) : "",+ cwd: legacySanitize(key),+ dir: root ? sanitizePeerId(root.split(/[/\\]/).filter(Boolean).pop() || "") : "",+ },+ };+ if (cache) writeCache(path, identity, now);+ return identity;+}diff --git a/examples/pi-experimental-context-management/shared/workspace-peer.d.mts b/examples/pi-experimental-context-management/shared/workspace-peer.d.mtsnew file mode 100644index 000000000..9a920fcc5--- /dev/null+++ b/examples/pi-experimental-context-management/shared/workspace-peer.d.mts@@ -0,0 +1,5 @@+export function deriveWorkspacePeerId(cwd: unknown): string;+export function resolveEffectivePeerId(input?: {+ cfg?: { peerId?: string; workspacePeer?: boolean };+ cwd?: string;+}): { peerId: string; source: "explicit" | "workspace" | "none" };diff --git a/examples/pi-experimental-context-management/shared/workspace-peer.mjs b/examples/pi-experimental-context-management/shared/workspace-peer.mjsnew file mode 100644index 000000000..89df30793--- /dev/null+++ b/examples/pi-experimental-context-management/shared/workspace-peer.mjs@@ -0,0 +1,134 @@+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.+/**+ * Which peer a workspace writes its memories under.+ *+ * The peer used to be the working directory with every non-alphanumeric byte+ * turned into a dash, which made the identity an accident of where the+ * repository happened to sit: a clone on another machine, a rename, a worktree+ * or simply `cd examples/` each minted a separate, empty namespace. The default+ * is now git's own idea of the repository, so one project keeps one memory+ * wherever it is checked out.+ *+ * `peer.source` decides the rule. Presets cover the three answers most people+ * want; a template — or a list of templates tried in order — covers the rest.+ * The old behaviour is still one word away, byte for byte.+ */++import { legacySanitize, resolveWorkspaceIdentity, sanitizePeerId } from "./workspace-identity.mjs";++/**+ * `git` is the default, and it resolves only inside a repository: the remote+ * first, because that is the one name every clone agrees on, then the+ * repository root for a repo that has none. Anywhere else it resolves to+ * nothing and no peer is sent — a scratch folder or an app's per-task+ * directory would otherwise mint a fresh, empty namespace each time, so those+ * memories go to the user-level space instead. Naming such a directory is what+ * `peer.id` is for, and deriving one from a bare path is what `cwd` is for;+ * both are opt-in.+ *+ * No preset adds a prefix. A path-derived id starts with `-` on POSIX, so it+ * cannot collide with a remote-derived one; anyone who wants a prefix writes+ * their own template.+ */+export const PEER_SOURCE_PRESETS = {+ git: ["{git_remote}", "{git_root}"],+ cwd: ["{cwd}"],+ none: [],+};++export const DEFAULT_PEER_SOURCE = "git";++const VARIABLE_RE = /\{([a-z_]+)\}/g;++export function deriveWorkspacePeerId(cwd) {+ return legacySanitize(cwd);+}++/**+ * Normalize `peer.source` — a preset name, a template, or a list — to templates.+ *+ * A bare string with no `{` is a misspelled preset, not a template: `Git` or+ * `gti` would otherwise become a peer literally named `Git`, quietly stranding+ * the workspace's memories in a namespace nobody meant to create. Such a value+ * warns and falls back to the default chain. An array is left alone — writing a+ * list is explicit enough to mean the constant it contains.+ */+export function peerSourceTemplates(source, onWarn = null) {+ if (Array.isArray(source)) return source.map(String).filter(Boolean);+ const raw = String(source ?? "").trim();+ if (!raw) return PEER_SOURCE_PRESETS[DEFAULT_PEER_SOURCE];+ if (Object.hasOwn(PEER_SOURCE_PRESETS, raw)) return PEER_SOURCE_PRESETS[raw];+ if (raw.includes("{")) return [raw];++ const message = `OpenViking: ignored peer.source ${JSON.stringify(raw)}: it is neither a preset `+ + `(${Object.keys(PEER_SOURCE_PRESETS).join(", ")}) nor a template such as "team-{dir}". `+ + `Falling back to ${DEFAULT_PEER_SOURCE}.`;+ if (typeof onWarn === "function") onWarn(message);+ else process.stderr.write(`${message}\n`);+ return PEER_SOURCE_PRESETS[DEFAULT_PEER_SOURCE];+}++/**+ * Substitute one template, or return "" when any variable it names is empty.+ *+ * All-or-nothing on purpose: a half-resolved template like `git-` would be a+ * silently shared identity, so an empty variable falls through to the next+ * template instead.+ */+export function renderPeerTemplate(template, vars) {+ const text = String(template || "");+ if (!text) return "";+ let empty = false;+ const rendered = text.replace(VARIABLE_RE, (match, name) => {+ if (!Object.hasOwn(vars, name)) {+ empty = true;+ return "";+ }+ const value = String(vars[name] ?? "");+ if (!value) empty = true;+ return value;+ });+ return empty ? "" : rendered;+}++/**+ * The peer this process should send, and where it came from.+ *+ * `source` keeps its three values — call sites compare it against the literal+ * `"workspace"` to decide whether a session pin may be reused — while `origin`+ * names the template that actually produced the id, and `legacyPeerId` carries+ * the pre-git id whenever it differs, so recall can still reach memories+ * written under it.+ */+export function resolveEffectivePeerId({ cfg = {}, cwd = "", identity = null, env = process.env, onWarn = null } = {}) {+ const explicit = String(cfg.peerId || "").trim();+ if (explicit) return { peerId: explicit, source: "explicit", origin: "explicit", legacyPeerId: "" };++ // `OPENVIKING_WORKSPACE_PEER=0` predates `peer.source` and still means "none".+ if (cfg.workspacePeer === false) return { peerId: "", source: "none", origin: "disabled", legacyPeerId: "" };++ const templates = peerSourceTemplates(cfg.peerSource, onWarn);+ if (!templates.length) return { peerId: "", source: "none", origin: "none", legacyPeerId: "" };++ // `harness` is composed here rather than in the identity, whose result is+ // cached on disk under a cwd-only key — two harnesses in one directory would+ // otherwise read each other's peer back out of that cache.+ const vars = {+ ...((identity || resolveWorkspaceIdentity({ cwd, env })).vars || {}),+ harness: sanitizePeerId(cfg.harness || cfg.clientId || ""),+ };+ const legacyPeerId = deriveWorkspacePeerId(cwd);+ for (const template of templates) {+ const peerId = renderPeerTemplate(template, vars);+ if (!peerId) continue;+ return {+ peerId,+ source: "workspace",+ origin: template,+ legacyPeerId: peerId === legacyPeerId ? "" : legacyPeerId,+ };+ }+ // No peer, but the pre-git id is still what earlier sessions in this+ // directory wrote under, so recall keeps reaching it.+ return { peerId: "", source: "none", origin: "unresolved", legacyPeerId };+}diff --git a/examples/pi-experimental-context-management/sync.ts b/examples/pi-experimental-context-management/sync.tsnew file mode 100644index 000000000..c43958f0b--- /dev/null+++ b/examples/pi-experimental-context-management/sync.ts@@ -0,0 +1,276 @@+import type { OVClient } from "./client.js";+import { createLogger } from "./shared/debug-log.mjs";+import type { OVConfig } from "./config.js";+import { deriveHarnessSessionId } from "./shared/session-model.mjs";+import { claimForReplay, dequeue, enqueue, incrementRetry, listPending, replayPending } from "./shared/pending-queue.mjs";+import { BATCH_LIMIT, sendSessionMessages } from "./shared/batch-send.mjs";+import { extractBranchCapturePayloads } from "./lib/capture-adapter.mjs";+import { estimatePayloadTokens } from "./lib/text-budget.mjs";++/** Queued addMessage entries this session still owes the server. */+function countUndeliveredForSession(pendingEntries: any[], sid: string): number {+ if (!sid) return 0;+ let count = 0;+ for (const item of Array.isArray(pendingEntries) ? pendingEntries : []) {+ const entry = item && typeof item === "object" && item.entry && typeof item.entry === "object"+ ? item.entry+ : item;+ if (entry?.type === "addMessage" && entry.sessionId === sid) count++;+ }+ return count;+}++// --- SyncManager ---++export interface AddPayloadResult {+ accepted: boolean;+ delivered: boolean;+}++export interface SyncBranchResult {+ added: number;+ tokens: number;+ allDelivered: boolean;+}++export class SyncManager {+ private client: OVClient;+ private config: OVConfig;+ private logger: ReturnType<typeof createLogger>;+ private ovSessionId: string | null = null;+ private syncedEntryCount = 0;+ /**+ * Messages this session lost for good: non-retryable (4xx) rejections and+ * queue entries whose retry budget ran out. They are counted as accepted so+ * the watermark can advance past them, which is what lets the flush barrier+ * clear — so the count has to survive separately, or a window would be cut+ * while claiming an archive that is missing those messages.+ */+ private droppedForever = 0;+ /** trace_id of the last commit response, failure included. */+ private lastCommitTrace = "";++ constructor(client: OVClient, config: OVConfig) {+ this.client = client;+ this.config = config;+ this.logger = createLogger("pi", {+ debug: Boolean(config.debugLogPath),+ debugLogPath: config.debugLogPath,+ });+ }++ get sessionId(): string | null { return this.ovSessionId; }+ get syncedCount(): number { return this.syncedEntryCount; }+ /** Messages OpenViking will never receive; they are missing from the archive. */+ get droppedCount(): number { return this.droppedForever; }+ get commitTraceId(): string { return this.lastCommitTrace; }++ restoreWatermark(n: number): void {+ const next = Math.max(0, Math.floor(Number(n) || 0));+ this.syncedEntryCount = next;+ }++ async ensureSession(piSessionId: string): Promise<boolean> {+ if (this.ovSessionId) return true;++ const id = deriveHarnessSessionId("pi-", piSessionId);+ this.ovSessionId = id;+ return true;+ }++ async replayPending(): Promise<void> {+ if (!this.client.connected) return;+ await replayPending(+ (path: string, init?: any) => this.client.fetchJSON(path, init, 10000),+ (stage: string, data: unknown) => this.logger.log(stage, data),+ );+ }++ /**+ * Barrier for a context-window reset: everything this session captured has+ * to be on the server before the local copy of it can be dropped.+ *+ * `budgetMs` caps the drain so a reset cannot block the tool call past its+ * own deadline; the remainder drains on later turns and the barrier simply+ * stays closed until then.+ */+ async flushBarrier(opts: { budgetMs?: number } = {}): Promise<boolean> {+ if (!this.ovSessionId) return false;+ // Drain is bounded (time / max batches). Remaining undelivered entries —+ // including any still claimed as `.processing` — keep the barrier closed+ // until a later turn finishes draining them.+ if (this.client.connected) await this.drainSessionBacklog(opts.budgetMs);+ const pending = await listPending();+ return countUndeliveredForSession(pending, this.ovSessionId) === 0;+ }++ /**+ * Replay this session's queued addMessage entries through the batch+ * endpoint, BATCH_LIMIT per request. The shared replayPending() sends one+ * request per entry and stops after one replay window, which is what let a+ * large offline backlog block the reset barrier for many turns (#4504).+ * Entries are claimed one batch at a time so a failed batch only costs a+ * retry for the entries it contained.+ *+ * Bounded per call by the caller's `budgetMs`, else by+ * OPENVIKING_PENDING_DRAIN_BUDGET_MS (default 60s), plus the optional+ * OPENVIKING_PENDING_DRAIN_MAX_BATCHES, so a huge backlog cannot block+ * turn_end for an unbounded wall time; remainder drains on later turns.+ */+ private async drainSessionBacklog(budgetMs?: number): Promise<void> {+ const sid = this.ovSessionId;+ if (!sid) return;+ const budgetRaw = Number(+ budgetMs === undefined ? process.env.OPENVIKING_PENDING_DRAIN_BUDGET_MS : budgetMs,+ );+ const timeBudgetMs = Number.isFinite(budgetRaw) && budgetRaw >= 0 ? budgetRaw : 60_000;+ const maxRaw = Number(process.env.OPENVIKING_PENDING_DRAIN_MAX_BATCHES);+ const maxBatches =+ Number.isFinite(maxRaw) && maxRaw > 0 ? Math.floor(maxRaw) : Number.POSITIVE_INFINITY;+ const started = Date.now();+ let batches = 0;++ const backlog = (await listPending()).filter(+ ({ entry }) => entry?.type === "addMessage" && entry.sessionId === sid,+ );+ for (let start = 0; start < backlog.length; start += BATCH_LIMIT) {+ if (batches >= maxBatches || Date.now() - started >= timeBudgetMs) {+ this.logger.log("drain", {+ session: sid,+ stopped: batches >= maxBatches ? "max-batches" : "time-budget",+ batches,+ remaining: backlog.length - start,+ elapsedMs: Date.now() - started,+ });+ return;+ }++ const claimed: Array<{ filename: string; entry: any }> = [];+ for (const { filename, entry } of backlog.slice(start, start + BATCH_LIMIT)) {+ const name = await claimForReplay(filename);+ if (name) claimed.push({ filename: name, entry });+ }+ if (claimed.length === 0) continue;+ batches += 1;++ let delivered = 0;+ await sendSessionMessages(+ this.fetchJSON,+ sid,+ claimed.map(({ entry }) => entry.payload),+ {+ onSent: async (count: number) => {+ for (let i = 0; i < count; i++) await dequeue(claimed[delivered++].filename);+ },+ },+ );+ if (delivered === claimed.length) continue;++ // Undelivered entries stay queued with one more retry; incrementRetry+ // drops them once the retry budget is exhausted.+ for (const { filename, entry } of claimed.slice(delivered)) {+ // false: the retry budget is spent and the entry was deleted, so that+ // message never reaches OpenViking.+ if ((await incrementRetry(filename, entry)) === false) this.droppedForever += 1;+ }+ this.logger.log("drain", {+ session: sid,+ delivered,+ retried: claimed.length - delivered,+ });+ return;+ }+ }++ private fetchJSON = (path: string, init?: any) => this.client.fetchJSON(path, init, 10000);++ async syncBranch(branch: any[]): Promise<SyncBranchResult> {+ if (!this.ovSessionId) return { added: 0, tokens: 0, allDelivered: true };++ const extracted = extractBranchCapturePayloads(branch, this.syncedEntryCount, this.config);+ if (extracted.resetWatermark) this.syncedEntryCount = 0;+ const sent = await this.sendPayloads(extracted.payloads);+ const added = sent.accepted;+ let tokens = 0;+ for (const payload of extracted.payloads.slice(0, added)) {+ tokens += estimatePayloadTokens(payload);+ }+ const allDelivered = sent.delivered === added;+ if (added === extracted.payloads.length) {+ this.syncedEntryCount = extracted.nextEntryCount;+ }+ // No threshold commit here: in this extension `new_context` and the pi+ // compaction fallback are the only writers of archive boundaries.+ return { added, tokens, allDelivered };+ }++ async addPayload(payload: any): Promise<AddPayloadResult> {+ const sent = await this.sendPayloads([payload]);+ return { accepted: sent.accepted === 1, delivered: sent.delivered === 1 };+ }++ /**+ * Send payloads in one batch request; retryable failures are queued to disk.+ * Returns how many payloads were accepted (sent or queued, always a prefix)+ * and how many of those were delivered to the server.+ */+ private async sendPayloads(payloads: any[]): Promise<{ accepted: number; delivered: number }> {+ if (!this.ovSessionId || payloads.length === 0) return { accepted: 0, delivered: 0 };+ const res = await sendSessionMessages(this.fetchJSON, this.ovSessionId, payloads, {+ enqueueOnRetryable: true,+ });+ if (res.failed > 0 || res.enqueueFailed > 0) {+ this.logger.log("send", {+ session: this.ovSessionId,+ sent: res.sent,+ queued: res.queued,+ failed: res.failed,+ enqueueFailed: res.enqueueFailed,+ error: res.lastError?.message || res.lastError?.code || "unknown",+ });+ }+ // A non-retryable rejection (4xx) drops the remaining payloads, the same+ // outcome replayPending() applies to such entries. Count them as accepted+ // so the watermark still advances past them; otherwise the next turn would+ // re-extract and re-send the payloads that were already delivered.+ const dropped = res.retryable ? 0 : res.failed;+ if (dropped > 0) this.droppedForever += dropped;+ return { accepted: res.sent + res.queued + dropped, delivered: res.sent };+ }++ async commit(opts: { queueOnFailure?: boolean; keepRecentCount?: number } = {}): Promise<any | null> {+ if (!this.ovSessionId) return null;+ const response = await this.client.commitSessionResponse(+ this.ovSessionId,+ opts.keepRecentCount,+ );+ const result = response.result;+ this.lastCommitTrace = response.traceId || "";+ if (!result) {+ this.logger.log("commit", {+ session: this.ovSessionId,+ ok: false,+ status: response.status ?? 0,+ trace_id: response.traceId || "none",+ error: response.error?.message || response.error?.code || "unknown",+ });+ if (opts.queueOnFailure !== false) {+ await enqueue("commitSession", this.ovSessionId, {+ keep_recent_count: opts.keepRecentCount ?? this.config.commitKeepRecentCount,+ });+ }+ return null;+ }+ this.lastCommitTrace = result.trace_id || response.traceId || "";+ this.logger.log("commit", {+ session: this.ovSessionId,+ ok: true,+ trace_id: result.trace_id || "none",+ });+ return result;+ }++ async shutdown(): Promise<void> {+ return;+ }+}diff --git a/examples/pi-experimental-context-management/tests/capture-adapter.test.mjs b/examples/pi-experimental-context-management/tests/capture-adapter.test.mjsnew file mode 100644index 000000000..84c1ac791--- /dev/null+++ b/examples/pi-experimental-context-management/tests/capture-adapter.test.mjs@@ -0,0 +1,161 @@+import test from "node:test";+import assert from "node:assert/strict";+import { extractBranchCapturePayloads } from "../lib/capture-adapter.mjs";++test("extractBranchCapturePayloads converts user text to message payload", () => {+ const branch = [+ { type: "message", message: { role: "user", content: "Remember this decision for later." } },+ ];++ const result = extractBranchCapturePayloads(branch, 0, { peerId: "peer-a" });+ assert.equal(result.nextEntryCount, 1);+ assert.equal(result.payloads.length, 1);+ assert.equal(result.payloads[0].role, "user");+ assert.equal(result.payloads[0].parts[0].type, "text");+ assert.match(result.payloads[0].parts[0].text, /Remember this decision/);+ assert.equal(result.payloads[0].peer_id, "peer-a");+});++test("extractBranchCapturePayloads emits structured tool parts", () => {+ const branch = [+ {+ type: "message",+ message: {+ role: "assistant",+ content: [+ { type: "text", text: "I will inspect it." },+ { type: "tool_call", id: "call-1", name: "read", input: { path: "a.txt" } },+ ],+ },+ },+ ];++ const result = extractBranchCapturePayloads(branch, 0, {+ captureAssistantTurns: true,+ captureToolMaxChars: 2000,+ });+ assert.equal(result.payloads.length, 1);+ assert.equal(result.payloads[0].role, "assistant");+ assert.ok(Array.isArray(result.payloads[0].parts));+ assert.equal(result.payloads[0].parts.some((part) => part.type === "tool" && part.tool_name === "read"), true);+});++test("extractBranchCapturePayloads resets watermark when branch shrinks", () => {+ const result = extractBranchCapturePayloads([+ { type: "message", message: { role: "user", content: "New compacted branch content." } },+ ], 5, {});++ assert.equal(result.resetWatermark, true);+ assert.equal(result.nextEntryCount, 1);+ assert.equal(result.payloads.length, 1);+});++test("capture is faithful without asking: ack, short, and punctuation turns are kept", () => {+ const branch = [+ { type: "message", message: { role: "user", content: "ok" } },+ { type: "message", message: { role: "user", content: "hi" } },+ { type: "message", message: { role: "user", content: "!!!" } },+ ];++ const result = extractBranchCapturePayloads(branch, 0, {});+ assert.equal(result.payloads.length, 3);+ assert.deepEqual(result.payloads.map((p) => p.parts[0].text), ["ok", "hi", "!!!"]);+});++test("faithful capture still skips commands and plugin status", () => {+ const result = extractBranchCapturePayloads([+ { type: "message", message: { role: "user", content: "/viking" } },+ { type: "message", message: { role: "assistant", content: "[OpenViking-memory] synced" } },+ ], 0, {});++ assert.equal(result.payloads.length, 0);+});++test("pi toolResult messages are captured as prefixed user turns", () => {+ const branch = [+ {+ type: "message",+ message: {+ role: "toolResult",+ toolCallId: "call-7",+ toolName: "read",+ content: "line one\nline two",+ },+ },+ ];++ const { payloads } = extractBranchCapturePayloads(branch, 0, {+ captureToolResults: true,+ captureToolMaxChars: 1000,+ peerId: "peer-a",+ });+ assert.equal(payloads.length, 1);+ assert.equal(payloads[0].role, "user");+ assert.equal(payloads[0].peer_id, "peer-a");+ assert.equal(payloads[0].parts[0].type, "text");+ assert.match(payloads[0].parts[0].text, /^\[tool-result read\] /);+ assert.match(payloads[0].parts[0].text, /line two/);+});++test("toolResult roles are recognised in every spelling pi and providers use", () => {+ for (const role of ["toolResult", "toolresult", "tool_result", "tool"]) {+ const { payloads } = extractBranchCapturePayloads(+ [{ type: "message", message: { role, toolName: "bash", content: "exit 0" } }],+ 0,+ { captureToolResults: true, captureToolMaxChars: 1000 },+ );+ assert.equal(payloads.length, 1, `role ${role} was dropped`);+ assert.match(payloads[0].parts[0].text, /^\[tool-result bash\] exit 0/);+ }+});++test("toolResult capture is dropped when captureToolResults is false", () => {+ const { payloads } = extractBranchCapturePayloads(+ [+ { type: "message", message: { role: "user", content: "run it" } },+ { type: "message", message: { role: "toolResult", toolName: "bash", content: "exit 0" } },+ ],+ 0,+ { captureToolResults: false },+ );+ assert.equal(payloads.length, 1);+ assert.equal(payloads[0].role, "user");+ assert.match(payloads[0].parts[0].text, /run it/);+});++test("toolResult text is truncated to captureToolMaxChars", () => {+ const { payloads } = extractBranchCapturePayloads(+ [{ type: "message", message: { role: "toolResult", toolName: "read", content: "z".repeat(5000) } }],+ 0,+ { captureToolResults: true, captureToolMaxChars: 400 },+ );+ assert.equal(payloads.length, 1);+ const text = payloads[0].parts[0].text;+ assert.ok(text.length < 500, `expected truncation, got ${text.length} chars`);+ assert.match(text, /\[truncated\]$/);+});++test("tool-only payloads carry tool output once, not duplicated as text", () => {+ const output = "z".repeat(5000);+ const { payloads } = extractBranchCapturePayloads(+ [+ {+ type: "message",+ message: {+ role: "assistant",+ content: [+ { type: "tool_result", tool_use_id: "call-dup-check", output },+ ],+ },+ },+ ],+ 0,+ { captureAssistantTurns: true, captureToolMaxChars: 1000000 },+ );++ const parts = payloads.flatMap((payload) => payload.parts || []);+ assert.equal(parts.filter((part) => part.type === "text").length, 0);+ const toolParts = parts.filter((part) => part.type === "tool");+ assert.equal(toolParts.length, 1);+ assert.equal(toolParts[0].tool_output, output);+});diff --git a/examples/pi-experimental-context-management/tests/client-archives.test.mjs b/examples/pi-experimental-context-management/tests/client-archives.test.mjsnew file mode 100644index 000000000..1caf390f0--- /dev/null+++ b/examples/pi-experimental-context-management/tests/client-archives.test.mjs@@ -0,0 +1,638 @@+import test, { after, before, beforeEach } from "node:test";+import assert from "node:assert/strict";+import { OVClient, archiveIdFromUri, archiveUriToRoot } from "../client.ts";++// Envelope shapes below are the ones recorded against the volc server:+// fs/ls -> { status: "ok", result: [{ uri, size, isDir, modTime, abstract }] }+// content/read -> { status: "ok", result: "<text>" }+// search/grep -> { status: "ok", result: { matches: [{ line, uri, content }] } }+// sessions/{id}-> { status: "ok", result: { session_id, uri, ... } }+// not found -> { status: "error", error: { code: "NOT_FOUND", message } }++const SID = "pi-sess-1";+const ROOT = "viking://user/default/sessions/pi-sess-1";+const ARCHIVE = `${ROOT}/history/archive_002`;++let originalFetch;+let calls;++before(() => {+ originalFetch = globalThis.fetch;+});++after(() => {+ globalThis.fetch = originalFetch;+});++beforeEach(() => {+ calls = [];+ globalThis.fetch = originalFetch;+});++/** Route the stub by URL substring; `handler` returns a body or { httpStatus, body }. */+function stubFetch(handler) {+ globalThis.fetch = async (url, init) => {+ calls.push({ url: String(url), init });+ const out = await handler(String(url), init);+ const httpStatus = out?.httpStatus ?? 200;+ const body = out?.httpStatus ? out.body : out;+ return new Response(JSON.stringify(body), {+ status: httpStatus,+ headers: { "Content-Type": "application/json" },+ });+ };+}++function makeClient() {+ return new OVClient({+ endpoint: "http://127.0.0.1:1933/",+ apiKey: "secret",+ account: "acct",+ user: "user",+ peerId: "peer",+ userAgent: "openviking-pi-xcm/0.1.0",+ commitKeepRecentCount: 10,+ });+}++const sessionOk = {+ status: "ok",+ result: { session_id: SID, uri: ROOT, message_count: 12, commit_count: 1 },+};+const notFound = {+ httpStatus: 404,+ body: { status: "error", error: { code: "NOT_FOUND", message: "not found" } },+};++// ---------- sessionRootUri / archiveUriToRoot ----------++test("sessionRootUri reads the canonical uri once and caches it", async () => {+ stubFetch((url) => {+ assert.ok(url.includes(`/api/v1/sessions/${SID}`));+ return sessionOk;+ });+ const client = makeClient();+ assert.equal(await client.sessionRootUri(SID), ROOT);+ assert.equal(await client.sessionRootUri(SID), ROOT);+ assert.equal(calls.length, 1, "second call must be served from the cache");+});++test("sessionRootUri falls back to the legacy alias and does not cache it", async () => {+ stubFetch(() => notFound);+ const client = makeClient();+ assert.equal(await client.sessionRootUri(SID), `viking://session/${SID}`);+ assert.equal(await client.sessionRootUri(SID), `viking://session/${SID}`);+ assert.equal(calls.length, 2, "a failed lookup must stay retryable");+});++test("sessionRootUri ignores a non-viking uri and never emits the ~ alias", async () => {+ stubFetch(() => ({ status: "ok", result: { session_id: SID, uri: "~/sessions/pi-sess-1" } }));+ const client = makeClient();+ const root = await client.sessionRootUri(SID);+ assert.equal(root, `viking://session/${SID}`);+ assert.ok(!root.includes("~"));+});++test("sessionRootUri normalizes a trailing slash and survives a transport failure", async () => {+ stubFetch(() => ({ status: "ok", result: { session_id: SID, uri: ` ${ROOT}/ ` } }));+ assert.equal(await makeClient().sessionRootUri(SID), ROOT);++ globalThis.fetch = async () => { throw new Error("ECONNREFUSED"); };+ assert.equal(await makeClient().sessionRootUri(SID), `viking://session/${SID}`);+});++test("archiveUriToRoot strips the archive segment", () => {+ assert.equal(archiveUriToRoot(ARCHIVE), ROOT);+ assert.equal(OVClient.archiveUriToRoot(`${ARCHIVE}/`), ROOT);+ assert.equal(makeClient().archiveUriToRoot(`${ARCHIVE}/messages.jsonl`), ROOT);+ assert.equal(archiveUriToRoot(`viking://session/${SID}/history/archive_010`), `viking://session/${SID}`);+ assert.equal(archiveUriToRoot(ROOT), ROOT, "a root passes through unchanged");+ assert.equal(archiveIdFromUri(`${ARCHIVE}/messages.jsonl`), "archive_002");+ assert.equal(archiveIdFromUri(ROOT), "");+});++// ---------- readArchiveOverview ----------++test("readArchiveOverview requests the encoded .overview.md uri", async () => {+ stubFetch(() => ({ status: "ok", result: "# Working Memory\n\n## Session Title\nx" }));+ const text = await makeClient().readArchiveOverview(ARCHIVE);+ assert.equal(text, "# Working Memory\n\n## Session Title\nx");+ assert.equal(calls.length, 1);+ const url = calls[0].url;+ assert.ok(url.startsWith("http://127.0.0.1:1933/api/v1/content/read?uri="));+ assert.ok(url.includes(encodeURIComponent(`${ARCHIVE}/.overview.md`)));+ assert.ok(url.includes("%3A%2F%2F"), "the uri query must be percent-encoded");+});++test("readArchiveOverview strips a leading YAML frontmatter block", async () => {+ stubFetch(() => ({+ status: "ok",+ result: "---\ntitle: archive_002\ngenerated: 2026-09-10\n---\n# Working Memory\nbody\n",+ }));+ assert.equal(await makeClient().readArchiveOverview(ARCHIVE), "# Working Memory\nbody\n");+});++test("readArchiveOverview keeps a body whose --- is not frontmatter", async () => {+ const body = "# Working Memory\n\n---\n\nnotes";+ stubFetch(() => ({ status: "ok", result: body }));+ assert.equal(await makeClient().readArchiveOverview(ARCHIVE), body);+});++// The real sidecar: openviking/storage/abstract_overview.py::render_abstract_overview+// writes `---\n<yaml>\n---\n\n<body>\n`, and content/read only strips frontmatter+// for memory URIs, so a session archive answers with the OKF document verbatim.+test("readArchiveOverview strips the OKF sidecar the server actually writes", async () => {+ const stored = [+ "---",+ "generated_by:",+ " component: Session",+ " trigger: archive_summary",+ `directory: ${ARCHIVE}`,+ "---",+ "",+ "# Working Memory",+ "",+ "## Session Title",+ "Phase one",+ "",+ ].join("\n");+ stubFetch(() => ({ status: "ok", result: stored }));+ const text = await makeClient().readArchiveOverview(ARCHIVE);+ assert.equal(text, "# Working Memory\n\n## Session Title\nPhase one\n");+ assert.ok(!text.startsWith("\n"), "the blank line after the frontmatter must go too");+ assert.ok(!text.includes("generated_by"));+});++test("readArchiveOverview treats a body-less sidecar as not ready", async () => {+ stubFetch(() => ({ status: "ok", result: "---\ndirectory: x\n---\n\n" }));+ assert.equal(await makeClient().readArchiveOverview(ARCHIVE), null);+ stubFetch(() => ({ status: "ok", result: " \n" }));+ assert.equal(await makeClient().readArchiveOverview(ARCHIVE), null);+});++test("readArchiveOverview returns null while phase 2 is still running", async () => {+ stubFetch(() => notFound);+ assert.equal(await makeClient().readArchiveOverview(ARCHIVE), null);+});++test("readArchiveOverview returns null when fetch itself blows up", async () => {+ globalThis.fetch = async () => { throw new Error("ECONNREFUSED"); };+ assert.equal(await makeClient().readArchiveOverview(ARCHIVE), null);+ assert.equal(await makeClient().readArchiveOverview(""), null);+});++// ---------- readArchiveMessages ----------++test("readArchiveMessages parses JSONL and keeps a malformed line as a placeholder", async () => {+ const lines = [+ JSON.stringify({ id: "m1", role: "user", parts: [{ type: "text", text: "hello" }], created_at: "2026-09-10T06:00:00Z" }),+ "{ this is not json",+ JSON.stringify({+ id: "m2",+ role: "assistant",+ parts: [+ { type: "text", text: "running it" },+ { type: "tool_result", name: "bash", output: "exit 0" },+ ],+ created_at: "2026-09-10T06:00:05Z",+ }),+ "",+ JSON.stringify({ id: "m3", role: "user", content: "plain content" }),+ ].join("\n");+ stubFetch(() => ({ status: "ok", result: lines }));++ const msgs = await makeClient().readArchiveMessages(ARCHIVE);+ // Five, not three: `search_contents` turns a grep hit's line number into an+ // item index, so every line of the file keeps its slot — a malformed one and+ // a blank one included — instead of shifting every pointer after it by one.+ assert.equal(msgs.length, 5);+ assert.ok(calls[0].url.includes(encodeURIComponent(`${ARCHIVE}/messages.jsonl`)));++ assert.deepEqual(msgs[0], {+ id: "m1",+ role: "user",+ text: "hello",+ parts: [{ type: "text", text: "hello" }],+ created_at: "2026-09-10T06:00:00Z",+ });+ assert.deepEqual(msgs[1], {+ id: "", role: "unreadable", text: "(unreadable archive line)", parts: [], created_at: "",+ });+ assert.equal(msgs[2].text, "running it\n[tool bash] exit 0");+ assert.equal(msgs[2].parts.length, 2);+ assert.deepEqual(msgs[3], {+ id: "", role: "blank", text: "(blank archive line)", parts: [], created_at: "",+ });+ assert.equal(msgs[4].text, "plain content");+ assert.equal(msgs[4].created_at, "");+});++test("readArchiveMessages returns null when the file is unreadable", async () => {+ stubFetch(() => notFound);+ assert.equal(await makeClient().readArchiveMessages(ARCHIVE), null);+});++// Part shapes below are exactly what openviking/message/message.py::_part_to_dict+// serializes into messages.jsonl: a tool call carries tool_input only, a tool+// result carries tool_output, and neither carries `output`/`text`.+test("readArchiveMessages renders the server's real tool/context/image parts", async () => {+ const lines = [+ JSON.stringify({+ id: "m1",+ role: "assistant",+ parts: [{+ type: "tool",+ tool_id: "call_1",+ tool_name: "bash",+ tool_uri: "",+ skill_uri: "",+ tool_status: "completed",+ tool_input: { command: "ls -la" },+ }],+ created_at: "2026-09-10T06:00:00Z",+ }),+ JSON.stringify({+ id: "m2",+ role: "user",+ parts: [{+ type: "tool",+ tool_name: "bash",+ tool_status: "completed",+ tool_input: { command: "ls -la" },+ tool_output: "total 0",+ }],+ created_at: "2026-09-10T06:00:01Z",+ }),+ JSON.stringify({+ id: "m3",+ role: "user",+ parts: [+ { type: "context", uri: "viking://user/default/memories/x", context_type: "memory", abstract: "codename ZEPHYR-9942" },+ { type: "image", image_url: { url: "data:image/png;base64,AAAA" } },+ ],+ created_at: "2026-09-10T06:00:02Z",+ }),+ JSON.stringify({+ id: "m4",+ role: "assistant",+ parts: [{ type: "tool", tool_name: "", tool_status: "error" }],+ created_at: "2026-09-10T06:00:03Z",+ }),+ JSON.stringify({+ id: "m5",+ role: "user",+ parts: [{+ type: "tool",+ tool_name: "read_file",+ tool_status: "completed",+ tool_output: "",+ tool_output_ref: `${ARCHIVE}/tools/call_9.txt`,+ }],+ created_at: "2026-09-10T06:00:04Z",+ }),+ ].join("\n");+ stubFetch(() => ({ status: "ok", result: lines }));++ const msgs = await makeClient().readArchiveMessages(ARCHIVE);+ assert.equal(msgs.length, 5);+ assert.equal(msgs[0].text, '[tool bash] {"command":"ls -la"}');+ assert.equal(msgs[1].text, '[tool bash] {"command":"ls -la"} total 0');+ assert.equal(+ msgs[2].text,+ "[context viking://user/default/memories/x] codename ZEPHYR-9942\n[image]",+ );+ assert.equal(msgs[3].text, "[tool unknown]", "a bare tool part must not read back blank");+ assert.equal(msgs[4].text, `[tool read_file] <output stored at ${ARCHIVE}/tools/call_9.txt>`);+ for (const m of msgs) assert.notEqual(m.text, "", "no archived part may vanish");+});++test("readArchiveMessages tolerates a non-array parts field and a JSON scalar line", async () => {+ const lines = [+ JSON.stringify({ id: "m1", role: "user", parts: "oops", content: "fallback text" }),+ "42",+ JSON.stringify(["not", "an", "object"]),+ JSON.stringify(null),+ JSON.stringify({ role: "assistant", parts: [{ type: "text", text: "kept" }] }),+ ].join("\r\n");+ stubFetch(() => ({ status: "ok", result: lines }));++ const msgs = await makeClient().readArchiveMessages(ARCHIVE);+ // The three lines that are not JSON objects keep their slots as placeholders.+ assert.equal(msgs.length, 5);+ assert.deepEqual(msgs[0], {+ id: "m1", role: "user", text: "fallback text", parts: [], created_at: "",+ });+ for (const i of [1, 2, 3]) assert.equal(msgs[i].role, "unreadable");+ assert.equal(msgs[4].id, "", "a missing id becomes an empty string, never 'undefined'");+ assert.equal(msgs[4].text, "kept");+});++test("readArchiveMessages returns [] for an archive that is present but empty", async () => {+ stubFetch(() => ({ status: "ok", result: "" }));+ assert.deepEqual(await makeClient().readArchiveMessages(ARCHIVE), []);+ assert.equal(await makeClient().readArchiveMessages(" "), null);+});++test("readArchiveMessages keeps blank lines numbered and drops only the final newline", async () => {+ // Two blank lines: the trailing newline terminates line 2 rather than opening+ // a line 3, so the file is two items, both placeholders. Anything else would+ // move `line - 1` off the item a grep hit points at.+ stubFetch(() => ({ status: "ok", result: "\n\n" }));+ const blanks = await makeClient().readArchiveMessages(ARCHIVE);+ assert.equal(blanks.length, 2);+ for (const item of blanks) {+ assert.deepEqual(item, {+ id: "", role: "blank", text: "(blank archive line)", parts: [], created_at: "",+ });+ }++ // A blank line between two real messages keeps the second one at line 3.+ const lines = [+ JSON.stringify({ id: "m1", role: "user", content: "one" }),+ "",+ JSON.stringify({ id: "m2", role: "user", content: "two" }),+ "",+ ].join("\n");+ stubFetch(() => ({ status: "ok", result: lines }));+ const msgs = await makeClient().readArchiveMessages(ARCHIVE);+ assert.equal(msgs.length, 3, "the trailing newline is not a fourth line");+ assert.equal(msgs[0].id, "m1");+ assert.equal(msgs[1].role, "blank");+ assert.equal(msgs[2].id, "m2");+});++// ---------- listSessionArchives ----------++test("listSessionArchives filters to archive_NNN and orders newest first", async () => {+ stubFetch((url) => {+ if (url.includes("/api/v1/sessions/")) return sessionOk;+ return {+ status: "ok",+ result: [+ { uri: `${ROOT}/history/archive_001`, size: 0, isDir: true, modTime: "2026-09-10T05:00:00Z", abstract: "# Working Memory" },+ { uri: `${ROOT}/history/archive_003`, size: 0, isDir: true, modTime: "2026-09-10T07:00:00Z", abstract: "[Directory abstract is not ready]" },+ { uri: `${ROOT}/history/.meta.json`, size: 12, isDir: false, modTime: "", abstract: "" },+ { uri: `${ROOT}/history/archive_002`, size: 0, isDir: true, modTime: "2026-09-10T06:00:00Z", abstract: "# Working Memory" },+ ],+ };+ });++ const rows = await makeClient().listSessionArchives(SID);+ assert.deepEqual(rows.map(r => r.archiveId), ["archive_003", "archive_002", "archive_001"]);+ assert.equal(rows[0].uri, `${ROOT}/history/archive_003`);+ assert.equal(rows[0].modTime, "2026-09-10T07:00:00Z");+ assert.equal(rows[2].abstract, "# Working Memory");++ const lsUrl = calls[1].url;+ assert.ok(lsUrl.startsWith("http://127.0.0.1:1933/api/v1/fs/ls?uri="));+ assert.ok(lsUrl.includes(encodeURIComponent(`${ROOT}/history`)));+ assert.ok(lsUrl.includes("sort_by=name"));+ assert.ok(lsUrl.includes("sort_order=desc"));+});++test("listSessionArchives skips a non-directory entry named like an archive", async () => {+ stubFetch((url) => {+ if (url.includes("/api/v1/sessions/")) return sessionOk;+ return {+ status: "ok",+ result: [+ { uri: `${ROOT}/history/archive_004`, isDir: false, modTime: "", abstract: "" },+ { uri: `${ROOT}/history/archive_002`, isDir: true, modTime: "", abstract: "" },+ { uri: "", name: "archive_001", isDir: true, modTime: "", abstract: "" },+ "not an object",+ ],+ };+ });+ const rows = await makeClient().listSessionArchives(SID);+ assert.deepEqual(rows.map(r => r.archiveId), ["archive_002", "archive_001"]);+});++test("listSessionArchives uses the legacy root when the session lookup fails", async () => {+ stubFetch((url) => (url.includes("/api/v1/sessions/") ? notFound : { status: "ok", result: [] }));+ await makeClient().listSessionArchives(SID);+ assert.ok(calls[1].url.includes(encodeURIComponent(`viking://session/${SID}/history`)));+ assert.ok(!calls[1].url.includes("~"));+});++test("listSessionArchives tells an empty history apart from an unreadable one", async () => {+ // A session that never committed has no `history` directory: an empty list.+ stubFetch((url) => (url.includes("/api/v1/sessions/") ? sessionOk : notFound));+ assert.deepEqual(await makeClient().listSessionArchives(SID), []);++ // A blocked or broken listing is null — `history` must not report it to the+ // model as "this session has no archived windows".+ for (const failure of [+ { httpStatus: 403, body: { status: "error", error: { code: "ApiBlocked", message: "blocked" } } },+ { httpStatus: 500, body: { status: "error", error: { message: "boom" } } },+ { status: "ok", result: { not: "an array" } },+ ]) {+ stubFetch((url) => (url.includes("/api/v1/sessions/") ? sessionOk : failure));+ assert.equal(await makeClient().listSessionArchives(SID), null);+ }+});++// ---------- grepSessionArchives ----------++test("grepSessionArchives posts a regex over the whole history and parses matches", async () => {+ stubFetch((url) => {+ if (url.includes("/api/v1/sessions/")) return sessionOk;+ return {+ status: "ok",+ result: {+ matches: [+ { line: 14, uri: `${ROOT}/history/archive_002/messages.jsonl`, content: "codename ZEPHYR-9942" },+ { line: 3, uri: `${ROOT}/history/archive_001/.overview.md`, content: "## Key Facts" },+ { line: "bad", uri: "", content: 7 },+ ],+ },+ };+ });++ const matches = await makeClient().grepSessionArchives(SID, "ZEPHYR.\\d+");+ assert.deepEqual(matches[0], {+ archiveId: "archive_002",+ file: "messages.jsonl",+ line: 14,+ content: "codename ZEPHYR-9942",+ });+ assert.deepEqual(matches[1], {+ archiveId: "archive_001",+ file: ".overview.md",+ line: 3,+ content: "## Key Facts",+ });+ assert.deepEqual(matches[2], { archiveId: "", file: "", line: 0, content: "" });++ const grepCall = calls[1];+ assert.equal(grepCall.url, "http://127.0.0.1:1933/api/v1/search/grep");+ assert.equal(grepCall.init.method, "POST");+ assert.deepEqual(JSON.parse(grepCall.init.body), {+ uri: `${ROOT}/history`,+ pattern: "ZEPHYR.\\d+",+ case_insensitive: true,+ node_limit: 256,+ });+});++test("grepSessionArchives scopes to one archive, escapes literals, honours options", async () => {+ stubFetch((url) => (url.includes("/api/v1/sessions/") ? sessionOk : { status: "ok", result: { matches: [] } }));+ const client = makeClient();+ await client.grepSessionArchives(SID, "a.b(c)", {+ archiveId: "archive_002",+ caseInsensitive: false,+ nodeLimit: 32,+ literal: true,+ });+ assert.deepEqual(JSON.parse(calls[1].init.body), {+ uri: `${ROOT}/history/archive_002`,+ pattern: "a\\.b\\(c\\)",+ case_insensitive: false,+ node_limit: 32,+ });++ await client.grepSessionArchives(SID, "a.b(c)", { archiveId: "../../etc" });+ assert.equal(JSON.parse(calls[2].init.body).uri, `${ROOT}/history`, "a bogus archive id must not escape the root");+});++test("grepSessionArchives accepts a bare array body and clamps node_limit", async () => {+ stubFetch((url) => {+ if (url.includes("/api/v1/sessions/")) return sessionOk;+ return { status: "ok", result: [{ line: 2, uri: `${ROOT}/history/archive_001/messages.jsonl`, content: "x" }, null] };+ });+ const client = makeClient();+ const matches = await client.grepSessionArchives(SID, "x", { nodeLimit: 99999 });+ assert.equal(matches.length, 1);+ assert.equal(matches[0].archiveId, "archive_001");+ assert.equal(JSON.parse(calls[1].init.body).node_limit, 4096);++ await client.grepSessionArchives(SID, "x", { nodeLimit: 0 });+ assert.equal(JSON.parse(calls[2].init.body).node_limit, 1);+ await client.grepSessionArchives(SID, "x", { nodeLimit: Number.NaN });+ assert.equal(JSON.parse(calls[3].init.body).node_limit, 256);+});++test("grepSessionArchives keeps the scoped archive id when a match has no uri", async () => {+ stubFetch((url) => {+ if (url.includes("/api/v1/sessions/")) return sessionOk;+ return { status: "ok", result: { matches: [{ line: 1, content: "hit" }] } };+ });+ const matches = await makeClient().grepSessionArchives(SID, "hit", { archiveId: "archive_007" });+ assert.deepEqual(matches[0], { archiveId: "archive_007", file: "", line: 1, content: "hit" });+});++test("grepSessionArchives returns [] on failure and for an empty pattern", async () => {+ stubFetch((url) => (url.includes("/api/v1/sessions/") ? sessionOk : notFound));+ const client = makeClient();+ assert.deepEqual(await client.grepSessionArchives(SID, "x"), []);+ const before = calls.length;+ assert.deepEqual(await client.grepSessionArchives(SID, ""), []);+ assert.equal(calls.length, before, "an empty pattern must not reach the server");+});++// ---------- getTask ----------++test("getTask reports phase 2 status, stage and error", async () => {+ stubFetch(() => ({ status: "ok", result: { task_id: "t-1", status: "running", stage: "extraction" } }));+ const running = await makeClient().getTask("t-1");+ assert.deepEqual(running, { status: "running", stage: "extraction" });+ assert.equal(calls[0].url, "http://127.0.0.1:1933/api/v1/tasks/t-1");++ stubFetch(() => ({ status: "ok", result: { status: "failed", error: "vlm timeout" } }));+ assert.deepEqual(await makeClient().getTask("t-1"), { status: "failed", error: "vlm timeout" });+});++// TaskRecord.to_dict() always emits stage and error, null when unset.+test("getTask ignores the null stage/error the tracker always serializes", async () => {+ stubFetch(() => ({+ status: "ok",+ result: {+ task_id: "t-2",+ task_type: "session_commit",+ status: "completed",+ stage: null,+ error: null,+ meta: {},+ result: { archived: 12 },+ created_at: 1,+ updated_at: 2,+ },+ }));+ assert.deepEqual(await makeClient().getTask("t-2"), { status: "completed" });+});++test("getTask survives a non-string error payload and a dead connection", async () => {+ stubFetch(() => ({ status: "ok", result: { status: "failed", error: { code: "VLM", msg: "boom" } } }));+ const t = await makeClient().getTask("t-3");+ assert.equal(t.status, "failed");+ assert.equal(t.error, '{"code":"VLM","msg":"boom"}');++ globalThis.fetch = async () => { throw new Error("ECONNREFUSED"); };+ assert.equal(await makeClient().getTask("t-3"), null);+});++test("getTask returns null on failure or an empty id", async () => {+ stubFetch(() => notFound);+ const client = makeClient();+ assert.equal(await client.getTask("t-1"), null);+ const before = calls.length;+ assert.equal(await client.getTask(""), null);+ assert.equal(calls.length, before);+});++// ---------- regressions on the methods the archive work was not allowed to change ----------++test("commitSessionResponse still returns the envelope, widened fields included", async () => {+ stubFetch(() => ({+ status: "ok",+ result: { session_id: SID, status: "accepted", task_id: "t-9", archive_uri: ARCHIVE, archived: true },+ trace_id: "trace-42",+ }));+ const res = await makeClient().commitSessionResponse(SID, 0);+ assert.equal(res.result.status, "accepted");+ assert.equal(res.result.archive_uri, ARCHIVE);+ assert.equal(res.result.archived, true);+ assert.equal(res.result.trace_id, "trace-42", "the envelope trace id is still back-filled");+ assert.deepEqual(JSON.parse(calls[0].init.body), { keep_recent_count: 0 });++ // A skipped commit sends archive_uri: null — callers must see it, not undefined.+ stubFetch(() => ({+ status: "ok",+ result: { session_id: SID, status: "skipped", archive_uri: null, archived: false, reason: "no_messages" },+ }));+ const skipped = (await makeClient().commitSessionResponse(SID, 0)).result;+ assert.equal(skipped.status, "skipped");+ assert.equal(skipped.archive_uri, null);+ assert.equal(skipped.reason, "no_messages");+});++test("ls, readContent and health keep their pre-existing behaviour", async () => {+ stubFetch((url) => {+ if (url.includes("/health")) return { status: "ok", result: {} };+ if (url.includes("/content/read")) return { status: "ok", result: "file body" };+ return { status: "ok", result: [{ uri: `${ROOT}/history`, isDir: true, size: 0, mode: 0, modTime: "t", abstract: "a" }] };+ });+ const client = makeClient();+ assert.equal(await client.health(), true);+ assert.equal(client.connected, true);+ assert.equal(await client.readContent(`${ARCHIVE}/messages.jsonl`), "file body");+ const rows = await client.ls(ROOT);+ assert.equal(rows.length, 1);+ assert.equal(rows[0].name, "history", "name still falls back to the uri basename");+});++test("fetchJSON reports a transport failure instead of throwing, and still times out", async () => {+ globalThis.fetch = async () => { throw new Error("ECONNREFUSED"); };+ const client = makeClient();+ const dead = await client.fetchJSON("/api/v1/health");+ assert.equal(dead.ok, false);+ assert.equal(dead.status, 0);+ assert.match(dead.error.message, /ECONNREFUSED/);++ globalThis.fetch = (url, init) => new Promise((_resolve, reject) => {+ init.signal.addEventListener("abort", () => reject(new Error("aborted")));+ });+ const started = Date.now();+ const timedOut = await client.fetchJSON("/api/v1/health", undefined, 20);+ assert.equal(timedOut.ok, false);+ assert.ok(Date.now() - started < 5000, "the abort timer must still fire");+});diff --git a/examples/pi-experimental-context-management/tests/config.test.mjs b/examples/pi-experimental-context-management/tests/config.test.mjsnew file mode 100644index 000000000..13a23922d--- /dev/null+++ b/examples/pi-experimental-context-management/tests/config.test.mjs@@ -0,0 +1,438 @@+import test from "node:test";+import assert from "node:assert/strict";+import { mkdtemp, rm, writeFile, readFile } from "node:fs/promises";+import { join, dirname } from "node:path";+import { tmpdir } from "node:os";+import { fileURLToPath, pathToFileURL } from "node:url";+import { loadConfig, loadConfigFromModuleUrl } from "../config.ts";++const EXTENSION_DIR = dirname(dirname(fileURLToPath(import.meta.url)));++const CONTEXT_WINDOW_DEFAULTS = {+ resetDeadlineMs: 60000,+ archivePollMs: 2000,+ overviewRefreshMaxAttempts: 20,+ overviewBudget: 3000,+ notesBudget: 1500,+ pendingRequestBudget: 400,+ softPercent: 70,+ hardPercent: 85,+ idleGapMinutes: 30,+ statusEveryTurn: true,+ historyItemMaxChars: 8000,+ recentResetGuardMs: 60000,+};++async function withConfigFile(body, fn, env = {}, cliConfig = null) {+ const dir = await mkdtemp(join(tmpdir(), "ov-pi-config-用户-"));+ const oldEnv = {+ OPENVIKING_URL: process.env.OPENVIKING_URL,+ OPENVIKING_API_KEY: process.env.OPENVIKING_API_KEY,+ OPENVIKING_ACCOUNT: process.env.OPENVIKING_ACCOUNT,+ OPENVIKING_USER: process.env.OPENVIKING_USER,+ OPENVIKING_PEER_ID: process.env.OPENVIKING_PEER_ID,+ OPENVIKING_WORKSPACE_PEER: process.env.OPENVIKING_WORKSPACE_PEER,+ OPENVIKING_RECALL_PEER_SCOPE: process.env.OPENVIKING_RECALL_PEER_SCOPE,+ OPENVIKING_CREDENTIAL_SOURCE: process.env.OPENVIKING_CREDENTIAL_SOURCE,+ OPENVIKING_CLI_CONFIG_FILE: process.env.OPENVIKING_CLI_CONFIG_FILE,+ OPENVIKING_CONFIG_FILE: process.env.OPENVIKING_CONFIG_FILE,+ OPENVIKING_DEBUG_LOG: process.env.OPENVIKING_DEBUG_LOG,+ OV_DEBUG_LOG: process.env.OV_DEBUG_LOG,+ OPENVIKING_CONTEXT_STATUS_EVERY_TURN: process.env.OPENVIKING_CONTEXT_STATUS_EVERY_TURN,+ OPENVIKING_CONTEXT_RESET_DEADLINE_MS: process.env.OPENVIKING_CONTEXT_RESET_DEADLINE_MS,+ };+ process.env.OPENVIKING_CREDENTIAL_SOURCE = "env";+ process.env.OPENVIKING_URL = "http://127.0.0.1:1933";+ process.env.OPENVIKING_CLI_CONFIG_FILE = join(dir, "ovcli.conf");+ process.env.OPENVIKING_CONFIG_FILE = join(dir, "ov.conf");+ delete process.env.OPENVIKING_API_KEY;+ delete process.env.OPENVIKING_ACCOUNT;+ delete process.env.OPENVIKING_USER;+ delete process.env.OPENVIKING_PEER_ID;+ delete process.env.OPENVIKING_WORKSPACE_PEER;+ delete process.env.OPENVIKING_RECALL_PEER_SCOPE;+ delete process.env.OPENVIKING_DEBUG_LOG;+ delete process.env.OV_DEBUG_LOG;+ delete process.env.OPENVIKING_CONTEXT_STATUS_EVERY_TURN;+ delete process.env.OPENVIKING_CONTEXT_RESET_DEADLINE_MS;+ for (const [key, value] of Object.entries(env)) {+ if (value === undefined) delete process.env[key];+ else process.env[key] = value;+ }++ try {+ await writeFile(join(dir, "config.json"), JSON.stringify(body), "utf8");+ if (cliConfig !== null) {+ await writeFile(join(dir, "ovcli.conf"), JSON.stringify(cliConfig), "utf8");+ }+ return await fn(loadConfig(dir), dir);+ } finally {+ for (const [key, value] of Object.entries(oldEnv)) {+ if (value === undefined) delete process.env[key];+ else process.env[key] = value;+ }+ await rm(dir, { recursive: true, force: true });+ }+}++test("loadConfig defaults capture to faithful, tool results on", async () => {+ await withConfigFile({}, (cfg) => {+ assert.equal(cfg.faithfulCapture, true);+ assert.equal(cfg.captureToolResults, true);+ assert.equal(cfg.captureAssistantTurns, true);+ assert.equal(cfg.captureMaxLength, 24000);+ assert.equal(cfg.captureToolMaxChars, 1000000);+ });+});++test("loadConfig carries no takeover or recall-ledger keys", async () => {+ // The fork dropped both features; a stale key in an old config.json is+ // passed through untouched but never read, so the defaults must not name it.+ await withConfigFile({}, (cfg) => {+ for (const key of Object.keys(cfg)) {+ assert.ok(!key.startsWith("takeover"), `unexpected takeover key: ${key}`);+ }+ assert.equal(cfg.recallLedger, undefined);+ });+});++test("loadConfig lets config.json turn tool-result capture off", async () => {+ await withConfigFile({ captureToolResults: false }, (cfg) => {+ assert.equal(cfg.captureToolResults, false);+ // faithfulCapture is not a switch: the archive is the only way back to a+ // closed window.+ assert.equal(cfg.faithfulCapture, true);+ });+});++test("loadConfigFromModuleUrl decodes Unicode paths", async () => {+ await withConfigFile({ commitKeepRecentCount: 3 }, (_cfg, dir) => {+ const moduleUrl = pathToFileURL(join(dir, "index.ts")).href;+ const cfg = loadConfigFromModuleUrl(moduleUrl);+ assert.equal(cfg.commitKeepRecentCount, 3);+ });+});++test("loadConfig clamps invalid values", async () => {+ await withConfigFile({+ commitKeepRecentCount: -5,+ captureMaxLength: 1,+ captureToolMaxChars: 10,+ recallLimit: 999,+ scoreThreshold: 5,+ }, (cfg) => {+ assert.equal(cfg.commitKeepRecentCount, 0);+ assert.equal(cfg.captureMaxLength, 200);+ assert.equal(cfg.captureToolMaxChars, 200);+ assert.equal(cfg.recallLimit, 50);+ assert.equal(cfg.scoreThreshold, 1);+ });+});++test("loadConfig derives workspace peer by default", async () => {+ // The default is now the repository, so the expectation follows whichever+ // template resolves where the suite runs — inside a checkout that is the+ // remote, and outside one it is still the old working-directory id.+ const { resolveEffectivePeerId } = await import("../shared/workspace-peer.mjs");+ const expected = resolveEffectivePeerId({ cfg: {}, cwd: process.cwd() });+ await withConfigFile({}, (cfg) => {+ assert.equal(cfg.peerId, expected.peerId);+ assert.equal(cfg.workspacePeer, true);+ assert.equal(cfg.recallPeerScope, "all");+ });+});++test("loadConfig prefers config peer over workspace derivation", async () => {+ await withConfigFile({+ peerId: " pi ",+ workspacePeer: true,+ }, (cfg) => {+ assert.equal(cfg.peerId, "pi");+ });+});++test("loadConfig keeps config peer when workspace derivation is disabled", async () => {+ await withConfigFile({+ peerId: "pi",+ workspacePeer: false,+ }, (cfg) => {+ assert.equal(cfg.peerId, "pi");+ assert.equal(cfg.workspacePeer, false);+ });+});++test("loadConfig gives environment peer precedence over config peer", async () => {+ await withConfigFile({+ peerId: "config-peer",+ recallPeerScope: "actor",+ workspacePeer: false,+ }, (cfg) => {+ assert.equal(cfg.peerId, "explicit-peer");+ assert.equal(cfg.workspacePeer, false);+ assert.equal(cfg.recallPeerScope, "actor");+ }, { OPENVIKING_PEER_ID: "explicit-peer" });+});++test("loadConfig leaves the debug log off when nothing asks for it", async () => {+ await withConfigFile({}, (cfg) => {+ assert.equal(cfg.debugLogPath, "");+ });+});++test("loadConfig reads the debug log path from OPENVIKING_DEBUG_LOG", async () => {+ await withConfigFile({}, (cfg) => {+ assert.equal(cfg.debugLogPath, "/tmp/ov-pi-shared.log");+ }, { OPENVIKING_DEBUG_LOG: "/tmp/ov-pi-shared.log" });+});++test("loadConfig still honours the deprecated OV_DEBUG_LOG", async () => {+ await withConfigFile({}, (cfg) => {+ assert.equal(cfg.debugLogPath, "/tmp/ov-pi-legacy.log");+ }, { OV_DEBUG_LOG: "/tmp/ov-pi-legacy.log" });+});++test("loadConfig prefers OPENVIKING_DEBUG_LOG over the deprecated alias", async () => {+ await withConfigFile({ debugLogPath: "/tmp/ov-pi-file.log" }, (cfg) => {+ assert.equal(cfg.debugLogPath, "/tmp/ov-pi-shared.log");+ }, {+ OPENVIKING_DEBUG_LOG: "/tmp/ov-pi-shared.log",+ OV_DEBUG_LOG: "/tmp/ov-pi-legacy.log",+ });+});++test("loadConfig falls back to the config file debug log path", async () => {+ await withConfigFile({ debugLogPath: " /tmp/ov-pi-file.log " }, (cfg) => {+ assert.equal(cfg.debugLogPath, "/tmp/ov-pi-file.log");+ });+});++test("loadConfig gives ovcli peer precedence over config peer", async () => {+ await withConfigFile({+ peerId: "config-peer",+ }, (cfg) => {+ assert.equal(cfg.peerId, "ovcli-peer");+ }, {+ OPENVIKING_CREDENTIAL_SOURCE: "cli",+ OPENVIKING_URL: undefined,+ }, {+ url: "http://127.0.0.1:1933",+ actor_peer_id: "ovcli-peer",+ });+});++test("loadConfig ships the contextWindow defaults", async () => {+ await withConfigFile({}, (cfg) => {+ assert.deepEqual(cfg.contextWindow, CONTEXT_WINDOW_DEFAULTS);+ });+});++test("the shipped config.json parses and restates the defaults exactly", async () => {+ // config.json spells every default out, so it silently overrides config.ts+ // once the two drift apart. Load the real file to keep them tied together.+ const shipped = JSON.parse(await readFile(join(EXTENSION_DIR, "config.json"), "utf8"));+ assert.ok(!("captureMode" in shipped), "the dead captureMode key is gone from config.json");+ await withConfigFile(shipped, (cfg) => {+ assert.deepEqual(cfg.contextWindow, CONTEXT_WINDOW_DEFAULTS);+ assert.equal(cfg.captureToolResults, true);+ assert.equal(cfg.captureMaxLength, 24000);+ assert.equal(cfg.captureToolMaxChars, 1000000);+ assert.equal(cfg.commitKeepRecentCount, 10);+ // Nothing in this fork reads them any more: `new_context` and the pi+ // compaction fallback are the only writers of archive boundaries.+ assert.equal("commitTokenThreshold" in shipped, false);+ assert.equal("resumeContextBudget" in shipped, false);+ // config.json must not name recallLimit or recallQueryExpansion: both+ // carry a "…Configured" flag that recall reads as "the user chose this".+ assert.equal(cfg.recallLimitConfigured, false);+ assert.equal(cfg.recallQueryExpansionConfigured, false);+ });+});++test("loadConfig never writes the clamped window back into the module defaults", async () => {+ // The window object is rebuilt per call and clamped in place; if it ever+ // aliased DEFAULT_CONFIG.contextWindow, the hardPercent lift below would+ // leak into every later load in the same process.+ await withConfigFile({ contextWindow: { softPercent: 90, hardPercent: 20 } }, (cfg) => {+ assert.equal(cfg.contextWindow.hardPercent, 90);+ });+ await withConfigFile({}, (cfg) => {+ assert.deepEqual(cfg.contextWindow, CONTEXT_WINDOW_DEFAULTS);+ });+});++test("loadConfig drops the dead captureMode key", async () => {+ // Capture is always faithful in this fork, so nothing reads a+ // semantic/keyword switch and the defaults must not name one.+ await withConfigFile({}, (cfg) => {+ assert.ok(!("captureMode" in cfg), "captureMode is gone from the defaults");+ assert.equal(cfg.captureMaxLength, 24000);+ assert.equal(cfg.captureToolMaxChars, 1000000);+ assert.equal(cfg.captureToolResults, true);+ });+});++test("loadConfig merges contextWindow over the defaults key by key", async () => {+ await withConfigFile({+ contextWindow: {+ resetDeadlineMs: 120000,+ notesBudget: 900,+ statusEveryTurn: false,+ unknownKey: "ignored",+ },+ }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 120000);+ assert.equal(cfg.contextWindow.notesBudget, 900);+ assert.equal(cfg.contextWindow.statusEveryTurn, false);+ assert.ok(!("unknownKey" in cfg.contextWindow), "unknown keys are ignored");+ // Untouched keys keep their defaults.+ assert.equal(cfg.contextWindow.archivePollMs, 2000);+ assert.equal(cfg.contextWindow.softPercent, 70);+ assert.equal(cfg.contextWindow.hardPercent, 85);+ assert.equal(cfg.contextWindow.historyItemMaxChars, 8000);+ });+});++test("loadConfig ignores a non-object contextWindow", async () => {+ for (const block of ["yes", null, 7, false, []]) {+ await withConfigFile({ contextWindow: block }, (cfg) => {+ assert.deepEqual(cfg.contextWindow, CONTEXT_WINDOW_DEFAULTS, `contextWindow: ${JSON.stringify(block)}`);+ });+ }+});++const CONTEXT_WINDOW_BOUNDS = [+ { key: "resetDeadlineMs", min: 5000, max: 600000 },+ { key: "archivePollMs", min: 250, max: 30000 },+ { key: "overviewRefreshMaxAttempts", min: 0, max: 200 },+ { key: "overviewBudget", min: 100, max: 50000 },+ { key: "notesBudget", min: 100, max: 20000 },+ { key: "pendingRequestBudget", min: 0, max: 8000 },+ { key: "softPercent", min: 10, max: 99, withHigh: { hardPercent: 99 } },+ { key: "hardPercent", min: 10, max: 99, withLow: { softPercent: 10 } },+ { key: "idleGapMinutes", min: 0, max: 1440 },+ { key: "historyItemMaxChars", min: 500, max: 100000 },+ { key: "recentResetGuardMs", min: 0, max: 600000 },+];++for (const { key, min, max, withLow, withHigh } of CONTEXT_WINDOW_BOUNDS) {+ test(`loadConfig clamps contextWindow.${key} to ${min}..${max}`, async () => {+ await withConfigFile({ contextWindow: { [key]: -1000000, ...(withLow || {}) } }, (cfg) => {+ assert.equal(cfg.contextWindow[key], min);+ });+ await withConfigFile({ contextWindow: { [key]: 100000000, ...(withHigh || {}) } }, (cfg) => {+ assert.equal(cfg.contextWindow[key], max);+ });+ });+}++test("loadConfig falls back to the default for a non-numeric contextWindow value", async () => {+ await withConfigFile({+ contextWindow: { resetDeadlineMs: "soon", overviewBudget: null, idleGapMinutes: {} },+ }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 60000);+ // null means "not set" for `??`, so it falls back before the clamp sees it.+ assert.equal(cfg.contextWindow.overviewBudget, 3000);+ assert.equal(cfg.contextWindow.idleGapMinutes, 30);+ });+});++test("loadConfig pulls a coercible junk value to the nearest bound", async () => {+ // `Number("")`, `Number([])` and `Number(true)` are 0 and 1, not NaN, so+ // these never reach the fallback — they land on the minimum. Pinned because+ // it is the one place the README's "falls back to the default" does not hold.+ await withConfigFile({+ contextWindow: { overviewBudget: "", notesBudget: [], archivePollMs: true },+ }, (cfg) => {+ assert.equal(cfg.contextWindow.overviewBudget, 100);+ assert.equal(cfg.contextWindow.notesBudget, 100);+ assert.equal(cfg.contextWindow.archivePollMs, 250);+ });+});++test("loadConfig accepts a numeric string from config.json", async () => {+ await withConfigFile({ contextWindow: { resetDeadlineMs: "120000" } }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 120000);+ });+});++test("loadConfig rounds fractional contextWindow values", async () => {+ await withConfigFile({ contextWindow: { archivePollMs: 2500.6, softPercent: 60.4 } }, (cfg) => {+ assert.equal(cfg.contextWindow.archivePollMs, 2501);+ assert.equal(cfg.contextWindow.softPercent, 60);+ });+});++test("loadConfig lifts hardPercent to softPercent when it is configured lower", async () => {+ await withConfigFile({ contextWindow: { softPercent: 80, hardPercent: 60 } }, (cfg) => {+ assert.equal(cfg.contextWindow.softPercent, 80);+ assert.equal(cfg.contextWindow.hardPercent, 80);+ });+ // Clamping happens first, so a below-range hardPercent is lifted too.+ await withConfigFile({ contextWindow: { softPercent: 40, hardPercent: 1 } }, (cfg) => {+ assert.equal(cfg.contextWindow.hardPercent, 40);+ });+ await withConfigFile({ contextWindow: { softPercent: 40, hardPercent: 90 } }, (cfg) => {+ assert.equal(cfg.contextWindow.hardPercent, 90);+ });+});++test("loadConfig reads statusEveryTurn spellings from config.json", async () => {+ await withConfigFile({ contextWindow: { statusEveryTurn: "off" } }, (cfg) => {+ assert.equal(cfg.contextWindow.statusEveryTurn, false);+ });+ await withConfigFile({ contextWindow: { statusEveryTurn: "yes" } }, (cfg) => {+ assert.equal(cfg.contextWindow.statusEveryTurn, true);+ });+ await withConfigFile({ contextWindow: { statusEveryTurn: 0 } }, (cfg) => {+ assert.equal(cfg.contextWindow.statusEveryTurn, false);+ });+});++test("OPENVIKING_CONTEXT_STATUS_EVERY_TURN overrides config.json", async () => {+ await withConfigFile({ contextWindow: { statusEveryTurn: true } }, (cfg) => {+ assert.equal(cfg.contextWindow.statusEveryTurn, false);+ }, { OPENVIKING_CONTEXT_STATUS_EVERY_TURN: "0" });+ await withConfigFile({ contextWindow: { statusEveryTurn: false } }, (cfg) => {+ assert.equal(cfg.contextWindow.statusEveryTurn, true);+ }, { OPENVIKING_CONTEXT_STATUS_EVERY_TURN: "on" });+ // An unparseable value leaves the configured one alone.+ await withConfigFile({ contextWindow: { statusEveryTurn: false } }, (cfg) => {+ assert.equal(cfg.contextWindow.statusEveryTurn, false);+ }, { OPENVIKING_CONTEXT_STATUS_EVERY_TURN: "maybe" });+});++test("OPENVIKING_CONTEXT_RESET_DEADLINE_MS overrides config.json and is clamped", async () => {+ await withConfigFile({ contextWindow: { resetDeadlineMs: 60000 } }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 120000);+ }, { OPENVIKING_CONTEXT_RESET_DEADLINE_MS: "120000" });+ await withConfigFile({ contextWindow: { resetDeadlineMs: 60000 } }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 600000);+ }, { OPENVIKING_CONTEXT_RESET_DEADLINE_MS: "9999999" });+ await withConfigFile({ contextWindow: { resetDeadlineMs: 90000 } }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 60000);+ }, { OPENVIKING_CONTEXT_RESET_DEADLINE_MS: "later" });+ // An empty value is not an override: the file value survives untouched.+ await withConfigFile({ contextWindow: { resetDeadlineMs: 90000 } }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 90000);+ }, { OPENVIKING_CONTEXT_RESET_DEADLINE_MS: "" });+ // "0" is a truthy string, so it overrides and then clamps up to the floor —+ // there is no way to ask for a zero (non-blocking) reset deadline.+ await withConfigFile({ contextWindow: { resetDeadlineMs: 90000 } }, (cfg) => {+ assert.equal(cfg.contextWindow.resetDeadlineMs, 5000);+ }, { OPENVIKING_CONTEXT_RESET_DEADLINE_MS: "0" });+});++test("statusEveryTurn stays a boolean whatever the file and env say", async () => {+ // envBool's fallback is the raw configured value, so an unparseable env var+ // on top of a string in config.json must still normalize to a boolean.+ await withConfigFile({ contextWindow: { statusEveryTurn: "off" } }, (cfg) => {+ assert.equal(cfg.contextWindow.statusEveryTurn, false);+ assert.equal(typeof cfg.contextWindow.statusEveryTurn, "boolean");+ }, { OPENVIKING_CONTEXT_STATUS_EVERY_TURN: "maybe" });+ for (const value of ["banana", "", 2, []]) {+ await withConfigFile({ contextWindow: { statusEveryTurn: value } }, (cfg) => {+ assert.equal(typeof cfg.contextWindow.statusEveryTurn, "boolean", `statusEveryTurn: ${JSON.stringify(value)}`);+ assert.equal(cfg.contextWindow.statusEveryTurn, true, "unreadable spellings fall back to the default");+ });+ }+});diff --git a/examples/pi-experimental-context-management/tests/context-window-adapter.test.mjs b/examples/pi-experimental-context-management/tests/context-window-adapter.test.mjsnew file mode 100644index 000000000..5a5c155c6--- /dev/null+++ b/examples/pi-experimental-context-management/tests/context-window-adapter.test.mjs@@ -0,0 +1,299 @@+import test from "node:test";+import assert from "node:assert/strict";+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { createContextWindowManager, readPiReserveTokens } from "../context-window.ts";+import { DEFAULT_RESERVE_TOKENS, pickReserveTokens, readReserveTokens, settingsPaths } from "../lib/pi-settings.mjs";+import { enqueue } from "../shared/pending-queue.mjs";++const SID = "pi-adapter-session";++function fakes(overrides = {}) {+ const calls = {+ addMessage: [],+ addPayload: [],+ commit: [],+ syncBranch: [],+ flush: [],+ overview: [],+ task: [],+ entries: [],+ logs: [],+ };+ const client = {+ connected: true,+ async addMessage(sid, role, content) {+ calls.addMessage.push({ sid, role, content });+ return true;+ },+ async readArchiveOverview(uri) {+ calls.overview.push(uri);+ return "# Working Memory\nbody";+ },+ async getTask(id) {+ calls.task.push(id);+ return { status: "completed" };+ },+ ...(overrides.client ?? {}),+ };+ const sync = {+ sessionId: SID,+ syncedCount: 7,+ async syncBranch(branch) {+ calls.syncBranch.push(branch);+ return { added: 0, tokens: 0, allDelivered: true };+ },+ async flushBarrier(opts) {+ calls.flush.push(opts);+ return true;+ },+ async addPayload(payload) {+ calls.addPayload.push(payload);+ return { accepted: true, delivered: true };+ },+ async commit(opts) {+ calls.commit.push(opts);+ return { status: "accepted", archive_uri: "viking://user/u/sessions/s/history/archive_001" };+ },+ ...(overrides.sync ?? {}),+ };+ const pi = {+ appendEntry(customType, data) {+ calls.entries.push({ customType, data });+ },+ };+ const config = {+ contextWindow: {+ resetDeadlineMs: 5000,+ archivePollMs: 250,+ overviewRefreshMaxAttempts: 3,+ overviewBudget: 3000,+ notesBudget: 1500,+ pendingRequestBudget: 400,+ softPercent: 70,+ hardPercent: 85,+ idleGapMinutes: 30,+ statusEveryTurn: true,+ historyItemMaxChars: 8000,+ },+ };+ const logger = { log: (stage, data) => calls.logs.push({ stage, data }) };+ const core = createContextWindowManager({ pi, client, sync, config, logger });+ return { core, calls, client, sync, pi, config };+}++test("the handoff note goes straight to addMessage, never through the queue", async () => {+ const { core, calls } = fakes();+ const ok = await core.io.postHandoff("[Context Window Handoff] w1 -> w2");+ assert.equal(ok, true);+ assert.deepEqual(calls.addMessage, [+ { sid: SID, role: "assistant", content: "[Context Window Handoff] w1 -> w2" },+ ]);+ // addPayload would queue on failure and land in the *next* archive.+ assert.equal(calls.addPayload.length, 0);+});++test("postHandoff fails closed when there is no session or addMessage throws", async () => {+ const noSession = fakes({ sync: { sessionId: null } });+ assert.equal(await noSession.core.io.postHandoff("x"), false);++ const throwing = fakes({+ client: {+ async addMessage() {+ throw new Error("boom");+ },+ },+ });+ assert.equal(await throwing.core.io.postHandoff("x"), false);+});++test("commit keeps nothing and never queues a retry", async () => {+ const { core, calls } = fakes();+ const result = await core.io.commit({ keepRecentCount: 0 });+ assert.equal(result.status, "accepted");+ assert.deepEqual(calls.commit, [{ queueOnFailure: false, keepRecentCount: 0 }]);++ // A core that passes no keepRecentCount still archives the whole window.+ await core.io.commit({});+ assert.deepEqual(calls.commit[1], { queueOnFailure: false, keepRecentCount: 0 });+});++test("a throwing commit becomes null rather than an exception", async () => {+ const { core } = fakes({+ sync: {+ async commit() {+ throw new Error("network down");+ },+ },+ });+ assert.equal(await core.io.commit({ keepRecentCount: 0 }), null);+});++test("syncBranch, watermark, connectivity and session id come from the managers", async () => {+ const { core, calls, client } = fakes();+ const branch = [{ id: "e1" }];+ assert.deepEqual(await core.io.syncBranch(branch), { added: 0, tokens: 0, allDelivered: true });+ assert.deepEqual(calls.syncBranch, [branch]);+ assert.equal(core.io.getWatermark(), 7);+ assert.equal(core.io.sessionId(), SID);+ assert.equal(core.io.connected(), true);+ client.connected = false;+ assert.equal(core.io.connected(), false);+});++test("readArchiveOverview and getTask swallow client failures", async () => {+ const { core } = fakes({+ client: {+ async readArchiveOverview() {+ throw new Error("404");+ },+ async getTask() {+ throw new Error("blocked");+ },+ },+ });+ assert.equal(await core.io.readArchiveOverview("viking://x"), null);+ assert.equal(await core.io.getTask("t1"), null);+});++test("persistEntry and log reach pi and the debug logger", async () => {+ const { core, calls } = fakes();+ core.io.persistEntry("ov-context-window", { windowIndex: 2 });+ assert.deepEqual(calls.entries, [{ customType: "ov-context-window", data: { windowIndex: 2 } }]);+ core.io.log("context-window: opened w2");+ assert.deepEqual(calls.logs, [{ stage: "window", data: "context-window: opened w2" }]);+});++test("pendingCount reports only this session's queued addMessage entries", async (t) => {+ const dir = mkdtempSync(join(tmpdir(), "ov-pending-"));+ const previous = process.env.OPENVIKING_PENDING_DIR;+ process.env.OPENVIKING_PENDING_DIR = dir;+ t.after(() => {+ if (previous === undefined) delete process.env.OPENVIKING_PENDING_DIR;+ else process.env.OPENVIKING_PENDING_DIR = previous;+ rmSync(dir, { recursive: true, force: true });+ });++ await enqueue("addMessage", SID, { role: "user", content: "mine 1" });+ await enqueue("addMessage", SID, { role: "user", content: "mine 2" });+ await enqueue("addMessage", "pi-other-session", { role: "user", content: "not mine" });+ await enqueue("commitSession", SID, { keep_recent_count: 0 });++ const { core } = fakes({ sync: { async flushBarrier() { return false; } } });+ assert.equal(await core.io.flush({ budgetMs: 1000 }), false);+ assert.equal(core.io.pendingCount(), 2);++ // A cleared barrier resets the count without another disk read.+ const clear = fakes();+ assert.equal(await clear.core.io.flush({ budgetMs: 1000 }), true);+ assert.equal(clear.core.io.pendingCount(), 0);+});++test("flush passes the caller's budget through to the barrier", async () => {+ const { core, calls } = fakes();+ await core.io.flush({ budgetMs: 4321 });+ assert.deepEqual(calls.flush, [{ budgetMs: 4321 }]);+});++test("sleep gives up as soon as the tool call is aborted", async () => {+ const { core } = fakes();+ const controller = new AbortController();+ const started = Date.now();+ const waited = core.io.sleep(60_000, controller.signal);+ controller.abort();+ await waited; // must not reject, and must not wait out the delay+ assert.ok(Date.now() - started < 5_000);++ // Already aborted: resolves immediately.+ const done = new AbortController();+ done.abort();+ await core.io.sleep(60_000, done.signal);++ // No signal: still a real (short) sleep.+ await core.io.sleep(1, null);+});++test("the core is constructed with the contextWindow config block", () => {+ const { core } = fakes();+ assert.equal(core.config.archivePollMs, 250);+ assert.equal(core.config.softPercent, 70);+ assert.equal(core.windowId, "w1");+ assert.equal(core.armed, false);+});++// ---- readPiReserveTokens -------------------------------------------------++test("pickReserveTokens takes the first usable file and defaults to 16384", () => {+ assert.equal(pickReserveTokens([JSON.stringify({ compaction: { reserveTokens: 4096 } })]), 4096);+ assert.equal(+ pickReserveTokens([null, JSON.stringify({ compaction: { reserveTokens: 8192 } })]),+ 8192,+ );+ // A broken project file must not hide the global one.+ assert.equal(+ pickReserveTokens(["{not json", JSON.stringify({ compaction: { reserveTokens: 2048 } })]),+ 2048,+ );+ assert.equal(pickReserveTokens([JSON.stringify({ compaction: {} }), null]), DEFAULT_RESERVE_TOKENS);+ assert.equal(pickReserveTokens([]), DEFAULT_RESERVE_TOKENS);+});++test("settingsPaths puts the project file before the global one", () => {+ assert.deepEqual(settingsPaths({ cwd: "/repo", configDirName: ".pi", homeDir: "/home/u" }), [+ "/repo/.pi/settings.json",+ "/home/u/.pi/agent/settings.json",+ ]);+ assert.deepEqual(settingsPaths({ cwd: "/repo", configDirName: ".pi", agentDir: "/custom/agent" }), [+ "/repo/.pi/settings.json",+ "/custom/agent/settings.json",+ ]);+});++test("readReserveTokens reads the project file first, then the global one", () => {+ const seen = [];+ const files = {+ "/repo/.pi/settings.json": JSON.stringify({ compaction: { reserveTokens: 1000 } }),+ "/home/u/.pi/agent/settings.json": JSON.stringify({ compaction: { reserveTokens: 2000 } }),+ };+ const readFile = (path) => {+ seen.push(path);+ return files[path] ?? null;+ };+ assert.equal(readReserveTokens({ cwd: "/repo", homeDir: "/home/u", readFile }), 1000);+ assert.deepEqual(seen, ["/repo/.pi/settings.json", "/home/u/.pi/agent/settings.json"]);++ delete files["/repo/.pi/settings.json"];+ assert.equal(readReserveTokens({ cwd: "/repo", homeDir: "/home/u", readFile }), 2000);++ delete files["/home/u/.pi/agent/settings.json"];+ assert.equal(readReserveTokens({ cwd: "/repo", homeDir: "/home/u", readFile }), DEFAULT_RESERVE_TOKENS);+});++test("readPiReserveTokens resolves real settings files, project before global", (t) => {+ const root = mkdtempSync(join(tmpdir(), "ov-pi-settings-"));+ const project = join(root, "project");+ const agent = join(root, "agent");+ mkdirSync(join(project, ".pi"), { recursive: true });+ mkdirSync(agent, { recursive: true });+ const previous = process.env.PI_CODING_AGENT_DIR;+ process.env.PI_CODING_AGENT_DIR = agent;+ t.after(() => {+ if (previous === undefined) delete process.env.PI_CODING_AGENT_DIR;+ else process.env.PI_CODING_AGENT_DIR = previous;+ rmSync(root, { recursive: true, force: true });+ });++ // Neither file exists yet.+ assert.equal(readPiReserveTokens(project), DEFAULT_RESERVE_TOKENS);++ writeFileSync(join(agent, "settings.json"), JSON.stringify({ compaction: { reserveTokens: 9000 } }));+ assert.equal(readPiReserveTokens(project), 9000);++ writeFileSync(+ join(project, ".pi", "settings.json"),+ JSON.stringify({ compaction: { reserveTokens: 3000 } }),+ );+ assert.equal(readPiReserveTokens(project), 3000);+});diff --git a/examples/pi-experimental-context-management/tests/context-window-core.test.mjs b/examples/pi-experimental-context-management/tests/context-window-core.test.mjsnew file mode 100644index 000000000..cdca53751--- /dev/null+++ b/examples/pi-experimental-context-management/tests/context-window-core.test.mjs@@ -0,0 +1,2167 @@+import test from "node:test";+import assert from "node:assert/strict";++import {+ COMPACTION_SENTINEL,+ ContextWindowCore,+ REMINDER_CUSTOM_TYPE,+ STATUS_CUSTOM_TYPE,+ WINDOW_ENTRY_TYPE,+ WINDOW_HEADER_OPEN,+ applyWindowCut,+ buildHandoffMessage,+ buildStatusLine,+ buildWindowHeader,+ computeCutRange,+ effectiveThresholds,+ formatDuration,+ formatTokens,+ lastUserTimestamps,+ messagesFromBranch,+ reminderText,+ windowConfig,+} from "../lib/context-window-core.mjs";+import { estimateTokens } from "../lib/text-budget.mjs";++// --------------------------------------------------------------------------+// fixtures+// --------------------------------------------------------------------------++const user = (content, timestamp) => (timestamp === undefined ? { role: "user", content } : { role: "user", content, timestamp });+const assistant = (content) => ({ role: "assistant", content });+const assistantCalls = (calls) => ({+ role: "assistant",+ content: calls.map((call) => ({ type: "toolCall", id: call.id, name: call.name })),+});+const toolResult = (toolCallId, toolName, content = "ok") => ({ role: "toolResult", toolCallId, toolName, content });++const ARCHIVE_URI = "viking://user/u1/sessions/pi-abc/history/archive_002";++function makeIo(overrides = {}) {+ const io = {+ clock: 1_700_000_000_000,+ calls: [],+ persisted: [],+ logs: [],+ handoffs: [],+ overview: "# Working Memory\n## Current State\nhalfway",+ task: { status: "running" },+ watermark: 42,+ connectedValue: true,+ sid: "pi-abc",+ syncBranch: async () => {+ io.calls.push("syncBranch");+ return { added: 3, tokens: 120, allDelivered: true };+ },+ flush: async (opts = {}) => {+ io.calls.push(`flush:${opts.budgetMs}`);+ return true;+ },+ postHandoff: async (text) => {+ io.calls.push("postHandoff");+ io.handoffs.push(text);+ return true;+ },+ commit: async (opts = {}) => {+ io.calls.push(`commit:${opts.keepRecentCount}`);+ return { status: "accepted", task_id: "task-1", archive_uri: ARCHIVE_URI };+ },+ readArchiveOverview: async () => {+ io.calls.push("readArchiveOverview");+ return io.overview;+ },+ getTask: async () => {+ io.calls.push("getTask");+ return io.task;+ },+ persistEntry: (type, data) => {+ io.persisted.push({ type, data });+ },+ getWatermark: () => io.watermark,+ now: () => io.clock,+ sleep: async (ms) => {+ io.clock += ms;+ },+ log: (message) => io.logs.push(message),+ connected: () => io.connectedValue,+ sessionId: () => io.sid,+ pendingCount: () => 2,+ };+ return Object.assign(io, overrides);+}++function makeCore(io, config = {}) {+ return new ContextWindowCore({ io, config });+}++function branchFor(anchor, extraCalls = []) {+ return [+ { id: "e1", type: "message", message: user("please split the work here", 10) },+ {+ id: "e2",+ type: "message",+ message: assistantCalls([{ id: anchor, name: "new_context" }, ...extraCalls]),+ },+ ];+}++async function openWindow(core, io, opts = {}) {+ return core.requestReset({+ reason: opts.reason ?? "phase one done",+ notes: opts.notes ?? "goal: ship the parser; next: write tests",+ nextSteps: opts.nextSteps ?? ["run the tests"],+ toolCallId: opts.toolCallId ?? "call-1",+ branch: opts.branch ?? branchFor(opts.toolCallId ?? "call-1"),+ signal: opts.signal ?? null,+ onProgress: opts.onProgress,+ });+}++// --------------------------------------------------------------------------+// config+// --------------------------------------------------------------------------++test("windowConfig applies defaults and clamps", () => {+ const defaults = windowConfig();+ assert.equal(defaults.resetDeadlineMs, 60000);+ assert.equal(defaults.archivePollMs, 2000);+ assert.equal(defaults.overviewRefreshMaxAttempts, 20);+ assert.equal(defaults.overviewBudget, 3000);+ assert.equal(defaults.notesBudget, 1500);+ assert.equal(defaults.pendingRequestBudget, 400);+ assert.equal(defaults.softPercent, 70);+ assert.equal(defaults.hardPercent, 85);+ assert.equal(defaults.idleGapMinutes, 30);+ assert.equal(defaults.statusEveryTurn, true);+ assert.equal(defaults.historyItemMaxChars, 8000);+ assert.equal(defaults.recentResetGuardMs, 60000);++ const clamped = windowConfig({+ resetDeadlineMs: 10,+ archivePollMs: 999999,+ overviewRefreshMaxAttempts: -5,+ overviewBudget: 1,+ notesBudget: 999999,+ pendingRequestBudget: -1,+ softPercent: 80,+ hardPercent: 40,+ idleGapMinutes: 99999,+ statusEveryTurn: false,+ historyItemMaxChars: 1,+ });+ assert.equal(clamped.resetDeadlineMs, 5000);+ assert.equal(clamped.archivePollMs, 30000);+ assert.equal(clamped.overviewRefreshMaxAttempts, 0);+ assert.equal(clamped.overviewBudget, 100);+ assert.equal(clamped.notesBudget, 20000);+ assert.equal(clamped.pendingRequestBudget, 0);+ assert.equal(clamped.softPercent, 80);+ assert.equal(clamped.hardPercent, 80, "hardPercent is forced to at least softPercent");+ assert.equal(clamped.idleGapMinutes, 1440);+ assert.equal(clamped.statusEveryTurn, false);+ assert.equal(clamped.historyItemMaxChars, 500);+ assert.deepEqual(windowConfig(windowConfig()), windowConfig(), "normalization is idempotent");+});++// --------------------------------------------------------------------------+// cut+// --------------------------------------------------------------------------++test("computeCutRange cuts a single tool call", () => {+ const messages = [+ user("hello"),+ assistant("hi"),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ user("keep me"),+ ];+ const range = computeCutRange(messages, "call-1");+ assert.deepEqual(range, {+ assistantIndex: 2,+ resultIndex: 3,+ cutEndIndex: 3,+ droppedToolResults: 1,+ siblingToolNames: [],+ });+});++test("computeCutRange drops the whole parallel batch when the reset is first", () => {+ const messages = [+ user("hello"),+ assistantCalls([+ { id: "call-1", name: "new_context" },+ { id: "call-2", name: "read" },+ { id: "call-3", name: "grep" },+ ]),+ toolResult("call-1", "new_context"),+ toolResult("call-2", "read"),+ toolResult("call-3", "grep"),+ user("after"),+ ];+ const range = computeCutRange(messages, "call-1");+ assert.equal(range.cutEndIndex, 4);+ assert.equal(range.droppedToolResults, 3);+ assert.deepEqual(range.siblingToolNames, ["read", "grep"]);+});++test("computeCutRange drops the whole parallel batch when the reset is last", () => {+ const messages = [+ assistantCalls([+ { id: "call-2", name: "read" },+ { id: "call-3", name: "grep" },+ { id: "call-1", name: "new_context" },+ ]),+ toolResult("call-2", "read"),+ toolResult("call-3", "grep"),+ toolResult("call-1", "new_context"),+ ];+ const range = computeCutRange(messages, "call-1");+ assert.equal(range.assistantIndex, 0);+ assert.equal(range.resultIndex, 3);+ assert.equal(range.cutEndIndex, 3);+ assert.equal(range.droppedToolResults, 3);+ assert.deepEqual(range.siblingToolNames, ["read", "grep"]);++ const cut = applyWindowCut(messages, { anchorToolCallId: "call-1", headerText: "HEADER" });+ assert.equal(cut.applied, true);+ assert.equal(cut.messages.length, 1);+ assert.ok(!cut.messages.some((m) => m.role === "toolResult"), "no orphan tool_result survives");+});++test("computeCutRange returns null when the anchor is missing", () => {+ const messages = [user("hello"), assistant("hi")];+ assert.equal(computeCutRange(messages, "call-1"), null);+ assert.equal(computeCutRange(messages, ""), null);+ const cut = applyWindowCut(messages, { anchorToolCallId: "call-1", headerText: "HEADER" });+ assert.equal(cut.applied, false);+ assert.equal(cut.droppedCount, 0);+ assert.equal(cut.messages, messages, "the original array is returned untouched");+});++test("computeCutRange still cuts when the issuing assistant message is gone", () => {+ const messages = [user("hello"), toolResult("call-1", "new_context"), assistant("done")];+ const range = computeCutRange(messages, "call-1");+ assert.equal(range.assistantIndex, -1);+ assert.equal(range.resultIndex, 1);+ assert.equal(range.cutEndIndex, 1);+ assert.deepEqual(range.siblingToolNames, []);+});++test("applyWindowCut merges the header into a kept user message with string content", () => {+ const messages = [+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ user("what about the parser?", 99),+ assistant("looking"),+ ];+ const cut = applyWindowCut(messages, { anchorToolCallId: "call-1", headerText: "HEADER" });+ assert.equal(cut.messages.length, 2);+ assert.equal(cut.messages[0].role, "user");+ assert.equal(cut.messages[0].content, "HEADER\n\nwhat about the parser?");+ assert.equal(cut.messages[0].timestamp, 99);+ assert.equal(messages[2].content, "what about the parser?", "the input message is not mutated");+ assert.equal(cut.droppedCount, 2);+});++test("applyWindowCut merges the header into a kept user message with block content", () => {+ const blocks = [{ type: "image", url: "x" }, { type: "text", text: "second block" }];+ const messages = [+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ { role: "user", content: blocks },+ ];+ const cut = applyWindowCut(messages, { anchorToolCallId: "call-1", headerText: "HEADER" });+ assert.deepEqual(cut.messages[0].content, [+ { type: "image", url: "x" },+ { type: "text", text: "HEADER\n\nsecond block" },+ ]);+ assert.equal(blocks[1].text, "second block", "the input blocks are not mutated");+});++test("applyWindowCut inserts a standalone header when nothing is kept", () => {+ const messages = [assistantCalls([{ id: "call-1", name: "new_context" }]), toolResult("call-1", "new_context")];+ const cut = applyWindowCut(messages, {+ anchorToolCallId: "call-1",+ headerText: "HEADER",+ headerTimestamp: 4242,+ });+ assert.deepEqual(cut.messages, [{ role: "user", content: "HEADER", timestamp: 4242 }]);+ assert.equal(cut.droppedCount, 2);+});++test("transformContext is byte-identical across repeated calls", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);++ const messages = [+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ assistant("still here"),+ ];+ const first = core.transformContext(messages);+ const second = core.transformContext(messages);+ assert.equal(JSON.stringify(first), JSON.stringify(second));+ assert.equal(first[0].content, second[0].content);+ assert.ok(first[0].content.startsWith(WINDOW_HEADER_OPEN));+ assert.equal(first.length, 2);+});++test("transformContext releases the boundary once when the anchor is gone", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ io.logs.length = 0;++ const messages = [user("fresh branch", 1), assistant("hi")];+ const out = core.transformContext(messages);+ assert.equal(out, messages);+ assert.equal(core.armed, false);+ assert.equal(core.windowIndex, 2, "the window index survives the release");+ core.transformContext(messages);+ assert.equal(io.logs.filter((line) => line.includes("anchor missing")).length, 1);+});++test("observeMessages records the window metrics but never releases the boundary", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);++ const messages = [+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ user("what is left?", 2),+ assistant("the tests"),+ ];+ const observed = core.observeMessages(messages);+ assert.equal(JSON.stringify(observed), JSON.stringify(core.transformContext(messages)));+ assert.equal(core.turnsInWindow, 1);++ // A list without the anchor — pi had not written it yet, or the caller built+ // the list from the branch — must not cost the boundary: the status line is+ // not allowed to hand an archived window back to the model.+ io.logs.length = 0;+ core.observeMessages([user("fresh branch", 3), assistant("hi")]);+ assert.equal(core.armed, true, "the anchor survives a metrics-only pass");+ assert.equal(io.logs.filter((line) => line.includes("anchor missing")).length, 0);+});++test("messagesFromBranch builds the list pi would send, entry by entry", () => {+ const branch = [+ { id: "e1", type: "message", message: user("first", 1) },+ { id: "e2", type: "thinking_level_change", thinkingLevel: "high" },+ {+ id: "e3",+ type: "custom_message",+ customType: STATUS_CUSTOM_TYPE,+ content: "[context-status] window w1",+ display: true,+ timestamp: "2026-09-10T06:00:00.000Z",+ },+ { id: "e4", type: "custom", customType: WINDOW_ENTRY_TYPE, data: { windowIndex: 2 } },+ { id: "e5", type: "message", message: assistant("second") },+ ];+ const messages = messagesFromBranch(branch);+ assert.deepEqual(messages.map((m) => m.role), ["user", "custom", "assistant"]);+ assert.equal(messages[0], branch[0].message, "message entries are passed through, not copied");+ assert.equal(messages[1].customType, STATUS_CUSTOM_TYPE);+ assert.equal(messages[1].timestamp, Date.parse("2026-09-10T06:00:00.000Z"));+ assert.deepEqual(messagesFromBranch(null), []);+});++test("messagesFromBranch replays a compaction the way buildSessionContext does", () => {+ const branch = [+ { id: "e1", type: "message", message: user("ancient", 1) },+ { id: "e2", type: "message", message: assistant("also ancient") },+ { id: "e3", type: "message", message: user("kept", 2) },+ {+ id: "e4",+ type: "compaction",+ summary: "SUMMARY",+ firstKeptEntryId: "e3",+ tokensBefore: 900,+ timestamp: "2026-09-10T06:00:00.000Z",+ },+ { id: "e5", type: "message", message: assistant("after the compaction") },+ ];+ const messages = messagesFromBranch(branch);+ assert.deepEqual(messages.map((m) => m.role), ["compactionSummary", "user", "assistant"]);+ assert.equal(messages[0].summary, "SUMMARY");+ assert.equal(messages[1].content, "kept");+ assert.equal(+ JSON.stringify(messages).includes("ancient"),+ false,+ "entries pi dropped at the compaction must not be counted again",+ );+});++// --------------------------------------------------------------------------+// header / handoff / status text+// --------------------------------------------------------------------------++test("buildHandoffMessage renders reason, notes and optional next steps", () => {+ const withSteps = buildHandoffMessage({+ windowId: "w2",+ nextWindowId: "w3",+ reason: "topic switch",+ notes: "parser is green",+ nextSteps: ["write docs", "open the PR"],+ });+ assert.equal(+ withSteps,+ [+ "[Context Window Handoff] w2 -> w3",+ "Reason: topic switch",+ "Handoff notes:",+ "parser is green",+ "Next steps:",+ "1. write docs",+ "2. open the PR",+ ].join("\n"),+ );++ const withoutSteps = buildHandoffMessage({ windowId: "w1", nextWindowId: "w2", reason: "r", notes: "n" });+ assert.ok(!withoutSteps.includes("Next steps:"));+});++test("buildWindowHeader renders the ready variant with every section", () => {+ const header = buildWindowHeader({+ windowId: "w3",+ previousWindowId: "w2",+ archiveId: "archive_002",+ openedAt: Date.UTC(2026, 8, 10, 6, 41, 12),+ reason: "phase one done",+ notes: "goal: ship the parser",+ nextSteps: ["run the tests"],+ pendingRequest: "please also update the docs",+ overview: "# Working Memory\n## Current State\nhalfway",+ overviewState: "ready",+ siblingToolNames: [],+ });++ assert.ok(header.startsWith(WINDOW_HEADER_OPEN));+ assert.ok(header.includes('<context_window id="w3" previous="w2" archive="archive_002" opened="2026-09-10T06:41:12Z">'));+ assert.ok(header.includes("Reason you gave: phase one done"));+ assert.ok(header.includes("<handoff-notes>goal: ship the parser</handoff-notes>"));+ assert.ok(header.includes("1. run the tests"));+ assert.ok(header.includes("<pending-request>please also update the docs</pending-request>"));+ assert.ok(header.includes('<working-memory archive="archive_002"># Working Memory'));+ assert.ok(header.includes('history {"action":"list_windows"}'));+ assert.ok(header.includes('{"action":"list_items","window":"w2"}'));+ // A placeholder, not a literal index: the archive rarely has 15 items and the+ // model would call read_item with an out-of-range id.+ assert.ok(header.includes('{"action":"read_item","item":"w2:<index from list_items>"}'));+ assert.ok(header.includes('{"action":"search_contents","query":"..."}'));+ assert.ok(header.endsWith("</context_window>\n</openviking-context>"));+ assert.ok(!header.includes("discarded with the same batch"));+});++test("buildWindowHeader truncates Chinese notes, pending request and overview to their budgets", () => {+ const header = buildWindowHeader({+ windowId: "w2",+ previousWindowId: "w1",+ archiveId: "archive_001",+ notes: "笔".repeat(4000),+ pendingRequest: "请".repeat(4000),+ overview: "忆".repeat(9000),+ overviewState: "ready",+ config: { notesBudget: 100, pendingRequestBudget: 100, overviewBudget: 100 },+ });++ const notes = header.match(/<handoff-notes>([\s\S]*?)<\/handoff-notes>/)[1];+ const pending = header.match(/<pending-request>([\s\S]*?)<\/pending-request>/)[1];+ const overview = header.match(/<working-memory archive="archive_001">([\s\S]*?)<\/working-memory>/)[1];+ for (const chunk of [notes, pending, overview]) {+ assert.ok(chunk.endsWith("\n...(truncated)"), "each truncated section is marked");+ assert.ok(estimateTokens(chunk.replace("\n...(truncated)", "")) <= 100);+ }+});++test("buildWindowHeader pending variant emits no empty working-memory element on the first reset", () => {+ const header = buildWindowHeader({+ windowId: "w2",+ previousWindowId: "w1",+ archiveId: "archive_001",+ notes: "notes",+ overview: "",+ overviewState: "pending",+ previousOverview: "",+ });+ assert.ok(!header.includes("<working-memory"), "never render an empty working-memory element");+ assert.ok(header.includes("is not ready yet"));+ assert.ok(header.includes("use history to read the archived messages directly"));+});++test("buildWindowHeader pending variant attaches the previous overview as stale", () => {+ const header = buildWindowHeader({+ windowId: "w3",+ previousWindowId: "w2",+ archiveId: "archive_002",+ previousArchiveId: "archive_001",+ overviewState: "pending",+ previousOverview: "older working memory",+ });+ // The block carries the archive it actually describes — never the one the+ // line above declares to have no Working Memory yet.+ assert.ok(+ header.includes(+ '<working-memory status="stale" archive="archive_001" describes="an earlier window, not the archive above">' ++ "older working memory</working-memory>",+ ),+ );+ assert.ok(header.includes("Working Memory for archive_002 is not ready yet"));+});++test("buildWindowHeader drops the archive attribute of a stale block whose archive is unknown", () => {+ const header = buildWindowHeader({+ windowId: "w3",+ previousWindowId: "w2",+ archiveId: "archive_002",+ overviewState: "pending",+ previousOverview: "older working memory",+ });+ assert.ok(header.includes('<working-memory status="stale" describes='));+ assert.equal(header.includes('archive="archive_002" describes'), false);+});++test("buildWindowHeader names messages OpenViking rejected for good", () => {+ const header = buildWindowHeader({+ windowId: "w2",+ previousWindowId: "w1",+ archiveId: "archive_001",+ overviewState: "ready",+ overview: "wm",+ undeliveredCount: 3,+ });+ assert.match(header, /3 messages of this session were rejected by OpenViking and are missing from the archive/);+ assert.match(header, /so history cannot show them\./);+ const one = buildWindowHeader({+ windowId: "w2",+ previousWindowId: "w1",+ archiveId: "archive_001",+ overviewState: "ready",+ overview: "wm",+ undeliveredCount: 1,+ });+ assert.match(+ one,+ /1 message of this session was rejected by OpenViking and is missing from the archive, so history cannot show it\./,+ );+ const clean = buildWindowHeader({+ windowId: "w2",+ previousWindowId: "w1",+ archiveId: "archive_001",+ overviewState: "ready",+ overview: "wm",+ });+ assert.equal(clean.includes("missing from the archive"), false);+});++test("buildWindowHeader unavailable variant is a short note with no element", () => {+ const header = buildWindowHeader({+ windowId: "w3",+ previousWindowId: "w2",+ archiveId: "archive_002",+ overviewState: "unavailable",+ previousOverview: "older working memory",+ });+ assert.ok(!header.includes("<working-memory"));+ assert.ok(header.includes("is unavailable"));+});++test("buildWindowHeader mentions discarded siblings only when there are any", () => {+ const base = {+ windowId: "w2",+ previousWindowId: "w1",+ archiveId: "archive_001",+ overviewState: "ready",+ overview: "wm",+ };+ const one = buildWindowHeader({ ...base, siblingToolNames: ["read"] });+ assert.ok(one.includes("1 other tool result was discarded with the same batch; re-run it if needed. Tools: read."));+ const two = buildWindowHeader({ ...base, siblingToolNames: ["read", "grep"] });+ assert.ok(two.includes("2 other tool results were discarded with the same batch; re-run them if needed. Tools: read, grep."));+ const none = buildWindowHeader({ ...base, siblingToolNames: [] });+ assert.ok(!none.includes("discarded with the same batch"));+});++test("formatTokens and formatDuration", () => {+ assert.equal(formatTokens(0), "0");+ assert.equal(formatTokens(512), "512");+ assert.equal(formatTokens(38000), "38k");+ assert.equal(formatTokens(38400), "38.4k");+ assert.equal(formatTokens(262144), "262k");+ assert.equal(formatDuration(0), "0s");+ assert.equal(formatDuration(12_000), "12s");+ assert.equal(formatDuration(3 * 60_000), "3m");+ assert.equal(formatDuration(47 * 60_000), "47m");+ assert.equal(formatDuration(72 * 60_000), "1h 12m");+ assert.equal(formatDuration(60 * 60_000), "1h");+});++test("buildStatusLine renders the one-line status and the idle note", () => {+ const line = buildStatusLine({+ windowId: "w2",+ turnsInWindow: 6,+ usedTokens: 38000,+ contextWindow: 262000,+ sinceLastUserMs: 5 * 60_000,+ idleGapMs: 47 * 60_000,+ idleGapMinutes: 30,+ });+ // The NOTE is about the gap the user just came back from, not about the gap+ // between the two messages before it — so a long `idleGapMs` alone is not it.+ assert.equal(line, "[context-status] window w2 · 6 turns · ~38k/262k tokens (15%) · 5m since your previous message");++ const idle = buildStatusLine({+ windowId: "w2",+ turnsInWindow: 1,+ usedTokens: 1000,+ contextWindow: 262000,+ estimated: true,+ sinceLastUserMs: 47 * 60_000,+ idleGapMs: 5 * 60_000,+ idleGapMinutes: 30,+ });+ const lines = idle.split("\n");+ assert.equal(lines.length, 2);+ assert.ok(lines[0].includes("(0%, estimated)"));+ assert.ok(lines[1].startsWith("NOTE: 47 minutes passed since the previous user message."));+ assert.ok(lines[1].includes("consider new_context before you begin"));++ // With no `sinceLastUserMs` at all the caller's gap is the only signal left.+ const fallback = buildStatusLine({ windowId: "w2", turnsInWindow: 1, idleGapMs: 99 * 60_000, idleGapMinutes: 30 });+ assert.equal(fallback.split("\n").length, 2, "idleGapMs is the fallback when nothing else is known");++ const noIdle = buildStatusLine({ windowId: "w1", turnsInWindow: 1, idleGapMs: 99 * 60_000, idleGapMinutes: 0 });+ assert.equal(noIdle.split("\n").length, 1, "idleGapMinutes 0 disables the note");+});++test("reminderText mentions new_context, notes and harness compaction", () => {+ const soft = reminderText("soft", { windowId: "w2", usedTokens: 184000, contextWindow: 262000 });+ assert.ok(soft.includes("w2"));+ assert.ok(soft.includes("70%"));+ assert.ok(soft.includes("new_context"));+ assert.ok(soft.includes("notes"));+ assert.ok(soft.includes("the harness compacts it for you"));++ const hard = reminderText("hard", { windowId: "w2", usedTokens: 223000, contextWindow: 262000 });+ assert.ok(hard.includes("exactly one call to new_context now"));+ assert.ok(hard.includes("85%"));+ assert.ok(hard.includes("the harness compacts it for you"));+});++test("lastUserTimestamps skips everything this extension injects", () => {+ const messages = [+ user("first real", 100),+ assistant("answer"),+ user(`${WINDOW_HEADER_OPEN}\n<context_window id="w2">`, 200),+ { role: "user", content: "[context-status] window w2", timestamp: 210 },+ { role: "user", content: "anything", customType: STATUS_CUSTOM_TYPE, timestamp: 220 },+ { role: "user", content: "anything", customType: REMINDER_CUSTOM_TYPE, timestamp: 230 },+ { role: "user", content: "[Context Window Handoff] w1 -> w2", timestamp: 240 },+ user("second real", 300),+ ];+ assert.deepEqual(lastUserTimestamps(messages), [300, 100]);+ assert.deepEqual(lastUserTimestamps([]), []);+});++// --------------------------------------------------------------------------+// requestReset+// --------------------------------------------------------------------------++test("requestReset drives io in order and opens the window", async () => {+ const io = makeIo();+ const core = makeCore(io);+ const out = await openWindow(core, io);++ assert.equal(out.ok, true);+ assert.equal(out.kind, "reset");+ assert.deepEqual(io.calls, ["syncBranch", "flush:15000", "postHandoff", "commit:0", "readArchiveOverview"]);+ assert.ok(io.handoffs[0].startsWith("[Context Window Handoff] w1 -> w2"));+ assert.ok(io.handoffs[0].includes("Reason: phase one done"));++ assert.equal(core.windowId, "w2");+ assert.equal(core.anchorToolCallId, "call-1");+ assert.equal(core.archiveId, "archive_002");+ assert.equal(core.archiveUri, ARCHIVE_URI);+ assert.equal(core.taskId, "task-1");+ assert.equal(core.overviewReady, true);+ assert.equal(core.awaitingFirstObservation, true);+ assert.equal(core.lastResetBy, "agent");+ assert.equal(core.syncedEntryCount, 42);+ assert.equal(core.pendingRequest, "please split the work here");++ assert.ok(out.text.includes("Context window w2 is open"));+ assert.ok(out.text.includes("archive_002"));+ assert.ok(out.text.includes("Working Memory is ready"));+ assert.ok(out.text.includes("not part of the new window"));+ assert.equal(out.details.overviewState, "ready");++ assert.equal(io.persisted.length, 1, "exactly one entry per reset");+ assert.equal(io.persisted[0].type, WINDOW_ENTRY_TYPE);+ assert.equal(io.persisted[0].data.headerText, core.headerText);+ assert.ok(core.headerText.includes('<working-memory archive="archive_002">'));+});++test("requestReset records sibling tool names from the issuing assistant message", async () => {+ const io = makeIo();+ const core = makeCore(io);+ const branch = branchFor("call-1", [{ id: "call-2", name: "read" }]);+ await openWindow(core, io, { branch });+ assert.deepEqual(core.siblingToolNames, ["read"]);+ assert.ok(core.headerText.includes("Tools: read."));+});++test("requestReset refuses when OpenViking is unreachable", async () => {+ const io = makeIo({ connectedValue: false });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.ok, false);+ assert.equal(out.kind, "refused");+ assert.ok(out.text.startsWith("Context window NOT reset:"));+ assert.ok(out.text.includes("unreachable"));+ assert.ok(out.text.includes("keep working"));+ assert.ok(out.text.includes("the harness will compact for you"));+ assert.deepEqual(io.calls, []);+ assert.equal(core.windowIndex, 1);+ assert.equal(core.armed, false);+ assert.equal(io.persisted.length, 0);+});++test("requestReset refuses when there is no OpenViking session", async () => {+ const io = makeIo({ sid: null });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.kind, "refused");+ assert.deepEqual(io.calls, []);+});++test("requestReset refuses when the branch was not fully delivered", async () => {+ const io = makeIo({+ syncBranch: async () => {+ io.calls.push("syncBranch");+ return { added: 2, tokens: 10, allDelivered: false };+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.kind, "refused");+ assert.equal(out.details.stage, "sync");+ assert.deepEqual(io.calls, ["syncBranch"]);+ assert.equal(core.windowIndex, 1);+});++test("requestReset refuses when the flush barrier does not clear", async () => {+ const io = makeIo({+ flush: async (opts) => {+ io.calls.push(`flush:${opts.budgetMs}`);+ return false;+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.kind, "refused");+ assert.equal(out.details.stage, "flush");+ assert.equal(out.details.pending, 2);+ assert.ok(out.text.includes("2 captured message(s) are still queued"));+ assert.deepEqual(io.calls, ["syncBranch", "flush:15000"]);+});++test("requestReset refuses when the handoff note cannot be written", async () => {+ const io = makeIo({+ postHandoff: async () => {+ io.calls.push("postHandoff");+ return false;+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.kind, "refused");+ assert.equal(out.details.stage, "handoff");+ assert.deepEqual(io.calls, ["syncBranch", "flush:15000", "postHandoff"]);+});++test("requestReset refuses when commit fails and reports the trace id", async () => {+ const nullCommit = makeIo({+ commit: async () => {+ nullCommit.calls.push("commit:0");+ return null;+ },+ });+ let core = makeCore(nullCommit);+ let out = await openWindow(core, nullCommit);+ assert.equal(out.kind, "refused");+ assert.equal(out.details.stage, "commit");+ assert.equal(core.windowIndex, 1);++ const failedCommit = makeIo({+ commit: async () => ({ status: "failed", trace_id: "trace-9" }),+ });+ core = makeCore(failedCommit);+ out = await openWindow(core, failedCommit);+ assert.equal(out.kind, "refused");+ assert.ok(out.text.includes("trace trace-9"));+});++test("requestReset is a no-op when OpenViking has nothing to archive", async () => {+ const io = makeIo({+ commit: async () => {+ io.calls.push("commit:0");+ return { status: "skipped", reason: "no_messages" };+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.ok, false);+ assert.equal(out.kind, "noop");+ assert.ok(out.text.includes("nothing to archive"));+ assert.equal(core.windowIndex, 1);+ assert.equal(core.armed, false);+ assert.equal(io.persisted.length, 0);+});++test("requestReset opens a degraded window when the overview never lands", async () => {+ const io = makeIo({ overview: null });+ const core = makeCore(io);+ const out = await openWindow(core, io);++ assert.equal(out.ok, true);+ assert.equal(out.details.overviewState, "pending");+ assert.equal(core.overviewReady, false);+ assert.equal(core.windowId, "w2");+ assert.ok(core.headerText.includes("is not ready yet"));+ assert.ok(!core.headerText.includes("<working-memory"), "first reset has no stale overview to show");+ assert.ok(io.calls.filter((c) => c === "getTask").length >= 1, "the task is polled every 5th attempt");+ assert.ok(io.clock >= 1_700_000_000_000 + 60000, "polling honours the deadline");+});++test("requestReset stops early and marks the window unavailable when the task failed", async () => {+ const io = makeIo({ overview: null, task: { status: "failed" } });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.ok, true);+ assert.equal(out.details.overviewState, "unavailable");+ // The task is first checked on the second attempt, so a failed one ends the+ // wait there instead of on the fifth.+ assert.equal(out.details.attempts, 2);+ assert.ok(core.headerText.includes("is unavailable"));+});++test("requestReset aborted before commit changes nothing", async () => {+ const io = makeIo();+ const core = makeCore(io);+ const out = await openWindow(core, io, { signal: { aborted: true } });+ assert.equal(out.ok, false);+ assert.equal(out.kind, "noop");+ assert.deepEqual(io.calls, []);+ assert.equal(core.windowIndex, 1);+ assert.equal(io.persisted.length, 0);+});++test("requestReset aborted after commit still opens a degraded window", async () => {+ const signal = { aborted: false };+ const io = makeIo({+ overview: null,+ commit: async () => {+ io.calls.push("commit:0");+ signal.aborted = true;+ return { status: "accepted", task_id: "task-1", archive_uri: ARCHIVE_URI };+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io, { signal });+ assert.equal(out.ok, true);+ assert.equal(out.details.overviewState, "pending");+ assert.equal(out.details.attempts, 0, "an aborted wait does not read the overview at all");+ assert.equal(core.windowId, "w2");+ assert.equal(core.overviewReady, false);+});++test("a second concurrent requestReset is a no-op and commits only once", async () => {+ let release;+ const gate = new Promise((resolve) => {+ release = resolve;+ });+ const io = makeIo({+ commit: async () => {+ io.calls.push("commit:0");+ await gate;+ return { status: "accepted", task_id: "task-1", archive_uri: ARCHIVE_URI };+ },+ });+ const core = makeCore(io);+ const first = openWindow(core, io);+ const second = await openWindow(core, io, { toolCallId: "call-2" });+ assert.equal(second.kind, "noop");+ assert.match(second.text, /^Context window NOT reset: a reset is already in progress\./);+ release();+ const out = await first;+ assert.equal(out.ok, true);+ assert.equal(io.calls.filter((c) => c === "commit:0").length, 1);+ assert.equal(core.anchorToolCallId, "call-1");+});++test("requestReset never throws when io explodes", async () => {+ const io = makeIo({+ postHandoff: async () => {+ throw new Error("socket hang up");+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.ok, false);+ assert.equal(out.details.stage, "error");+ assert.ok(out.text.includes("socket hang up"));+ assert.equal(core.resetting, false);+});++test("restore rebuilds the same anchor and header bytes in a new process", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);++ const entries = [{ type: "custom", customType: WINDOW_ENTRY_TYPE, data: io.persisted[0].data }];+ const restored = makeCore(makeIo());+ restored.restore(entries);++ assert.equal(restored.windowId, "w2");+ assert.equal(restored.anchorToolCallId, "call-1");+ assert.equal(restored.headerText, core.headerText);+ assert.equal(restored.archiveId, "archive_002");+ assert.equal(restored.overviewReady, true);++ const messages = [+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ assistant("carry on"),+ ];+ assert.equal(+ JSON.stringify(restored.transformContext(messages)),+ JSON.stringify(core.transformContext(messages)),+ );+});++// --------------------------------------------------------------------------+// refreshPendingOverview+// --------------------------------------------------------------------------++test("refreshPendingOverview upgrades the header exactly once", async () => {+ const io = makeIo({ overview: null });+ const core = makeCore(io);+ await openWindow(core, io);+ const persistedAfterReset = io.persisted.length;++ assert.equal(await core.refreshPendingOverview(), false);+ io.overview = "# Working Memory\nlate but real";+ assert.equal(await core.refreshPendingOverview(), true);+ assert.equal(core.overviewReady, true);+ assert.ok(core.headerText.includes('<working-memory archive="archive_002"># Working Memory'));+ assert.equal(io.persisted.length, persistedAfterReset + 1);+ assert.ok(io.logs.some((line) => line === "context-window: working memory attached to w2"));++ assert.equal(await core.refreshPendingOverview(), false, "no further reads once ready");+ assert.equal(io.persisted.length, persistedAfterReset + 1);+});++test("refreshPendingOverview gives up after the attempt budget and marks it unavailable once", async () => {+ const io = makeIo({ overview: null });+ const core = makeCore(io, { overviewRefreshMaxAttempts: 2 });+ await openWindow(core, io);+ const persistedAfterReset = io.persisted.length;++ assert.equal(await core.refreshPendingOverview(), false);+ assert.equal(await core.refreshPendingOverview(), false);+ assert.ok(core.headerText.includes("is unavailable"));+ assert.equal(io.persisted.length, persistedAfterReset + 1);++ assert.equal(await core.refreshPendingOverview(), false);+ assert.equal(io.persisted.length, persistedAfterReset + 1, "unavailable is recorded only once");+});++// --------------------------------------------------------------------------+// reminders and status+// --------------------------------------------------------------------------++test("reminders fire once per level and are re-armed by a reset", async () => {+ const io = makeIo();+ const core = makeCore(io);+ const contextWindow = 100000;++ core.lastWindowTokens = 71000;+ assert.equal(core.dueReminder({ usage: { tokens: null }, contextWindow }), "soft");+ assert.equal(core.dueReminder({ usage: { tokens: null }, contextWindow }), null);++ core.lastWindowTokens = 86000;+ assert.equal(core.dueReminder({ usage: { tokens: null }, contextWindow }), "hard");+ assert.equal(core.dueReminder({ usage: { tokens: null }, contextWindow }), null);++ await openWindow(core, io);+ assert.equal(core.awaitingFirstObservation, true);+ assert.equal(core.dueReminder({ usage: { tokens: 99000 }, contextWindow }), null, "suppressed until an assistant answers");++ core.observeAssistantResponse();+ core.lastWindowTokens = 1000;+ assert.equal(core.dueReminder({ usage: { tokens: 90000 }, contextWindow }), "hard", "reported usage wins once observed");+});++test("dueReminder prefers the local estimate and needs a context window", () => {+ const core = makeCore(makeIo());+ core.lastWindowTokens = 90000;+ assert.equal(core.dueReminder({ usage: { tokens: null }, contextWindow: 0 }), null);+ assert.equal(core.dueReminder({ usage: null, contextWindow: 100000 }), "hard");+});++test("statusSnapshot reports usage, idle gap and advice", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ core.observeAssistantResponse();++ const now = io.clock + 47 * 60_000;+ const messages = [+ user("earlier", io.clock - 60 * 60_000),+ assistant("ok"),+ user("latest", io.clock),+ ];+ const snap = core.statusSnapshot({ usage: { tokens: 20000, contextWindow: 100000 }, now, messages });+ assert.equal(snap.windowId, "w2");+ assert.equal(snap.usedTokens, 20000);+ assert.equal(snap.percent, 20);+ assert.equal(snap.tokensLeft, 80000);+ assert.equal(snap.estimated, false);+ assert.equal(snap.sinceLastUserMs, 47 * 60_000);+ assert.equal(snap.idleGapMs, 60 * 60_000);+ assert.equal(snap.archiveId, "archive_002");+ assert.equal(snap.overviewReady, true);+ assert.equal(snap.advice, "no action needed");++ const soft = core.statusSnapshot({ usage: { tokens: 75000, contextWindow: 100000 }, now, messages });+ assert.equal(soft.advice, "past the soft threshold: update your notes and reset at the next stopping point");+ const hard = core.statusSnapshot({ usage: { tokens: 90000, contextWindow: 100000 }, now, messages });+ assert.equal(hard.advice, "save your notes and call new_context now");+});++test("statusSnapshot falls back to the local estimate while awaiting the first observation", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ core.lastWindowTokens = 1234;+ const snap = core.statusSnapshot({ usage: { tokens: 99000, contextWindow: 100000 }, now: io.clock, messages: [] });+ assert.equal(snap.usedTokens, 1234);+ assert.equal(snap.estimated, true);+ assert.equal(snap.sinceLastUserMs, null);+ assert.equal(snap.idleGapMs, null);+});++test("transformContext keeps the turn count and token estimate of the new window", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);++ const messages = [+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ assistant("first answer in the new window"),+ user("more", 2),+ assistant("second answer"),+ ];+ const out = core.transformContext(messages);+ assert.equal(core.turnsInWindow, 2);+ assert.equal(core.awaitingFirstObservation, false);+ assert.ok(core.lastWindowTokens > 0);+ assert.ok(core.lastWindowTokens < estimateTokens(JSON.stringify(messages)) + 10000);+ assert.equal(out[0].role, "user");+});++// --------------------------------------------------------------------------+// pi compaction fallback+// --------------------------------------------------------------------------++function compactionEntries({ withTail = true } = {}) {+ const entries = [+ { id: "e1", type: "message", message: user("start", 1) },+ { id: "e2", type: "message", message: assistantCalls([{ id: "call-1", name: "new_context" }]) },+ { id: "e3", type: "message", message: toolResult("call-1", "new_context") },+ ];+ if (withTail) {+ entries.push({ id: "e4", type: "message", message: user("after the reset", 2) });+ entries.push({ id: "e5", type: "message", message: assistant("sure") });+ }+ return entries;+}++test("handleBeforeCompact keeps preparation.firstKeptEntryId when it is already past the anchor", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ core.lastResetAt = 0;++ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e5", tokensBefore: 123 },+ branchEntries: compactionEntries(),+ });+ assert.equal(out.compaction.firstKeptEntryId, "e5");+ assert.equal(out.compaction.tokensBefore, 123);+ assert.equal(out.compaction.summary, core.headerText);+ assert.equal(core.windowId, "w3");+ assert.equal(core.anchorToolCallId, null, "pi made a native cut, the virtual anchor is dropped");+ assert.equal(core.lastResetBy, "pi-compaction");+});++test("handleBeforeCompact skips forward when preparation would resurrect archived messages", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ core.lastResetAt = 0;++ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e1", tokensBefore: 5 },+ branchEntries: compactionEntries(),+ });+ assert.equal(out.compaction.firstKeptEntryId, "e4");+});++test("handleBeforeCompact uses the sentinel when the anchor batch is the tail", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ core.lastResetAt = 0;++ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e1", tokensBefore: 5 },+ branchEntries: compactionEntries({ withTail: false }),+ });+ assert.equal(out.compaction.firstKeptEntryId, COMPACTION_SENTINEL);+});++test("handleBeforeCompact falls back to preparation when no anchor is armed", async () => {+ const io = makeIo();+ const core = makeCore(io);+ core.headerText = "";+ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e1", tokensBefore: 5 },+ branchEntries: compactionEntries(),+ });+ assert.equal(out.compaction.firstKeptEntryId, "e1");+});++test("handleBeforeCompact does not re-commit right after a reset", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ const header = core.headerText;+ io.calls.length = 0;+ io.clock += 30_000; // inside recentResetGuardMs++ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e1", tokensBefore: 7 },+ branchEntries: compactionEntries(),+ });+ assert.equal(out.compaction.summary, header);+ assert.equal(out.compaction.firstKeptEntryId, "e4");+ assert.deepEqual(io.calls, [], "the guard commits nothing");+ assert.equal(core.windowId, "w2");+ assert.equal(core.anchorToolCallId, "call-1");++ io.clock += 40_000; // past the guard+ io.watermark = 99;+ const later = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e1", tokensBefore: 7 },+ branchEntries: compactionEntries(),+ });+ assert.ok(io.calls.includes("commit:0"), "past the guard the archive is written");+ assert.equal(later.compaction.firstKeptEntryId, "e4");+});++test("handleBeforeCompact returns undefined when a step fails", async () => {+ const flushFails = makeIo({ flush: async () => false });+ let core = makeCore(flushFails);+ assert.equal(+ await core.handleBeforeCompact({ preparation: { firstKeptEntryId: "e1" }, branchEntries: compactionEntries() }),+ undefined,+ );++ const commitFails = makeIo({ commit: async () => null });+ core = makeCore(commitFails);+ assert.equal(+ await core.handleBeforeCompact({ preparation: { firstKeptEntryId: "e1" }, branchEntries: compactionEntries() }),+ undefined,+ );++ const skipped = makeIo({ commit: async () => ({ status: "skipped", reason: "no_messages" }) });+ core = makeCore(skipped);+ assert.equal(+ await core.handleBeforeCompact({ preparation: { firstKeptEntryId: "e1" }, branchEntries: compactionEntries() }),+ undefined,+ );++ const offline = makeIo({ connectedValue: false });+ core = makeCore(offline);+ assert.equal(+ await core.handleBeforeCompact({ preparation: { firstKeptEntryId: "e1" }, branchEntries: compactionEntries() }),+ undefined,+ );+});++test("absorbExternalCompaction drops the anchor and re-arms the reminders", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ core.remindersSent = { soft: true, hard: true };+ const before = io.persisted.length;++ core.absorbExternalCompaction("pi compacted natively");+ assert.equal(core.anchorToolCallId, null);+ assert.equal(core.windowId, "w3");+ assert.deepEqual(core.remindersSent, { soft: false, hard: false });+ assert.equal(io.persisted.length, before + 1);+});++// --------------------------------------------------------------------------+// restore / shutdown+// --------------------------------------------------------------------------++test("restore takes the newest entry and ignores malformed or foreign ones", () => {+ const io = makeIo();+ const core = makeCore(io);+ const entries = [+ { type: "custom", customType: WINDOW_ENTRY_TYPE, data: { windowIndex: 5, anchorToolCallId: "old", headerText: "OLD" } },+ { customType: WINDOW_ENTRY_TYPE, data: { windowIndex: 7, anchorToolCallId: "newer", headerText: "NEWER" } },+ { type: WINDOW_ENTRY_TYPE, data: { windowIndex: 9, anchorToolCallId: "newest", headerText: "NEWEST" } },+ { type: "custom", customType: WINDOW_ENTRY_TYPE, data: "not an object" },+ { type: "custom", customType: WINDOW_ENTRY_TYPE, data: null },+ { type: "custom", customType: WINDOW_ENTRY_TYPE, data: { ovSessionId: "pi-other", windowIndex: 42 } },+ { type: "custom", customType: "something-else", data: { windowIndex: 99 } },+ ];+ core.restore(entries);+ assert.equal(core.windowIndex, 9);+ assert.equal(core.anchorToolCallId, "newest");+ assert.equal(core.headerText, "NEWEST");+ assert.equal(core.armed, true);+});++test("a fresh session restores to w1 and stays unarmed", () => {+ const core = makeCore(makeIo());+ const state = core.restore([]);+ assert.equal(state.windowIndex, 1);+ assert.equal(core.windowId, "w1");+ assert.equal(core.armed, false);+ assert.equal(core.headerText, "");+ assert.equal(core.transformContext([user("hi", 1)]).length, 1);+});++test("persist dedupes and shutdown refreshes the watermark", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ assert.equal(io.persisted.length, 1);++ core.persist();+ assert.equal(io.persisted.length, 1, "an unchanged state is not written twice");++ io.watermark = 137;+ await core.shutdown();+ assert.equal(io.persisted.length, 2);+ assert.equal(io.persisted[1].data.syncedEntryCount, 137);+});++// --------------------------------------------------------------------------+// adversarial / verification pass+// --------------------------------------------------------------------------++test("an abort-aware io.sleep that rejects still opens a degraded window", async () => {+ const io = makeIo({+ overview: null,+ sleep: async () => {+ throw new Error("aborted while waiting");+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io);++ assert.equal(out.ok, true, "the archive exists, so the window must open");+ assert.equal(out.details.overviewState, "pending");+ assert.equal(core.windowId, "w2");+ assert.ok(!out.text.includes("NOT reset"));+});++test("a post-commit failure still opens the window instead of claiming nothing changed", async () => {+ // The commit emptied the OpenViking session (keep_recent_count 0), so a refusal+ // here would leave the model carrying the old context while believing its+ // history is still live and re-readable.+ const io = makeIo({ overview: null });+ const realNow = io.now;+ io.commit = async () => {+ io.calls.push("commit:0");+ io.now = () => {+ throw new Error("clock exploded");+ };+ return { status: "accepted", task_id: "task-1", archive_uri: ARCHIVE_URI };+ };+ const core = makeCore(io);+ core.io.now = () => io.now();+ const out = await openWindow(core, io);++ assert.equal(out.ok, true, "the archive exists, so the window must open");+ assert.equal(out.kind, "reset");+ assert.equal(out.details.overviewState, "pending");+ assert.equal(out.details.archiveId, "archive_002");+ assert.ok(out.details.error.includes("clock exploded"));+ assert.ok(!out.text.includes("NOT reset"));+ assert.equal(core.windowId, "w2");+ assert.equal(core.anchorToolCallId, "call-1");+ assert.equal(core.overviewReady, false);+ assert.ok(core.headerText.startsWith(WINDOW_HEADER_OPEN));+ assert.ok(core.headerText.includes("is not ready yet"));+ assert.equal(io.persisted.length, 1, "the window is persisted even on the recovery path");+ assert.equal(core.resetting, false);+ io.now = realNow;+});++test("a steering user message that lands after the batch stays a real user turn", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);++ const steer = user("actually, also check the parser", 4242);+ const out = core.transformContext([+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ steer,+ ]);++ assert.equal(out.length, 1, "the header is merged into the steering message");+ assert.equal(out[0].role, "user");+ assert.ok(out[0].content.startsWith(WINDOW_HEADER_OPEN));+ assert.ok(out[0].content.includes("actually, also check the parser"));+ assert.deepEqual(+ lastUserTimestamps(out),+ [4242],+ "a merged real user message must not be mistaken for something we injected",+ );+ assert.equal(core.statusSnapshot({ now: 4242 + 60000, messages: out }).sinceLastUserMs, 60000);+});++test("a stale pressure reminder is dropped by the cut instead of landing in the new window", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);++ const reminder = {+ role: "user",+ customType: REMINDER_CUSTOM_TYPE,+ content: `${reminderText("hard", { windowId: "w1", usedTokens: 90000, contextWindow: 100000 })}`,+ timestamp: 7,+ };+ const out = core.transformContext([+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ reminder,+ ]);++ assert.equal(out.length, 1);+ assert.ok(!JSON.stringify(out).includes("[context-reminder]"), "w1's reminder must not follow the header into w2");+ assert.ok(String(out[0].content).startsWith(WINDOW_HEADER_OPEN));+});++test("a reminder in front of a real steering message is dropped but the message survives", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);++ const out = core.transformContext([+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ { role: "user", content: "[context-reminder] window w1 is about 90% full", timestamp: 6 },+ user("keep going with the parser", 7),+ ]);++ assert.equal(out.length, 1);+ assert.ok(String(out[0].content).includes("keep going with the parser"));+ assert.ok(!String(out[0].content).includes("[context-reminder]"));+});++test("the window token estimate counts tool call arguments and thinking blocks", () => {+ const core = makeCore(makeIo());+ const payload = "x".repeat(40000);+ core.recordWindowMetrics(+ [+ user("hi", 1),+ {+ role: "assistant",+ content: [+ { type: "thinking", thinking: "y".repeat(4000) },+ { type: "toolCall", id: "t1", name: "write", arguments: { path: "a.txt", content: payload } },+ ],+ },+ { role: "toolResult", toolCallId: "t1", toolName: "write", content: [{ type: "text", text: "ok" }] },+ ],+ -1,+ );+ assert.ok(+ core.lastWindowTokens > 9000,+ `a 40k-char tool argument must not read as a handful of tokens (got ${core.lastWindowTokens})`,+ );+});++test("thresholds are clamped under pi's own auto-compaction line", () => {+ // pi compacts as soon as contextTokens > contextWindow - reserveTokens.+ assert.deepEqual(effectiveThresholds({ softPercent: 70, hardPercent: 85, contextWindow: 262144, reserveTokens: 16384 }), {+ softPercent: 70,+ hardPercent: 85,+ });+ const small = effectiveThresholds({ softPercent: 70, hardPercent: 85, contextWindow: 32768, reserveTokens: 16384 });+ assert.equal(small.hardPercent, 49, "50% is pi's line on a 32k window, so the hard reminder sits below it");+ assert.equal(small.softPercent, 49);+ assert.deepEqual(+ effectiveThresholds({ softPercent: 70, hardPercent: 85, contextWindow: 32768, reserveTokens: 0 }),+ { softPercent: 70, hardPercent: 85 },+ "an unknown reserve leaves the configured thresholds alone",+ );++ const core = makeCore(makeIo());+ core.lastWindowTokens = 17000;+ assert.equal(core.dueReminder({ usage: { tokens: null }, contextWindow: 32768 }), null, "85% is never reached first");+ assert.equal(+ core.dueReminder({ usage: { tokens: null }, contextWindow: 32768, reserveTokens: 16384 }),+ "hard",+ "with the reserve known the hard reminder fires before pi compacts",+ );+ const snap = core.statusSnapshot({+ usage: { tokens: 17000, contextWindow: 32768 },+ reserveTokens: 16384,+ now: 1,+ });+ assert.equal(snap.hardPercent, 49);+ assert.equal(snap.advice, "save your notes and call new_context now");+});++test("after an external compaction the guard does not reuse the stale window header", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ const staleHeader = core.headerText;++ io.clock += 5000;+ core.absorbExternalCompaction("pi compacted without us");+ io.clock += 1000;++ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e9", tokensBefore: 12 },+ branchEntries: [],+ });+ assert.notEqual(out?.compaction?.summary, staleHeader, "that header claims an archive that no longer covers the branch");+ assert.equal(out?.compaction?.details.reason, "pi-compaction", "a real archive is taken instead");+});++test("two resets in one session archive twice and leave only the newest window visible", async () => {+ let archive = 2;+ const io = makeIo({+ commit: async () => {+ io.calls.push("commit:0");+ return {+ status: "accepted",+ task_id: `task-${archive}`,+ archive_uri: `viking://user/u1/sessions/pi-abc/history/archive_00${archive++}`,+ };+ },+ });+ const core = makeCore(io);++ await openWindow(core, io, { reason: "phase one", notes: "note one", toolCallId: "call-1" });+ const firstHeader = core.headerText;+ assert.equal(core.windowId, "w2");++ io.clock += 120000;+ io.overview = "# Working Memory\n## Current State\nphase two";+ const branch2 = [+ { id: "e1", type: "message", message: user("first request", 10) },+ { id: "e2", type: "message", message: assistantCalls([{ id: "call-1", name: "new_context" }]) },+ { id: "e3", type: "message", message: toolResult("call-1", "new_context") },+ { id: "e4", type: "message", message: user("second request", 60) },+ { id: "e5", type: "message", message: assistantCalls([{ id: "call-2", name: "new_context" }]) },+ ];+ const second = await openWindow(core, io, {+ reason: "phase two",+ notes: "note two",+ toolCallId: "call-2",+ branch: branch2,+ });++ assert.equal(second.ok, true);+ assert.equal(core.windowId, "w3");+ assert.equal(core.archiveId, "archive_003");+ assert.equal(core.pendingRequest, "second request");+ assert.equal(io.calls.filter((c) => c === "commit:0").length, 2);+ assert.ok(core.headerText.includes('id="w3"'));+ assert.ok(core.headerText.includes('previous="w2"'));+ assert.ok(core.headerText.includes("note two"));+ assert.ok(!core.headerText.includes("note one"));+ assert.notEqual(core.headerText, firstHeader);+ assert.equal(io.persisted.length, 2);++ const out = core.transformContext([+ user("first request", 10),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ user("second request", 60),+ assistantCalls([{ id: "call-2", name: "new_context" }]),+ toolResult("call-2", "new_context"),+ ]);+ assert.equal(out.length, 1);+ assert.equal(out[0].role, "user");+ assert.ok(!JSON.stringify(out).includes("first request"), "w1 is gone");+ assert.equal(+ out[0].content.split("second request").length - 1,+ 1,+ "w2's transcript is gone; the text survives only inside <pending-request>",+ );+ assert.ok(out[0].content.includes("<pending-request>second request</pending-request>"));+ assert.equal(+ JSON.stringify(core.transformContext([+ user("first request", 10),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ user("second request", 60),+ assistantCalls([{ id: "call-2", name: "new_context" }]),+ toolResult("call-2", "new_context"),+ ])),+ JSON.stringify(out),+ "the second window header is byte-stable too",+ );+});++test("a second reset carries the previous Working Memory as a stale block while the new one is pending", async () => {+ const secondUri = "viking://user/u1/sessions/pi-abc/history/archive_003";+ // The io methods are bound at construction, so the second archive id has to+ // come from a field the closure reads, not from a later reassignment.+ const io = makeIo();+ io.commit = async (opts = {}) => {+ io.calls.push(`commit:${opts.keepRecentCount}`);+ return {+ status: "accepted",+ task_id: "task-1",+ archive_uri: io.calls.filter((c) => c.startsWith("commit:")).length > 1 ? secondUri : ARCHIVE_URI,+ };+ };+ const core = makeCore(io);+ await openWindow(core, io, { toolCallId: "call-1" });+ assert.equal(core.overviewReady, true);++ io.overview = null;+ const out = await openWindow(core, io, { toolCallId: "call-2", branch: branchFor("call-2") });+ assert.equal(out.details.overviewState, "pending");+ // The stale block belongs to the *previous* archive; tagging it with the new+ // one would present a summary as belonging to the archive that has none.+ assert.ok(core.headerText.includes('<working-memory status="stale" archive="archive_002"'));+ assert.equal(core.headerText.includes('<working-memory status="pending" archive="archive_003"'), false);+ assert.ok(core.headerText.includes("Current State"));+ assert.match(core.headerText, /Working Memory for archive_003 is not ready yet/);+});++test("restore ignores a window entry written by a different OpenViking session", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ const data = io.persisted[0].data;++ const foreign = makeCore(makeIo({ sid: "pi-somewhere-else" }));+ foreign.restore([{ type: "custom", customType: WINDOW_ENTRY_TYPE, data }]);+ assert.equal(foreign.windowIndex, 1, "a foreign window must not be adopted");+ assert.equal(foreign.armed, false);+ assert.equal(foreign.headerText, "");++ const same = makeCore(makeIo());+ same.restore([{ type: "custom", customType: WINDOW_ENTRY_TYPE, data }]);+ assert.equal(same.windowIndex, 2);+ assert.equal(same.headerText, data.headerText);+});++test("a restored pending window rebuilds byte-identically to the in-process rebuild", async () => {+ const io = makeIo({ overview: null });+ const core = makeCore(io);+ await openWindow(core, io);+ assert.equal(core.overviewReady, false);++ const data = io.persisted[0].data;+ const io2 = makeIo({ overview: "# Working Memory\n## Current State\nlanded late" });+ const restored = makeCore(io2);+ restored.restore([{ type: "custom", customType: WINDOW_ENTRY_TYPE, data }]);+ assert.equal(restored.headerText, data.headerText, "restore reproduces the frozen bytes");++ io.overview = "# Working Memory\n## Current State\nlanded late";+ assert.equal(await core.refreshPendingOverview(), true);+ assert.equal(await restored.refreshPendingOverview(), true);+ assert.equal(restored.headerText, core.headerText, "the upgraded header is identical across processes");+ assert.ok(restored.headerText.includes('previous="w1"'));+});++test("a leading compaction summary is dropped and the cut still starts with the header", () => {+ const cut = applyWindowCut(+ [+ user("<compaction-summary>everything before this was compacted</compaction-summary>", 1),+ user("do the thing", 2),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ assistant("done"),+ ],+ { anchorToolCallId: "call-1", headerText: "HDR", headerTimestamp: 99 },+ );+ assert.equal(cut.applied, true);+ assert.equal(cut.messages.length, 2);+ assert.equal(cut.messages[0].role, "user");+ assert.equal(cut.messages[0].content, "HDR");+ assert.equal(cut.messages[0].timestamp, 99);+ assert.ok(!JSON.stringify(cut.messages).includes("compaction-summary"));+});++test("the cut never leaves an orphan tool result behind when more batches follow", () => {+ const messages = [+ user("go", 1),+ assistantCalls([+ { id: "call-1", name: "new_context" },+ { id: "call-2", name: "read" },+ ]),+ toolResult("call-2", "read"),+ toolResult("call-1", "new_context"),+ assistantCalls([{ id: "call-3", name: "grep" }]),+ toolResult("call-3", "grep"),+ ];+ const cut = applyWindowCut(messages, { anchorToolCallId: "call-1", headerText: "HDR" });+ const roles = cut.messages.map((m) => m.role);+ assert.deepEqual(roles, ["user", "assistant", "toolResult"]);++ const ids = new Set(+ cut.messages+ .filter((m) => m.role === "assistant")+ .flatMap((m) => (Array.isArray(m.content) ? m.content : []))+ .filter((b) => b.type === "toolCall")+ .map((b) => b.id),+ );+ for (const msg of cut.messages) {+ if (msg.role === "toolResult") {+ assert.ok(ids.has(msg.toolCallId), `orphan tool result ${msg.toolCallId} survived the cut`);+ }+ }+});++test("the reset still opens a degraded window when a slow flush eats the deadline", async () => {+ const io = makeIo({+ overview: null,+ flush: async (opts = {}) => {+ io.calls.push(`flush:${opts.budgetMs}`);+ io.clock += 59_000;+ return true;+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io);++ assert.equal(out.ok, true);+ assert.equal(out.details.overviewState, "pending");+ assert.ok(out.details.attempts <= 2, "the poll respects the deadline that the flush already spent");+ assert.equal(core.windowId, "w2");+ assert.ok(core.headerText.includes("is not ready yet"));+});++test("an image-only user message is not mistaken for something this extension injected", () => {+ const stamps = lastUserTimestamps([+ { role: "user", content: [{ type: "image", data: "AAAA", mimeType: "image/png" }], timestamp: 500 },+ ]);+ assert.deepEqual(stamps, [500]);+});++test("Chinese notes, pending request and overview survive the merge into a kept user message", async () => {+ const io = makeIo({ overview: "工作记忆".repeat(400) });+ const core = makeCore(io, { notesBudget: 100, pendingRequestBudget: 30, overviewBudget: 120 });+ await openWindow(core, io, {+ notes: "目标:把解析器切到流式实现;下一步:补齐测试".repeat(40),+ branch: [{ id: "e1", message: user("把解析器改成流式的,注意兼容旧配置".repeat(10), 3) }],+ });++ assert.ok(core.headerText.includes("...(truncated)"));+ assert.ok(estimateTokens(core.notes) > 100, "the raw notes are kept whole in state");++ const out = core.transformContext([+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ user("继续", 9),+ ]);+ assert.equal(out.length, 1);+ assert.ok(out[0].content.startsWith(WINDOW_HEADER_OPEN));+ assert.ok(out[0].content.endsWith("继续"));+ assert.deepEqual(lastUserTimestamps(out), [9]);+});++// --------------------------------------------------------------------------+// abort, deadline and commit-transport follow-ups+// --------------------------------------------------------------------------++test("an abort during the sync stops before the flush barrier", async () => {+ const signal = { aborted: false };+ const io = makeIo({+ syncBranch: async () => {+ io.calls.push("syncBranch");+ signal.aborted = true;+ return { added: 1, tokens: 10, allDelivered: true };+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io, { signal });++ assert.equal(out.ok, false);+ assert.equal(out.kind, "noop");+ assert.equal(out.details.stage, "aborted-before-flush");+ assert.deepEqual(io.calls, ["syncBranch"]);+ assert.equal(core.windowIndex, 1);+ assert.equal(io.persisted.length, 0);+});++test("an abort during the flush leaves no handoff message in the live session", async () => {+ const signal = { aborted: false };+ const io = makeIo({+ flush: async (opts = {}) => {+ io.calls.push(`flush:${opts.budgetMs}`);+ signal.aborted = true;+ return true;+ },+ });+ const core = makeCore(io);+ const out = await openWindow(core, io, { signal });++ assert.equal(out.kind, "noop");+ assert.equal(out.details.stage, "aborted-before-handoff");+ assert.deepEqual(io.calls, ["syncBranch", "flush:15000"], "no postHandoff, no commit");+ assert.deepEqual(io.handoffs, [], "a cancelled reset must not leave a handoff note behind");+ assert.equal(core.windowIndex, 1);+ assert.equal(core.armed, false);+});++test("the flush budget never drops below two seconds", async () => {+ const io = makeIo({+ syncBranch: async () => {+ io.calls.push("syncBranch");+ io.clock += 4900; // almost the whole 5s deadline+ return { added: 1, tokens: 10, allDelivered: true };+ },+ });+ const core = makeCore(io, { resetDeadlineMs: 5000 });+ const out = await openWindow(core, io);++ assert.equal(out.ok, true);+ assert.ok(io.calls.includes("flush:2000"), `expected a 2s floor, got ${io.calls.join(",")}`);+});++test("a deadline exhausted before the commit refuses without writing the handoff", async () => {+ const io = makeIo({+ syncBranch: async () => {+ io.calls.push("syncBranch");+ io.clock += 9000; // past the 5s deadline+ return { added: 1, tokens: 10, allDelivered: true };+ },+ });+ const core = makeCore(io, { resetDeadlineMs: 5000 });+ const out = await openWindow(core, io);++ assert.equal(out.ok, false);+ assert.equal(out.kind, "refused");+ assert.equal(out.details.stage, "deadline");+ assert.ok(out.text.includes("deadline was exhausted while syncing"));+ assert.deepEqual(io.calls, ["syncBranch", "flush:2000"]);+ assert.deepEqual(io.handoffs, []);+ assert.equal(core.windowIndex, 1);+});++test("a commit that throws is fail-closed and forces a connectivity re-check next time", async () => {+ let throwOnCommit = true;+ const io = makeIo({+ commit: async () => {+ io.calls.push("commit:0");+ if (throwOnCommit) throw new Error("ECONNRESET");+ return { status: "accepted", task_id: "task-2", archive_uri: ARCHIVE_URI };+ },+ });+ const core = makeCore(io);++ const out = await openWindow(core, io);+ assert.equal(out.ok, false);+ assert.equal(out.kind, "refused");+ assert.equal(out.details.stage, "commit-transport");+ assert.ok(out.text.includes("may or may not exist"));+ assert.equal(core.windowIndex, 1, "fail-closed: nothing is cut");+ assert.equal(core.armed, false);+ assert.ok(core.lastCommitError.message.includes("ECONNRESET"));+ assert.equal(core.state.lastCommitError.message, core.lastCommitError.message);+ assert.ok(io.logs.some((line) => line.includes("commit transport error; the archive may or may not exist")));++ io.connectedValue = false;+ io.calls.length = 0;+ const offline = await openWindow(core, io);+ assert.equal(offline.kind, "refused");+ assert.equal(offline.details.stage, "commit-transport");+ assert.deepEqual(io.calls, [], "an unresolved commit must not sync or flush again while offline");++ io.connectedValue = true;+ throwOnCommit = false;+ const retry = await openWindow(core, io);+ assert.equal(retry.ok, true);+ assert.equal(core.windowId, "w2");+ assert.equal(core.lastCommitError, null, "a successful attempt clears the unresolved commit");+});++// --------------------------------------------------------------------------+// handleBeforeCompact: sync before the barrier+// --------------------------------------------------------------------------++test("handleBeforeCompact syncs the branch before the flush barrier", async () => {+ const io = makeIo();+ const core = makeCore(io);++ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e5", tokensBefore: 11 },+ branchEntries: compactionEntries(),+ });+ assert.ok(out, "the compaction is taken over");+ assert.deepEqual(io.calls, ["syncBranch", "flush:15000", "postHandoff", "commit:0", "readArchiveOverview"]);+ assert.equal(core.lastResetBy, "pi-compaction");+});++test("handleBeforeCompact gives up when the branch cannot be delivered", async () => {+ const io = makeIo({+ syncBranch: async () => {+ io.calls.push("syncBranch");+ return { added: 0, tokens: 0, allDelivered: false };+ },+ });+ const core = makeCore(io);+ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e1", tokensBefore: 1 },+ branchEntries: compactionEntries(),+ });+ assert.equal(out, undefined, "pi writes its own summary instead");+ assert.deepEqual(io.calls, ["syncBranch"], "the barrier is not even attempted");+});++// --------------------------------------------------------------------------+// window metrics after a disarm+// --------------------------------------------------------------------------++test("disarm clears the window metrics", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ core.turnsInWindow = 9;+ core.lastWindowTokens = 54321;++ core.disarm("anchor missing, boundary released");+ assert.equal(core.turnsInWindow, 0);+ assert.equal(core.lastWindowTokens, 0);+ assert.equal(core.armed, false);+});++test("after a disarm the turn count only covers assistants newer than the reset", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ const resetAt = core.lastResetAt;++ // The anchor is gone (a fork, /tree or a native compaction), so the whole+ // session comes back: without the lastResetAt filter every old assistant turn+ // would be reported as part of the current window.+ const out = core.transformContext([+ user("way back", resetAt - 600_000),+ { role: "assistant", content: "old answer 1", timestamp: resetAt - 500_000 },+ { role: "assistant", content: "old answer 2", timestamp: resetAt - 400_000 },+ user("recent", resetAt + 1000),+ { role: "assistant", content: "new answer", timestamp: resetAt + 2000 },+ ]);+ assert.equal(core.armed, false);+ assert.equal(out.length, 5, "nothing is cut once the anchor is gone");+ assert.equal(core.turnsInWindow, 1, "only the assistant message after the reset counts");+});++// --------------------------------------------------------------------------+// lazy session validation+// --------------------------------------------------------------------------++function restoredIn(sid, data) {+ const io = makeIo({ sid: null });+ const core = makeCore(io);+ core.restore([{ type: "custom", customType: WINDOW_ENTRY_TYPE, data }]);+ io.sid = sid;+ return { io, core };+}++test("a window restored before the session id is known is validated lazily", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ const data = io.persisted[0].data;++ const foreign = restoredIn("pi-somewhere-else", data);+ assert.equal(foreign.core.armed, true, "the entry is adopted while the session id is unknown");+ assert.equal(foreign.core.pendingSessionCheck, true);+ assert.equal(foreign.core.validateSession(), false);+ assert.equal(foreign.core.armed, false);+ assert.equal(foreign.core.headerText, "");+ assert.equal(foreign.core.windowIndex, 1);+ assert.equal(foreign.core.ovSessionId, "pi-somewhere-else");+ assert.equal(foreign.core.validateSession(), true, "the check is settled and does not repeat");++ const same = restoredIn("pi-abc", data);+ assert.equal(same.core.validateSession(), true);+ assert.equal(same.core.armed, true);+ assert.equal(same.core.headerText, data.headerText);+ assert.equal(same.core.windowIndex, 2);+});++test("transformContext validates a lazily restored window before it cuts anything", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io);+ const data = io.persisted[0].data;++ const foreign = restoredIn("pi-somewhere-else", data);+ const messages = [+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ assistant("carry on"),+ ];+ const out = foreign.core.transformContext(messages);+ assert.equal(out, messages, "a foreign window never cuts this session's context");+ assert.equal(foreign.core.armed, false);++ const same = restoredIn("pi-abc", data);+ const cut = same.core.transformContext(messages);+ assert.equal(cut.length, 2, "the same session still cuts");+ assert.ok(String(cut[0].content).startsWith(WINDOW_HEADER_OPEN));+});++// --------------------------------------------------------------------------+// previousOverview / overviewUnavailable round trip+// --------------------------------------------------------------------------++test("a pending window keeps its stale Working Memory block across a persist/restore round trip", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io, { toolCallId: "call-1" });+ assert.equal(core.overviewReady, true);++ io.overview = null;+ await openWindow(core, io, { toolCallId: "call-2", branch: branchFor("call-2") });+ assert.equal(core.overviewReady, false);+ assert.ok(core.previousOverview.includes("Current State"));++ const data = io.persisted[1].data;+ assert.ok(data.previousOverview.includes("Current State"), "the stale overview is persisted");+ assert.equal(data.overviewUnavailable, false);++ const restored = makeCore(makeIo({ overview: null }));+ restored.restore([{ type: "custom", customType: WINDOW_ENTRY_TYPE, data }]);+ assert.equal(restored.previousOverview, data.previousOverview);+ assert.ok(restored.headerText.includes('status="stale"'), "the frozen header still carries it");+ assert.ok(+ restored.rebuildHeader({ overviewState: "pending" }).includes('status="stale"'),+ "and a rebuild in the new process does not lose it",+ );+});++test("the persisted previousOverview is capped at overviewBudget", async () => {+ const io = makeIo({ overview: "记忆".repeat(5000) });+ const core = makeCore(io, { overviewBudget: 100 });+ await openWindow(core, io, { toolCallId: "call-1" });+ io.overview = null;+ await openWindow(core, io, { toolCallId: "call-2", branch: branchFor("call-2") });++ const data = io.persisted[1].data;+ assert.ok(estimateTokens(data.previousOverview) <= 100, "a huge overview is not carried whole into the entry");+ assert.ok(estimateTokens(core.previousOverview) > 100, "the in-memory copy is untouched");+});++test("an unavailable window survives a restore and spends no further overview read", async () => {+ const io = makeIo({ overview: null, task: { status: "failed" } });+ const core = makeCore(io);+ await openWindow(core, io);+ assert.equal(core.overviewUnavailable, true);++ const data = io.persisted[0].data;+ assert.equal(data.overviewUnavailable, true);++ const io2 = makeIo({ overview: "# Working Memory\ntoo late" });+ const restored = makeCore(io2);+ restored.restore([{ type: "custom", customType: WINDOW_ENTRY_TYPE, data }]);+ assert.equal(restored.overviewUnavailable, true);+ assert.equal(await restored.refreshPendingOverview(), false);+ assert.deepEqual(io2.calls, [], "an unavailable window does not read .overview.md again");+});++// --------------------------------------------------------------------------+// terminal archive tasks, handoff retraction, the archive ledger+// --------------------------------------------------------------------------++test("a task that completes without a Working Memory ends the wait instead of burning the deadline", async () => {+ const io = makeIo({ overview: null, task: { status: "completed" } });+ const core = makeCore(io);+ const out = await openWindow(core, io);++ assert.equal(out.ok, true);+ assert.equal(out.details.overviewState, "unavailable");+ // Two polls to see the terminal status, three more for a write that is only+ // a moment behind — not the full 60s deadline.+ assert.equal(out.details.attempts, 5);+ assert.ok(io.clock < 1_700_000_000_000 + 60000, "the deadline is not spent");+ assert.ok(core.headerText.includes("is unavailable"));+});++test("a cancelled archive task ends the wait as unavailable", async () => {+ const io = makeIo({ overview: null, task: { status: "cancelled" } });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.details.overviewState, "unavailable");+ assert.equal(out.details.attempts, 2);+});++test("a Working Memory that lands inside the grace period is still picked up", async () => {+ const io = makeIo({ overview: null, task: { status: "completed" } });+ io.readArchiveOverview = async () => {+ io.calls.push("readArchiveOverview");+ // Arrives one poll after the task reported completed.+ return io.calls.filter((c) => c === "readArchiveOverview").length >= 3 ? "# Working Memory\nlate" : null;+ };+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.details.overviewState, "ready");+ assert.ok(core.headerText.includes("late"));+});++test("a refusal after the handoff note was written retracts it", async () => {+ const io = makeIo({ commit: async () => null });+ const core = makeCore(io);+ const out = await openWindow(core, io);++ assert.equal(out.ok, false);+ assert.equal(io.handoffs.length, 2);+ assert.match(io.handoffs[0], /^\[Context Window Handoff\] w1 -> w2/);+ assert.match(io.handoffs[1], /RETRACTED/);+ assert.match(io.handoffs[1], /this window is still open/);+ assert.equal(core.windowIndex, 1);+});++test("a refusal before the handoff note leaves the session untouched", async () => {+ const io = makeIo({ flush: async () => false });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.equal(out.ok, false);+ assert.deepEqual(io.handoffs, []);+});++test("an accepted commit without an archive_uri refuses instead of opening a nameless window", async () => {+ const io = makeIo({ commit: async () => ({ status: "accepted", task_id: "t", trace_id: "tr-9" }) });+ const core = makeCore(io);+ const out = await openWindow(core, io);++ assert.equal(out.ok, false);+ assert.equal(out.kind, "refused");+ assert.match(out.text, /^Context window NOT reset: OpenViking refused the archive commit \(trace tr-9\)/);+ assert.equal(core.windowIndex, 1);+ assert.equal(core.armed, false);+ assert.match(io.handoffs[1], /RETRACTED/);+});++test("a null commit reports the trace id the transport recorded", async () => {+ const io = makeIo({ commit: async () => null, commitTraceId: () => "tr-transport" });+ const core = makeCore(io);+ const out = await openWindow(core, io);+ assert.match(out.text, /\(trace tr-transport\)/);+});++test("every archive is recorded with the window it closed", async () => {+ const uris = [+ "viking://user/u1/sessions/pi-abc/history/archive_001",+ "viking://user/u1/sessions/pi-abc/history/archive_002",+ ];+ const io = makeIo();+ io.commit = async (opts = {}) => {+ io.calls.push(`commit:${opts.keepRecentCount}`);+ const n = io.calls.filter((c) => c.startsWith("commit:")).length;+ return { status: "accepted", task_id: "t", archive_uri: uris[n - 1] };+ };+ const core = makeCore(io);+ await openWindow(core, io, { toolCallId: "call-1" });+ // A compaction nobody asked us for closes w2 without producing an archive.+ core.absorbExternalCompaction("pi compaction");+ assert.equal(core.windowId, "w3");+ await openWindow(core, io, { toolCallId: "call-9", branch: branchFor("call-9") });++ assert.deepEqual(+ core.archives.map((a) => `${a.windowId}:${a.archiveId}`),+ ["w1:archive_001", "w3:archive_002"],+ "w2 closed without an archive, so it is not in the ledger",+ );+ assert.equal(core.statusSnapshot().archiveCount, 2, "not 3, the window index over-counts");+ assert.deepEqual(+ core.persistedState().archives.map((a) => a.windowId),+ ["w1", "w3"],+ "the ledger survives into the persisted entry",+ );++ const restored = makeCore(makeIo());+ restored.restore([{ type: "custom", customType: WINDOW_ENTRY_TYPE, data: core.persistedState() }]);+ assert.deepEqual(restored.archives, core.archives);+});++test("messages OpenViking rejected for good are named in the window header", async () => {+ let dropped = 0;+ const io = makeIo({ droppedCount: () => dropped });+ const core = makeCore(io);+ dropped = 2;+ await openWindow(core, io);+ assert.match(core.headerText, /2 messages of this session were rejected by OpenViking/);+ assert.equal(core.statusSnapshot().undeliveredCount, 2);+});++test("a stale [context-reminder] is dropped in pi's own custom-message shape", () => {+ const messages = [+ user("old", 1),+ assistantCalls([{ id: "call-1", name: "new_context" }]),+ toolResult("call-1", "new_context"),+ // What pi actually emits before convertToLlm rewrites it: role "custom".+ { role: "custom", customType: REMINDER_CUSTOM_TYPE, content: "[context-reminder] w1 is 87% full", timestamp: 5 },+ user("carry on", 6),+ ];+ const cut = applyWindowCut(messages, { anchorToolCallId: "call-1", headerText: "HEADER" });+ assert.equal(cut.applied, true);+ assert.equal(cut.messages.length, 1);+ assert.ok(String(cut.messages[0].content).startsWith("HEADER"));+ assert.equal(JSON.stringify(cut.messages).includes("87% full"), false);+});++test("the pi-compaction fallback does not present the previous window's notes as this one's", async () => {+ const io = makeIo();+ const core = makeCore(io);+ await openWindow(core, io, { toolCallId: "call-1", notes: "notes written for w2" });+ assert.ok(core.headerText.includes("notes written for w2"));++ io.clock += 10 * 60_000; // past the recent-reset guard+ io.watermark = 99;+ const out = await core.handleBeforeCompact({+ preparation: { firstKeptEntryId: "e1", tokensBefore: 1000 },+ branchEntries: [{ id: "e1", type: "message", message: user("still here", io.clock) }],+ });++ assert.ok(out, "the fallback took over");+ assert.equal(out.compaction.summary.includes("notes written for w2"), false);+ assert.equal(core.notes, "");+ const handoff = io.handoffs.at(-1);+ assert.match(handoff, /automatic: pi compaction threshold/);+ assert.match(handoff, /the harness compacted this window before new_context was called/);+ assert.equal(handoff.includes("notes written for w2"), false);+});diff --git a/examples/pi-experimental-context-management/tests/index-load.test.mjs b/examples/pi-experimental-context-management/tests/index-load.test.mjsnew file mode 100644index 000000000..a4822c5ba--- /dev/null+++ b/examples/pi-experimental-context-management/tests/index-load.test.mjs@@ -0,0 +1,969 @@+import test from "node:test";+import assert from "node:assert/strict";+import { createServer } from "node:http";+import { existsSync, mkdtempSync, rmSync } from "node:fs";+import { createRequire } from "node:module";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { fileURLToPath } from "node:url";++// pi loads extensions through the jiti it bundles, so that is the loader this+// smoke check has to use — a plain `import` of index.ts would not resolve the+// TypeScript or the `.js`-suffixed relative specifiers.+const EXTENSION_DIR = dirname(dirname(fileURLToPath(import.meta.url)));++/**+ * jiti, wherever pi is installed: the global homebrew prefix on this machine,+ * a local node_modules in CI, or an explicit override. Without it these tests+ * skip rather than silently testing nothing.+ */+function findJiti() {+ const candidates = [process.env.PI_JITI_PATH || ""];+ try {+ const require = createRequire(join(EXTENSION_DIR, "package.json"));+ candidates.push(+ require.resolve("@earendil-works/pi-coding-agent/node_modules/jiti/lib/jiti.mjs"),+ );+ } catch {+ // not installed as a dependency here+ }+ candidates.push(+ "/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/jiti/lib/jiti.mjs",+ "/usr/local/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/jiti/lib/jiti.mjs",+ );+ return candidates.find((path) => path && existsSync(path)) ?? "";+}++const JITI_PATH = findJiti();++/** The pi surface index.ts touches, and nothing more. */+function fakePi(calls, options = {}) {+ return {+ on(event, handler) {+ calls.events.push(event);+ calls.handlers.set(event, handler);+ },+ registerTool(tool) { calls.tools.push(tool?.name); calls.toolDefs.set(tool?.name, tool); },+ registerCommand(name, def) { calls.commands.push(name); calls.commandDefs.set(name, def); },+ appendEntry(customType, data) { calls.entries.push({ customType, data }); },+ getAllTools() { return options.getAllTools ? options.getAllTools() : []; },+ sendMessage(message, options2) { calls.sent.push({ message, options: options2 }); },+ };+}++/** The `ctx` shape the handlers read: session manager, ui, context usage. */+function fakeCtx(overrides = {}) {+ const branch = overrides.branch ?? [];+ return {+ sessionManager: {+ getSessionId: () => overrides.sessionId ?? "pi-session-abc",+ getBranch: () => branch,+ getLeafId: () => overrides.leafId ?? "entry-9",+ },+ ui: {+ notify: (...args) => (overrides.notified ?? []).push(args),+ setStatus: (...args) => (overrides.statuses ?? []).push(args),+ },+ getContextUsage: () => overrides.usage ?? { tokens: 1000, contextWindow: 262144, percent: 1 },+ };+}++/** Load index.ts and run it against a fake pi, with OV pointed at a dead port. */+async function loadExtension(options = {}) {+ const { createJiti } = await import(JITI_PATH);+ const jiti = createJiti(import.meta.url, { interopDefault: true });+ const mod = await jiti.import(join(EXTENSION_DIR, "index.ts"), { default: true });+ assert.equal(typeof mod, "function");++ const calls = {+ events: [],+ handlers: new Map(),+ tools: [],+ toolDefs: new Map(),+ commands: [],+ commandDefs: new Map(),+ entries: [],+ sent: [],+ };+ await mod(fakePi(calls, options));+ return calls;+}++const OV_ENV = {+ // Port 1 refuses immediately: the health check must fail fast and the+ // extension must still arm its offline half.+ OPENVIKING_URL: "http://127.0.0.1:1",+ OPENVIKING_API_KEY: "test-key",+};++function withDeadServer(t) {+ const previous = {};+ for (const [key, value] of Object.entries(OV_ENV)) {+ previous[key] = process.env[key];+ process.env[key] = value;+ }+ t.after(() => {+ for (const [key, value] of Object.entries(previous)) {+ if (value === undefined) delete process.env[key];+ else process.env[key] = value;+ }+ });+}++test("index.ts loads through pi's jiti and registers its surface", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ const calls = await loadExtension();++ for (const event of [+ "session_start",+ "before_agent_start",+ "context",+ "tool_call",+ "turn_end",+ "session_before_compact",+ "session_compact",+ "session_shutdown",+ "agent_end",+ ]) {+ assert.ok(calls.events.includes(event), `missing handler for ${event}`);+ }+ assert.deepEqual(calls.commands, ["viking"]);+});++test("session_start registers the six viking tools and the three context window tools", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ const calls = await loadExtension();++ await calls.handlers.get("session_start")({ type: "session_start" }, fakeCtx());+ // session_start is fire-and-forget; before_agent_start awaits the same chain.+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "hello", systemPrompt: "BASE" },+ fakeCtx(),+ );++ assert.deepEqual(calls.tools, [+ "viking_search",+ "viking_read",+ "viking_browse",+ "viking_remember",+ "viking_forget",+ "viking_add_resource",+ "new_context",+ "history",+ "get_context_remaining",+ ]);+ // `viking_archive_expand` read viking://session/{sid}, a namespace the server+ // does not have; `history` replaced it and it must not come back.+ assert.equal(calls.tools.includes("viking_archive_expand"), false);+ assert.equal(calls.toolDefs.get("new_context").executionMode, "sequential");+ assert.equal(typeof calls.toolDefs.get("history").execute, "function");+});++test("before_agent_start ships the window guidance and one status line, server or no server", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ const calls = await loadExtension();++ const result = await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "hello", systemPrompt: "BASE" },+ fakeCtx(),+ );++ assert.ok(result.systemPrompt.startsWith("BASE\n\n"));+ assert.match(result.systemPrompt, /<context-window-management>/);+ assert.match(result.systemPrompt, /new_context, history, get_context_remaining\./);+ // Codex hides this machinery from the user; the demo deliberately does not.+ assert.equal(/never (mention|disclose|reveal)/i.test(result.systemPrompt), false);++ assert.equal(result.message.customType, "ov-context-status");+ assert.equal(result.message.display, true);+ assert.match(result.message.content, /^\[context-status\] window w1/);+});++test("the first status line of a process counts the branch, not an empty window", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ const calls = await loadExtension();++ // A `pi -c` continuation: the window was opened in the previous process, so+ // the `context` hook — the only place that records the window metrics — has+ // never run here. Reading them off the branch is what stops the first line of+ // the session from claiming an open window has no turns and no idle gap.+ const now = Date.now();+ const headerText =+ '<openviking-context source="context-window">\n' ++ '<context_window id="w2" previous="w1" archive="archive_001">restored</context_window>\n' ++ "</openviking-context>";+ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "phase one", timestamp: now - 3_600_000 } },+ {+ type: "message",+ id: "e2",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: now - 3_500_000,+ },+ },+ {+ type: "custom",+ id: "e3",+ customType: "ov-context-window",+ data: {+ version: 1,+ ovSessionId: "pi-pi-session-abc",+ windowIndex: 2,+ anchorToolCallId: "call-1",+ openedAt: now - 3_400_000,+ headerText,+ reason: "phase one is done",+ notes: "codename ZEPHYR-9942",+ nextSteps: [],+ pendingRequest: "",+ archiveId: "archive_001",+ archiveUri: ARCHIVE,+ taskId: "task-1",+ overviewReady: true,+ overviewUnavailable: false,+ overviewAttempts: 0,+ previousOverview: "",+ siblingToolNames: [],+ syncedEntryCount: 4,+ lastResetAt: now - 3_400_000,+ lastResetBy: "agent",+ },+ },+ {+ type: "message",+ id: "e4",+ message: { role: "toolResult", toolCallId: "call-1", toolName: "new_context", content: "ok", timestamp: now - 3_400_000 },+ },+ // The window's own two turns: a user prompt five minutes ago, answered.+ { type: "message", id: "e5", message: { role: "user", content: "what is left?", timestamp: now - 300_000 } },+ { type: "message", id: "e6", message: { role: "assistant", content: "the tests", timestamp: now - 290_000 } },+ ];++ const first = await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "run them", systemPrompt: "BASE" },+ fakeCtx({ branch }),+ );+ const line = first.message.content.split("\n")[0];+ assert.match(line, /^\[context-status\] window w2 · 1 turn · /, `singular turn count: ${line}`);+ assert.match(line, / 5m since your previous message$/);++ // The window entry is restored once, so a longer branch on the next prompt+ // has to move the count — and pluralize it.+ const grown = [+ ...branch,+ { type: "message", id: "e7", message: { role: "user", content: "and now?", timestamp: now - 120_000 } },+ { type: "message", id: "e8", message: { role: "assistant", content: "done", timestamp: now - 110_000 } },+ ];+ const second = await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "next", systemPrompt: "BASE" },+ fakeCtx({ branch: grown }),+ );+ assert.match(second.message.content, /^\[context-status\] window w2 · 2 turns · /);+ assert.match(second.message.content.split("\n")[0], / 2m since your previous message$/);+});++test("the context hook returns the messages untouched while no window is armed", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ const calls = await loadExtension();+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "hello", systemPrompt: "BASE" },+ fakeCtx(),+ );++ const messages = [+ { role: "user", content: "first", timestamp: 1 },+ { role: "assistant", content: "second", timestamp: 2 },+ ];+ const result = await calls.handlers.get("context")({ type: "context", messages }, fakeCtx());+ assert.deepEqual(result.messages, messages);+});++// ---------------------------------------------------------------------------+// End to end through the wiring: a fake OpenViking server, a real reset, the+// cut the next sampling sees, and the signals that follow it.+// ---------------------------------------------------------------------------++const ROOT = "viking://user/u1/sessions/pi-session-abc";+const ARCHIVE = `${ROOT}/history/archive_001`;++const ARCHIVED_MESSAGES = [+ { id: "m1", role: "user", parts: [{ type: "text", text: "start phase one" }], created_at: "2026-09-10T01:00:00Z" },+ { id: "m2", role: "assistant", parts: [{ type: "text", text: `noted ${"X".repeat(9000)}` }], created_at: "2026-09-10T01:00:05Z" },+]+ .map((row) => JSON.stringify(row))+ .join("\n");++/** The handful of OpenViking routes one reset (and `history`) walks through. */+function startFakeOv(t, options = {}) {+ const seen = [];+ const greps = [];+ const server = createServer(async (req, res) => {+ let body = "";+ for await (const chunk of req) body += chunk;+ const url = new URL(req.url, "http://ov.invalid");+ seen.push(`${req.method} ${url.pathname}`);+ const send = (payload, code = 200) => {+ res.writeHead(code, { "content-type": "application/json" });+ res.end(JSON.stringify(payload));+ };+ if (url.pathname === "/health") return send({ status: "ok" });+ if (/\/messages\/batch$/.test(url.pathname)) return send({ result: { added: 1 } });+ if (/\/messages$/.test(url.pathname)) return send({ result: { ok: true } });+ if (/\/commit$/.test(url.pathname)) {+ return send({+ result: { status: "accepted", archived: 2, task_id: "task-1", archive_uri: ARCHIVE },+ });+ }+ if (req.method === "GET" && /^\/api\/v1\/sessions\/[^/]+$/.test(url.pathname)) {+ return send({ result: { uri: ROOT } });+ }+ if (url.pathname === "/api/v1/fs/ls") {+ // The gateway blocks this route on some deployments (403 ApiBlocked).+ if (options.blockLs) return send({ error: { code: "ApiBlocked", message: "blocked" } }, 403);+ if (options.emptyLs) return send({ result: [] });+ return send({+ result: [{ uri: ARCHIVE, isDir: true, modTime: "2026-09-10T01:00:00Z", abstract: "# Working Memory\nphase one" }],+ });+ }+ if (url.pathname === "/api/v1/content/read") {+ const uri = url.searchParams.get("uri") || "";+ if (uri.endsWith(".overview.md")) return send({ result: "# Working Memory\n\nphase one" });+ if (uri.endsWith("messages.jsonl")) return send({ result: ARCHIVED_MESSAGES });+ return send({ error: { message: "NOT_FOUND" } }, 404);+ }+ if (url.pathname === "/api/v1/search/grep") {+ greps.push(JSON.parse(body || "{}"));+ return send({+ result: {+ matches: [+ { uri: `${ARCHIVE}/messages.jsonl`, line: 2, content: "Z".repeat(900) },+ { uri: `${ARCHIVE}/.overview.md`, line: 4, content: "codename ZEPHYR-9942" },+ ],+ },+ });+ }+ // Recall: a block the injector would prepend to the newest user message.+ if (url.pathname === "/api/v1/search/recall") {+ return send({ result: { rendered: "- recalled memory", entries: [{ uri: "viking://x" }] } });+ }+ return send({ error: { message: "not found" } }, 404);+ });+ t.after(() => server.close());+ return new Promise((resolve) => {+ server.listen(0, "127.0.0.1", () => resolve({ port: server.address().port, seen, greps }));+ });+}++/** Isolated env: a live fake server and a pending queue that is not the user's. */+function withFakeServer(t, port) {+ const dir = mkdtempSync(join(tmpdir(), "ov-index-"));+ const previous = {};+ const env = {+ OPENVIKING_URL: `http://127.0.0.1:${port}`,+ OPENVIKING_API_KEY: "test-key",+ OPENVIKING_PENDING_DIR: dir,+ };+ for (const [key, value] of Object.entries(env)) {+ previous[key] = process.env[key];+ process.env[key] = value;+ }+ t.after(() => {+ for (const [key, value] of Object.entries(previous)) {+ if (value === undefined) delete process.env[key];+ else process.env[key] = value;+ }+ rmSync(dir, { recursive: true, force: true });+ });+}++test("a reset archives the window, cuts it out of the next context and stays quiet in the same turn", { skip: !JITI_PATH }, async (t) => {+ const { port } = await startFakeOv(t);+ withFakeServer(t, port);+ const calls = await loadExtension();++ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "start phase one PAD1", timestamp: 1 } },+ { type: "message", id: "e2", message: { role: "assistant", content: "phase one done", timestamp: 2 } },+ { type: "message", id: "e3", message: { role: "user", content: "wrap it up", timestamp: 3 } },+ {+ type: "message",+ id: "e4",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 4,+ },+ },+ ];+ // Pi reports the *untransformed* session, so right after the cut this number+ // still describes the window that was just archived.+ const usage = { tokens: 250000, contextWindow: 262144, percent: 95 };+ const ctx = fakeCtx({ branch, usage });++ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "wrap it up", systemPrompt: "BASE" },+ ctx,+ );++ const result = await calls.toolDefs.get("new_context").execute(+ "call-1",+ { reason: "phase one is done", notes: "codename ZEPHYR-9942", next_steps: ["start phase two"] },+ undefined,+ () => {},+ ctx,+ );+ assert.equal(result.isError, false);+ // A reset must never terminate the agent loop: the next sampling is what+ // consumes it.+ assert.equal("terminate" in result, false);+ assert.match(result.content[0].text, /Context window w2 is open/);++ // The turn the reset happened in ends here. Its assistant message predates+ // the reset, so no reminder may fire off the stale usage — one would tell the+ // model to reset again immediately and burn the level for the whole window.+ await calls.handlers.get("turn_end")(+ {+ type: "turn_end",+ turnIndex: 0,+ message: branch[3].message,+ toolResults: [{ role: "toolResult", toolCallId: "call-1" }],+ },+ ctx,+ );+ assert.deepEqual(calls.sent, [], "no reminder in the turn that reset the window");++ // The next sampling: the archived window is gone, the header is the context.+ const messages = [+ { role: "user", content: "start phase one PAD1", timestamp: 1 },+ { role: "assistant", content: "phase one done", timestamp: 2 },+ { role: "user", content: "wrap it up", timestamp: 3 },+ {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 4,+ },+ { role: "toolResult", toolCallId: "call-1", toolName: "new_context", content: "ok", timestamp: 5 },+ ];+ const cut = await calls.handlers.get("context")({ type: "context", messages }, ctx);+ assert.equal(cut.messages.length, 1);+ assert.equal(cut.messages[0].role, "user");+ const header = String(cut.messages[0].content);+ assert.ok(header.startsWith('<openviking-context source="context-window">'), header.slice(0, 80));+ assert.match(header, /id="w2" previous="w1" archive="archive_001"/);+ assert.match(header, /ZEPHYR-9942/);+ assert.match(header, /<working-memory[^>]*>/); // the fake's Working Memory+ assert.match(header, /<pending-request>\s*wrap it up/);+ // The archived turns are gone; only the notes and the pending request survive.+ assert.equal(header.includes("PAD1"), false);+ // Recall runs after the cut and its guard leaves the frozen header alone.+ assert.equal(header.includes("recalled memory"), false);++ // One window entry, so `pi -c` can rebuild the same anchor and header.+ const windowEntries = calls.entries.filter((e) => e.customType === "ov-context-window");+ assert.equal(windowEntries.length, 1);+ assert.equal(windowEntries[0].data.archiveId, "archive_001");+ assert.equal(windowEntries[0].data.anchorToolCallId, "call-1");+ assert.equal(windowEntries[0].data.overviewReady, true);++ // A later turn, whose assistant answered inside the new window: now the+ // reported usage is about this window again, so a full window does warn —+ // once, and steered because the batch is still running.+ await calls.handlers.get("turn_end")(+ {+ type: "turn_end",+ turnIndex: 1,+ message: { role: "assistant", content: "working", timestamp: Date.now() + 1000 },+ toolResults: [{ role: "toolResult", toolCallId: "call-2" }],+ },+ ctx,+ );+ assert.equal(calls.sent.length, 1);+ assert.equal(calls.sent[0].message.customType, "ov-context-reminder");+ assert.equal(calls.sent[0].options.deliverAs, "steer");+ assert.match(calls.sent[0].message.content, /new_context/);++ // At the end of a turn with no tool results the reminder waits for the next+ // turn instead of jumping the queue — and it never repeats a level.+ await calls.handlers.get("turn_end")(+ {+ type: "turn_end",+ turnIndex: 2,+ message: { role: "assistant", content: "still working", timestamp: Date.now() + 2000 },+ toolResults: [],+ },+ ctx,+ );+ assert.equal(calls.sent.length, 1, "each level fires once per window");+});++test("history reads the archived window back and get_context_remaining reports the new one", { skip: !JITI_PATH }, async (t) => {+ const { port, greps } = await startFakeOv(t);+ withFakeServer(t, port);+ const calls = await loadExtension();++ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "start phase one", timestamp: 1 } },+ {+ type: "message",+ id: "e2",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ },+ ];+ const ctx = fakeCtx({ branch, usage: { tokens: 40000, contextWindow: 262144, percent: 15 } });+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "start phase one", systemPrompt: "BASE" },+ ctx,+ );+ await calls.toolDefs.get("new_context").execute(+ "call-1",+ { reason: "phase one is done", notes: "codename ZEPHYR-9942" },+ undefined,+ () => {},+ ctx,+ );++ const history = calls.toolDefs.get("history");+ const run = async (params) => (await history.execute("h", params, undefined, () => {}, ctx)).content[0].text;++ // w1 is the oldest archive; the open window is listed but not readable.+ const windows = await run({ action: "list_windows" });+ assert.match(windows, /^w1 {2}archive_001 {2}2026-09-10T01:00:00Z {2}# Working Memory$/m);+ assert.match(windows, /^w2 {2}\(current\) {2}this window is still open and not archived$/m);++ const items = await run({ action: "list_items", window: "w1" });+ assert.match(items, /\[id: w1:0\] {2}user 2026-09-10T01:00:00Z {2}start phase one/);+ assert.match(items, /\[id: w1:1\].*\[truncated, \d+ more characters\]/);+ assert.match(items, /Showing 0-1 of 2 items \(end of window\)\./);++ // read_item goes up to historyItemMaxChars (8000) rather than the list clip.+ const item = await run({ action: "read_item", item: "w1:1" });+ assert.match(item, /^\[id: w1:1\] {2}assistant {2}2026-09-10T01:00:05Z$/m);+ assert.ok(item.length > 8000 && item.length < 8200, `unexpected length ${item.length}`);+ assert.match(await run({ action: "read_item", item: "w1:7" }), /has 2 items \(0-1\); 7 is out of range/);+ assert.match(await run({ action: "list_items", window: "w7" }), /No archived window named "w7"/);++ const found = await run({ action: "search_contents", query: "ZEPHYR" });+ assert.match(found, /^w1 {2}archive_001$/m);+ // Long grep lines are clipped, and a messages.jsonl hit points at read_item.+ assert.match(found, /messages\.jsonl:2 {2}Z+… \[truncated, \d+ more characters\] {2}→ \{"action":"read_item","item":"w1:1"\}/);+ assert.match(found, /\.overview\.md:4 {2}codename ZEPHYR-9942/);+ assert.equal(greps.at(-1).case_insensitive, true);++ // A query that is not a valid expression is searched verbatim instead of+ // failing server-side as a broken regex.+ await run({ action: "search_contents", query: "phase one (unfinished" });+ assert.equal(greps.at(-1).pattern, "phase one \\(unfinished");++ const remaining = (await calls.toolDefs+ .get("get_context_remaining")+ .execute("g", {}, undefined, () => {}, ctx)).content[0].text;+ assert.match(remaining, /^window: w2, opened /m);+ assert.match(remaining, /^archives: 1 \(latest archive_001, Working Memory ready\)$/m);+ assert.match(remaining, /^tokens_left: /m);+ assert.match(remaining, /^advice: /m);+});++test("a window restored with OpenViking down still cuts the archived conversation", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ const calls = await loadExtension();++ const headerText =+ '<openviking-context source="context-window">\n' ++ '<context_window id="w2" previous="w1" archive="archive_001">restored</context_window>\n' ++ "</openviking-context>";+ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "phase one PAD1", timestamp: 1 } },+ {+ type: "message",+ id: "e2",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ },+ {+ type: "custom",+ customType: "ov-context-window",+ data: {+ version: 1,+ ovSessionId: "pi-pi-session-abc",+ windowIndex: 2,+ anchorToolCallId: "call-1",+ openedAt: 1000,+ headerText,+ reason: "phase one is done",+ notes: "codename ZEPHYR-9942",+ nextSteps: [],+ pendingRequest: "",+ archiveId: "archive_001",+ archiveUri: ARCHIVE,+ taskId: "task-1",+ overviewReady: true,+ overviewUnavailable: false,+ overviewAttempts: 0,+ previousOverview: "",+ siblingToolNames: [],+ syncedEntryCount: 42,+ lastResetAt: 1000,+ lastResetBy: "agent",+ },+ },+ ];+ const ctx = fakeCtx({ branch });++ const started = await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "what was the codename?", systemPrompt: "BASE" },+ ctx,+ );+ // Window state and tools are restored before the health check, so an+ // unreachable server does not hand the archived window back to the model.+ assert.match(started.message.content, /^\[context-status\] window w2/);+ assert.ok(calls.tools.includes("new_context"));++ const messages = [+ { role: "user", content: "phase one PAD1", timestamp: 1 },+ {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ { role: "toolResult", toolCallId: "call-1", toolName: "new_context", content: "ok", timestamp: 3 },+ { role: "user", content: "what was the codename?", timestamp: 4 },+ ];+ const cut = await calls.handlers.get("context")({ type: "context", messages }, ctx);+ assert.equal(cut.messages.length, 1);+ assert.ok(String(cut.messages[0].content).startsWith(headerText));+ // The window header merges into the surviving user message instead of+ // producing two user messages in a row.+ assert.match(String(cut.messages[0].content), /what was the codename\?$/);+ assert.equal(JSON.stringify(cut.messages).includes("PAD1"), false);++ // Offline, pi keeps its own summarizer: no archive, no header as summary.+ const compact = await calls.handlers.get("session_before_compact")(+ { type: "session_before_compact", preparation: { firstKeptEntryId: "e2", tokensBefore: 100 }, branchEntries: branch },+ ctx,+ );+ assert.equal(compact, undefined);++ // A compaction that was not ours already cut the history natively, so the+ // virtual boundary has to be released or the model would lose live context.+ await calls.handlers.get("session_compact")(+ { type: "session_compact", fromExtension: false, compactionEntry: {}, reason: "threshold" },+ ctx,+ );+ const after = await calls.handlers.get("context")({ type: "context", messages }, ctx);+ assert.equal(after.messages.length, messages.length);++ // The final watermark is persisted even though the server never answered.+ await calls.handlers.get("session_shutdown")({ type: "session_shutdown", reason: "quit" }, ctx);+ const windowEntries = calls.entries.filter((e) => e.customType === "ov-context-window");+ assert.ok(windowEntries.length >= 1);+ assert.equal(windowEntries.at(-1).data.windowIndex, 3, "the absorbed compaction opened w3");+});++test("the fork ships no takeover module", () => {+ for (const file of ["takeover.ts", "lib/takeover-core.mjs", "shared/recall-ledger.mjs"]) {+ assert.equal(existsSync(join(EXTENSION_DIR, file)), false, `${file} should not exist`);+ }+});++// ---------------------------------------------------------------------------+// Coexistence with the non-experimental extension, and the signals that must+// not fire off a stale usage reading.+// ---------------------------------------------------------------------------++/** A `viking_search` some other extension registered. */+const PEER_TOOL = { name: "viking_search", sourceInfo: { path: "/somewhere/else/openviking" } };++test("a peer that registers viking_search later still makes this extension stand down", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ // The other extension registers only after its own awaited health check, so+ // at the moment start() begins the probe sees nothing.+ let peerLoaded = false;+ const calls = await loadExtension({ getAllTools: () => (peerLoaded ? [PEER_TOOL] : []) });++ const notified = [];+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "hello", systemPrompt: "BASE" },+ fakeCtx({ notified }),+ );+ assert.ok(calls.tools.includes("viking_search"), "the early probe found nothing, so we registered");++ peerLoaded = true;+ const result = await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "again", systemPrompt: "BASE" },+ fakeCtx({ notified }),+ );+ assert.equal(result, undefined, "the second writer stands down instead of syncing the same session");+ assert.ok(+ notified.some(([message]) => /another OpenViking extension is already active/.test(message)),+ JSON.stringify(notified),+ );++ // And it stays down: no cut, no sync, no reminders.+ const messages = [{ role: "user", content: "hi", timestamp: 1 }];+ assert.equal(await calls.handlers.get("context")({ type: "context", messages }, fakeCtx()), undefined);+});++test("our own viking_search is not mistaken for a peer's", { skip: !JITI_PATH }, async (t) => {+ withDeadServer(t);+ const calls = await loadExtension({+ getAllTools: () => [{ name: "viking_search", sourceInfo: { path: EXTENSION_DIR } }],+ });+ const result = await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "hello", systemPrompt: "BASE" },+ fakeCtx(),+ );+ assert.ok(result?.systemPrompt, "the extension keeps working");+ assert.ok(calls.tools.includes("new_context"));+});++test("a turn that ended in a provider error does not re-arm the reminders", { skip: !JITI_PATH }, async (t) => {+ const { port } = await startFakeOv(t);+ withFakeServer(t, port);+ const calls = await loadExtension();++ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "start", timestamp: 1 } },+ {+ type: "message",+ id: "e2",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ },+ ];+ // pi reports the untransformed session, so this is the *closed* window's size.+ const ctx = fakeCtx({ branch, usage: { tokens: 250000, contextWindow: 262144, percent: 95 } });+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "start", systemPrompt: "BASE" },+ ctx,+ );+ await calls.toolDefs.get("new_context").execute(+ "call-1", { reason: "phase one done", notes: "codename ZEPHYR-9942" }, undefined, () => {}, ctx,+ );++ // A provider error (or Esc) ends the turn with a freshly stamped assistant+ // message pi refuses to read usage from. Re-arming on it would fire the hard+ // reminder into a window that holds nothing but the header.+ for (const stopReason of ["error", "aborted"]) {+ await calls.handlers.get("turn_end")(+ {+ type: "turn_end",+ turnIndex: 1,+ message: { role: "assistant", content: "", stopReason, timestamp: Date.now() + 5000 },+ toolResults: [],+ },+ ctx,+ );+ }+ assert.deepEqual(calls.sent, [], "no reminder off a response pi does not trust");++ // A real response in the new window re-arms as before.+ await calls.handlers.get("turn_end")(+ {+ type: "turn_end",+ turnIndex: 2,+ message: { role: "assistant", content: "working", stopReason: "stop", timestamp: Date.now() + 6000 },+ toolResults: [],+ },+ ctx,+ );+ assert.equal(calls.sent.length, 1);+ assert.equal(calls.sent[0].message.customType, "ov-context-reminder");+});++test("a recall failure costs the recall block, never the window cut", { skip: !JITI_PATH }, async (t) => {+ const { port } = await startFakeOv(t);+ withFakeServer(t, port);+ const calls = await loadExtension();++ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "start PAD1", timestamp: 1 } },+ {+ type: "message",+ id: "e2",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ },+ ];+ const ctx = fakeCtx({ branch });+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "start PAD1", systemPrompt: "BASE" },+ ctx,+ );+ await calls.toolDefs.get("new_context").execute(+ "call-1", { reason: "done", notes: "codename ZEPHYR-9942" }, undefined, () => {}, ctx,+ );++ // pi keeps the untransformed list when a context handler throws, so a recall+ // exception must not be allowed to escape: it would hand the model the+ // archived window back together with the tool result that archived it.+ const messages = [+ { role: "user", content: "start PAD1", timestamp: 1 },+ {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ { role: "toolResult", toolCallId: "call-1", toolName: "new_context", content: "ok", timestamp: 3 },+ // A message shape injectRecall would trip over.+ { role: "user", content: null, timestamp: 4 },+ null,+ ];+ const cut = await calls.handlers.get("context")({ type: "context", messages }, ctx);+ assert.ok(Array.isArray(cut.messages));+ assert.ok(String(cut.messages[0].content).includes("ZEPHYR-9942"));+ assert.ok(cut.messages.length < messages.length, "the archived window stays cut");+ assert.equal(+ cut.messages.some((m) => m?.role === "toolResult" || m?.role === "assistant"),+ false,+ "the reset's own call and result are gone",+ );+ assert.equal(JSON.stringify(cut.messages).includes("recalled memory"), false, "recall failed, the cut did not");+});++test("history says so when OpenViking cannot answer the archive listing", { skip: !JITI_PATH }, async (t) => {+ const { port } = await startFakeOv(t, { blockLs: true });+ withFakeServer(t, port);+ const calls = await loadExtension();+ const ctx = fakeCtx();+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "hi", systemPrompt: "BASE" },+ ctx,+ );++ const out = await calls.toolDefs+ .get("history")+ .execute("h", { action: "list_windows" }, undefined, () => {}, ctx);+ const body = out.content[0].text;+ assert.match(body, /did not answer the archive listing/);+ assert.equal(/0 archived windows/.test(body), false, "an unreadable history is not an empty one");+});++test("an empty history does not point list_items at the open window", { skip: !JITI_PATH }, async (t) => {+ const { port } = await startFakeOv(t, { emptyLs: true });+ withFakeServer(t, port);+ const calls = await loadExtension();+ const ctx = fakeCtx();+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "hi", systemPrompt: "BASE" },+ ctx,+ );++ const body = (await calls.toolDefs+ .get("history")+ .execute("h", { action: "list_windows" }, undefined, () => {}, ctx)).content[0].text;+ assert.match(body, /^0 archived windows in this session:$/m);+ assert.match(body, /^w1 {2}\(current\)/m);+ // The only id in the list is the open window, and list_items refuses it — a+ // pointer at it would buy a refused call and imply history can read it.+ assert.equal(+ /\{"action":"list_items","window":"w1"\}/.test(body),+ false,+ "no pointer at the window that is not archived",+ );+ assert.match(body, /Nothing is archived yet/);+});++test("session_before_compact runs offline so the recent-reset guard still applies", { skip: !JITI_PATH }, async (t) => {+ const { port } = await startFakeOv(t);+ withFakeServer(t, port);+ const calls = await loadExtension();++ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "start", timestamp: 1 } },+ {+ type: "message",+ id: "e2",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ },+ ];+ const ctx = fakeCtx({ branch });+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "start", systemPrompt: "BASE" },+ ctx,+ );+ await calls.toolDefs.get("new_context").execute(+ "call-1", { reason: "done", notes: "codename ZEPHYR-9942" }, undefined, () => {}, ctx,+ );++ // A provider hiccup right after the reset makes pi estimate from the+ // untransformed list and try to compact a window that just opened. The guard+ // needs no network, so it has to run even with the server gone.+ const compact = await calls.handlers.get("session_before_compact")(+ { type: "session_before_compact", preparation: { firstKeptEntryId: "e1", tokensBefore: 10 }, branchEntries: branch },+ ctx,+ );+ assert.ok(compact?.compaction, "the freshly opened window is handed back as the summary");+ assert.equal(compact.compaction.details.reason, "recent-reset-guard");+ assert.ok(compact.compaction.summary.includes("ZEPHYR-9942"));+});++test("window ids survive a compaction that produced no archive", { skip: !JITI_PATH }, async (t) => {+ const { port } = await startFakeOv(t);+ withFakeServer(t, port);+ const calls = await loadExtension();++ const branch = [+ { type: "message", id: "e1", message: { role: "user", content: "start", timestamp: 1 } },+ {+ type: "message",+ id: "e2",+ message: {+ role: "assistant",+ content: [{ type: "toolCall", id: "call-1", name: "new_context", arguments: {} }],+ timestamp: 2,+ },+ },+ ];+ const ctx = fakeCtx({ branch });+ await calls.handlers.get("before_agent_start")(+ { type: "before_agent_start", prompt: "start", systemPrompt: "BASE" },+ ctx,+ );+ await calls.toolDefs.get("new_context").execute(+ "call-1", { reason: "done", notes: "codename ZEPHYR-9942" }, undefined, () => {}, ctx,+ );+ // w2 closes without an archive: pi compacted on its own.+ await calls.handlers.get("session_compact")(+ { type: "session_compact", fromExtension: false, compactionEntry: {}, reason: "threshold" },+ ctx,+ );++ const windows = (await calls.toolDefs+ .get("history")+ .execute("h", { action: "list_windows" }, undefined, () => {}, ctx)).content[0].text;+ // archive_001 keeps the id of the window it closed, and the open window is w3+ // — numbering the server's list positionally would call the open one w2 and+ // point every recovery hint at a window history cannot resolve.+ assert.match(windows, /^w1 {2}archive_001 {2}/m);+ assert.match(windows, /^w3 {2}\(current\)/m);+ assert.match(+ (await calls.toolDefs.get("history").execute("h", { action: "list_items", window: "w1" }, undefined, () => {}, ctx))+ .content[0].text,+ /^w1 \(archive_001\), 2 items:/m,+ );++ const remaining = (await calls.toolDefs+ .get("get_context_remaining")+ .execute("g", {}, undefined, () => {}, ctx)).content[0].text;+ assert.match(remaining, /^window: w3/m);+ assert.match(remaining, /^archives: 1 \(latest archive_001/m, "one archive, not two windows worth");+});diff --git a/examples/pi-experimental-context-management/tests/recall-deferred.test.mjs b/examples/pi-experimental-context-management/tests/recall-deferred.test.mjsnew file mode 100644index 000000000..49a10bb07--- /dev/null+++ b/examples/pi-experimental-context-management/tests/recall-deferred.test.mjs@@ -0,0 +1,89 @@+import test from "node:test";+import assert from "node:assert/strict";+import { RecallManager } from "../recall.ts";++function config(overrides = {}) {+ return {+ minQueryLength: 3,+ recallLimit: 6,+ recallMaxContentChars: 500,+ recallTokenBudget: 2000,+ scoreThreshold: 0.35,+ peerId: "",+ ...overrides,+ };+}++test("queued recall waits for the context phase and still injects current-query memory", async () => {+ const calls = [];+ const client = {+ fetchJSON: async (path, init) => {+ calls.push({ path, init });+ return {+ ok: true,+ result: { rendered: "- current prompt memory" },+ };+ },+ };+ const recall = new RecallManager(client, config());++ recall.queueSearch("current prompt");+ assert.equal(calls.length, 0, "queueing in before_agent_start must not perform I/O");++ await recall.searchPending();+ assert.equal(calls.length, 1);+ assert.equal(calls[0].path, "/api/v1/search/search");+ assert.equal(JSON.parse(calls[0].init.body).mode, "context");++ const messages = [{ role: "user", content: "current prompt" }];+ const injected = recall.injectRecall(messages);+ assert.match(injected[0].content, /current prompt memory/);+ assert.match(injected[0].content, /current prompt$/);++ await recall.searchPending();+ assert.equal(calls.length, 1, "later context iterations must reuse the cached recall");+});++test("recall sends the OV session id so dedup and expansion engage", async () => {+ const bodies = [];+ const client = {+ fetchJSON: async (path, init) => {+ bodies.push(JSON.parse(init.body));+ return { ok: true, result: { rendered: "- memory" } };+ },+ };+ // The sync manager owns the id and is constructed after the recall manager,+ // so it arrives as a getter and is null until a session has been opened.+ let sessionId = null;+ const recall = new RecallManager(client, config({ recallDedupTurns: 5 }), () => sessionId);++ recall.queueSearch("first prompt");+ await recall.searchPending();+ assert.equal(bodies[0].session_id, undefined);++ sessionId = "pi-session-1";+ recall.queueSearch("second prompt");+ await recall.searchPending();+ assert.equal(bodies[1].session_id, "pi-session-1");+ assert.equal(bodies[1].dedup_turns, 5);+});++test("a queued short prompt clears the previous recall block", async () => {+ const client = {+ fetchJSON: async () => ({+ ok: true,+ result: { rendered: "- stale memory" },+ }),+ };+ const recall = new RecallManager(client, config());++ recall.queueSearch("long enough prompt");+ await recall.searchPending();++ recall.queueSearch("x");+ await recall.searchPending();++ const messages = [{ role: "user", content: "x" }];+ assert.deepEqual(recall.injectRecall(messages), messages);+ assert.equal(messages[0].content, "x");+});diff --git a/examples/pi-experimental-context-management/tests/sync-barrier.test.mjs b/examples/pi-experimental-context-management/tests/sync-barrier.test.mjsnew file mode 100644index 000000000..e48a6b0a7--- /dev/null+++ b/examples/pi-experimental-context-management/tests/sync-barrier.test.mjs@@ -0,0 +1,381 @@+import test from "node:test";+import assert from "node:assert/strict";+import { mkdtemp, readFile, rm } from "node:fs/promises";+import { join } from "node:path";+import { tmpdir } from "node:os";+import { SyncManager } from "../sync.ts";+import { enqueue, listPending } from "../shared/pending-queue.mjs";++function config(overrides = {}) {+ return {+ commitKeepRecentCount: 10,+ captureAssistantTurns: true,+ captureToolMaxChars: 2000,+ captureMaxLength: 24000,+ ...overrides,+ };+}++function client(overrides = {}) {+ return {+ connected: true,+ addMessagePayload: async () => true,+ getSession: async () => ({ pending_tokens: 0 }),+ commitSession: async () => ({ task_id: "t-1", archive_uri: "viking://archive/1" }),+ commitSessionResponse: async () => ({+ result: { task_id: "t-1", archive_uri: "viking://archive/1" },+ }),+ fetchJSON: async () => ({ ok: true, result: {} }),+ ...overrides,+ };+}++async function withPendingDir(fn) {+ const previous = process.env.OPENVIKING_PENDING_DIR;+ const dir = await mkdtemp(join(tmpdir(), "ov-pi-pending-"));+ process.env.OPENVIKING_PENDING_DIR = dir;+ try {+ return await fn(dir);+ } finally {+ if (previous === undefined) delete process.env.OPENVIKING_PENDING_DIR;+ else process.env.OPENVIKING_PENDING_DIR = previous;+ await rm(dir, { recursive: true, force: true });+ }+}++test("syncBranch returns added token accounting and delivered status", async () => {+ await withPendingDir(async () => {+ const c = client();+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");++ const result = await sync.syncBranch([+ { type: "message", message: { role: "user", content: "Remember this implementation decision for the next run." } },+ ]);++ assert.equal(result.added, 1);+ assert.ok(result.tokens > 0);+ assert.equal(result.allDelivered, true);+ assert.equal(sync.syncedCount, 1);+ });+});++async function readLastRecord(path) {+ const lines = (await readFile(path, "utf8")).trim().split("\n");+ return JSON.parse(lines[lines.length - 1]);+}++test("commit writes success trace_id to the pi debug log", async () => {+ await withPendingDir(async (dir) => {+ const debugLogPath = join(dir, "pi-debug.log");+ const c = client({+ commitSessionResponse: async () => ({+ result: {+ task_id: "t-trace",+ archive_uri: "viking://archive/trace",+ trace_id: "trace-pi-commit",+ },+ traceId: "trace-pi-commit",+ }),+ });+ const sync = new SyncManager(c, config({ debugLogPath }));+ await sync.ensureSession("pi-trace-session");++ const result = await sync.commit();+ assert.equal(result.trace_id, "trace-pi-commit");+ const record = await readLastRecord(debugLogPath);+ assert.equal(record.hook, "pi");+ assert.equal(record.stage, "commit");+ assert.equal(record.data.ok, true);+ assert.equal(record.data.trace_id, "trace-pi-commit");+ });+});++test("commit writes failure trace_id to the pi debug log", async () => {+ await withPendingDir(async (dir) => {+ const debugLogPath = join(dir, "pi-debug-error.log");+ const c = client({+ commitSessionResponse: async () => ({+ result: null,+ status: 500,+ traceId: "trace-pi-error",+ error: { message: "commit failed" },+ }),+ });+ const sync = new SyncManager(c, config({ debugLogPath }));+ await sync.ensureSession("pi-trace-error");++ assert.equal(await sync.commit({ queueOnFailure: false }), null);+ const record = await readLastRecord(debugLogPath);+ assert.equal(record.stage, "commit");+ assert.equal(record.data.ok, false);+ assert.equal(record.data.trace_id, "trace-pi-error");+ assert.equal(record.data.error, "commit failed");+ });+});++test("queued addMessage keeps the flush barrier closed until replay succeeds", async () => {+ await withPendingDir(async () => {+ let replayOk = false;+ const c = client({+ addMessagePayload: async () => false,+ fetchJSON: async () => ({ ok: replayOk, status: replayOk ? 200 : 500, result: {} }),+ });+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");++ const result = await sync.syncBranch([+ { type: "message", message: { role: "user", content: "This should be queued for flush barrier testing." } },+ ]);++ assert.equal(result.added, 1);+ assert.equal(result.allDelivered, false);+ assert.equal((await listPending()).length, 1);+ assert.equal(await sync.flushBarrier(), false);++ replayOk = true;+ assert.equal(await sync.flushBarrier(), true);+ assert.equal((await listPending()).length, 0);+ });+});++test("current-session addMessage 500 remains queued and keeps barrier closed", async () => {+ await withPendingDir(async () => {+ const c = client({+ addMessagePayload: async () => false,+ fetchJSON: async () => ({ ok: false, status: 500 }),+ });+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");++ await sync.addPayload({ role: "user", content: "Queued content with retryable server failure." });++ assert.equal(await sync.flushBarrier(), false);+ const pending = await listPending();+ assert.equal(pending.length, 1);+ assert.equal(pending[0].entry.type, "addMessage");+ assert.equal(pending[0].entry.sessionId, sync.sessionId);+ });+});++test("other-session addMessage and commit queue entries do not block the barrier", async () => {+ await withPendingDir(async () => {+ const c = client({+ fetchJSON: async () => ({ ok: false, status: 500 }),+ });+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");++ await enqueue("addMessage", "different-session", { role: "user", content: "other" });+ await enqueue("commitSession", sync.sessionId, { keep_recent_count: 1 });++ assert.equal(await sync.flushBarrier(), true);+ });+});++test("restoreWatermark prevents pi -c from re-syncing already captured entries", async () => {+ await withPendingDir(async () => {+ const calls = [];+ const c = client({+ fetchJSON: async (_path, init) => {+ calls.push(...JSON.parse(init.body).messages);+ return { ok: true, result: {} };+ },+ });+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");+ sync.restoreWatermark(1);++ const result = await sync.syncBranch([+ { type: "message", message: { role: "user", content: "Already captured entry should be skipped." } },+ { type: "message", message: { role: "user", content: "Fresh entry should be captured now." } },+ ]);++ assert.equal(result.added, 1);+ assert.equal(calls.length, 1);+ assert.match(calls[0].parts[0].text, /Fresh entry/);+ });+});++function batchClient(overrides = {}) {+ const calls = [];+ const c = client({+ fetchJSON: async (path, init) => {+ calls.push({ path: String(path), body: init?.body ? JSON.parse(init.body) : null });+ return overrides.respond ? overrides.respond(calls.length, path) : { ok: true, result: {} };+ },+ });+ return { c, calls };+}++test("syncBranch sends the whole turn in one batch request", async () => {+ await withPendingDir(async () => {+ const { c, calls } = batchClient();+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");++ const result = await sync.syncBranch([+ { type: "message", message: { role: "user", content: "First user message for the batch write test." } },+ { type: "message", message: { role: "assistant", content: "Assistant reply for the batch write test." } },+ { type: "message", message: { role: "user", content: "Second user message for the batch write test." } },+ ]);++ assert.equal(result.added, 3);+ assert.equal(result.allDelivered, true);+ assert.equal(calls.length, 1);+ assert.match(calls[0].path, /\/messages\/batch$/);+ assert.equal(calls[0].body.messages.length, 3);+ });+});++test("the barrier drains a large backlog through the batch endpoint", async () => {+ await withPendingDir(async () => {+ const { c, calls } = batchClient();+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");+ const t0 = Date.now();+ for (let i = 0; i < 250; i++) {+ await enqueue("addMessage", sync.sessionId, { role: "user", content: `m${i}` }, { createdAt: t0 + i });+ }+ await enqueue("addMessage", "other-session", { role: "user", content: "other" }, { createdAt: t0 + 999 });++ assert.equal(await sync.flushBarrier(), true);+ assert.deepEqual(calls.map((call) => call.body.messages.length), [100, 100, 50]);+ // Order preserved across batches.+ assert.equal(calls[0].body.messages[0].content, "m0");+ assert.equal(calls[2].body.messages[49].content, "m249");+ const left = await listPending();+ assert.equal(left.length, 1);+ assert.equal(left[0].entry.sessionId, "other-session");+ });+});++test("failed batch keeps its entries queued with one retry and leaves the rest untouched", async () => {+ await withPendingDir(async () => {+ const { c, calls } = batchClient({ respond: () => ({ ok: false, status: 500 }) });+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");+ const t0 = Date.now();+ for (let i = 0; i < 120; i++) {+ await enqueue("addMessage", sync.sessionId, { role: "user", content: `m${i}` }, { createdAt: t0 + i });+ }++ assert.equal(await sync.flushBarrier(), false);+ assert.equal(calls.length, 1);+ const retries = (await listPending()).map((p) => p.entry.retries);+ assert.equal(retries.length, 120);+ assert.equal(retries.filter((r) => r === 1).length, 100);+ assert.equal(retries.filter((r) => r === 0).length, 20);+ });+});++test("non-retryable batch failure drops the payloads but still advances the sync watermark", async () => {+ await withPendingDir(async () => {+ const { c, calls } = batchClient({ respond: () => ({ ok: false, status: 400, error: { message: "bad" } }) });+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");++ const result = await sync.syncBranch([+ { type: "message", message: { role: "user", content: "Poison payload one for watermark test." } },+ { type: "message", message: { role: "user", content: "Poison payload two for watermark test." } },+ ]);++ assert.equal(result.added, 2);+ assert.equal(result.allDelivered, false);+ assert.equal(sync.syncedCount, 2);+ assert.equal(calls.length, 1);+ assert.equal((await listPending()).length, 0);+ });+});++test("drainSessionBacklog stops after maxBatches and leaves remainder for later turns", async () => {+ await withPendingDir(async () => {+ const previous = process.env.OPENVIKING_PENDING_DRAIN_MAX_BATCHES;+ process.env.OPENVIKING_PENDING_DRAIN_MAX_BATCHES = "1";+ try {+ const { c, calls } = batchClient();+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");+ const t0 = Date.now();+ for (let i = 0; i < 250; i++) {+ await enqueue("addMessage", sync.sessionId, { role: "user", content: `m${i}` }, { createdAt: t0 + i });+ }++ assert.equal(await sync.flushBarrier(), false);+ assert.equal(calls.length, 1);+ assert.equal(calls[0].body.messages.length, 100);+ assert.equal((await listPending()).length, 150);+ } finally {+ if (previous === undefined) delete process.env.OPENVIKING_PENDING_DRAIN_MAX_BATCHES;+ else process.env.OPENVIKING_PENDING_DRAIN_MAX_BATCHES = previous;+ }+ });+});++test("flushBarrier budgetMs caps the drain so a reset cannot hang on it", async () => {+ await withPendingDir(async () => {+ const { c, calls } = batchClient();+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");+ const t0 = Date.now();+ for (let i = 0; i < 10; i++) {+ await enqueue("addMessage", sync.sessionId, { role: "user", content: `m${i}` }, { createdAt: t0 + i });+ }++ // A zero budget is spent before the first batch, so nothing is sent and+ // the barrier reports closed instead of blocking.+ assert.equal(await sync.flushBarrier({ budgetMs: 0 }), false);+ assert.equal(calls.length, 0);+ assert.equal((await listPending()).length, 10);++ // Without the cap the same backlog drains and the barrier opens.+ assert.equal(await sync.flushBarrier(), true);+ assert.equal(calls.length, 1);+ assert.equal((await listPending()).length, 0);+ });+});++test("flushBarrier still honours OPENVIKING_PENDING_DRAIN_BUDGET_MS as the fallback", async () => {+ await withPendingDir(async () => {+ const previous = process.env.OPENVIKING_PENDING_DRAIN_BUDGET_MS;+ process.env.OPENVIKING_PENDING_DRAIN_BUDGET_MS = "0";+ try {+ const { c, calls } = batchClient();+ const sync = new SyncManager(c, config());+ await sync.ensureSession("pi-session");+ await enqueue("addMessage", sync.sessionId, { role: "user", content: "m0" });++ assert.equal(await sync.flushBarrier(), false);+ assert.equal(calls.length, 0);+ } finally {+ if (previous === undefined) delete process.env.OPENVIKING_PENDING_DRAIN_BUDGET_MS;+ else process.env.OPENVIKING_PENDING_DRAIN_BUDGET_MS = previous;+ }+ });+});++test("syncBranch never auto-commits: archive boundaries belong to the reset path", async () => {+ await withPendingDir(async () => {+ let commits = 0;+ const c = client({+ getSession: async () => ({ pending_tokens: 10_000_000 }),+ commitSessionResponse: async () => {+ commits++;+ return { result: { task_id: "t-1", archive_uri: "viking://archive/1" } };+ },+ });+ // `commitTokenThreshold` is deliberately not an OVConfig key any more, so+ // it goes in as an unknown extra: the guard is that a config still carrying+ // the old auto-commit threshold — and a server reporting ten million+ // pending tokens — makes syncBranch commit exactly nothing.+ const sync = new SyncManager(c, { ...config(), commitTokenThreshold: 1 });+ await sync.ensureSession("pi-session");++ await sync.syncBranch([+ { type: "message", message: { role: "user", content: "A turn well past the old commit threshold." } },+ ]);++ assert.equal(commits, 0);+ assert.equal(typeof sync.commitIfNeeded, "undefined");+ });+});diff --git a/examples/pi-experimental-context-management/tests/text-budget.test.mjs b/examples/pi-experimental-context-management/tests/text-budget.test.mjsnew file mode 100644index 000000000..d1a12f910--- /dev/null+++ b/examples/pi-experimental-context-management/tests/text-budget.test.mjs@@ -0,0 +1,80 @@+import test from "node:test";+import assert from "node:assert/strict";+import {+ CONTEXT_BLOCK_MARKER,+ countUserTurns,+ estimatePayloadTokens,+ estimateTokens,+ fingerprintMessage,+ flattenContent,+ isUserTurnStart,+ truncateToTokens,+} from "../lib/text-budget.mjs";++function msg(role, content) {+ return { role, content };+}++const user = (text) => msg("user", text);+const assistant = (text) => msg("assistant", text);++test("flattenContent handles strings and text arrays", () => {+ assert.equal(flattenContent(user("hello")), "hello");+ assert.equal(+ flattenContent(user([{ type: "text", text: "a" }, { type: "image" }, { type: "text", text: "b" }])),+ "ab",+ );+ assert.equal(flattenContent(user(null)), "");+ assert.equal(flattenContent(null), "");+});++test("fingerprintMessage includes role length and 200-char prefix", () => {+ const fp = fingerprintMessage(user("x".repeat(250)));+ assert.equal(fp, `user:250:${"x".repeat(200)}`);+ assert.notEqual(fingerprintMessage(user("same")), fingerprintMessage(assistant("same")));+});++test("user turn helpers ignore messages this extension injected", () => {+ const messages = [+ user("first"),+ assistant("answer"),+ user(`${CONTEXT_BLOCK_MARKER} source="context-window">…`),+ user("second"),+ ];+ assert.equal(isUserTurnStart(messages[0]), true);+ assert.equal(isUserTurnStart(messages[1]), false);+ assert.equal(isUserTurnStart(messages[2]), false);+ assert.equal(countUserTurns(messages), 2);+});++test("estimateTokens and truncateToTokens handle CJK conservatively", () => {+ assert.equal(estimateTokens(""), 0);+ assert.equal(estimateTokens("a".repeat(100)), 25);+ assert.equal(estimateTokens("界".repeat(10)), 15);+ assert.equal(estimateTokens("界界" + "a".repeat(8)), 5);+ assert.equal(truncateToTokens("hello", 100), "hello");+ assert.equal(truncateToTokens("hello", 0), "");+ const truncated = truncateToTokens("界".repeat(9000), 3000);+ assert.ok(estimateTokens(truncated) <= 3000);+ assert.ok(truncated.length < 2500);+});++test("truncateToTokens returns the longest prefix inside the budget", () => {+ const text = "a".repeat(400);+ const cut = truncateToTokens(text, 10);+ assert.equal(cut.length, 40);+ assert.equal(estimateTokens(cut), 10);+ assert.equal(estimateTokens(text.slice(0, cut.length + 1)), 11);+});++test("estimatePayloadTokens counts content and structured parts", () => {+ assert.equal(estimatePayloadTokens({ content: "a".repeat(40) }), 10);+ assert.equal(estimatePayloadTokens(null), 0);+ const withParts = estimatePayloadTokens({+ parts: [+ { type: "text", text: "a".repeat(40) },+ { type: "tool", tool_name: "read", tool_input: { path: "file" }, tool_status: "running" },+ ],+ });+ assert.ok(withParts > 10);+});diff --git a/examples/pi-experimental-context-management/tests/uri-guard.test.mjs b/examples/pi-experimental-context-management/tests/uri-guard.test.mjsnew file mode 100644index 000000000..0338dcc5f--- /dev/null+++ b/examples/pi-experimental-context-management/tests/uri-guard.test.mjs@@ -0,0 +1,31 @@+import test from "node:test"+import assert from "node:assert/strict"+import { guardVikingUriToolCall } from "../lib/uri-guard-adapter.mjs"++test("pi URI guard blocks builtin file tools on viking URIs", () => {+ const decision = guardVikingUriToolCall({+ type: "tool_call",+ toolName: "read",+ input: { path: "viking://resources/project/file.md" },+ })++ assert.equal(decision?.block, true)+ assert.match(decision?.reason ?? "", /viking:\/\/ URIs are OpenViking virtual paths/)+ assert.match(decision?.reason ?? "", /Use viking_read instead/)+})++test("pi URI guard blocks bash commands containing viking URI", () => {+ const decision = guardVikingUriToolCall({+ type: "tool_call",+ toolName: "bash",+ input: { command: "cat viking://resources/project/file.md" },+ })++ assert.equal(decision?.block, true)+ assert.match(decision?.reason ?? "", /Use viking_read or viking_search instead/)+})++test("pi URI guard allows normal local paths and OpenViking native tools", () => {+ assert.equal(guardVikingUriToolCall({ toolName: "read", input: { path: "/tmp/file.md" } }), null)+ assert.equal(guardVikingUriToolCall({ toolName: "viking_read", input: { uri: "viking://resources/file.md" } }), null)+})diff --git a/examples/pi-experimental-context-management/tools.ts b/examples/pi-experimental-context-management/tools.tsnew file mode 100644index 000000000..c0a17e014--- /dev/null+++ b/examples/pi-experimental-context-management/tools.ts@@ -0,0 +1,671 @@+import { Type } from "typebox";+import { StringEnum } from "@earendil-works/pi-ai";+import type { OVClient, OVArchiveEntry, OVArchiveMessage } from "./client.js";+import type { OVConfig } from "./config.js";+import type { SyncManager } from "./sync.js";+import type { ContextWindowCore } from "./lib/context-window-core.mjs";+import { formatDuration, formatTokens } from "./lib/context-window-core.mjs";+import { readPiReserveTokens } from "./context-window.js";++export function registerTools(pi: any, client: OVClient, sync?: SyncManager): void {++ // --- viking_search ---+ pi.registerTool({+ name: "viking_search",+ label: "Viking Search",+ description: "Semantic search over the OpenViking knowledge base. Returns ranked results with viking:// URIs and abstracts. Use to recall past decisions, user preferences, or project-specific knowledge not in current context.",+ promptSnippet: "Search OpenViking for past decisions, preferences, and project knowledge",+ promptGuidelines: [+ "Use viking_search when you need information from previous sessions not in MEMORY.md.",+ "Use viking_search before making decisions that might conflict with past decisions.",+ ],+ parameters: Type.Object({+ query: Type.String({ description: "Search query" }),+ scope: Type.Optional(Type.String({+ // The server rejects the `viking://~` home alias with "Invalid scope '~'",+ // so the examples name the two forms it does accept.+ description:+ "Viking URI prefix to scope search, e.g. 'viking://user/<space>/memories/' " ++ "or 'viking://session/<session id>/'",+ })),+ limit: Type.Optional(Type.Number({ description: "Max results (default: 10)" })),+ }),+ async execute(+ _id: string, params: any, _signal: AbortSignal,+ _onUpdate: any, _ctx: any,+ ) {+ if (!client.connected) {+ return { content: [{ type: "text", text: "OpenViking server is not reachable." }] };+ }+ const results = await client.find(params.query, {+ targetUri: params.scope,+ topK: params.limit ?? 10,+ });+ if (results.length === 0) {+ return { content: [{ type: "text", text: "No results found." }] };+ }+ const maxChars = client.cfg.recallMaxContentChars;+ const lines = results.map(r => {+ const abs = r.abstract.length > maxChars+ ? r.abstract.slice(0, maxChars) + "..."+ : r.abstract;+ return `[${r.score.toFixed(2)}] ${r.uri}\n ${abs}`; }+ );+ return {+ content: [{ type: "text", text: lines.join("\n\n") }],+ details: { results },+ };+ },+ });++ // --- viking_read ---+ pi.registerTool({+ name: "viking_read",+ label: "Viking Read",+ description: "Read content at a viking:// URI. Three detail levels: 'abstract' (~100 tokens), 'overview' (~2k tokens), 'full' (complete). Start with abstract, escalate when needed.",+ promptSnippet: "Read OpenViking content at a viking:// URI with tiered detail levels",+ parameters: Type.Object({+ uri: Type.String({ description: "viking:// URI to read" }),+ level: StringEnum(["abstract", "overview", "full"] as const),+ }),+ async execute(+ _id: string, params: any, _signal: AbortSignal,+ _onUpdate: any, _ctx: any,+ ) {+ if (!client.connected) {+ return { content: [{ type: "text", text: "OpenViking server is not reachable." }] };+ }+ let content: string | null = null;+ switch (params.level) {+ case "abstract": content = await client.abstract(params.uri); break;+ case "overview": content = await client.overview(params.uri); break;+ case "full": content = await client.readContent(params.uri); break;+ }+ if (!content) {+ return { content: [{ type: "text", text: `No content at ${params.uri}` }] };+ }+ return { content: [{ type: "text", text: content }] };+ },+ });++ // --- viking_browse ---+ pi.registerTool({+ name: "viking_browse",+ label: "Viking Browse",+ description: "Browse the OpenViking knowledge store like a filesystem. List directory contents or get metadata.",+ promptSnippet: "Browse the viking:// directory tree in OpenViking",+ parameters: Type.Object({+ action: StringEnum(["list", "stat"] as const),+ uri: Type.Optional(Type.String({ description: "viking:// URI (default: 'viking://')" })),+ }),+ async execute(+ _id: string, params: any, _signal: AbortSignal,+ _onUpdate: any, _ctx: any,+ ) {+ if (!client.connected) {+ return { content: [{ type: "text", text: "OpenViking server is not reachable." }] };+ }+ const uri = params.uri ?? "viking://";+ if (params.action === "stat") {+ const info = await client.stat(uri);+ if (!info) return { content: [{ type: "text", text: `Not found: ${uri}` }] };+ return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };+ }+ // list+ const entries = await client.ls(uri);+ if (entries.length === 0) {+ return { content: [{ type: "text", text: `Empty directory: ${uri}` }] };+ }+ const lines = entries.map(e => `${e.isDir ? "📁" : "📄"} ${e.name}`);+ return { content: [{ type: "text", text: lines.join("\n") }] };+ },+ });++ // --- viking_remember ---+ pi.registerTool({+ name: "viking_remember",+ label: "Viking Remember",+ description: "Store a fact or memory in OpenViking. Stored as a session message and extracted into long-term memory on commit. Use for important information the agent should remember: preferences, decisions, gotchas, lessons learned.",+ promptSnippet: "Store a fact in OpenViking for cross-session persistence",+ promptGuidelines: [+ "Use viking_remember for facts that should survive across sessions but don't belong in MEMORY.md.",+ "Good for: user preferences, architectural decisions, gotchas, environment details.",+ ],+ parameters: Type.Object({+ content: Type.String({ description: "The fact or observation to store" }),+ category: Type.Optional(Type.String({ description: "Category hint: 'preference', 'entity', 'event', 'case', 'pattern'" })),+ }),+ async execute(+ _id: string, params: any, _signal: AbortSignal,+ _onUpdate: any, _ctx: any,+ ) {+ if (!client.connected) {+ return { content: [{ type: "text", text: "OpenViking server is not reachable." }] };+ }+ // Store as a tagged message directly in OV — the extractor picks up [Remember — ...] prefix+ const category = params.category ?? "general";+ const tagged = `[Remember — ${category}] ${params.content}`;++ // Directly add to OV session if available+ let stored = false;+ if (sync?.sessionId) {+ stored = await client.addMessage(sync.sessionId, "user", tagged);+ }++ return {+ content: [{+ type: "text",+ text: stored+ ? `Remembered in OpenViking: "${params.content}" (${category})`+ : `Not stored: OpenViking did not accept the message and nothing was queued. ` ++ `Repeat "${params.content}" in your next handoff notes if it matters.`,+ }],+ details: { stored, category, tagged },+ };+ },+ });++ // --- viking_forget ---+ pi.registerTool({+ name: "viking_forget",+ label: "Viking Forget",+ description: "Delete a memory by URI, or search for a specific memory and remove it. Use to correct outdated or wrong information.",+ promptSnippet: "Delete a memory from OpenViking by URI or query",+ parameters: Type.Object({+ uri: Type.Optional(Type.String({ description: "Exact viking:// URI to delete" })),+ query: Type.Optional(Type.String({ description: "Search query — deletes the strongest match if score > 0.8" })),+ }),+ async execute(+ _id: string, params: any, _signal: AbortSignal,+ _onUpdate: any, _ctx: any,+ ) {+ if (!client.connected) {+ return { content: [{ type: "text", text: "OpenViking server is not reachable." }] };+ }+ if (params.uri) {+ const ok = await client.delete(params.uri);+ return {+ content: [{ type: "text", text: ok ? `Deleted: ${params.uri}` : `Failed to delete: ${params.uri}` }],+ };+ }+ if (params.query) {+ const results = await client.find(params.query, { topK: 1 });+ if (results.length > 0 && results[0].score > 0.8) {+ const ok = await client.delete(results[0].uri);+ return {+ content: [{ type: "text", text: ok ? `Deleted: ${results[0].uri}` : `Failed: ${results[0].uri}` }],+ };+ }+ return { content: [{ type: "text", text: "No strong match found (score > 0.8 required)." }] };+ }+ return { content: [{ type: "text", text: "Provide either 'uri' or 'query'." }] };+ },+ });++ // --- viking_add_resource ---+ pi.registerTool({+ name: "viking_add_resource",+ label: "Viking Add Resource",+ description: "Ingest a URL into OpenViking. The page is auto-processed into L0/L1/L2 tiers and indexed for semantic search. HTTP only — local file paths are not supported by the OV server.",+ promptSnippet: "Ingest a URL into OpenViking for indexed retrieval",+ parameters: Type.Object({+ url: Type.String({ description: "URL to ingest (HTTP only, no file paths)" }),+ }),+ async execute(+ _id: string, params: any, _signal: AbortSignal,+ _onUpdate: any, _ctx: any,+ ) {+ if (!client.connected) {+ return { content: [{ type: "text", text: "OpenViking server is not reachable." }] };+ }+ const result = await client.addResource(params.url);+ if (!result) {+ return { content: [{ type: "text", text: `Failed to ingest: ${params.url}` }] };+ }+ return {+ content: [{ type: "text", text: `Ingested: ${result.root_uri}` }],+ details: result,+ };+ },+ });+}++// ================================================================+// Context window tools (Codex bare names: new_context / history /+// get_context_remaining — plan §4)+// ================================================================++const NOT_REACHABLE = "OpenViking server is not reachable.";+const NO_SESSION = "No OpenViking session is attached to this pi session yet.";++/** Options the extension passes through so the tools stay free of pi state. */+export interface ContextWindowToolOptions {+ /**+ * The message list the `context` hook last handed to the provider — the only+ * list that reflects the current window. Without it `get_context_remaining`+ * still works, it just cannot report "time since your previous message".+ */+ getMessages?: () => any[] | undefined;+ /** pi's `compaction.reserveTokens`; read from pi's settings when omitted. */+ reserveTokens?: number;+}++function text(body: string, details?: any) {+ return { content: [{ type: "text", text: body }], details: details ?? {}, isError: false };+}++/** Truncate to `max` characters, saying so instead of trailing off silently. */+function clip(raw: string, max: number): string {+ const value = String(raw ?? "");+ if (max <= 0 || value.length <= max) return value;+ return `${value.slice(0, max)}… [truncated, ${value.length - max} more characters]`;+}++function firstLine(raw: string): string {+ const line = String(raw ?? "").split("\n").find((l) => l.trim());+ return line ? line.trim() : "";+}++/** Archives oldest first, so index 0 is the oldest window of the session. */+function orderedArchives(archives: OVArchiveEntry[]): OVArchiveEntry[] {+ return [...archives].reverse();+}++/**+ * Window id per archive.+ *+ * The core records `{windowId, archiveId}` for every archive it writes, so a+ * window that closed *without* producing one (an external compaction advances+ * the index but writes nothing) cannot shift every later id. Positional+ * numbering is only the fallback for an archive the core does not know — one+ * written before the persisted state existed, or by another process.+ */+function windowIdsFor(+ ordered: OVArchiveEntry[],+ recorded: Array<{ windowId: string; archiveId: string }>,+): string[] {+ const known = new Map<string, string>();+ for (const row of Array.isArray(recorded) ? recorded : []) {+ if (row?.archiveId && row?.windowId) known.set(String(row.archiveId), String(row.windowId));+ }+ return ordered.map((entry, i) => known.get(entry.archiveId) ?? `w${i + 1}`);+}++/**+ * `"w2"`, `"2"` or `"archive_002"` → the archive it names, resolved through the+ * recorded window ids.+ */+function resolveArchive(+ spec: string,+ ordered: OVArchiveEntry[],+ windowIds: string[],+): { entry: OVArchiveEntry; windowId: string } | null {+ const raw = String(spec ?? "").trim();+ if (!raw) return null;+ const byWindow = /^w(\d+)$/i.exec(raw) || /^(\d+)$/.exec(raw);+ if (byWindow) {+ const wanted = `w${Number(byWindow[1])}`;+ const idx = windowIds.indexOf(wanted);+ if (idx < 0) return null;+ return { entry: ordered[idx], windowId: windowIds[idx] };+ }+ const idx = ordered.findIndex((a) => a.archiveId === raw);+ if (idx < 0) return null;+ return { entry: ordered[idx], windowId: windowIds[idx] };+}++/** `"w2:14"` or a bare `"14"` when `window` carries the archive. */+function parseItemRef(item: string, windowSpec?: string): { windowSpec: string; index: number } | null {+ const raw = String(item ?? "").trim();+ if (!raw) return null;+ const parts = raw.split(":");+ if (parts.length === 2) {+ const index = Number(parts[1]);+ if (!Number.isInteger(index) || index < 0) return null;+ return { windowSpec: parts[0].trim(), index };+ }+ const index = Number(raw);+ if (!Number.isInteger(index) || index < 0) return null;+ const spec = String(windowSpec ?? "").trim();+ if (!spec) return null;+ return { windowSpec: spec, index };+}++function renderItemLine(windowId: string, index: number, msg: OVArchiveMessage): string {+ const when = msg.created_at ? ` ${msg.created_at}` : "";+ return `[id: ${windowId}:${index}] ${msg.role || "unknown"}${when} ${clip(oneLine(msg.text), 200)}`;+}++function oneLine(raw: string): string {+ return String(raw ?? "").replace(/\s+/g, " ").trim();+}++/** `get_context_remaining` body — plan §4, derived only from the snapshot. */+function renderStatusReport(snap: any): string {+ const lines: string[] = [];+ lines.push(+ `tokens_left: ${snap.tokensLeft === null ? "unknown (the provider did not report a window size)" : formatTokens(snap.tokensLeft)}`,+ );+ lines.push(+ `used: ~${formatTokens(snap.usedTokens)}` ++ (snap.contextWindow > 0 ? ` / ${formatTokens(snap.contextWindow)} (${snap.percent}%)` : ""),+ );+ lines.push(+ `window: ${snap.windowId}` ++ (snap.windowAgeMs === null ? " (first window of this session)" : `, opened ${formatDuration(snap.windowAgeMs)} ago`),+ );+ lines.push(`turns in this window: ${snap.turnsInWindow}`);+ lines.push(+ `since the user's last message: ${snap.sinceLastUserMs === null ? "unknown" : formatDuration(snap.sinceLastUserMs)}`,+ );+ lines.push(+ `gap before that message: ${snap.idleGapMs === null ? "unknown" : formatDuration(snap.idleGapMs)}`,+ );+ // The recorded archives, not `windowId - 1`: a window closed by an external+ // compaction advances the index without producing an archive.+ const archives = Math.max(0, Number(snap.archiveCount) || 0);+ lines.push(+ `archives: ${archives}` ++ (snap.archiveId+ ? ` (latest ${snap.archiveId}, Working Memory ${snap.overviewReady ? "ready" : "not ready"})`+ : ""),+ );+ if (Number(snap.undeliveredCount) > 0) {+ lines.push(+ `missing from the archives: ${snap.undeliveredCount} message(s) OpenViking rejected; history cannot show them`,+ );+ }+ lines.push(`accuracy: ${snap.estimated ? "estimated" : "exact"}`);+ lines.push(`advice: ${snap.advice}`);+ return lines.join("\n");+}++export function registerContextWindowTools(+ pi: any,+ client: OVClient,+ sync: SyncManager,+ windows: ContextWindowCore,+ config: OVConfig,+ opts: ContextWindowToolOptions = {},+): void {+ const reserveTokens = () =>+ typeof opts.reserveTokens === "number" ? opts.reserveTokens : readPiReserveTokens(process.cwd());++ // --- new_context ---+ pi.registerTool({+ name: "new_context",+ label: "New Context Window",+ description:+ "Start a new context window. Does not clear, reset, or otherwise affect environment state. " ++ "The conversation so far is archived to OpenViking (which generates a Working Memory of it) and " ++ "your next window starts with that Working Memory, your handoff notes and the user's last request. " ++ "Call it alone — tool results from the same batch are discarded with the old window — and read the " ++ '<openviking-context source="context-window"> block that follows. If instead this result says ' ++ '"Context window NOT reset", nothing was archived and nothing was removed from your context: read ' ++ "the reason, keep working in the current window, and do not call new_context again until that reason is gone.",+ promptSnippet: "Archive this context window to OpenViking and continue in a fresh one",+ promptGuidelines: [+ "Call new_context when a phase of the work is finished and its details are no longer needed, when the user switches to an unrelated topic or code area, when they come back after a long idle gap with something new, or when the context status line or a [context-reminder] says the window is filling up.",+ 'A result starting with "Context window NOT reset" means nothing changed: no archive was written and your context is intact. Keep working; do not retry the call until the stated cause is gone.',+ "Write the handoff notes before you call it: goal, decisions and why, what is done, what is in flight, exact paths and identifiers, and the next steps. Write them for someone who has not seen this conversation.",+ "Do not call new_context in the middle of an unverified edit sequence, right after a previous reset, or to avoid a problem you have not solved.",+ "Call it alone, not alongside other tool calls: the results of the others are discarded together with the old window.",+ ],+ executionMode: "sequential",+ parameters: Type.Object({+ reason: Type.String({+ description: "One sentence: why this context window should end now.",+ }),+ notes: Type.String({+ description:+ "Handoff notes for the next window: goal, decisions and why, what is done, what is in flight, " ++ "exact paths and identifiers, next steps. Written for someone who has not seen this conversation.",+ }),+ next_steps: Type.Optional(+ Type.Array(Type.String(), { description: "Ordered next steps for the new window." }),+ ),+ }),+ async execute(+ toolCallId: string, params: any, signal: AbortSignal,+ onUpdate: any, ctx: any,+ ) {+ const result = await windows.requestReset({+ reason: params?.reason,+ notes: params?.notes,+ nextSteps: params?.next_steps,+ toolCallId,+ branch: ctx?.sessionManager?.getBranch?.() ?? [],+ signal,+ onProgress: (message: string) => {+ try {+ onUpdate?.({ content: [{ type: "text", text: message }], details: {} });+ } catch {+ // progress reporting must never break the reset+ }+ },+ });+ // Never `terminate`: a refusal has to leave the agent running, and a+ // successful reset is consumed by the context hook of the next sampling.+ return { content: [{ type: "text", text: result.text }], details: result.details, isError: false };+ },+ });++ // --- history ---+ pi.registerTool({+ name: "history",+ label: "Context History",+ description:+ "Read the context windows of this session that were already archived to OpenViking. " ++ "list_windows lists them, list_items lists the messages of one window, read_item reads one message " ++ "in full, and search_contents greps every archive. Window ids are the ones in the window header, " ++ "oldest first; the numbering can have gaps, because a window that ended without being archived is " ++ 'not listed here. Item ids look like "w2:14" and come from list_items.',+ promptSnippet: "Read messages and tool output from earlier, already archived context windows",+ promptGuidelines: [+ "Use history when the window header or your notes do not cover a detail from an earlier window; start from search_contents or list_items rather than reading whole windows back in.",+ "Do not ask the user to repeat something that is in an archived window — look it up here first.",+ ],+ parameters: Type.Object({+ action: StringEnum(["list_windows", "list_items", "read_item", "search_contents"] as const),+ window: Type.Optional(Type.String({ description: 'Window or archive id, e.g. "w2" or "archive_002".' })),+ item: Type.Optional(Type.String({ description: 'Item id, e.g. "w2:14", or "14" together with `window`.' })),+ query: Type.Optional(Type.String({ description: "search_contents: text or regular expression to look for." })),+ offset: Type.Optional(Type.Number({ description: "list_items: first item index to show (default 0)." })),+ limit: Type.Optional(Type.Number({ description: "list_items: how many items to show (default 40)." })),+ }),+ async execute(+ _id: string, params: any, _signal: AbortSignal,+ _onUpdate: any, _ctx: any,+ ) {+ if (!client.connected) return text(NOT_REACHABLE);+ const sid = sync?.sessionId;+ if (!sid) return text(NO_SESSION);++ const archives = await client.listSessionArchives(sid);+ if (archives === null) {+ return text(+ "OpenViking did not answer the archive listing, so the archived windows are unreadable right now. " ++ "This is not the same as an empty history — do not conclude that nothing was archived, and do not " ++ "ask the user to repeat what an archived window holds. Try again later or work from the window header.",+ { error: "listing-failed" },+ );+ }+ const ordered = orderedArchives(archives);+ const windowIds = windowIdsFor(ordered, windows.archives ?? []);+ // The window the model is in right now: its own counter, which also+ // covers windows that closed without producing an archive.+ const currentWindowId = windows.windowId;++ switch (params?.action) {+ case "list_windows": {+ const lines = ordered.map((entry, i) => {+ const when = entry.modTime || "unknown time";+ const abstract = firstLine(entry.abstract) || "(Working Memory not ready)";+ return `${windowIds[i]} ${entry.archiveId} ${when} ${clip(abstract, 200)}`;+ });+ lines.push(`${currentWindowId} (current) this window is still open and not archived`);+ // With nothing archived the only id in the list is the open window,+ // which `list_items` cannot read — pointing at it would just buy a+ // refusal and suggest the current window is readable through history.+ const trailer =+ windowIds.length > 0+ ? `Read one with history {"action":"list_items","window":"${windowIds[0]}"}.`+ : "Nothing is archived yet: everything this session has said is still in front of you, " ++ "and the current window becomes readable here only after new_context archives it.";+ return text(+ [+ `${ordered.length} archived window${ordered.length === 1 ? "" : "s"} in this session:`,+ ...lines,+ "",+ trailer,+ ].join("\n"),+ { archives: ordered, windowIds, currentWindowId },+ );+ }++ case "list_items": {+ const target = resolveArchive(params?.window, ordered, windowIds);+ if (!target) {+ return text(+ `No archived window named "${String(params?.window ?? "")}". ` ++ `Known: ${windowIds.join(", ") || "none"} (${currentWindowId} is current and not archived yet).`,+ );+ }+ const items = await client.readArchiveMessages(target.entry.uri);+ if (!items) {+ return text(+ `${target.windowId} (${target.entry.archiveId}): its messages could not be read from OpenViking right now ` ++ `(the archive itself is readable as soon as it is committed, so this is a transport, permission or ` ++ `routing failure rather than a wait). Try {"action":"search_contents"} instead, or continue from the ` ++ `window header; do not repeat this call more than once.`,+ );+ }+ const offsetRaw = Number(params?.offset);+ const offset = Number.isInteger(offsetRaw) && offsetRaw > 0 ? offsetRaw : 0;+ const limitRaw = Number(params?.limit);+ const limit = Number.isInteger(limitRaw) && limitRaw > 0 ? Math.min(limitRaw, 200) : 40;+ const slice = items.slice(offset, offset + limit);+ const lines = slice.map((msg, i) => renderItemLine(target.windowId, offset + i, msg));+ const end = offset + slice.length;+ const trailer =+ end < items.length+ ? `Showing ${offset}-${end - 1} of ${items.length} items. Next: {"action":"list_items","window":"${target.windowId}","offset":${end}}.`+ : `Showing ${offset}-${Math.max(offset, end - 1)} of ${items.length} items (end of window).`;+ return text(+ [+ `${target.windowId} (${target.entry.archiveId}), ${items.length} items:`,+ ...lines,+ "",+ trailer,+ `Read one in full with {"action":"read_item","item":"${target.windowId}:${offset}"}.`,+ ].join("\n"),+ { windowId: target.windowId, archiveId: target.entry.archiveId, total: items.length, offset, limit },+ );+ }++ case "read_item": {+ const ref = parseItemRef(params?.item, params?.window);+ if (!ref) return text('Provide an item id, e.g. {"action":"read_item","item":"w2:14"}.');+ const target = resolveArchive(ref.windowSpec, ordered, windowIds);+ if (!target) {+ return text(+ `No archived window named "${ref.windowSpec}". ` ++ `Known: ${windowIds.join(", ") || "none"} (${currentWindowId} is current and not archived yet).`,+ );+ }+ const items = await client.readArchiveMessages(target.entry.uri);+ if (!items) {+ return text(+ `${target.windowId} (${target.entry.archiveId}): its messages could not be read from OpenViking right now ` ++ `(the archive itself is readable as soon as it is committed, so this is a transport, permission or ` ++ `routing failure rather than a wait). Try {"action":"search_contents"} instead, or continue from the ` ++ `window header; do not repeat this call more than once.`,+ );+ }+ const msg = items[ref.index];+ if (!msg) {+ return text(+ `${target.windowId} has ${items.length} items (0-${Math.max(0, items.length - 1)}); ${ref.index} is out of range.`,+ );+ }+ const header = `[id: ${target.windowId}:${ref.index}] ${msg.role || "unknown"}${msg.created_at ? ` ${msg.created_at}` : ""}`;+ return text(+ [header, clip(msg.text, config.contextWindow.historyItemMaxChars)].join("\n"),+ { windowId: target.windowId, archiveId: target.entry.archiveId, index: ref.index, role: msg.role },+ );+ }++ case "search_contents": {+ const query = String(params?.query ?? "").trim();+ if (!query) return text('Provide a query, e.g. {"action":"search_contents","query":"ZEPHYR"}.');+ // The server reads the pattern as a regular expression, and a model's+ // query is usually plain text: one stray "(" would come back as a+ // server error this tool cannot tell apart from "no match", and the+ // model would conclude the archive does not hold what it is looking+ // for. A pattern that is not a valid expression is searched verbatim.+ let literal = false;+ try {+ new RegExp(query);+ } catch {+ literal = true;+ }+ const matches = await client.grepSessionArchives(sid, query, {+ caseInsensitive: true,+ literal,+ });+ if (matches.length === 0) {+ return text(`No match for "${query}" in the ${ordered.length} archived window(s) of this session.`);+ }+ const windowOf = new Map(ordered.map((e, i) => [e.archiveId, windowIds[i]]));+ const shown = matches.slice(0, 20);+ const groups = new Map<string, string[]>();+ for (const m of shown) {+ const windowId = windowOf.get(m.archiveId) ?? "(unknown window)";+ const key = `${windowId} ${m.archiveId}`;+ // messages.jsonl holds one message per line, so the line number is+ // the item index + 1 — enough to point read_item at the message.+ const pointer =+ m.file === "messages.jsonl" && m.line > 0 ? ` → {"action":"read_item","item":"${windowId}:${m.line - 1}"}` : "";+ const list = groups.get(key) ?? [];+ list.push(` ${m.file}:${m.line} ${clip(oneLine(m.content), 400)}${pointer}`);+ groups.set(key, list);+ }+ const out: string[] = [`${matches.length} match(es) for "${query}"${matches.length > shown.length ? `, showing ${shown.length}` : ""}:`];+ for (const [key, list] of groups) {+ out.push(key, ...list);+ }+ return text(out.join("\n"), { matches: shown, total: matches.length });+ }++ default:+ return text('Unknown action. Use list_windows, list_items, read_item or search_contents.');+ }+ },+ });++ // --- get_context_remaining ---+ pi.registerTool({+ name: "get_context_remaining",+ label: "Context Remaining",+ description:+ "How much of the current context window is left, how long it has been open, and how long since the " ++ "user's last message. Read-only — use it to decide whether to keep going or call new_context.",+ promptSnippet: "Check how much of the current context window is left",+ promptGuidelines: [+ "Call get_context_remaining before starting a large step, so you can open a fresh window first instead of running out halfway through.",+ ],+ parameters: Type.Object({}),+ async execute(+ _id: string, _params: any, _signal: AbortSignal,+ _onUpdate: any, ctx: any,+ ) {+ const snapshot = windows.statusSnapshot({+ usage: ctx?.getContextUsage?.(),+ now: Date.now(),+ messages: opts.getMessages?.(),+ reserveTokens: reserveTokens(),+ });+ return text(renderStatusReport(snapshot), snapshot);+ },+ });+}