Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(pi): say why /viking commit did not archive (#5468)

Zayn Jarvisb20f192e6139
diff --git a/examples/pi-coding-agent-extension/README.md b/examples/pi-coding-agent-extension/README.md
index 4d08929a9..9dd107dc5 100644
--- a/examples/pi-coding-agent-extension/README.md
+++ b/examples/pi-coding-agent-extension/README.md
@@ -411,6 +411,7 @@ TypeScript is loaded directly by pi's jiti transpiler. The official MCP client i
| Extension crashes on load | Wrong OV server URL or network issue | Check `logLevel` and server accessibility |
| No memories extracted | Wrong embedding/extraction model in OV config | Check OV's `embedding` / `vlm` configuration |
| Takeover never advances | Pending addMessage replay or commit failed, or the archive summary never arrives (Working Memory disabled on the server) | Set `OPENVIKING_DEBUG_LOG=/tmp/ov-pi.log` and retry `/viking commit` |
+| `/viking commit`: `nothing new to archive … (all_within_keep_window)` | The server already archived everything older than the last `takeoverKeepRecentTurns` user turns (an earlier archive whose summary failed, a native-compaction archive, or a 0.3.x commit) | Nothing to fix; the next commit archives once more user turns accumulate. If it follows `archive_NNN failed on the server`, check the server log for the Phase 2 (Working Memory) error |
## License
diff --git a/examples/pi-coding-agent-extension/index.ts b/examples/pi-coding-agent-extension/index.ts
index e6fb3e17c..4a15f444f 100644
--- a/examples/pi-coding-agent-extension/index.ts
+++ b/examples/pi-coding-agent-extension/index.ts
@@ -25,7 +25,7 @@ import { guardVikingUriToolCall, noticeVikingUriToolResult } from "./lib/uri-gua
import { createMcpBridge, DEFAULT_HANDSHAKE_BUDGET_MS } from "./lib/mcp-bridge.mjs";
import { registerMcpTools } from "./tools.js";
import { createTakeoverManager } from "./takeover.js";
-import { HANDLER_BUDGET_MS } from "./lib/takeover-core.mjs";
+import { HANDLER_BUDGET_MS, describeSkip } from "./lib/takeover-core.mjs";
/** This extension's directory, published for the experimental fork's probe. */
const EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
@@ -447,9 +447,11 @@ export default async function (pi: ExtensionAPI) {
const commitResult = config.takeoverEnabled ? null : await sync.commit();
// Manual commit freezes and confirms the boundary against the current
// branch, exactly like the automatic path.
+ // A `skipped` result archived nothing; it is not a successful commit.
+ const skipped = commitResult?.status === "skipped";
const ok = config.takeoverEnabled
? await takeover.commitAndAdvance(() => ctx.sessionManager.getBranch())
- : commitResult !== null;
+ : commitResult !== null && !skipped;
if (!ok && config.takeoverEnabled && takeover.state.pendingArchive) {
ctx.ui.notify(
"OpenViking: committed; the context is trimmed once the archive summary is ready",
@@ -462,7 +464,19 @@ export default async function (pi: ExtensionAPI) {
"info",
);
} else {
- ctx.ui.notify("OpenViking: commit failed", "error");
+ // Say why: a bare "commit failed" left users with nothing to act on.
+ const reason = config.takeoverEnabled
+ ? takeover.lastFailure
+ : skipped
+ ? describeSkip(String(commitResult?.reason || ""), config.commitKeepRecentCount)
+ : sync.lastCommitError;
+ logger.log("commit", { ok: false, manual: true, reason: reason || "unknown" });
+ if (reason.startsWith("nothing")) {
+ // Not an error: the server already holds this history.
+ ctx.ui.notify(`OpenViking: ${reason}`, "warning");
+ } else {
+ ctx.ui.notify(`OpenViking: commit failed${reason ? ` — ${reason}` : ""}`, "error");
+ }
}
return;
}
diff --git a/examples/pi-coding-agent-extension/lib/takeover-core.d.mts b/examples/pi-coding-agent-extension/lib/takeover-core.d.mts
index 28fdddc1a..45a12a081 100644
--- a/examples/pi-coding-agent-extension/lib/takeover-core.d.mts
+++ b/examples/pi-coding-agent-extension/lib/takeover-core.d.mts
@@ -80,6 +80,8 @@ export interface TakeoverIo {
sleep?: (ms: number) => Promise<void>;
/** Clock for handler deadlines; defaults to Date.now. */
now?: () => number;
+ /** Why the last commit request returned no result, e.g. `HTTP 500: ...`. */
+ lastCommitError?: () => string;
log?: (message: string) => void;
}
@@ -112,6 +114,8 @@ export function buildOverviewMessage(overview: string, firstKeptTs?: number, bud
export function countUndeliveredForSession(pendingEntries: any[], sid: string): number;
export function deriveHistoryUri(archiveUri: string): string;
export function commitOutcome(committed: unknown): CommitOutcome;
+/** A user-facing reading of a `skipped` commit's `reason`. */
+export function describeSkip(reason: string, keepRecentCount?: number): string;
export type TakeoverState = TakeoverPersistedState & {
coveredThroughEntryId: string;
@@ -128,6 +132,8 @@ export class TakeoverCore {
constructor(opts?: { config?: TakeoverConfig; io?: TakeoverIo });
get enabled(): boolean;
get state(): TakeoverState;
+ /** Why the last commitAndAdvance() returned false; empty after a success. */
+ lastFailure: string;
restore(entries: any[]): TakeoverState;
/** `branch` is pi's `getBranch()`; the boundary is located on its context projection. */
transformContext(messages: TakeoverMessage[], branch?: any[] | (() => any[])): TakeoverMessage[];
diff --git a/examples/pi-coding-agent-extension/lib/takeover-core.mjs b/examples/pi-coding-agent-extension/lib/takeover-core.mjs
index 4c9440827..daf0a574e 100644
--- a/examples/pi-coding-agent-extension/lib/takeover-core.mjs
+++ b/examples/pi-coding-agent-extension/lib/takeover-core.mjs
@@ -311,6 +311,23 @@ export function commitOutcome(committed) {
};
}
+function archiveName(archiveUri) {
+ const parts = String(archiveUri || "").replace(/\/+$/, "").split("/");
+ return parts[parts.length - 1] || "the archive";
+}
+
+/** A user-facing reading of a `skipped` commit. */
+export function describeSkip(reason, keepRecentCount = 0) {
+ if (reason === "all_within_keep_window") {
+ return (
+ `nothing new to archive: the server session holds at most the ${keepRecentCount} most recent ` +
+ "messages this commit keeps, and anything older was already archived (all_within_keep_window)"
+ );
+ }
+ if (reason === "no_messages") return "nothing to archive: the server session has no live messages (no_messages)";
+ return `the server skipped the archive (${reason || "unknown"})`;
+}
+
export class TakeoverCore {
constructor({ config = {}, io = {} } = {}) {
this.config = takeoverConfig(config);
@@ -338,6 +355,9 @@ export class TakeoverCore {
availableTools: io.availableTools || (() => []),
sleep: io.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
now: io.now || (() => Date.now()),
+ // Why the last commit request returned no result (HTTP status and the
+ // server's message), so a manual commit can say more than "failed".
+ lastCommitError: io.lastCommitError || (() => ""),
log: io.log || (() => {}),
};
// The covered prefix ends at this pi entry, inclusive. Entry ids survive
@@ -370,6 +390,9 @@ export class TakeoverCore {
// Whether the last context actually carried the boundary, so leaving and
// re-entering the covered branch is logged once, not on every request.
this.boundaryApplied = false;
+ // Why the last commitAndAdvance() returned false, for `/viking commit` to
+ // show; empty after a success. Not persisted.
+ this.lastFailure = "";
}
get enabled() {
@@ -595,15 +618,17 @@ export class TakeoverCore {
* the commit only get what is left of `deadline`.
*/
async commitAndAdvance(branch = [], { deadline } = {}) {
- if (!this.enabled || this.committing) return false;
+ if (!this.enabled) return this.fail("takeover is disabled");
+ if (this.committing) return this.fail("another commit is still running");
const until = this.deadlineFrom(deadline);
this.committing = true;
+ this.lastFailure = "";
try {
if (this.pendingArchive) return await this.resolvePendingArchive(branch);
return await this.beginArchive(branch, until);
} catch (error) {
this.log(`takeover: archive preparation failed (${errorMessage(error)}); boundary held`);
- return false;
+ return this.fail(`archive preparation failed: ${errorMessage(error)}`);
} finally {
this.committing = false;
}
@@ -613,7 +638,7 @@ export class TakeoverCore {
async beginArchive(branch, until) {
if (this.captureGap) {
this.log("takeover: capture gap present; boundary held, native compaction stays with pi");
- return false;
+ return this.fail("some messages never reached OpenViking (capture gap); takeover is off for this session");
}
// One snapshot is frozen, synced and counted, so the archive and
@@ -623,16 +648,25 @@ export class TakeoverCore {
const frozen = this.freezeBoundary(snapshot);
if (!frozen) {
this.log("takeover: no advanceable boundary; commit skipped");
- return false;
+ return this.fail(
+ `nothing new to archive: the context needs more than ${this.config.takeoverKeepRecentTurns} ` +
+ "user turns beyond the last archive",
+ );
}
const delivered = await this.confirmDelivery(snapshot, until);
- if (!delivered) return false;
+ if (!delivered) {
+ return this.fail(
+ this.captureGap
+ ? "some messages never reached OpenViking (capture gap); takeover is off for this session"
+ : "queued messages are not delivered yet; retry once the server is reachable",
+ );
+ }
const left = this.remaining(until);
if (left < COMMIT_RESERVE_MS) {
this.log("takeover: handler budget spent before commit; commit postponed");
- return false;
+ return this.fail("ran out of time delivering messages; retry");
}
const committed = await this.io.commit({
queueOnFailure: false,
@@ -645,12 +679,16 @@ export class TakeoverCore {
// the next threshold crossing retries, and never fall back to /context.
if (outcome.reason === "no_result") {
this.log("takeover: commit failed; boundary held");
- } else if (outcome.reason.startsWith("skipped:")) {
- this.log(`takeover: archive skipped (${outcome.reason.slice(8)}); boundary held`);
- } else {
- this.log(`takeover: commit returned no usable archive (${outcome.reason}); boundary held`);
+ const detail = String(this.io.lastCommitError() || "").trim();
+ return this.fail(`the server rejected the commit${detail ? ` (${detail})` : ""}`);
}
- return false;
+ if (outcome.reason.startsWith("skipped:")) {
+ const reason = outcome.reason.slice(8);
+ this.log(`takeover: archive skipped (${reason}); boundary held`);
+ return this.fail(describeSkip(reason, frozen.keepRecentCount));
+ }
+ this.log(`takeover: commit returned no usable archive (${outcome.reason}); boundary held`);
+ return this.fail(`the server returned no archive (${outcome.reason})`);
}
const archive = {
@@ -727,7 +765,7 @@ export class TakeoverCore {
this.pendingArchive = null;
this.persist();
this.log("takeover: frozen boundary no longer in history; advance abandoned");
- return false;
+ return this.fail("the archived turns left the active context (branch switch or compaction); advance abandoned");
}
let overview = await this.readOverviewOnce(pending.archiveUri);
@@ -743,7 +781,10 @@ export class TakeoverCore {
this.pendingTokens = Math.max(0, this.pendingTokens - (Number(pending.frozenTokens) || 0));
this.persist();
this.log(`takeover: ${pending.archiveUri} ${state} without Working Memory; boundary held`);
- return false;
+ return this.fail(
+ `${archiveName(pending.archiveUri)} ${state} on the server without a Working Memory summary ` +
+ "(check the server log for the Phase 2 error)",
+ );
}
}
@@ -756,7 +797,7 @@ export class TakeoverCore {
this.pendingTokens = Math.max(0, this.pendingTokens - (Number(pending.frozenTokens) || 0));
this.persist();
this.log(`takeover: native-compaction archive completed at ${pending.archiveUri}`);
- return false;
+ return this.fail(`${archiveName(pending.archiveUri)} completed after pi compacted natively; nothing to trim`);
}
return this.advanceTo(branch, pending, overview);
}
@@ -767,7 +808,7 @@ export class TakeoverCore {
this.pendingArchive = null;
this.persist();
this.log("takeover: frozen boundary no longer in history; advance abandoned");
- return false;
+ return this.fail("the archived turns left the active context (branch switch or compaction); advance abandoned");
}
this.coveredThroughEntryId = frozen.coveredThroughEntryId;
@@ -789,6 +830,12 @@ export class TakeoverCore {
return true;
}
+ /** Record why a commit did not advance, for `/viking commit` to show. */
+ fail(reason) {
+ this.lastFailure = String(reason || "");
+ return false;
+ }
+
inActiveContext(branch, entryId) {
if (!entryId) return false;
return projectContextEntries(currentBranch(branch)).some((entry) => entry?.id === entryId);
diff --git a/examples/pi-coding-agent-extension/package-lock.json b/examples/pi-coding-agent-extension/package-lock.json
index acec93146..7f82c5751 100644
--- a/examples/pi-coding-agent-extension/package-lock.json
+++ b/examples/pi-coding-agent-extension/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "openviking-pi-extension",
- "version": "0.4.6",
+ "version": "0.4.7",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "openviking-pi-extension",
- "version": "0.4.6",
+ "version": "0.4.7",
"dependencies": {
"@modelcontextprotocol/client": "2.0.0"
},
diff --git a/examples/pi-coding-agent-extension/package.json b/examples/pi-coding-agent-extension/package.json
index d1600353b..93adffa9e 100644
--- a/examples/pi-coding-agent-extension/package.json
+++ b/examples/pi-coding-agent-extension/package.json
@@ -1,6 +1,6 @@
{
"name": "openviking-pi-extension",
- "version": "0.4.6",
+ "version": "0.4.7",
"description": "OpenViking memory and context extension for the pi coding agent",
"private": true,
"type": "module",
diff --git a/examples/pi-coding-agent-extension/sync.ts b/examples/pi-coding-agent-extension/sync.ts
index 892f3c04d..780979cc8 100644
--- a/examples/pi-coding-agent-extension/sync.ts
+++ b/examples/pi-coding-agent-extension/sync.ts
@@ -39,6 +39,8 @@ export class SyncManager {
* signal. Takeover persists the resulting boolean with its own session state.
*/
private droppedForever = 0;
+ /** Why the last commit request got no result, for `/viking commit` to show. */
+ private lastCommitFailure = "";
constructor(client: OVClient, config: OVConfig) {
this.client = client;
@@ -53,6 +55,8 @@ export class SyncManager {
get syncedCount(): number { return this.syncedEntryCount; }
/** Messages OpenViking will never receive; they are missing from the archive. */
get droppedCount(): number { return this.droppedForever; }
+ /** `HTTP <status>: <server message>` of the last failed commit; empty after a success. */
+ get lastCommitError(): string { return this.lastCommitFailure; }
/**
* How many payloads the capture path would actually send for a slice of the
@@ -287,7 +291,10 @@ export class SyncManager {
async commit(
opts: { queueOnFailure?: boolean; keepRecentCount?: number; timeoutMs?: number } = {},
): Promise<any | null> {
- if (!this.ovSessionId) return null;
+ if (!this.ovSessionId) {
+ this.lastCommitFailure = "no OpenViking session yet";
+ return null;
+ }
const response = await this.client.commitSessionResponse(
this.ovSessionId,
opts.keepRecentCount,
@@ -295,6 +302,7 @@ export class SyncManager {
);
const result = response.result;
if (!result) {
+ this.lastCommitFailure = describeCommitError(response.status, response.error);
this.logger.log("commit", {
session: this.ovSessionId,
ok: false,
@@ -309,6 +317,7 @@ export class SyncManager {
}
return null;
}
+ this.lastCommitFailure = "";
this.logger.log("commit", {
session: this.ovSessionId,
ok: true,
@@ -322,6 +331,14 @@ export class SyncManager {
}
}
+/** One line for a failed commit request: status (0 = no response) and the server's message. */
+export function describeCommitError(status: number | undefined, error: any): string {
+ const code = Number(status) || 0;
+ const raw = String(error?.message || error?.code || "unknown error").replace(/\s+/g, " ").trim();
+ const message = raw.length > 200 ? `${raw.slice(0, 200)}…` : raw;
+ return code > 0 ? `HTTP ${code}: ${message}` : `no response: ${message}`;
+}
+
async function hasProcessingMessage(sessionId: string): Promise<boolean> {
const dir = process.env.OPENVIKING_PENDING_DIR || join(homedir(), ".openviking", "pending");
let names: string[];
diff --git a/examples/pi-coding-agent-extension/takeover.ts b/examples/pi-coding-agent-extension/takeover.ts
index c8f53208e..7e5f6aa1f 100644
--- a/examples/pi-coding-agent-extension/takeover.ts
+++ b/examples/pi-coding-agent-extension/takeover.ts
@@ -35,6 +35,7 @@ export function createTakeoverManager(opts: {
},
getWatermark: () => sync.syncedCount,
droppedCount: () => sync.droppedCount,
+ lastCommitError: () => sync.lastCommitError,
availableTools: () => typeof pi?.getActiveTools === "function" ? pi.getActiveTools() : [],
log: opts.log,
},
diff --git a/examples/pi-coding-agent-extension/tests/sync-barrier.test.mjs b/examples/pi-coding-agent-extension/tests/sync-barrier.test.mjs
index f514e7df3..c836ff091 100644
--- a/examples/pi-coding-agent-extension/tests/sync-barrier.test.mjs
+++ b/examples/pi-coding-agent-extension/tests/sync-barrier.test.mjs
@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
import { mkdtemp, readFile, rename, rm } from "node:fs/promises";
import { join } from "node:path";
import { tmpdir } from "node:os";
-import { SyncManager } from "../sync.ts";
+import { SyncManager, describeCommitError } from "../sync.ts";
import { enqueue, listPending } from "../shared/pending-queue.mjs";
function config(overrides = {}) {
@@ -115,6 +115,27 @@ test("commit writes failure trace_id to the pi debug log", async () => {
});
});
+test("a failed commit keeps its status and server message for /viking commit", async () => {
+ await withPendingDir(async () => {
+ let response = { result: null, status: 403, error: { message: "identity deleted\n" } };
+ const sync = new SyncManager(client({ commitSessionResponse: async () => response }), config());
+ await sync.ensureSession("pi-commit-error");
+
+ assert.equal(await sync.commit({ queueOnFailure: false }), null);
+ assert.equal(sync.lastCommitError, "HTTP 403: identity deleted");
+ response = { result: { status: "accepted", archive_uri: "viking://archive/1" } };
+ assert.ok(await sync.commit({ queueOnFailure: false }));
+ assert.equal(sync.lastCommitError, "");
+ });
+});
+
+test("describeCommitError names a missing response and bounds the message", () => {
+ assert.equal(describeCommitError(0, { message: "fetch failed" }), "no response: fetch failed");
+ assert.equal(describeCommitError(undefined, null), "no response: unknown error");
+ const long = describeCommitError(500, { message: "x".repeat(300) });
+ assert.equal(long, `HTTP 500: ${"x".repeat(200)}…`);
+});
+
test("queued addMessage makes takeover flush barrier false until replay succeeds", async () => {
await withPendingDir(async () => {
let replayOk = false;
diff --git a/examples/pi-coding-agent-extension/tests/takeover-core.test.mjs b/examples/pi-coding-agent-extension/tests/takeover-core.test.mjs
index 21b5353ef..e64d75bcc 100644
--- a/examples/pi-coding-agent-extension/tests/takeover-core.test.mjs
+++ b/examples/pi-coding-agent-extension/tests/takeover-core.test.mjs
@@ -7,6 +7,7 @@ import {
buildOverviewMessage,
commitOutcome,
countUndeliveredForSession,
+ describeSkip,
countUserTurns,
estimatePayloadTokens,
estimateTokens,
@@ -1043,3 +1044,65 @@ test("shutdown persists deduped state once", async () => {
assert.equal(calls.persisted.length, 1);
assert.equal(calls.persisted[0].data.syncedEntryCount, 9);
});
+
+test("a manual commit the server skips says why instead of a bare failure", async () => {
+ // 0.4.22 user report: /viking commit POSTed keep_recent_count=125, the server
+ // answered 200 `skipped: all_within_keep_window`, and pi only showed
+ // "commit failed".
+ const { core } = makeCore({
+ commitResult: {
+ status: "skipped", archived: false, archive_uri: null, task_id: null,
+ reason: "all_within_keep_window", trace_id: "",
+ },
+ });
+ const branch = branchOf(user("one"), assistant("a"), user("two"), assistant("b"));
+ assert.equal(await core.commitAndAdvance(branch), false);
+ assert.match(core.lastFailure, /^nothing new to archive/);
+ assert.match(core.lastFailure, /all_within_keep_window/);
+ assert.match(core.lastFailure, / 2 most recent messages/);
+ assert.equal(core.state.coveredThroughEntryId, "");
+});
+
+test("a rejected commit carries the HTTP status and server message", async () => {
+ const { core } = makeCore({
+ commitResult: null,
+ io: { lastCommitError: () => "HTTP 500: Session commit failed: disk full" },
+ });
+ const branch = branchOf(user("one"), user("two"));
+ assert.equal(await core.commitAndAdvance(branch), false);
+ assert.equal(core.lastFailure, "the server rejected the commit (HTTP 500: Session commit failed: disk full)");
+});
+
+test("every commit that does not advance records a reason; a success clears it", async () => {
+ const cases = [
+ ["too few turns", makeCore(), branchOf(user("only")), /nothing new to archive: the context needs more than 1 user turns/],
+ ["flush closed", makeCore({ flushResult: false }), branchOf(user("one"), user("two")), /not delivered yet/],
+ ["capture gap", makeCore({ syncResult: { permanentFailures: 1 } }), branchOf(user("one"), user("two")), /capture gap/],
+ ["no archive uri", makeCore({ commitResult: { status: "accepted", archived: true } }), branchOf(user("one"), user("two")), /no archive \(no_archive_uri\)/],
+ ["throws", makeCore({ io: { syncBranch: async () => { throw new Error("boom"); } } }), branchOf(user("one"), user("two")), /archive preparation failed: boom/],
+ ];
+ for (const [name, { core }, branch, expected] of cases) {
+ assert.equal(await core.commitAndAdvance(branch), false, name);
+ assert.match(core.lastFailure, expected, name);
+ }
+ const { core } = makeCore();
+ core.lastFailure = "stale";
+ assert.equal(await core.commitAndAdvance(branchOf(user("one"), user("two"))), true);
+ assert.equal(core.lastFailure, "");
+});
+
+test("an archive that failed on the server without a summary is named in the reason", async () => {
+ const { core } = makeCore({ overviews: [""], io: { archiveState: async () => "failed" } });
+ const branch = branchOf(user("one"), user("two"));
+ assert.equal(await core.commitAndAdvance(branch), false);
+ assert.ok(core.state.pendingArchive);
+ assert.equal(await core.commitAndAdvance(branch), false);
+ assert.equal(core.state.pendingArchive, null);
+ assert.match(core.lastFailure, /^archive_001 failed on the server without a Working Memory summary/);
+});
+
+test("describeSkip reads the server skip reasons", () => {
+ assert.match(describeSkip("no_messages"), /no live messages/);
+ assert.match(describeSkip("all_within_keep_window", 125), /at most the 125 most recent messages/);
+ assert.equal(describeSkip("weird"), "the server skipped the archive (weird)");
+});