Skip to content

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

fix(session): recover partial capture sessions (#3820)

t0saki0ab48f96fcbd
diff --git a/.github/scripts/stage-memory-plugin-marketplace.sh b/.github/scripts/stage-memory-plugin-marketplace.sh
index af0e9f4a8..ae9dc3ba6 100644
--- a/.github/scripts/stage-memory-plugin-marketplace.sh
+++ b/.github/scripts/stage-memory-plugin-marketplace.sh
@@ -56,10 +56,12 @@ for required in \
zcode-memory-plugin/scripts/shared/async-writer.mjs \
zcode-memory-plugin/scripts/shared/agent-hook-runtime.mjs \
zcode-memory-plugin/scripts/shared/batch-send.mjs \
+ zcode-memory-plugin/scripts/shared/retryable.mjs \
zcode-memory-plugin/servers/mcp-proxy.mjs \
memory-plugin-shared/lib/agent-hook-runtime.mjs \
memory-plugin-shared/lib/agent-uri-guard.mjs \
memory-plugin-shared/lib/async-writer.mjs \
+ memory-plugin-shared/lib/retryable.mjs \
memory-plugin-shared/lib/uri-guard.mjs \
memory-plugin-shared/lib/mcp-proxy-core.mjs; do
test -f "${STAGE}/${required}" || {
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index 9f33202b8..89638ada9 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -38,6 +38,7 @@ jobs:
examples/codex-memory-plugin/scripts/recall-compressor-profile.test.mjs \
examples/codex-memory-plugin/scripts/auto-recall.test.mjs \
examples/codex-memory-plugin/scripts/session-start-commit.test.mjs \
+ examples/claude-code-memory-plugin/scripts/auto-capture.test.mjs \
examples/claude-code-memory-plugin/scripts/marketplace.test.mjs \
examples/claude-code-memory-plugin/scripts/skill-experience.test.mjs \
examples/claude-code-memory-plugin/scripts/uri-guard.test.mjs \
diff --git a/examples/claude-code-memory-plugin/.claude-plugin/plugin.json b/examples/claude-code-memory-plugin/.claude-plugin/plugin.json
index edb729849..ae86dcc50 100644
--- a/examples/claude-code-memory-plugin/.claude-plugin/plugin.json
+++ b/examples/claude-code-memory-plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.4.3",
+ "version": "0.4.4",
"description": "Long-term semantic memory for Claude Code, powered by OpenViking. Auto-recall relevant memories at session start and capture important information during conversations.",
"author": {
"name": "OpenViking",
diff --git a/examples/claude-code-memory-plugin/package-lock.json b/examples/claude-code-memory-plugin/package-lock.json
index 5a1c0e9a8..6771592ec 100644
--- a/examples/claude-code-memory-plugin/package-lock.json
+++ b/examples/claude-code-memory-plugin/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "claude-code-openviking-memory",
- "version": "0.4.3",
+ "version": "0.4.4",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "claude-code-openviking-memory",
- "version": "0.4.3",
+ "version": "0.4.4",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.1",
"zod": "^4.3.6"
diff --git a/examples/claude-code-memory-plugin/package.json b/examples/claude-code-memory-plugin/package.json
index b8218b070..fb5df652c 100644
--- a/examples/claude-code-memory-plugin/package.json
+++ b/examples/claude-code-memory-plugin/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-code-openviking-memory",
- "version": "0.4.3",
+ "version": "0.4.4",
"description": "OpenViking memory plugin for Claude Code — semantic long-term memory",
"type": "module",
"scripts": {
diff --git a/examples/claude-code-memory-plugin/scripts/auto-capture.mjs b/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
index f89601171..60d17ea23 100644
--- a/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
+++ b/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
@@ -67,7 +67,7 @@ function stateFilePath(sessionId) {
async function loadState(sessionId) {
try {
const data = await readFile(stateFilePath(sessionId), "utf-8");
- return JSON.parse(data);
+ return { capturedTurnCount: 0, ...JSON.parse(data) };
} catch {
return { capturedTurnCount: 0 };
}
@@ -80,6 +80,52 @@ async function saveState(sessionId, state) {
} catch { /* best effort */ }
}
+async function reconcileKnownFailedCapture(sessionId, ovSessionId, state) {
+ if (
+ state.capturedTurnCount <= 0
+ || cfg.captureMode !== "semantic"
+ || !cfg.captureAssistantTurns
+ ) {
+ return;
+ }
+
+ const lastCapture = readJsonState("last-capture.json");
+ if (
+ lastCapture?.cc_session_id !== sessionId
+ || lastCapture?.ov_session_id !== ovSessionId
+ || Number(lastCapture.turns_failed || 0) <= 0
+ || Number(lastCapture.turns_captured || 0) > 0
+ || Number(lastCapture.turns_queued || 0) > 0
+ ) {
+ return;
+ }
+
+ const res = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}`);
+ if (!res.ok && res.status !== 404) {
+ log("capture_state_verification_deferred", {
+ sessionId,
+ ovSessionId,
+ status: res.status || 0,
+ });
+ return;
+ }
+
+ const meta = res.ok ? (res.result || {}) : {};
+ const hasDurableCapture = Number(meta.message_count || 0) > 0
+ || Number(meta.total_message_count || 0) > 0
+ || Number(meta.commit_count || 0) > 0;
+ if (!hasDurableCapture) {
+ log("capture_state_rewound", {
+ sessionId,
+ ovSessionId,
+ previousCapturedTurnCount: state.capturedTurnCount,
+ status: res.status || 200,
+ });
+ state.capturedTurnCount = 0;
+ await saveState(sessionId, state);
+ }
+}
+
// ---------------------------------------------------------------------------
// Text processing (ported from openclaw-plugin/text-utils.ts)
// ---------------------------------------------------------------------------
@@ -407,7 +453,13 @@ async function pushTurnsToOv(ovSessionId, turns, peerId = "") {
const res = await sendSessionMessages(fetchJSON, ovSessionId, payloads, {
enqueueOnRetryable: true,
});
- return { ok: res.sent, queued: res.queued, failed: res.failed, enqueueFailed: res.enqueueFailed };
+ return {
+ ok: res.sent,
+ queued: res.queued,
+ failed: res.failed,
+ enqueueFailed: res.enqueueFailed,
+ lastError: res.lastError,
+ };
}
async function enqueueTurnsToPending(ovSessionId, turns, peerId = "") {
@@ -426,6 +478,11 @@ async function enqueueTurnsToPending(ovSessionId, turns, peerId = "") {
return { ok: 0, queued, failed, enqueueFailed: failed };
}
+function isMissingSessionState(error) {
+ const code = String(error?.code || "").toUpperCase();
+ return code === "NOT_FOUND";
+}
+
// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------
@@ -492,6 +549,7 @@ async function main() {
}
const state = await loadState(sessionId);
+ await reconcileKnownFailedCapture(sessionId, ovSessionId, state);
const newTurns = allTurns.slice(state.capturedTurnCount);
const captureTurns = cfg.captureAssistantTurns
? newTurns
@@ -511,7 +569,10 @@ async function main() {
}
if (captureTurns.length === 0) {
- await saveState(sessionId, { capturedTurnCount: allTurns.length });
+ await saveState(sessionId, {
+ ...state,
+ capturedTurnCount: allTurns.length,
+ });
log("state_update", { newCapturedTurnCount: allTurns.length, reason: "assistant_only_increment" });
approve();
return;
@@ -532,7 +593,10 @@ async function main() {
const combined = formatTurnsAsText(captureTurns);
if (!sanitize(combined)) {
log("skip", { stage: "batch_empty" });
- await saveState(sessionId, { capturedTurnCount: allTurns.length });
+ await saveState(sessionId, {
+ ...state,
+ capturedTurnCount: allTurns.length,
+ });
approve();
return;
}
@@ -545,7 +609,10 @@ async function main() {
);
if (!hasTrigger) {
log("skip", { stage: "keyword_mode_no_trigger", turns: captureTurns.length });
- await saveState(sessionId, { capturedTurnCount: allTurns.length });
+ await saveState(sessionId, {
+ ...state,
+ capturedTurnCount: allTurns.length,
+ });
approve();
return;
}
@@ -575,7 +642,10 @@ async function main() {
approve();
return;
}
- await saveState(sessionId, { capturedTurnCount: allTurns.length });
+ await saveState(sessionId, {
+ ...state,
+ capturedTurnCount: allTurns.length,
+ });
log("state_update", { newCapturedTurnCount: allTurns.length, reason: "pending_queued" });
writeJsonState("last-capture.json", {
turns_captured: 0,
@@ -604,16 +674,39 @@ async function main() {
enqueueFailed: result.enqueueFailed,
});
- if (result.enqueueFailed > 0) {
- logError("pending_enqueue", "some retryable failures could not be enqueued; state not advanced");
+ if (result.enqueueFailed > 0 || (
+ result.failed > 0
+ && result.ok === 0
+ && result.queued === 0
+ && isMissingSessionState(result.lastError)
+ )) {
+ logError(
+ "capture_write",
+ "some turns were neither sent nor queued; state not advanced",
+ );
+ writeJsonState("last-capture.json", {
+ turns_captured: result.ok,
+ turns_queued: result.queued,
+ turns_failed: result.failed + result.enqueueFailed,
+ pending_tokens: 0,
+ commit_threshold: cfg.commitTokenThreshold,
+ committed: false,
+ commit_count: 0,
+ total_message_count: 0,
+ ov_session_id: ovSessionId,
+ cc_session_id: sessionId,
+ });
approve();
return;
}
- // Advance state only after every retryable write was either sent or durably
- // enqueued. Non-retryable 4xx failures are still treated as terminal so they
- // do not loop forever.
- await saveState(sessionId, { capturedTurnCount: allTurns.length });
+ // A missing live-message file is recoverable after the server is fixed, so
+ // retain the cursor for that failure. Other non-retryable 4xx responses keep
+ // the historical terminal behavior instead of retrying invalid payloads.
+ await saveState(sessionId, {
+ ...state,
+ capturedTurnCount: allTurns.length,
+ });
log("state_update", { newCapturedTurnCount: allTurns.length });
// Client-driven commit (ported from openclaw-plugin/context-engine.ts:afterTurn).
diff --git a/examples/claude-code-memory-plugin/scripts/auto-capture.test.mjs b/examples/claude-code-memory-plugin/scripts/auto-capture.test.mjs
new file mode 100644
index 000000000..6b5899b2d
--- /dev/null
+++ b/examples/claude-code-memory-plugin/scripts/auto-capture.test.mjs
@@ -0,0 +1,229 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+
+function writeJson(res, statusCode, value) {
+ res.writeHead(statusCode, { "Content-Type": "application/json" });
+ res.end(JSON.stringify(value));
+}
+
+function readRequestBody(req) {
+ return new Promise((resolve, reject) => {
+ const chunks = [];
+ req.on("data", (chunk) => chunks.push(chunk));
+ req.on("end", () => {
+ const raw = Buffer.concat(chunks).toString("utf-8");
+ try {
+ resolve(raw ? JSON.parse(raw) : null);
+ } catch (err) {
+ reject(err);
+ }
+ });
+ req.on("error", reject);
+ });
+}
+
+async function withMockOpenViking(handler, fn) {
+ const server = http.createServer((req, res) => {
+ handler(req, res).catch((err) => {
+ writeJson(res, 500, { status: "error", error: String(err?.stack || err) });
+ });
+ });
+ await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+ try {
+ const { port } = server.address();
+ return await fn(`http://127.0.0.1:${port}`);
+ } finally {
+ await new Promise((resolve) => server.close(resolve));
+ }
+}
+
+function runAutoCapture(input, env) {
+ return new Promise((resolve, reject) => {
+ const cleanEnv = { ...process.env };
+ for (const key of Object.keys(cleanEnv)) {
+ if (key.startsWith("OPENVIKING_")) delete cleanEnv[key];
+ }
+ const child = spawn(process.execPath, [join(SCRIPT_DIR, "auto-capture.mjs")], {
+ env: { ...cleanEnv, ...env },
+ stdio: ["pipe", "pipe", "pipe"],
+ });
+ let stdout = "";
+ let stderr = "";
+ child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+ child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+ child.on("error", reject);
+ child.on("close", (code) => {
+ if (code !== 0) {
+ reject(new Error(`auto-capture exited ${code}: ${stderr}`));
+ return;
+ }
+ resolve({ stdout, stderr });
+ });
+ child.stdin.end(JSON.stringify(input));
+ });
+}
+
+function hookEnv(root, baseUrl) {
+ return {
+ HOME: root,
+ TMPDIR: root,
+ OPENVIKING_AUTO_CAPTURE: "1",
+ OPENVIKING_CAPTURE_ASSISTANT_TURNS: "1",
+ OPENVIKING_MEMORY_ENABLED: "1",
+ OPENVIKING_STATE_DIR: join(root, "state"),
+ OPENVIKING_WRITE_PATH_ASYNC: "0",
+ OPENVIKING_TIMEOUT_MS: "5000",
+ OPENVIKING_URL: baseUrl,
+ };
+}
+
+async function writeTranscript(path) {
+ await writeFile(
+ path,
+ [
+ JSON.stringify({ role: "user", content: "remember the capture regression" }),
+ JSON.stringify({ role: "assistant", content: "I will retain that context" }),
+ ].join("\n"),
+ );
+}
+
+test("failed non-retryable capture keeps the cursor for a later retry", async () => {
+ const root = await mkdtemp(join(tmpdir(), "ov-cc-capture-retry-"));
+ const transcriptPath = join(root, "transcript.jsonl");
+ const sessionId = "capture-retry";
+ let rejectWrites = true;
+ const batches = [];
+
+ try {
+ await writeTranscript(transcriptPath);
+ await withMockOpenViking(async (req, res) => {
+ const url = new URL(req.url, "http://127.0.0.1");
+ if (req.method === "GET" && url.pathname === "/health") {
+ writeJson(res, 200, { status: "ok", result: { healthy: true } });
+ return;
+ }
+ if (req.method === "POST" && url.pathname.endsWith("/messages/batch")) {
+ const body = await readRequestBody(req);
+ if (rejectWrites) {
+ writeJson(res, 404, {
+ status: "error",
+ error: { code: "NOT_FOUND", message: "Resource not found" },
+ });
+ return;
+ }
+ batches.push(body);
+ writeJson(res, 200, { status: "ok", result: { added: body.messages.length } });
+ return;
+ }
+ if (req.method === "POST" && url.pathname.endsWith("/messages")) {
+ await readRequestBody(req);
+ writeJson(res, 404, {
+ status: "error",
+ error: { code: "NOT_FOUND", message: "Resource not found" },
+ });
+ return;
+ }
+ if (req.method === "GET" && url.pathname === "/api/v1/sessions/cc-capture-retry") {
+ writeJson(res, 200, {
+ status: "ok",
+ result: { message_count: 2, pending_tokens: 10, commit_count: 0 },
+ });
+ return;
+ }
+ writeJson(res, 404, { status: "error", error: { code: "NOT_FOUND" } });
+ }, async (baseUrl) => {
+ const input = { session_id: sessionId, transcript_path: transcriptPath, cwd: root };
+ await runAutoCapture(input, hookEnv(root, baseUrl));
+ rejectWrites = false;
+ await runAutoCapture(input, hookEnv(root, baseUrl));
+ });
+
+ assert.equal(batches.length, 1);
+ assert.equal(batches[0].messages.length, 2);
+ const state = JSON.parse(
+ await readFile(join(root, "openviking-cc-capture-state", `${sessionId}.json`), "utf-8"),
+ );
+ assert.equal(state.capturedTurnCount, 2);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("legacy advanced cursor rewinds when the server session is empty", async () => {
+ const root = await mkdtemp(join(tmpdir(), "ov-cc-capture-rewind-"));
+ const transcriptPath = join(root, "transcript.jsonl");
+ const sessionId = "legacy-empty-session";
+ const stateDir = join(root, "openviking-cc-capture-state");
+ let captured = false;
+ const batches = [];
+
+ try {
+ await writeTranscript(transcriptPath);
+ await mkdir(stateDir, { recursive: true });
+ await writeFile(
+ join(stateDir, `${sessionId}.json`),
+ JSON.stringify({ capturedTurnCount: 2 }),
+ );
+ await mkdir(join(root, ".openviking", "state"), { recursive: true });
+ await writeFile(
+ join(root, ".openviking", "state", "last-capture.json"),
+ JSON.stringify({
+ turns_captured: 0,
+ turns_queued: 0,
+ turns_failed: 2,
+ ov_session_id: "cc-legacy-empty-session",
+ cc_session_id: sessionId,
+ }),
+ );
+
+ await withMockOpenViking(async (req, res) => {
+ const url = new URL(req.url, "http://127.0.0.1");
+ if (req.method === "GET" && url.pathname === "/health") {
+ writeJson(res, 200, { status: "ok", result: { healthy: true } });
+ return;
+ }
+ if (req.method === "GET" && url.pathname === "/api/v1/sessions/cc-legacy-empty-session") {
+ writeJson(res, 200, {
+ status: "ok",
+ result: {
+ message_count: captured ? 2 : 0,
+ total_message_count: null,
+ commit_count: 0,
+ pending_tokens: captured ? 10 : 0,
+ },
+ });
+ return;
+ }
+ if (req.method === "POST" && url.pathname.endsWith("/messages/batch")) {
+ const body = await readRequestBody(req);
+ batches.push(body);
+ captured = true;
+ writeJson(res, 200, { status: "ok", result: { added: body.messages.length } });
+ return;
+ }
+ writeJson(res, 404, { status: "error", error: { code: "NOT_FOUND" } });
+ }, async (baseUrl) => {
+ await runAutoCapture(
+ { session_id: sessionId, transcript_path: transcriptPath, cwd: root },
+ hookEnv(root, baseUrl),
+ );
+ });
+
+ assert.equal(batches.length, 1);
+ assert.equal(batches[0].messages.length, 2);
+ const state = JSON.parse(
+ await readFile(join(stateDir, `${sessionId}.json`), "utf-8"),
+ );
+ assert.equal(state.capturedTurnCount, 2);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/examples/claude-code-memory-plugin/scripts/lib/ov-session.mjs b/examples/claude-code-memory-plugin/scripts/lib/ov-session.mjs
index 8e06e06ff..d375f9ce5 100644
--- a/examples/claude-code-memory-plugin/scripts/lib/ov-session.mjs
+++ b/examples/claude-code-memory-plugin/scripts/lib/ov-session.mjs
@@ -24,6 +24,7 @@ import {
deriveHarnessSessionId,
isBypassed,
} from "../shared/session-model.mjs";
+import { isRetryableFailure as isSharedRetryableFailure } from "../shared/retryable.mjs";
/**
* Check whether a CC session_id or cwd matches any bypass pattern.
@@ -75,9 +76,7 @@ export function makeFetchJSON(cfg, timeoutKey = "timeoutMs") {
}
export function isRetryableFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status >= 500 || status === 408 || status === 429;
+ return isSharedRetryableFailure(res);
}
function warnNonRetryable(operation, res) {
diff --git a/examples/claude-code-memory-plugin/scripts/lib/pending-queue.test.mjs b/examples/claude-code-memory-plugin/scripts/lib/pending-queue.test.mjs
index 3e1afd840..b3239dfcb 100644
--- a/examples/claude-code-memory-plugin/scripts/lib/pending-queue.test.mjs
+++ b/examples/claude-code-memory-plugin/scripts/lib/pending-queue.test.mjs
@@ -62,7 +62,7 @@ test("addMessage queues retryable failures", async () => {
test("addMessage does not queue non-retryable client failures", async () => {
await withPendingDir(async () => {
- for (const status of [401, 403, 404, 422]) {
+ for (const status of [401, 403, 404, 409, 422]) {
const res = await addMessage(
async () => ({ ok: false, status, error: { message: `HTTP ${status}` } }),
`cc-client-error-${status}`,
@@ -78,6 +78,39 @@ test("addMessage does not queue non-retryable client failures", async () => {
});
});
+test("addMessage queues conflicts only when the server marks them retryable", async () => {
+ await withPendingDir(async () => {
+ const retryable = await addMessage(
+ async () => ({
+ ok: false,
+ status: 409,
+ error: {
+ code: "CONFLICT",
+ details: { conflict_type: "path_busy", retryable: true },
+ },
+ }),
+ "cc-retryable-conflict",
+ { role: "user", content: "retry after lock contention" },
+ );
+ assert.equal(retryable.pendingQueued, true);
+
+ const terminal = await addMessage(
+ async () => ({
+ ok: false,
+ status: 409,
+ error: {
+ code: "ALREADY_EXISTS",
+ details: { retryable: false },
+ },
+ }),
+ "cc-terminal-conflict",
+ { role: "user", content: "do not retry business conflict" },
+ );
+ assert.equal(terminal.pendingQueued, undefined);
+ assert.equal((await listPending()).length, 1);
+ });
+});
+
test("replayPending sends queued entries and removes them after success", async () => {
await withPendingDir(async () => {
const payload = { role: "assistant", content: "queued response" };
diff --git a/examples/claude-code-memory-plugin/scripts/shared/batch-send.mjs b/examples/claude-code-memory-plugin/scripts/shared/batch-send.mjs
index 6d929d6bf..d7ec355cc 100644
--- a/examples/claude-code-memory-plugin/scripts/shared/batch-send.mjs
+++ b/examples/claude-code-memory-plugin/scripts/shared/batch-send.mjs
@@ -1,12 +1,11 @@
// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
import { enqueue } from "./pending-queue.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
export const BATCH_LIMIT = 100;
export function isRetryableSendFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status === 408 || status === 429 || status >= 500;
+ return isRetryableFailure(res);
}
function makeResult() {
diff --git a/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs b/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs
index 16e4da0dc..04ae9a9da 100644
--- a/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs
+++ b/examples/claude-code-memory-plugin/scripts/shared/pending-queue.mjs
@@ -24,6 +24,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
import { createHash } from "node:crypto";
import { join } from "node:path";
import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
const DEFAULT_MAX_RETRIES = 3;
const DEFAULT_TTL_DAYS = 7;
@@ -109,9 +110,7 @@ function pendingFromProcessingFilename(filename) {
}
function isRetryableReplayFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status >= 500 || status === 408 || status === 429;
+ return isRetryableFailure(res);
}
async function readEntry(dir, filename) {
diff --git a/examples/claude-code-memory-plugin/scripts/shared/retryable.mjs b/examples/claude-code-memory-plugin/scripts/shared/retryable.mjs
new file mode 100644
index 000000000..8be4b14e8
--- /dev/null
+++ b/examples/claude-code-memory-plugin/scripts/shared/retryable.mjs
@@ -0,0 +1,9 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function isRetryableFailure(result) {
+ if (!result || result.ok) return false;
+ const status = Number(result.status || 0);
+ if (!status || status === 408 || status === 429 || status >= 500) {
+ return true;
+ }
+ return status === 409 && result.error?.details?.retryable === true;
+}
diff --git a/examples/codex-memory-plugin/.codex-plugin/plugin.json b/examples/codex-memory-plugin/.codex-plugin/plugin.json
index 109f7801a..edc6b96f1 100644
--- a/examples/codex-memory-plugin/.codex-plugin/plugin.json
+++ b/examples/codex-memory-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.7.4",
+ "version": "0.7.5",
"description": "Long-term semantic memory for Codex, powered by OpenViking. Recall on UserPromptSubmit, incremental add_message on Stop (per turn), commit on PreCompact, and active-window heuristic + idle-TTL sweep on SessionStart (source=startup|clear). Includes a local stdio MCP proxy that reads OpenViking credentials from env/ovcli.conf.",
"author": {
"name": "OpenViking",
diff --git a/examples/codex-memory-plugin/scripts/shared/batch-send.mjs b/examples/codex-memory-plugin/scripts/shared/batch-send.mjs
index 6d929d6bf..d7ec355cc 100644
--- a/examples/codex-memory-plugin/scripts/shared/batch-send.mjs
+++ b/examples/codex-memory-plugin/scripts/shared/batch-send.mjs
@@ -1,12 +1,11 @@
// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
import { enqueue } from "./pending-queue.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
export const BATCH_LIMIT = 100;
export function isRetryableSendFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status === 408 || status === 429 || status >= 500;
+ return isRetryableFailure(res);
}
function makeResult() {
diff --git a/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs b/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs
index 16e4da0dc..04ae9a9da 100644
--- a/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs
+++ b/examples/codex-memory-plugin/scripts/shared/pending-queue.mjs
@@ -24,6 +24,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
import { createHash } from "node:crypto";
import { join } from "node:path";
import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
const DEFAULT_MAX_RETRIES = 3;
const DEFAULT_TTL_DAYS = 7;
@@ -109,9 +110,7 @@ function pendingFromProcessingFilename(filename) {
}
function isRetryableReplayFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status >= 500 || status === 408 || status === 429;
+ return isRetryableFailure(res);
}
async function readEntry(dir, filename) {
diff --git a/examples/codex-memory-plugin/scripts/shared/retryable.mjs b/examples/codex-memory-plugin/scripts/shared/retryable.mjs
new file mode 100644
index 000000000..8be4b14e8
--- /dev/null
+++ b/examples/codex-memory-plugin/scripts/shared/retryable.mjs
@@ -0,0 +1,9 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function isRetryableFailure(result) {
+ if (!result || result.ok) return false;
+ const status = Number(result.status || 0);
+ if (!status || status === 408 || status === 429 || status >= 500) {
+ return true;
+ }
+ return status === 409 && result.error?.details?.retryable === true;
+}
diff --git a/examples/cursor-memory-plugin/.cursor-plugin/plugin.json b/examples/cursor-memory-plugin/.cursor-plugin/plugin.json
index 9f8ad045c..70080c4da 100644
--- a/examples/cursor-memory-plugin/.cursor-plugin/plugin.json
+++ b/examples/cursor-memory-plugin/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "openviking-memory",
"displayName": "OpenViking Memory",
- "version": "0.1.2",
+ "version": "0.1.3",
"description": "Automatic long-term memory recall and conversation capture for Cursor",
"author": {
"name": "OpenViking"
diff --git a/examples/cursor-memory-plugin/openviking.integration.json b/examples/cursor-memory-plugin/openviking.integration.json
index 00b38d312..b98703465 100644
--- a/examples/cursor-memory-plugin/openviking.integration.json
+++ b/examples/cursor-memory-plugin/openviking.integration.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"id": "openviking-memory",
- "version": "0.1.2",
+ "version": "0.1.3",
"clients": ["cursor"],
"capabilities": ["hooks", "mcp", "rules", "skills"]
}
diff --git a/examples/memory-plugin-shared/batch-send.test.mjs b/examples/memory-plugin-shared/batch-send.test.mjs
index d5782fa31..44201de5b 100644
--- a/examples/memory-plugin-shared/batch-send.test.mjs
+++ b/examples/memory-plugin-shared/batch-send.test.mjs
@@ -133,6 +133,43 @@ test("sendSessionMessages treats non-retryable failures as failed without enqueu
});
});
+test("sendSessionMessages queues only explicitly retryable conflicts", async () => {
+ await withPendingDir(async () => {
+ const retryable = await sendSessionMessages(
+ async () => ({
+ ok: false,
+ status: 409,
+ error: {
+ code: "CONFLICT",
+ details: { conflict_type: "path_busy", retryable: true },
+ },
+ }),
+ "retryable-conflict",
+ payloads(2),
+ { enqueueOnRetryable: true },
+ );
+ assert.equal(retryable.queued, 2);
+ assert.equal(retryable.failed, 0);
+
+ const terminal = await sendSessionMessages(
+ async () => ({
+ ok: false,
+ status: 409,
+ error: {
+ code: "ALREADY_EXISTS",
+ details: { retryable: false },
+ },
+ }),
+ "terminal-conflict",
+ payloads(2, 2),
+ { enqueueOnRetryable: true },
+ );
+ assert.equal(terminal.queued, 0);
+ assert.equal(terminal.failed, 2);
+ assert.equal((await listPending()).length, 2);
+ });
+});
+
test("sendSessionMessages treats missing status failures as retryable", async () => {
await withPendingDir(async () => {
const res = await sendSessionMessages(
diff --git a/examples/memory-plugin-shared/install.sh b/examples/memory-plugin-shared/install.sh
index 20a70679f..f3046eafd 100644
--- a/examples/memory-plugin-shared/install.sh
+++ b/examples/memory-plugin-shared/install.sh
@@ -1758,6 +1758,7 @@ assemble_agent_integration() { # assemble_agent_integration <source-subdir> <des
for file in \
agent-hook-runtime.mjs agent-uri-guard.mjs credentials.mjs debug-log.mjs \
batch-send.mjs mcp-proxy-core.mjs pending-queue.mjs plugin-config.mjs profile-inject.mjs \
+ retryable.mjs \
recall-compress-core.mjs recall-core.mjs \
session-model.mjs uri-guard.mjs workspace-peer.mjs; do
cp "$shared/lib/$file" "$shared_dest.tmp/$file"
diff --git a/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs b/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs
index 195778eb0..ce96b76b3 100644
--- a/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs
+++ b/examples/memory-plugin-shared/lib/agent-hook-runtime.mjs
@@ -9,6 +9,7 @@ import { sendSessionMessages } from "./batch-send.mjs";
import { enqueue, replayPending } from "./pending-queue.mjs";
import { buildProfileBlock } from "./profile-inject.mjs";
import { buildRecallBlock } from "./recall-core.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
import { deriveHarnessSessionId, isBypassed } from "./session-model.mjs";
import { resolveEffectivePeerId } from "./workspace-peer.mjs";
@@ -195,17 +196,12 @@ export function makeAgentFetchJSON(cfg, cwd = process.cwd()) {
return { fetchJSON, effectivePeer };
}
-function retryable(result) {
- const status = Number(result?.status || 0);
- return !status || status === 408 || status === 429 || status >= 500;
-}
-
export async function addAgentMessage(fetchJSON, sessionId, payload) {
const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`, {
method: "POST",
body: JSON.stringify(payload),
});
- if (!result.ok && retryable(result)) await enqueue("addMessage", sessionId, payload);
+ if (!result.ok && isRetryableFailure(result)) await enqueue("addMessage", sessionId, payload);
return result;
}
@@ -218,7 +214,7 @@ export async function commitAgentSession(fetchJSON, sessionId) {
method: "POST",
body: "{}",
});
- if (!result.ok && retryable(result)) await enqueue("commitSession", sessionId, {});
+ if (!result.ok && isRetryableFailure(result)) await enqueue("commitSession", sessionId, {});
return result;
}
diff --git a/examples/memory-plugin-shared/lib/batch-send.mjs b/examples/memory-plugin-shared/lib/batch-send.mjs
index ce32c3af9..473c35290 100644
--- a/examples/memory-plugin-shared/lib/batch-send.mjs
+++ b/examples/memory-plugin-shared/lib/batch-send.mjs
@@ -1,11 +1,10 @@
import { enqueue } from "./pending-queue.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
export const BATCH_LIMIT = 100;
export function isRetryableSendFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status === 408 || status === 429 || status >= 500;
+ return isRetryableFailure(res);
}
function makeResult() {
diff --git a/examples/memory-plugin-shared/lib/pending-queue.mjs b/examples/memory-plugin-shared/lib/pending-queue.mjs
index 749bf5977..5306c330c 100644
--- a/examples/memory-plugin-shared/lib/pending-queue.mjs
+++ b/examples/memory-plugin-shared/lib/pending-queue.mjs
@@ -23,6 +23,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
import { createHash } from "node:crypto";
import { join } from "node:path";
import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
const DEFAULT_MAX_RETRIES = 3;
const DEFAULT_TTL_DAYS = 7;
@@ -108,9 +109,7 @@ function pendingFromProcessingFilename(filename) {
}
function isRetryableReplayFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status >= 500 || status === 408 || status === 429;
+ return isRetryableFailure(res);
}
async function readEntry(dir, filename) {
diff --git a/examples/memory-plugin-shared/lib/retryable.mjs b/examples/memory-plugin-shared/lib/retryable.mjs
new file mode 100644
index 000000000..2b63b2bb7
--- /dev/null
+++ b/examples/memory-plugin-shared/lib/retryable.mjs
@@ -0,0 +1,8 @@
+export function isRetryableFailure(result) {
+ if (!result || result.ok) return false;
+ const status = Number(result.status || 0);
+ if (!status || status === 408 || status === 429 || status >= 500) {
+ return true;
+ }
+ return status === 409 && result.error?.details?.retryable === true;
+}
diff --git a/examples/memory-plugin-shared/sync.mjs b/examples/memory-plugin-shared/sync.mjs
index faddc5cea..09718e9b0 100644
--- a/examples/memory-plugin-shared/sync.mjs
+++ b/examples/memory-plugin-shared/sync.mjs
@@ -16,6 +16,7 @@ const HARNESS_SHARED_FILES = [
"plugin-config.mjs",
"recall-compress-core.mjs",
"recall-core.mjs",
+ "retryable.mjs",
"workspace-peer.mjs",
"profile-inject.mjs",
"uri-guard.mjs",
diff --git a/examples/opencode-plugin/lib/memory-session.mjs b/examples/opencode-plugin/lib/memory-session.mjs
index 6646a6896..10307b59b 100644
--- a/examples/opencode-plugin/lib/memory-session.mjs
+++ b/examples/opencode-plugin/lib/memory-session.mjs
@@ -15,6 +15,9 @@ import {
import {
sendSessionMessages,
} from "./shared/batch-send.mjs"
+import {
+ isRetryableFailure,
+} from "./shared/retryable.mjs"
import {
log,
effectivePeerId,
@@ -475,9 +478,4 @@ export function createMemorySessionManager({ config, pluginRoot }) {
}
}
- function isRetryableFailure(res) {
- if (!res || res.ok) return false
- const status = Number(res.status || 0)
- return !status || status >= 500 || status === 408 || status === 429
- }
}
diff --git a/examples/opencode-plugin/lib/shared/batch-send.mjs b/examples/opencode-plugin/lib/shared/batch-send.mjs
index 6d929d6bf..d7ec355cc 100644
--- a/examples/opencode-plugin/lib/shared/batch-send.mjs
+++ b/examples/opencode-plugin/lib/shared/batch-send.mjs
@@ -1,12 +1,11 @@
// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
import { enqueue } from "./pending-queue.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
export const BATCH_LIMIT = 100;
export function isRetryableSendFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status === 408 || status === 429 || status >= 500;
+ return isRetryableFailure(res);
}
function makeResult() {
diff --git a/examples/opencode-plugin/lib/shared/pending-queue.mjs b/examples/opencode-plugin/lib/shared/pending-queue.mjs
index 16e4da0dc..04ae9a9da 100644
--- a/examples/opencode-plugin/lib/shared/pending-queue.mjs
+++ b/examples/opencode-plugin/lib/shared/pending-queue.mjs
@@ -24,6 +24,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
import { createHash } from "node:crypto";
import { join } from "node:path";
import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
const DEFAULT_MAX_RETRIES = 3;
const DEFAULT_TTL_DAYS = 7;
@@ -109,9 +110,7 @@ function pendingFromProcessingFilename(filename) {
}
function isRetryableReplayFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status >= 500 || status === 408 || status === 429;
+ return isRetryableFailure(res);
}
async function readEntry(dir, filename) {
diff --git a/examples/opencode-plugin/lib/shared/retryable.mjs b/examples/opencode-plugin/lib/shared/retryable.mjs
new file mode 100644
index 000000000..8be4b14e8
--- /dev/null
+++ b/examples/opencode-plugin/lib/shared/retryable.mjs
@@ -0,0 +1,9 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function isRetryableFailure(result) {
+ if (!result || result.ok) return false;
+ const status = Number(result.status || 0);
+ if (!status || status === 408 || status === 429 || status >= 500) {
+ return true;
+ }
+ return status === 409 && result.error?.details?.retryable === true;
+}
diff --git a/examples/opencode-plugin/package.json b/examples/opencode-plugin/package.json
index 3f9d897db..56788b21c 100644
--- a/examples/opencode-plugin/package.json
+++ b/examples/opencode-plugin/package.json
@@ -1,6 +1,6 @@
{
"name": "@openviking/opencode-plugin",
- "version": "0.2.3",
+ "version": "0.2.4",
"author": "@openviking",
"description": "Unified OpenCode plugin for OpenViking repository retrieval and long-term memory",
"type": "module",
diff --git a/examples/pi-coding-agent-extension/shared/pending-queue.mjs b/examples/pi-coding-agent-extension/shared/pending-queue.mjs
index 16e4da0dc..04ae9a9da 100644
--- a/examples/pi-coding-agent-extension/shared/pending-queue.mjs
+++ b/examples/pi-coding-agent-extension/shared/pending-queue.mjs
@@ -24,6 +24,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
import { createHash } from "node:crypto";
import { join } from "node:path";
import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
const DEFAULT_MAX_RETRIES = 3;
const DEFAULT_TTL_DAYS = 7;
@@ -109,9 +110,7 @@ function pendingFromProcessingFilename(filename) {
}
function isRetryableReplayFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status >= 500 || status === 408 || status === 429;
+ return isRetryableFailure(res);
}
async function readEntry(dir, filename) {
diff --git a/examples/pi-coding-agent-extension/shared/retryable.mjs b/examples/pi-coding-agent-extension/shared/retryable.mjs
new file mode 100644
index 000000000..8be4b14e8
--- /dev/null
+++ b/examples/pi-coding-agent-extension/shared/retryable.mjs
@@ -0,0 +1,9 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function isRetryableFailure(result) {
+ if (!result || result.ok) return false;
+ const status = Number(result.status || 0);
+ if (!status || status === 408 || status === 429 || status >= 500) {
+ return true;
+ }
+ return status === 409 && result.error?.details?.retryable === true;
+}
diff --git a/examples/trae-memory-hooks/openviking.integration.json b/examples/trae-memory-hooks/openviking.integration.json
index fe7da2ce0..b1a3a2190 100644
--- a/examples/trae-memory-hooks/openviking.integration.json
+++ b/examples/trae-memory-hooks/openviking.integration.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"id": "openviking-memory",
- "version": "0.1.2",
+ "version": "0.1.3",
"clients": ["trae", "trae-cn"],
"capabilities": ["hooks", "mcp"]
}
diff --git a/examples/zcode-memory-plugin/.zcode-plugin/plugin.json b/examples/zcode-memory-plugin/.zcode-plugin/plugin.json
index 8ea5f3604..edd2e936f 100644
--- a/examples/zcode-memory-plugin/.zcode-plugin/plugin.json
+++ b/examples/zcode-memory-plugin/.zcode-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.1.0",
+ "version": "0.1.1",
"description": "Long-term semantic memory for ZCode, powered by OpenViking. Auto-recall relevant memories at session start and capture important information during conversations.",
"author": {
"name": "OpenViking",
diff --git a/examples/zcode-memory-plugin/openviking.integration.json b/examples/zcode-memory-plugin/openviking.integration.json
index f1febf7ed..1b9170959 100644
--- a/examples/zcode-memory-plugin/openviking.integration.json
+++ b/examples/zcode-memory-plugin/openviking.integration.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"id": "openviking-memory",
- "version": "0.1.0",
+ "version": "0.1.1",
"clients": ["zcode"],
"capabilities": ["hooks", "mcp"]
}
diff --git a/examples/zcode-memory-plugin/scripts/shared/agent-hook-runtime.mjs b/examples/zcode-memory-plugin/scripts/shared/agent-hook-runtime.mjs
index 68a5b30ea..7a32faf15 100644
--- a/examples/zcode-memory-plugin/scripts/shared/agent-hook-runtime.mjs
+++ b/examples/zcode-memory-plugin/scripts/shared/agent-hook-runtime.mjs
@@ -10,6 +10,7 @@ import { sendSessionMessages } from "./batch-send.mjs";
import { enqueue, replayPending } from "./pending-queue.mjs";
import { buildProfileBlock } from "./profile-inject.mjs";
import { buildRecallBlock } from "./recall-core.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
import { deriveHarnessSessionId, isBypassed } from "./session-model.mjs";
import { resolveEffectivePeerId } from "./workspace-peer.mjs";
@@ -196,17 +197,12 @@ export function makeAgentFetchJSON(cfg, cwd = process.cwd()) {
return { fetchJSON, effectivePeer };
}
-function retryable(result) {
- const status = Number(result?.status || 0);
- return !status || status === 408 || status === 429 || status >= 500;
-}
-
export async function addAgentMessage(fetchJSON, sessionId, payload) {
const result = await fetchJSON(`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`, {
method: "POST",
body: JSON.stringify(payload),
});
- if (!result.ok && retryable(result)) await enqueue("addMessage", sessionId, payload);
+ if (!result.ok && isRetryableFailure(result)) await enqueue("addMessage", sessionId, payload);
return result;
}
@@ -219,7 +215,7 @@ export async function commitAgentSession(fetchJSON, sessionId) {
method: "POST",
body: "{}",
});
- if (!result.ok && retryable(result)) await enqueue("commitSession", sessionId, {});
+ if (!result.ok && isRetryableFailure(result)) await enqueue("commitSession", sessionId, {});
return result;
}
diff --git a/examples/zcode-memory-plugin/scripts/shared/batch-send.mjs b/examples/zcode-memory-plugin/scripts/shared/batch-send.mjs
index 6d929d6bf..d7ec355cc 100644
--- a/examples/zcode-memory-plugin/scripts/shared/batch-send.mjs
+++ b/examples/zcode-memory-plugin/scripts/shared/batch-send.mjs
@@ -1,12 +1,11 @@
// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
import { enqueue } from "./pending-queue.mjs";
+import { isRetryableFailure } from "./retryable.mjs";
export const BATCH_LIMIT = 100;
export function isRetryableSendFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status === 408 || status === 429 || status >= 500;
+ return isRetryableFailure(res);
}
function makeResult() {
diff --git a/examples/zcode-memory-plugin/scripts/shared/pending-queue.mjs b/examples/zcode-memory-plugin/scripts/shared/pending-queue.mjs
index 16e4da0dc..04ae9a9da 100644
--- a/examples/zcode-memory-plugin/scripts/shared/pending-queue.mjs
+++ b/examples/zcode-memory-plugin/scripts/shared/pending-queue.mjs
@@ -24,6 +24,7 @@ import { mkdir, readdir, readFile, rename, writeFile, unlink, stat, chmod } from
import { createHash } from "node:crypto";
import { join } from "node:path";
import { homedir } from "node:os";
+import { isRetryableFailure } from "./retryable.mjs";
const DEFAULT_MAX_RETRIES = 3;
const DEFAULT_TTL_DAYS = 7;
@@ -109,9 +110,7 @@ function pendingFromProcessingFilename(filename) {
}
function isRetryableReplayFailure(res) {
- if (!res || res.ok) return false;
- const status = Number(res.status || 0);
- return !status || status >= 500 || status === 408 || status === 429;
+ return isRetryableFailure(res);
}
async function readEntry(dir, filename) {
diff --git a/examples/zcode-memory-plugin/scripts/shared/retryable.mjs b/examples/zcode-memory-plugin/scripts/shared/retryable.mjs
new file mode 100644
index 000000000..8be4b14e8
--- /dev/null
+++ b/examples/zcode-memory-plugin/scripts/shared/retryable.mjs
@@ -0,0 +1,9 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+export function isRetryableFailure(result) {
+ if (!result || result.ok) return false;
+ const status = Number(result.status || 0);
+ if (!status || status === 408 || status === 429 || status >= 500) {
+ return true;
+ }
+ return status === 409 && result.error?.details?.retryable === true;
+}
diff --git a/openviking/retrieve/context_assembler/pipeline.py b/openviking/retrieve/context_assembler/pipeline.py
index cbb4e3467..c09159b39 100644
--- a/openviking/retrieve/context_assembler/pipeline.py
+++ b/openviking/retrieve/context_assembler/pipeline.py
@@ -41,6 +41,8 @@ async def _load_session(service: Any, ctx: RequestContext, session_id: Optional[
return None
try:
session = service.sessions.session(ctx, session_id)
+ if not await session.is_materialized():
+ return None
await session.load()
return session
except Exception as exc:
diff --git a/openviking/session/session.py b/openviking/session/session.py
index 72c718b2a..d8291a684 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -736,12 +736,29 @@ class Session:
raise
return False
+ async def is_materialized(self) -> bool:
+ """Check whether the session's authoritative live-message file exists."""
+ try:
+ await self._viking_fs.stat(
+ f"{self._session_uri}/messages.jsonl",
+ ctx=self.ctx,
+ )
+ return True
+ except Exception as exc:
+ if not _is_storage_not_found(exc):
+ raise
+ return False
+
async def ensure_exists(self) -> None:
"""Materialize session root and messages file if missing."""
if await self.exists():
return
await self._viking_fs.mkdir(self._session_uri, exist_ok=True, ctx=self.ctx)
- await self._viking_fs.write_file(f"{self._session_uri}/messages.jsonl", "", ctx=self.ctx)
+ await self._viking_fs.write_file(
+ f"{self._session_uri}/messages.jsonl",
+ "",
+ ctx=self.ctx,
+ )
await self._save_meta()
async def _save_meta(self, lease_ref: Optional[Any] = None) -> None:
@@ -1177,7 +1194,14 @@ class Session:
session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
)
try:
- self._messages = await self._read_live_messages_strict()
+ live_messages_missing = False
+ try:
+ self._messages = await self._read_live_messages_strict()
+ except Exception as exc:
+ if not _is_storage_not_found(exc):
+ raise
+ self._messages = []
+ live_messages_missing = True
in_memory_meta = self._meta
try:
meta_content = await self._viking_fs.read_file(
@@ -1192,12 +1216,20 @@ class Session:
self._apply_appended_messages_to_state(messages)
batch_content = "".join(message.to_jsonl() + "\n" for message in messages)
- await self._viking_fs.append_file(
- f"{self._session_uri}/messages.jsonl",
- batch_content,
- ctx=self.ctx,
- lease_ref=lease,
- )
+ if live_messages_missing:
+ await self._viking_fs.write_file(
+ f"{self._session_uri}/messages.jsonl",
+ batch_content,
+ ctx=self.ctx,
+ lease_ref=lease,
+ )
+ else:
+ await self._viking_fs.append_file(
+ f"{self._session_uri}/messages.jsonl",
+ batch_content,
+ ctx=self.ctx,
+ lease_ref=lease,
+ )
await self._save_meta(lease_ref=lease)
finally:
await self._viking_fs._async_agfs.pathlock_release(lease)
diff --git a/tests/server/test_api_search_context.py b/tests/server/test_api_search_context.py
index 5ac8d9f2f..3b54f3c0d 100644
--- a/tests/server/test_api_search_context.py
+++ b/tests/server/test_api_search_context.py
@@ -322,3 +322,38 @@ async def test_context_mode_dedup_ledger_round_trips_through_agfs(
second = await client.post("/api/v1/search/search", json=payload)
assert second.json()["result"]["entries"] == []
assert second.json()["result"]["stats"]["dedup"]["cooled"] == 1
+
+
+async def test_context_mode_unknown_session_does_not_create_recall_ledger(
+ client: httpx.AsyncClient,
+ service,
+ monkeypatch,
+):
+ file_uri = "viking://user/default/memories/events/unknown-session.md"
+ ctx = RequestContext(user=UserIdentifier.the_default_user("default"), role=Role.ROOT)
+ await service.viking_fs.write_file(uri=file_uri, content="# Summary\nrecalled fact", ctx=ctx)
+
+ async def fake_find(**kwargs):
+ del kwargs
+ return _FakeFindResult([_memory(file_uri, 0.7, "recall abstract")])
+
+ monkeypatch.setattr(service.search, "find", fake_find)
+ session_id = "context-before-capture"
+ response = await client.post(
+ "/api/v1/search/search",
+ json={
+ "query": "recall before capture",
+ "mode": "context",
+ "session_id": session_id,
+ "dedup_turns": 3,
+ "query_expansion": "off",
+ },
+ )
+
+ assert response.status_code == 200
+ assert [entry["uri"] for entry in response.json()["result"]["entries"]] == [file_uri]
+ assert response.json()["result"]["stats"]["dedup"]["status"] == "off"
+ assert not await service.viking_fs.exists(
+ f"viking://user/default/sessions/{session_id}/.recall_log.json",
+ ctx=ctx,
+ )
diff --git a/tests/server/test_api_sessions.py b/tests/server/test_api_sessions.py
index 72fc33443..25ba3600f 100644
--- a/tests/server/test_api_sessions.py
+++ b/tests/server/test_api_sessions.py
@@ -187,6 +187,112 @@ async def test_legacy_session_uri_alias_reads_current_user_session(client: httpx
assert "legacy alias message" in resp.json()["result"]
[email protected]("artifact", ["empty", "recall_ledger", "meta"])
+async def test_add_message_repairs_session_directory_without_live_messages(
+ client: httpx.AsyncClient,
+ service,
+ artifact: str,
+):
+ session_id = f"{artifact}-only-session"
+ ctx = RequestContext(user=DEFAULT_USER, role=Role.ROOT)
+ ledger_uri = f"viking://user/default/sessions/{session_id}/.recall_log.json"
+ meta_uri = f"viking://user/default/sessions/{session_id}/.meta.json"
+ await service.viking_fs.mkdir(
+ f"viking://user/default/sessions/{session_id}",
+ exist_ok=True,
+ ctx=ctx,
+ )
+ if artifact == "recall_ledger":
+ await service.viking_fs.write_file(
+ uri=ledger_uri,
+ content=json.dumps({"version": 1, "updated_turn": 0, "entries": {}}),
+ ctx=ctx,
+ )
+ elif artifact == "meta":
+ meta = service.sessions.session(ctx, session_id).meta.to_dict()
+ meta["last_commit_at"] = "preserve-existing-meta"
+ await service.viking_fs.write_file(
+ uri=meta_uri,
+ content=json.dumps(meta),
+ ctx=ctx,
+ )
+
+ resp = await client.post(
+ f"/api/v1/sessions/{session_id}/messages",
+ json=_message_request("user", content="first captured message"),
+ )
+
+ assert resp.status_code == 200
+ assert resp.json()["result"]["message_count"] == 1
+ messages = await service.viking_fs.read_file(
+ f"viking://user/default/sessions/{session_id}/messages.jsonl",
+ ctx=ctx,
+ )
+ assert "first captured message" in messages
+ assert await service.viking_fs.exists(ledger_uri, ctx=ctx) is (artifact == "recall_ledger")
+ persisted_meta = json.loads(await service.viking_fs.read_file(meta_uri, ctx=ctx))
+ if artifact == "meta":
+ assert persisted_meta["last_commit_at"] == "preserve-existing-meta"
+
+
+async def test_partial_session_remains_visible_and_deletable(
+ client: httpx.AsyncClient,
+ service,
+):
+ session_id = "partial-session-lifecycle"
+ ctx = RequestContext(user=DEFAULT_USER, role=Role.ROOT)
+ session_uri = f"viking://user/default/sessions/{session_id}"
+ await service.viking_fs.mkdir(session_uri, exist_ok=True, ctx=ctx)
+
+ get_resp = await client.get(f"/api/v1/sessions/{session_id}")
+ assert get_resp.status_code == 200
+ assert get_resp.json()["result"]["message_count"] == 0
+
+ duplicate = await client.post("/api/v1/sessions", json={"session_id": session_id})
+ assert duplicate.status_code == 409
+
+ delete_resp = await client.delete(f"/api/v1/sessions/{session_id}")
+ assert delete_resp.status_code == 200
+ assert not await service.viking_fs.exists(session_uri, ctx=ctx)
+
+
+async def test_add_message_recovers_after_interrupted_session_initialization(
+ client: httpx.AsyncClient,
+ service,
+ monkeypatch,
+):
+ session_id = "interrupted-initialization"
+ ctx = RequestContext(user=DEFAULT_USER, role=Role.ROOT)
+ session_uri = f"viking://user/default/sessions/{session_id}"
+ original_write_file = service.viking_fs.write_file
+ failed_once = False
+
+ async def fail_first_message_file(uri, content, **kwargs):
+ nonlocal failed_once
+ if uri == f"{session_uri}/messages.jsonl" and not failed_once:
+ failed_once = True
+ raise OSError("simulated initialization interruption")
+ return await original_write_file(uri, content, **kwargs)
+
+ monkeypatch.setattr(service.viking_fs, "write_file", fail_first_message_file)
+ first = await client.post(
+ f"/api/v1/sessions/{session_id}/messages",
+ json=_message_request("user", content="first attempt"),
+ )
+ assert first.status_code == 500
+ assert await service.viking_fs.exists(session_uri, ctx=ctx)
+ assert not await service.viking_fs.exists(f"{session_uri}/messages.jsonl", ctx=ctx)
+
+ second = await client.post(
+ f"/api/v1/sessions/{session_id}/messages",
+ json=_message_request("user", content="second attempt"),
+ )
+ assert second.status_code == 200
+ assert second.json()["result"]["message_count"] == 1
+ messages = await service.viking_fs.read_file(f"{session_uri}/messages.jsonl", ctx=ctx)
+ assert "second attempt" in messages
+
+
async def test_get_session_context(client: httpx.AsyncClient):
create_resp = await client.post("/api/v1/sessions", json={})
session_id = create_resp.json()["result"]["session_id"]