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
import type { OVConfig } from "./config.js";
// --- OV API Response Shapes ---
// All OV responses wrap in: { status: "ok"|"error", result: T, error?: {...}, ... }
// This client normalizes to { ok, result } internally.
export interface OVSearchResult {
uri: string;
context_type: string; // "memory" | "resource" | "skill"
score: number;
abstract: string;
overview: string | null;
level: number; // 0=L0, 1=L1, 2=L2
category: string;
match_reason: string;
}
export interface OVDirEntry {
uri: string;
name: string;
isDir: boolean;
size: number;
mode: number;
modTime: string;
abstract: string;
}
export interface OVStatInfo {
name: string;
size: number;
mode: number;
modTime: string;
isDir: boolean;
isLocked: boolean;
uri?: string;
count?: number; // directories only
}
export interface OVSessionMeta {
session_id: string;
message_count: number;
total_message_count?: number;
commit_count: number;
pending_tokens?: number;
memories_extracted?: Record<string, number>;
last_commit_at?: string;
/** Canonical session root, e.g. `viking://user/default/sessions/pi-abc`. */
uri?: string;
}
export interface OVSessionContext {
latest_archive_overview: string | null;
pre_archive_abstracts: any[];
messages: any[];
estimatedTokens: number;
stats: {
totalArchives: number;
includedArchives: number;
droppedArchives: number;
failedArchives: number;
activeTokens: number;
archiveTokens: number;
};
}
export interface OVCommitResult {
/**
* `accepted` = phase 1 wrote `history/archive_NNN/messages.jsonl` and a
* background task is generating the Working Memory; `skipped` = nothing to
* archive (see `reason`, e.g. `no_messages`).
*/
status?: "accepted" | "skipped" | string;
/** Number of messages archived (server also uses a boolean in some builds). */
archived?: number | boolean;
reason?: string;
task_id?: string;
/** `null` on a `skipped` commit — the server sends the key either way. */
archive_uri?: string | null;
trace_id?: string;
}
/** One message of `history/archive_NNN/messages.jsonl`. */
export interface OVArchiveMessage {
id: string;
role: string;
/**
* Parts rendered to one string: `text` parts verbatim, `tool` parts as
* `[tool <name>] <input> <output>`, `context` parts as `[context <uri>]`.
* A part the renderer does not understand never silently disappears.
*/
text: string;
parts: any[];
created_at: string;
}
/** One `history/archive_NNN` directory of a session. */
export interface OVArchiveEntry {
archiveId: string;
uri: string;
modTime: string;
abstract: string;
}
/** One grep hit inside a session archive. */
export interface OVArchiveGrepMatch {
archiveId: string;
/** File inside the archive, e.g. `messages.jsonl` or `.overview.md`. */
file: string;
line: number;
content: string;
}
export interface OVTaskStatus {
status: string;
stage?: string;
error?: string;
}
export interface OVCommitResponse {
result: OVCommitResult | null;
traceId?: string;
error?: any;
status?: number;
}
export interface OVResponse<T> {
ok: boolean;
result: T | null;
error?: any;
status?: number;
traceId?: string;
}
export class OVClient {
private baseUrl: string;
private apiKey: string;
private account: string;
private user: string;
private peerId: string;
connected: boolean = false;
private resolvedSpaces: Map<string, string> = new Map();
/** Canonical session roots, keyed by session id. Only successes are cached. */
private sessionRoots: Map<string, string> = new Map();
private static RESERVED_USER = new Set(["memories"]);
private static RESERVED_AGENT = new Set(["memories", "skills", "instructions", "workspaces"]);
/** Read-only access to config (for value access across modules). */
readonly cfg: OVConfig;
constructor(config: OVConfig) {
this.cfg = config;
this.baseUrl = config.endpoint.replace(/\/+$/, "");
this.apiKey = config.apiKey;
this.account = config.account;
this.user = config.user;
this.peerId = config.peerId;
}
private headers(): Record<string, string> {
const h: Record<string, string> = { "Content-Type": "application/json" };
if (this.apiKey) h["Authorization"] = `Bearer ${this.apiKey}`;
if (this.account) h["X-OpenViking-Account"] = this.account;
if (this.user) h["X-OpenViking-User"] = this.user;
if (this.peerId) h["X-OpenViking-Actor-Peer"] = this.peerId;
if (this.cfg.userAgent) h["User-Agent"] = this.cfg.userAgent;
return h;
}
/** Core fetch wrapper. Returns { ok, result } after parsing OV's { status, result } envelope. */
async fetchJSON<T>(path: string, init?: RequestInit, timeoutMs = 10000): Promise<OVResponse<T>> {
const controller = new AbortController();
// Cleared in `finally`: when fetch rejects the timer would otherwise keep
// the event loop alive for the full timeout.
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const resp = await fetch(`${this.baseUrl}${path}`, {
...init,
headers: { ...this.headers(), ...(init?.headers as Record<string, string> || {}) },
signal: controller.signal,
});
// A complete non-JSON body falls back to `{}`; a body cut off after the
// headers rejects into the status-0 branch below so writes stay retryable.
const body = await resp.json().catch((error: unknown) => {
if (!(error instanceof SyntaxError)) throw error;
return {};
});
const traceId = body?.result?.trace_id || body?.error?.trace_id || body?.trace_id || undefined;
if (!resp.ok || body.status === "error") {
return {
ok: false,
result: null,
status: resp.status,
error: body.error || { message: `HTTP ${resp.status}` },
traceId,
};
}
return { ok: true, result: (body.result ?? body) as T, traceId };
} catch (err: any) {
return { ok: false, result: null, status: 0, error: { message: err?.message || String(err) } };
} finally {
clearTimeout(timer);
}
}
// ========== Health ==========
async health(): Promise<boolean> {
const res = await this.fetchJSON<any>("/health", undefined, 5000);
this.connected = res.ok;
return res.ok;
}
// ========== Sessions ==========
/** POST /api/v1/sessions — create or reuse session */
async createSession(sessionId: string): Promise<boolean> {
const res = await this.fetchJSON<any>("/api/v1/sessions", {
method: "POST",
body: JSON.stringify({ session_id: sessionId }),
});
return res.ok;
}
/** GET /api/v1/sessions/{id} — session metadata */
async getSession(sessionId: string, autoCreate = false): Promise<OVSessionMeta | null> {
const q = autoCreate ? "?auto_create=true" : "";
const res = await this.fetchJSON<OVSessionMeta>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}${q}`,
undefined, 5000,
);
return res.ok ? res.result : null;
}
/** GET /api/v1/sessions/{id}/context — assembled context with archive overview */
async getSessionContext(sessionId: string, tokenBudget = 128000): Promise<OVSessionContext | null> {
const res = await this.fetchJSON<OVSessionContext>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/context?token_budget=${tokenBudget}`,
undefined, 10000,
);
return res.ok ? res.result : null;
}
/** POST /api/v1/sessions/{id}/messages — add a message (simple text mode) */
async addMessage(sessionId: string, role: string, content: string): Promise<boolean> {
const res = await this.fetchJSON<any>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
{ method: "POST", body: JSON.stringify({ role, content }) },
10000,
);
return res.ok;
}
/** POST /api/v1/sessions/{id}/messages — add a message with parts */
async addMessageParts(sessionId: string, role: string, parts: any[]): Promise<boolean> {
const res = await this.fetchJSON<any>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
{ method: "POST", body: JSON.stringify({ role, parts }) },
10000,
);
return res.ok;
}
async addMessagePayload(sessionId: string, payload: any): Promise<boolean> {
const res = await this.fetchJSON<any>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
{ method: "POST", body: JSON.stringify(payload) },
10000,
);
return res.ok;
}
/** POST /api/v1/sessions/{id}/commit — commit session for archiving + extraction */
async commitSessionResponse(
sessionId: string,
keepRecentCount = this.cfg.commitKeepRecentCount,
): Promise<OVCommitResponse> {
const res = await this.fetchJSON<OVCommitResult>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
{ method: "POST", body: JSON.stringify({ keep_recent_count: keepRecentCount }) },
30000,
);
if (res.ok && res.result && !res.result.trace_id && res.traceId) {
res.result.trace_id = res.traceId;
}
return {
result: res.ok ? res.result : null,
traceId: res.traceId,
error: res.error,
status: res.status,
};
}
async commitSession(
sessionId: string,
keepRecentCount = this.cfg.commitKeepRecentCount,
): Promise<OVCommitResult | null> {
return (await this.commitSessionResponse(sessionId, keepRecentCount)).result;
}
/** DELETE /api/v1/sessions/{id} */
async deleteSession(sessionId: string): Promise<boolean> {
const res = await this.fetchJSON<any>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}`,
{ method: "DELETE" },
10000,
);
return res.ok;
}
// ========== Session archives ==========
//
// `GET /api/v1/sessions/{id}/archives/{archive_id}` is blocked (403 ApiBlocked)
// on the target gateway, so everything here goes through the generic
// filesystem / content / grep routes against the session root URI.
//
// Every method in this section is failure-tolerant by contract: it returns
// null (single value) or [] (list) instead of throwing, so callers can treat
// "OpenViking did not answer" the same as "nothing there".
/**
* Session root URI, e.g. `viking://user/default/sessions/pi-abc`.
*
* Reads the canonical `uri` from `GET /api/v1/sessions/{id}` and caches it.
* If the metadata request fails, use the current user's home alias. The
* fallback is not cached so a later call can still pick up the canonical URI.
*/
async sessionRootUri(sessionId: string): Promise<string> {
const id = String(sessionId ?? "");
const cached = this.sessionRoots.get(id);
if (cached) return cached;
try {
const meta = await this.getSession(id);
const uri = typeof meta?.uri === "string" ? stripTrailingSlash(meta.uri.trim()) : "";
if (uri.startsWith("viking://")) {
this.sessionRoots.set(id, uri);
return uri;
}
} catch {
// fall through to the home alias
}
return `viking://~/sessions/${id}`;
}
/** Strip `/history/archive_NNN` off a commit's `archive_uri` to get the session root. */
static archiveUriToRoot(archiveUri: string): string {
return archiveUriToRoot(archiveUri);
}
/** Instance alias of {@link OVClient.archiveUriToRoot}. */
archiveUriToRoot(archiveUri: string): string {
return archiveUriToRoot(archiveUri);
}
/**
* Working Memory of one archive: `GET /content/read?uri=<archive>/.overview.md`.
*
* Returns null while commit phase 2 is still running (the server answers 404
* NOT_FOUND until then) and on any other failure. The server stores this
* sidecar as OKF Markdown — `---\n<yaml>\n---\n\n<body>\n` — and
* `content/read` only strips that for memory URIs, not for session archives,
* so the frontmatter is removed here and callers get the Working Memory body.
*
* A file that is present but has no body counts as "not ready" (null), so a
* caller polling for the Working Memory cannot be fooled by an empty write.
*/
async readArchiveOverview(archiveUri: string): Promise<string | null> {
const base = stripTrailingSlash(String(archiveUri ?? "").trim());
if (!base) return null;
const res = await this.fetchJSON<string>(
`/api/v1/content/read?uri=${encodeURIComponent(`${base}/.overview.md`)}`,
undefined, 15000,
);
if (!res.ok || typeof res.result !== "string") return null;
const body = stripFrontmatter(res.result);
return body.trim() ? body : null;
}
/**
* Messages of one archive: `GET /content/read?uri=<archive>/messages.jsonl`.
*
* Readable right after commit phase 1. A line that is malformed or blank
* becomes a placeholder item rather than failing the read or shifting the
* ones after it. Returns null when the file cannot be read at all.
*/
async readArchiveMessages(archiveUri: string): Promise<OVArchiveMessage[] | null> {
const base = stripTrailingSlash(String(archiveUri ?? "").trim());
if (!base) return null;
const res = await this.fetchJSON<string>(
`/api/v1/content/read?uri=${encodeURIComponent(`${base}/messages.jsonl`)}`,
undefined, 15000,
);
if (!res.ok || typeof res.result !== "string") return null;
// Every line of the file has to produce exactly one item, because
// `search_contents` turns a grep hit's line number into an item index
// (`line - 1`). The only thing dropped is the empty string left behind by a
// trailing final newline, which is not a line of its own.
const lines = res.result.split("\n");
if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
const out: OVArchiveMessage[] = [];
for (const rawLine of lines) {
const line = rawLine.trim();
let obj: any = null;
if (line) {
try {
obj = JSON.parse(line);
} catch {
obj = null; // a truncated or non-JSON line must not lose the rest
}
}
if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
out.push({
id: "",
role: line ? "unreadable" : "blank",
text: line ? "(unreadable archive line)" : "(blank archive line)",
parts: [],
created_at: "",
});
continue;
}
const parts = Array.isArray(obj.parts) ? obj.parts : [];
out.push({
id: obj.id == null ? "" : String(obj.id),
role: obj.role == null ? "" : String(obj.role),
text: renderMessageText(parts, obj.content),
parts,
created_at: obj.created_at == null ? "" : String(obj.created_at),
});
}
return out;
}
/**
* Archive directories of a session, newest first.
* `GET /fs/ls?uri=<root>/history&sort_by=name&sort_order=desc`.
*
* Returns `null` when the listing request itself failed (401/403/5xx/timeout)
* and `[]` only when the session genuinely has no archives. The two must stay
* distinguishable: `history` tells the model to trust an empty history and
* not ask the user, which would be exactly wrong for an unreachable server.
*/
async listSessionArchives(sessionId: string): Promise<OVArchiveEntry[] | null> {
const root = await this.sessionRootUri(sessionId);
const res = await this.fetchJSON<any[]>(
`/api/v1/fs/ls?uri=${encodeURIComponent(`${root}/history`)}&sort_by=name&sort_order=desc`,
undefined, 10000,
);
// A missing history directory is an empty history, not a failure.
if (!res.ok) return isNotFound(res) ? [] : null;
if (!Array.isArray(res.result)) return null;
const rows: OVArchiveEntry[] = [];
for (const e of res.result) {
// The agent-format listing has no `name`, so the URI basename leads.
const uri = stripTrailingSlash(typeof e?.uri === "string" ? e.uri : "");
const archiveId = uriBasename(uri) || (typeof e?.name === "string" ? e.name : "");
if (!ARCHIVE_ID_RE.test(archiveId)) continue;
if (e?.isDir === false) continue; // an archive is always a directory
rows.push({
archiveId,
uri,
modTime: typeof e?.modTime === "string" ? e.modTime : "",
abstract: typeof e?.abstract === "string" ? e.abstract : "",
});
}
// Do not rely on the server honouring sort_order: archive ids are numbered,
// so order them here as well.
rows.sort((a, b) => archiveIndex(b.archiveId) - archiveIndex(a.archiveId));
return rows;
}
/**
* `POST /search/grep` over `<root>/history` (or one archive).
*
* `pattern` is a REGULAR EXPRESSION by default; pass `{ literal: true }` to
* search for the text verbatim (the pattern is regex-escaped then).
*/
async grepSessionArchives(
sessionId: string,
pattern: string,
opts?: { archiveId?: string; caseInsensitive?: boolean; nodeLimit?: number; literal?: boolean },
): Promise<OVArchiveGrepMatch[]> {
const raw = String(pattern ?? "");
if (!raw) return [];
const root = await this.sessionRootUri(sessionId);
const archiveId = opts?.archiveId && ARCHIVE_ID_RE.test(opts.archiveId) ? opts.archiveId : "";
const uri = archiveId ? `${root}/history/${archiveId}` : `${root}/history`;
const nodeLimit = Number.isFinite(opts?.nodeLimit as number)
? Math.max(1, Math.min(4096, Math.floor(opts!.nodeLimit as number)))
: 256;
const res = await this.fetchJSON<any>("/api/v1/search/grep", {
method: "POST",
body: JSON.stringify({
uri,
pattern: opts?.literal ? escapeRegExp(raw) : raw,
case_insensitive: opts?.caseInsensitive !== false,
node_limit: nodeLimit,
}),
}, 15000);
if (!res.ok || !res.result) return [];
const matches = Array.isArray(res.result?.matches)
? res.result.matches
: Array.isArray(res.result) ? res.result : [];
const out: OVArchiveGrepMatch[] = [];
for (const m of matches) {
if (!m || typeof m !== "object") continue;
const matchUri = stripTrailingSlash(typeof m.uri === "string" ? m.uri : "");
const line = Number(m.line);
out.push({
archiveId: archiveIdFromUri(matchUri) || archiveId,
file: archiveFileFromUri(matchUri),
line: Number.isFinite(line) ? line : 0,
content: typeof m.content === "string" ? m.content : "",
});
}
return out;
}
/** `GET /api/v1/tasks/{id}` — commit phase 2 progress (`pending|running|completed|failed`). */
async getTask(taskId: string): Promise<OVTaskStatus | null> {
const id = String(taskId ?? "").trim();
if (!id) return null;
const res = await this.fetchJSON<any>(
`/api/v1/tasks/${encodeURIComponent(id)}`,
undefined, 10000,
);
if (!res.ok || !res.result || typeof res.result !== "object") return null;
const r = res.result as any;
const out: OVTaskStatus = { status: String(r.status ?? r.state ?? "") };
if (typeof r.stage === "string" && r.stage) out.stage = r.stage;
const err = r.error ?? r.error_message ?? r.message;
if (err) out.error = typeof err === "string" ? err : safeStringify(err);
return out;
}
// ========== Search ==========
/** POST /api/v1/search/find — basic vector search */
async find(
query: string,
opts?: { targetUri?: string; topK?: number; scoreThreshold?: number },
): Promise<OVSearchResult[]> {
const body: Record<string, unknown> = { query };
if (opts?.targetUri) body.target_uri = opts.targetUri;
if (opts?.topK) body.limit = opts.topK;
if (opts?.scoreThreshold) body.score_threshold = opts.scoreThreshold;
const res = await this.fetchJSON<any>("/api/v1/search/find", {
method: "POST", body: JSON.stringify(body),
}, 10000);
if (!res.ok || !res.result) return [];
// OV returns { memories: [...], resources: [...], skills: [...], total }
const all: OVSearchResult[] = [];
for (const bucket of ["memories", "resources", "skills"]) {
const items = res.result[bucket];
if (Array.isArray(items)) {
for (const m of items) {
all.push({
uri: m.uri ?? "",
context_type: m.context_type ?? (bucket === "memories" ? "memory" : bucket === "skills" ? "skill" : "resource"),
score: m.score ?? 0,
abstract: m.abstract ?? "",
overview: m.overview ?? null,
level: m.level ?? 0,
category: m.category ?? "",
match_reason: m.match_reason ?? "",
});
}
}
}
return all;
}
// ========== Content ==========
/** GET /api/v1/content/abstract — L0 summary */
async abstract(uri: string): Promise<string | null> {
const res = await this.fetchJSON<string>(
`/api/v1/content/abstract?uri=${encodeURIComponent(uri)}`,
undefined, 10000,
);
return res.ok ? res.result : null;
}
/** GET /api/v1/content/overview — L1 overview (directories only) */
async overview(uri: string): Promise<string | null> {
const res = await this.fetchJSON<string>(
`/api/v1/content/overview?uri=${encodeURIComponent(uri)}`,
undefined, 10000,
);
return res.ok ? res.result : null;
}
/** GET /api/v1/content/read — L2 full content (files only) */
async readContent(uri: string): Promise<string | null> {
const res = await this.fetchJSON<string>(
`/api/v1/content/read?uri=${encodeURIComponent(uri)}`,
undefined, 10000,
);
return res.ok ? res.result : null;
}
// ========== Filesystem ==========
/** GET /api/v1/fs/ls — list directory */
async ls(uri: string): Promise<OVDirEntry[]> {
const res = await this.fetchJSON<any[]>(
`/api/v1/fs/ls?uri=${encodeURIComponent(uri)}`,
undefined, 10000,
);
if (!res.ok || !Array.isArray(res.result)) return [];
return res.result.map(e => ({
uri: e.uri ?? "",
name: e.name ?? uriBasename(e.uri ?? ""),
isDir: e.isDir ?? false,
size: e.size ?? 0,
mode: e.mode ?? 0,
modTime: e.modTime ?? "",
abstract: e.abstract ?? "",
}));
}
/** GET /api/v1/fs/stat — file/directory metadata */
async stat(uri: string): Promise<OVStatInfo | null> {
const res = await this.fetchJSON<OVStatInfo>(
`/api/v1/fs/stat?uri=${encodeURIComponent(uri)}`,
undefined, 10000,
);
return res.ok ? res.result : null;
}
/** DELETE /api/v1/fs — remove file or directory */
async delete(uri: string, recursive = false): Promise<boolean> {
const res = await this.fetchJSON<any>(
`/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=${recursive}`,
{ method: "DELETE" },
10000,
);
return res.ok;
}
// ========== Resources ==========
/** POST /api/v1/resources — ingest a URL or file path */
async addResource(
path: string, opts?: { to?: string },
): Promise<{ root_uri: string } | null> {
const body: Record<string, unknown> = { path };
if (opts?.to) body.to = opts.to;
const res = await this.fetchJSON<{ root_uri: string }>(
"/api/v1/resources",
{ method: "POST", body: JSON.stringify(body) },
30000,
);
return res.ok ? res.result : null;
}
// ========== URI Space Resolution ==========
async resolveScopeSpace(scope: "user" | "agent"): Promise<string> {
const cached = this.resolvedSpaces.get(scope);
if (cached) return cached;
// Probe system status for user identity fallback
let fallbackSpace = "default";
const statusRes = await this.fetchJSON<any>("/api/v1/system/status", undefined, 5000);
if (statusRes.ok && typeof statusRes.result?.user === "string" && statusRes.result.user.trim()) {
fallbackSpace = statusRes.result.user.trim();
}
// List scope root for actual namespaces
const reserved = scope === "user" ? OVClient.RESERVED_USER : OVClient.RESERVED_AGENT;
const entries = await this.ls(`viking://${scope}/`);
const spaces = entries
.filter(e => e.isDir && !e.name.startsWith(".") && !reserved.has(e.name))
.map(e => e.name);
if (spaces.length > 0) {
// Prefer the fallback space if it exists, then "default", then first available
let chosen = spaces[0];
if (spaces.includes(fallbackSpace)) chosen = fallbackSpace;
else if (spaces.includes("default")) chosen = "default";
this.resolvedSpaces.set(scope, chosen);
return chosen;
}
this.resolvedSpaces.set(scope, fallbackSpace);
return fallbackSpace;
}
async resolveTargetUri(targetUri: string): Promise<string> {
const trimmed = targetUri.trim().replace(/\/+$/, "");
const m = trimmed.match(/^viking:\/\/(user|agent)(?:\/(.*))?$/);
if (!m) return trimmed;
const scope = m[1] as "user" | "agent";
const rawRest = (m[2] ?? "").trim();
if (!rawRest) return trimmed;
const parts = rawRest.split("/").filter(Boolean);
if (parts.length === 0) return trimmed;
const reserved = scope === "user" ? OVClient.RESERVED_USER : OVClient.RESERVED_AGENT;
if (!reserved.has(parts[0])) return trimmed; // already has space
const space = await this.resolveScopeSpace(scope);
return `viking://${scope}/${space}/${parts.join("/")}`;
}
}
function uriBasename(uri: string): string {
const cleaned = uri.replace(/\/+$/, "");
const last = cleaned.lastIndexOf("/");
return last >= 0 ? cleaned.slice(last + 1) : cleaned;
}
const ARCHIVE_ID_RE = /^archive_\d+$/;
/**
* "The path is not there" as opposed to "the request failed". A session that
* never committed has no `history` directory, which is an empty archive list,
* not an unreachable server.
*/
function isNotFound(res: { status?: number; error?: any }): boolean {
if (res.status === 404) return true;
const code = String(res.error?.code ?? res.error?.message ?? "");
return /NOT_?FOUND/i.test(code);
}
function stripTrailingSlash(uri: string): string {
return uri.replace(/\/+$/, "");
}
/** `viking://…/sessions/x/history/archive_003` → `viking://…/sessions/x`. */
export function archiveUriToRoot(archiveUri: string): string {
const cleaned = stripTrailingSlash(String(archiveUri ?? "").trim());
return cleaned.replace(/\/history\/archive_\d+(?:\/.*)?$/, "");
}
/** First `archive_NNN` segment of a URI, "" when there is none. */
export function archiveIdFromUri(uri: string): string {
for (const seg of stripTrailingSlash(String(uri ?? "")).split("/")) {
if (ARCHIVE_ID_RE.test(seg)) return seg;
}
return "";
}
/** Path inside the archive directory, e.g. `messages.jsonl` / `.overview.md`. */
function archiveFileFromUri(uri: string): string {
const segs = stripTrailingSlash(String(uri ?? "")).split("/");
const at = segs.findIndex(s => ARCHIVE_ID_RE.test(s));
if (at >= 0) return segs.slice(at + 1).join("/");
return segs.length ? segs[segs.length - 1] : "";
}
function archiveIndex(archiveId: string): number {
const n = Number.parseInt(archiveId.replace(/^archive_/, ""), 10);
return Number.isFinite(n) ? n : -1;
}
function escapeRegExp(text: string): string {
return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
/**
* Drop a leading `---` … `---` YAML frontmatter block, if the text opens with
* one, together with the blank line the server writes after it (its sidecars
* are rendered as `---\n<yaml>\n---\n\n<body>\n`).
*/
function stripFrontmatter(text: string): string {
const m = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
if (!m) return text;
return text.slice(m[0].length).replace(/^(?:[ \t]*\r?\n)+/, "");
}
function safeStringify(value: unknown): string {
try {
return JSON.stringify(value) ?? String(value);
} catch {
return String(value);
}
}
function renderValue(value: unknown): string {
if (value == null) return "";
return typeof value === "string" ? value : safeStringify(value);
}
/**
* Render one `tool` part.
*
* The server serializes a tool part as `{type:"tool", tool_id, tool_name,
* tool_uri, skill_uri, tool_status, tool_input?, tool_output?, …}` (see
* `openviking/message/message.py::_part_to_dict`) — a call carries only
* `tool_input`, a result carries `tool_output`. Older/foreign shapes
* (`output` / `result` / `input` / `arguments`) are still accepted.
*
* The `[tool <name>]` label is emitted even when both sides are empty: a
* message whose only part is a tool call must not read back as blank, which is
* the whole promise of the `history` tool.
*/
function renderToolPart(part: any): string {
const rawName = part.tool_name ?? part.toolName ?? part.name ?? "";
const name = String(rawName ?? "").trim() || "unknown";
const input = renderValue(part.tool_input ?? part.input ?? part.arguments ?? part.args);
let output = renderValue(part.tool_output ?? part.output ?? part.result);
if (!output && typeof part.content === "string") output = part.content;
if (!output && typeof part.text === "string") output = part.text;
// Large outputs are stored outside the message; point at them instead of
// rendering an empty result.
if (!output && typeof part.tool_output_ref === "string" && part.tool_output_ref) {
output = `<output stored at ${part.tool_output_ref}>`;
}
const chunks: string[] = [];
if (input) chunks.push(input);
if (output) chunks.push(output);
return chunks.length ? `[tool ${name}] ${chunks.join(" ")}` : `[tool ${name}]`;
}
/** Render one archived part; unknown shapes render to "" and are dropped. */
function renderPart(part: any): string {
if (part == null) return "";
if (typeof part === "string") return part;
if (typeof part !== "object") return "";
const type = typeof part.type === "string" ? part.type : "";
const isTool = type.includes("tool")
|| part.tool_name != null || part.toolName != null
|| part.tool_output != null || part.tool_input != null;
if (isTool) return renderToolPart(part);
if (type === "context") {
const uri = typeof part.uri === "string" ? part.uri : "";
const abstract = typeof part.abstract === "string" ? part.abstract.trim() : "";
if (!uri && !abstract) return "";
return abstract ? `[context ${uri}] ${abstract}` : `[context ${uri}]`;
}
if (type === "image") return "[image]";
if (typeof part.text === "string") return part.text;
if (typeof part.content === "string") return part.content;
return "";
}
function renderMessageText(parts: any[], content?: unknown): string {
const chunks: string[] = [];
for (const part of parts) {
const rendered = renderPart(part);
if (rendered) chunks.push(rendered);
}
if (chunks.length === 0 && typeof content === "string") return content;
return chunks.join("\n");
}