Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
/**
* Root-only lifecycle operations: list checkpoints, restore a page, purge a
* session or a whole project. Imported from a separate entry point,
* `ai-memory-ts/admin`, so an application that only reads and writes pages
* never loads code that can purge a project.
*
* ```ts
* import { AdminClient } from "ai-memory-ts/admin";
*
* const admin = new AdminClient({ serverUrl, token: rootToken });
* const preview = await admin.purgeSession({ workspace, project, sessionId });
* // preview.dryRun === true: counts only, nothing deleted
* await admin.purgeSession({ workspace, project, sessionId, dryRun: false, confirm: true });
* ```
*
* Every `/admin/*` route is root-only once the server has a DB user or
* trusted-proxy identities; a user `aim_` key is always user-level and gets
* {@link ForbiddenError}.
*
* @module
*/
import { requireText } from "./core.js";
import { array, num, optStr, record, str, strings } from "./decode.js";
import { ArgumentError, ProtocolError } from "./errors.js";
import { validateScope } from "./scope.js";
import { Transport, type CallOptions, type ConnectionOptions } from "./transport.js";
import type { Raw } from "./types.js";
export {
AbortError,
AiMemoryError,
ArgumentError,
AuthError,
ConfigError,
ForbiddenError,
HttpError,
NotFoundError,
ProtocolError,
RateLimitedError,
ScopeError,
TimeoutError,
TransportError,
} from "./errors.js";
export type { CallOptions, ConnectionOptions, FetchLike } from "./transport.js";
/** Options of {@link AdminClient}: connection settings only, no default scope. */
export type AdminClientOptions = ConnectionOptions;
/** One wiki git checkpoint. */
export interface Checkpoint {
/** Full commit id; usable as `rev` in {@link AdminClient.restorePage}. */
readonly oid: string;
/** First 12 hex characters. */
readonly shortOid: string;
/** Commit time in seconds since the Unix epoch. */
readonly time: number;
/** First line of the commit message (`memory_delete_page: <path>` for a delete). */
readonly summary: string;
}
/** Arguments of {@link AdminClient.restorePage}. */
export interface RestorePageArgs {
/** Workspace; must exist. */
workspace: string;
/** Project; must exist. */
project: string;
/** Wiki path to restore. */
path: string;
/**
* A git revision that still holds the page: a delete's `preCheckpoint`, or
* `<checkpoint>~1` when `preCheckpoint` was `null`.
*/
rev: string;
}
/** Result of {@link AdminClient.restorePage}. */
export interface RestorePageResult {
/** The new latest version id of the restored page. */
readonly pageId: string;
/** Path restored. */
readonly path: string;
/** The revision it came from. */
readonly restoredFrom: string;
/** Checkpoint taken before the restore, when the tree had changes. */
readonly preCheckpoint: string | undefined;
/** Checkpoint recording the restore, when it changed the tree. */
readonly checkpoint: string | undefined;
/** The server's decoded JSON. */
readonly raw: Raw;
}
/** Flags shared by both purges. */
interface PurgeFlags {
/**
* Preview only. Default `true`: the server reports the counts a purge
* would produce and deletes nothing.
*/
dryRun?: boolean;
/** Required, together with `dryRun: false`, for an irreversible purge. */
confirm?: boolean;
/** Rebuild the FTS indexes and `VACUUM` after a real purge to reclaim space. */
compact?: boolean;
}
/** Arguments of {@link AdminClient.purgeSession}. */
export interface PurgeSessionArgs extends PurgeFlags {
/** Workspace; must exist. */
workspace: string;
/** Project; must exist and own the session. */
project: string;
/** Full session UUID. */
sessionId: string;
}
/** Arguments of {@link AdminClient.purgeProject}. */
export interface PurgeProjectArgs extends PurgeFlags {
/** Workspace; must exist. */
workspace: string;
/** Project; must exist. */
project: string;
/**
* Purge even while a managed workstream under the project holds a live run
* lease. The running agent then loses the lease row and cannot save its
* history. Without it the server answers 409.
*/
force?: boolean;
}
/** Result of {@link AdminClient.purgeSession}. */
export interface PurgeSessionReport {
/** True for a preview: nothing was deleted. */
readonly dryRun: boolean;
/** Session purged (or previewed). */
readonly sessionId: string;
/** Observations deleted. */
readonly observationsDeleted: number;
/** Handoffs the session authored, deleted. */
readonly handoffsDeleted: number;
/** Page rows deleted, superseded versions included. */
readonly pagesDeleted: number;
/** Distinct page paths whose rows were deleted. */
readonly removedPaths: readonly string[];
/** The server's decoded JSON (collateral counts, files, checkpoints). */
readonly raw: Raw;
}
/** Result of {@link AdminClient.purgeProject}. */
export interface PurgeProjectReport {
/** True for a preview: nothing was deleted. */
readonly dryRun: boolean;
/** Page rows deleted. */
readonly pagesDeleted: number;
/** Sessions deleted. */
readonly sessionsDeleted: number;
/** Observations deleted. */
readonly observationsDeleted: number;
/** Handoffs deleted. */
readonly handoffsDeleted: number;
/** The server's decoded JSON (collateral counts, files, checkpoints). */
readonly raw: Raw;
}
/**
* Decide whether a purge is a preview, refusing an irreversible call that
* lacks either flag before anything is sent.
*/
function purgeMode(args: PurgeFlags, where: string): { dryRun: boolean } {
if (args.dryRun !== undefined && typeof args.dryRun !== "boolean") {
throw new ArgumentError(`${where}: dryRun must be a boolean`);
}
const dryRun = args.dryRun !== false;
if (!dryRun && args.confirm !== true) {
throw new ArgumentError(
`${where}: an irreversible purge needs dryRun: false and confirm: true in the same call`,
);
}
return { dryRun };
}
function adminArgs<T extends object>(value: T, where: string): T {
if (value === null || typeof value !== "object" || Array.isArray(value)) {
throw new ArgumentError(`${where}: arguments must be an object`);
}
return value;
}
/**
* Client for the root-only `/admin/*` lifecycle routes. Every method needs
* the server's root token once the server has DB users.
*/
export class AdminClient {
readonly #transport: Transport;
/** @throws {@link ConfigError} for an unusable URL, token or timeout. */
constructor(options: AdminClientOptions) {
this.#transport = new Transport(options);
}
/** The server URL the client talks to. */
get serverUrl(): string {
return this.#transport.serverUrl;
}
async #post(path: string, body: unknown, mutating: boolean, options?: CallOptions) {
return this.#transport.json("POST", path, { json: body, route: "admin", mutating }, options);
}
/** Recent wiki checkpoints, newest first (up to 100). `GET /admin/checkpoints`. */
async checkpoints(args: { limit?: number } = {}, options?: CallOptions): Promise<Checkpoint[]> {
const a = adminArgs(args, "checkpoints");
const body = await this.#transport.json(
"GET",
"/admin/checkpoints",
{
query: { limit: a.limit === undefined ? undefined : String(a.limit) },
route: "admin",
mutating: false,
},
options,
);
return array(body, "/admin/checkpoints").map((item, index) => {
const where = `/admin/checkpoints[${index}]`;
const o = record(item, where);
return {
oid: str(o, "oid", where),
shortOid: str(o, "short_oid", where),
time: num(o, "time", where),
summary: this.#transport.safeText(str(o, "summary", where)),
};
});
}
/**
* Write a page's content at `rev` back as its latest version. There is no
* dry run: this always writes a new version (the server checkpoints first).
* `POST /admin/restore-page`.
*/
async restorePage(args: RestorePageArgs, options?: CallOptions): Promise<RestorePageResult> {
const where = "restorePage";
const a = adminArgs(args, where);
const scope = validateScope({ workspace: a.workspace, project: a.project }, where);
requireText(a.path, "path", where);
requireText(a.rev, "rev", where);
const body = await this.#post(
"/admin/restore-page",
{ workspace: scope.workspace, project: scope.project, path: a.path, rev: a.rev },
true,
options,
);
const o = record(body, "/admin/restore-page");
return {
pageId: str(o, "page_id", "/admin/restore-page"),
path: str(o, "path", "/admin/restore-page"),
restoredFrom: str(o, "restored_from", "/admin/restore-page"),
preCheckpoint: optStr(o, "pre_checkpoint", "/admin/restore-page"),
checkpoint: optStr(o, "checkpoint", "/admin/restore-page"),
raw: o,
};
}
/**
* Purge one session: its observations, the handoffs it authored and the
* pages it produced. Defaults to a dry run. An irreversible purge needs
* `dryRun: false` and `confirm: true` together; otherwise the call is
* refused with {@link ArgumentError} before anything is sent.
* `POST /admin/purge-session`.
*/
async purgeSession(args: PurgeSessionArgs, options?: CallOptions): Promise<PurgeSessionReport> {
const where = "purgeSession";
const a = adminArgs(args, where);
const scope = validateScope({ workspace: a.workspace, project: a.project }, where);
requireText(a.sessionId, "sessionId", where);
const { dryRun } = purgeMode(a, where);
const body = await this.#post(
"/admin/purge-session",
{
workspace: scope.workspace,
project: scope.project,
session_id: a.sessionId,
// A preview always sends confirm: false, so a server that ignored
// dry_run would refuse instead of purging.
confirm: !dryRun,
dry_run: dryRun,
compact: a.compact === true,
},
!dryRun,
options,
);
const path = "/admin/purge-session";
const o = record(body, path);
const reportedDryRun = o["dry_run"] === true;
if (dryRun && !reportedDryRun) {
throw new ProtocolError(`${path}: the server did not confirm a dry run`);
}
return {
dryRun: reportedDryRun,
sessionId: str(o, "session_id", path),
observationsDeleted: num(o, "observations_deleted", path),
handoffsDeleted: num(o, "handoffs_deleted", path),
pagesDeleted: num(o, "pages_deleted", path),
removedPaths: strings(o, "removed_paths", path),
raw: o,
};
}
/**
* Purge a whole project: every page, session, observation and handoff, and
* its wiki directory. Defaults to a dry run. An irreversible purge needs
* `dryRun: false` and `confirm: true` together. `force` is a separate flag
* that purges despite a live managed-workstream lease.
* `POST /admin/purge-project`.
*/
async purgeProject(args: PurgeProjectArgs, options?: CallOptions): Promise<PurgeProjectReport> {
const where = "purgeProject";
const a = adminArgs(args, where);
const scope = validateScope({ workspace: a.workspace, project: a.project }, where);
const { dryRun } = purgeMode(a, where);
if (a.force !== undefined && typeof a.force !== "boolean") {
throw new ArgumentError(`${where}: force must be a boolean`);
}
const body = await this.#post(
"/admin/purge-project",
{
workspace: scope.workspace,
project: scope.project,
confirm: !dryRun,
dry_run: dryRun,
compact: a.compact === true,
force: a.force === true,
},
!dryRun,
options,
);
const path = "/admin/purge-project";
const o = record(body, path);
const reportedDryRun = o["dry_run"] === true;
if (dryRun && !reportedDryRun) {
throw new ProtocolError(`${path}: the server did not confirm a dry run`);
}
return {
dryRun: reportedDryRun,
pagesDeleted: num(o, "pages_deleted", path),
sessionsDeleted: num(o, "sessions_deleted", path),
observationsDeleted: num(o, "observations_deleted", path),
handoffsDeleted: num(o, "handoffs_deleted", path),
raw: o,
};
}
/** Serialized form: the server URL, never the token. */
toJSON(): Record<string, unknown> {
return this.#transport.toJSON();
}
/** @internal */
[Symbol.for("nodejs.util.inspect.custom")](): string {
return `AdminClient ${JSON.stringify(this.toJSON())}`;
}
}