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
/**
* 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.
}
}
}