Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/** Dedicated, bounded local persistence transport. Hook IPC keeps its own small frame budget. */
import net, { type Server, type Socket } from 'node:net';
import { randomUUID } from 'node:crypto';
import { chmodSync, lstatSync, unlinkSync } from 'node:fs';
import { isAbsolute } from 'node:path';
import { OperationError, opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { redactConnectionInfo } from '../audit/redact-connection-info.ts';
import type { Action } from '../agent-output.ts';
import type { ProjectionBacklog } from '../page-state/projections.ts';
import { resolveSocketPathForConfig, socketHasLiveListener } from '../context/resolve-ipc.ts';
import { ownerExceptionFailure, ownerExceptionLogText } from './publication-failure.ts';
import { isWriteErrorCode, isWriteReceipt, isWriteRequestId, publicWriteReceipt, type WriteReceipt } from './types.ts';
import { isPersistenceAdminExtension, isPersistenceAdminOperation, PERSISTENCE_ADMIN_EXTENSIONS, PERSISTENCE_ADMIN_OPERATIONS, type PersistenceAdminExtension, type PersistenceAdminOperation } from './admin-contract.ts';
import { claimLocalIpcBinding, isWindowsIpcPipe, prepareLocalIpcPath } from '../context/ipc-path.ts';
export const PERSISTENCE_IPC_VERSION = 1;
// Five million content bytes can require six JSON bytes each (e.g. NUL).
// Leave bounded room for frontmatter, credentials, routing, and the envelope.
export const PERSISTENCE_IPC_MAX_BYTES = 32 * 1024 * 1024;
export const PERSISTENCE_IPC_MAX_CONNECTIONS = 8;
export const PERSISTENCE_IPC_OPERATIONS = [
'put_page', 'put_pages', 'capture', 'delete_page', 'restore_page', 'revert_version', 'edit_page', 'append_page',
'remember', 'forget', 'extract_facts', 'get_write_request', 'list_write_requests', 'cancel_write_request',
'get_page', 'fetch', 'get_recent_transcripts',
'list_skills', 'get_skill', 'get_skill_asset', 'list_brain_skillpack',
'put_skill', 'delete_skill', 'join_brain', 'sync_brain_skills', 'leave_brain',
'get_skill_policy', 'set_skill_policy', 'get_skill_retention', 'prune_skill_revisions',
'retain_skill_revision', 'import_skill_proposal',
'add_tag', 'remove_tag', 'add_timeline_entry', 'add_link', 'remove_link', 'takes_add', 'takes_update', 'takes_supersede', 'takes_resolve', 'takes_remove', 'takes_rebuild',
'purge_fact', 'list_page_purges', 'unpurge_page',
] as const;
/**
* Owner-only operations the resident owner runs for its verified local CLI
* registration alone (never for a stdio or HTTP MCP session it also hosts),
* whatever the writer grant's scopes. The CLI asks for the user's typed
* confirmation before it sends one; the handler re-checks that binding.
*/
export const LOCAL_CLI_OWNER_OPERATIONS: ReadonlySet<string> = new Set(['purge_fact', 'list_page_purges', 'unpurge_page']);
export type PersistenceIpcOperation = typeof PERSISTENCE_IPC_OPERATIONS[number];
const OPERATIONS = new Set<string>(PERSISTENCE_IPC_OPERATIONS);
const MUTATIONS = new Set<string>([
'put_page', 'put_pages', 'capture', 'delete_page', 'restore_page', 'revert_version', 'edit_page', 'append_page', 'remember', 'forget', 'extract_facts',
'put_skill', 'delete_skill', 'import_skill_proposal',
'add_tag', 'remove_tag', 'add_timeline_entry', 'add_link', 'remove_link', 'takes_add', 'takes_update', 'takes_supersede', 'takes_resolve', 'takes_remove', 'takes_rebuild',
]);
export interface PersistenceIpcRegistration {
id: string;
credential: string;
lane: 'cli' | 'stdio';
}
export interface PersistenceIpcRequest {
version: 1;
kind: 'operation';
brain_id: string;
operation: PersistenceIpcOperation;
params: Record<string, unknown>;
registration: PersistenceIpcRegistration;
/** Client resolves flag/env/dotfile tiers; owner resolves DB tiers using this cwd. */
routing: { source: string | null; cwd: string };
/** #5232: the caller's commit wait; sent only to owners advertising `write_wait`. */
write_wait_ms?: number;
/** GBRA-498: the room the CLI's `--room` named; sent only to owners advertising `room`, which answer `{ [PERSISTENCE_ROOM_MARKED_KEY]: … }`. */
room?: string;
}
export interface PersistenceIpcCapabilities {
version: 1;
brain_id: string;
operations: readonly PersistenceIpcOperation[];
max_frame_bytes: number;
/** Optional for protocol compatibility with owners predating local administration. Frozen: new operations go in `administration_extensions`. */
administration?: readonly PersistenceAdminOperation[];
/** #6650: administration added after `administration` froze; older clients ignore the key, a client keeps only the entries it knows. */
administration_extensions?: readonly PersistenceAdminExtension[];
/** #5232: the owner honors `write_wait_ms` on operation requests. */
write_wait?: true;
/** GBRA-498: the owner marks its trusted local CLI's answer for a `room` on operation requests. */
room?: true;
}
/** GBRA-498: the one key of an owner's answer to a request that named a room: the marked result, its room meta and notices. */
export const PERSISTENCE_ROOM_MARKED_KEY = 'room_marked';
/** The longest `--room` a request carries; a longer one stays with the CLI, which marks every item unknown. */
export const PERSISTENCE_ROOM_MAX_CHARS = 4_096;
export interface PersistenceIpcAdminRequest {
version: 1;
kind: 'administration';
brain_id: string;
operation: PersistenceAdminOperation;
params: Record<string, unknown>;
registration: PersistenceIpcRegistration;
}
/**
* #5401: the resident's queued text-projection backlog. Counts only, never
* identifiers. #6803: `pending` and `failed` keep their meaning (rows the
* resident drains); the class counts are optional, so an older doctor reading
* a new reply sees an unchanged `pending` and a new doctor reading an old one
* knows the resident predates them.
*/
export type PersistenceProjectionStatus = ProjectionBacklog;
const PROJECTION_CLASS_KEYS = ['sealable', 'sealable_with_visual', 'reimport', 'ocr_required', 'protected', 'archived'] as const;
export interface PersistenceIpcProvider {
brainId: string;
/** Read-only and credential-free, like capabilities: serves doctor while this process holds the datastore. */
projectionStatus?(): Promise<PersistenceProjectionStatus>;
/** Authenticate registration against the DB, reconstruct context, then dispatch through the registry. */
dispatch(request: PersistenceIpcRequest): Promise<unknown>;
/** Verify the live CLI registration again; never accept stdio or a wire trust assertion. */
administer?(request: PersistenceIpcAdminRequest): Promise<unknown>;
}
export interface PersistenceIpcBinding {
server: Server;
socketPath: string;
/** Stops admission. In-flight durable work is drained by the owner's persistence lifecycle. */
close(): void;
}
export function isPersistenceIpcOperation(value: unknown): value is PersistenceIpcOperation {
return typeof value === 'string' && OPERATIONS.has(value);
}
export function isPersistenceIpcMutation(value: string): boolean {
return MUTATIONS.has(value);
}
export function persistenceSocketPathForConfig(config: Parameters<typeof resolveSocketPathForConfig>[0]): string | null {
return resolveSocketPathForConfig(config, 'persistence');
}
function record(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
return Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
}
export function isPersistenceIpcRegistration(value: unknown): value is PersistenceIpcRegistration {
return record(value) && exactKeys(value, ['id', 'credential', 'lane'])
&& isWriteRequestId(value.id)
&& typeof value.credential === 'string' && /^[a-f0-9]{64}$/.test(value.credential)
&& (value.lane === 'cli' || value.lane === 'stdio');
}
const OPERATION_REQUEST_KEYS = ['version', 'kind', 'brain_id', 'operation', 'params', 'registration', 'routing'];
function operationRequest(value: unknown): value is PersistenceIpcRequest {
if (!record(value) || !exactKeys(value, [...OPERATION_REQUEST_KEYS, ...['write_wait_ms', 'room'].filter(k => Object.prototype.hasOwnProperty.call(value, k))])) return false;
if (value.room !== undefined && !(typeof value.room === 'string' && value.room.length <= PERSISTENCE_ROOM_MAX_CHARS)) return false;
if (value.write_wait_ms !== undefined && !(typeof value.write_wait_ms === 'number'
&& Number.isSafeInteger(value.write_wait_ms) && value.write_wait_ms >= 0)) return false;
if (value.version !== 1 || value.kind !== 'operation' || !isWriteRequestId(value.brain_id)
|| !isPersistenceIpcOperation(value.operation) || !record(value.params)
|| !isPersistenceIpcRegistration(value.registration) || !record(value.routing)
|| !exactKeys(value.routing, ['source', 'cwd'])) return false;
if (!(value.routing.source === null || typeof value.routing.source === 'string' && /^(?:[a-z0-9-]{1,32}|__all__)$/.test(value.routing.source))) return false;
if (typeof value.routing.cwd !== 'string' || value.routing.cwd.length > 32_768 || !isAbsolute(value.routing.cwd)) return false;
// Wire mutations always have an ID BEFORE bytes are sent. Never allocate
// an ID on the listener: a lost acknowledgment must be replayable.
return !isPersistenceIpcMutation(value.operation) || isWriteRequestId(value.params.request_id);
}
function administrationRequest(value: unknown): value is PersistenceIpcAdminRequest {
return record(value) && exactKeys(value, ['version', 'kind', 'brain_id', 'operation', 'params', 'registration'])
&& value.version === 1 && value.kind === 'administration' && isWriteRequestId(value.brain_id)
&& isPersistenceAdminOperation(value.operation) && record(value.params)
&& isPersistenceIpcRegistration(value.registration) && value.registration.lane === 'cli';
}
const writerStatusFix = (why: string): Action => readFix(why, { argv: ['gbrain', 'sources', 'writer', 'status', '--json'] });
const ownerVersionsFix = (): Action => writerStatusFix(
'Shows the running owner, this host and the latest admitter and consumer versions per host, read-only, to spot a CLI and owner on different releases.');
const clientBug = (message: string): OperationError => opError('invalid_params', message,
'This gbrain build produced a malformed local persistence request, so nothing was sent to the owner. It is a client fault, not a caller mistake: run gbrain doctor --json on this host and report it to the user with the command that failed.',
{ fix: readFix('Checks this installation and its persistence owner without changing anything.', { argv: ['gbrain', 'doctor', '--json'] }) });
/**
* #9224: an owner fault that is not an OperationError crosses the socket as `internal_error` with an incident ID,
* how to recover and a read-only fix naming the owner; the cause itself goes only to the owner's own stderr.
*/
function publicError(error: unknown, requestId?: string): Record<string, unknown> {
if (error instanceof OperationError) return error.toJSON();
const incident = randomUUID();
// Never reflect driver errors, SQL, credentials, or private payloads: the cause stays on this host's owner log.
try {
process.stderr.write(`[gbrain persistence] request failed in this owner (incident ${incident}):${redactConnectionInfo(ownerExceptionLogText(ownerExceptionFailure(error).detail))}\n`);
} catch { /* stderr gone */ }
return opError('internal_error', `The persistence owner failed while running this request (incident ${incident}); the request itself was not at fault.`,
`The process that holds this brain (the command in fix names it) hit an internal fault and wrote the cause to its own stderr under incident ${incident}; nothing about it crosses the local socket. ${requestId
? `The write may have partly run: inspect request ${requestId} with gbrain write-request ${requestId} before resubmitting it. `
: ''}Restart that owner (for a gbrain serve an agent app launched, restart its MCP server or the agent session), then run the same command again; with no owner running, the CLI opens the brain itself. If it fails again after a restart, tell the user and give them the incident ID.`,
{ detail: 'owner_internal', fix: writerStatusFix('Names the process that owns this brain (its PID, lane and gbrain version), read-only, so it can be restarted.') }).toJSON();
}
function responseFrame(value: unknown): string {
const frame = JSON.stringify(value) + '\n';
if (Buffer.byteLength(frame) > PERSISTENCE_IPC_MAX_BYTES) {
throw opError('response_too_large', 'Persistence response exceeds the local transport limit.',
`Nothing larger than ${PERSISTENCE_IPC_MAX_BYTES} bytes crosses the local persistence socket, so this frame was not delivered. A write may still have committed on the owner: inspect it by its request_id (get_write_request, or gbrain write-request on the CLI) before resubmitting; for a read, ask for less (a smaller page, limit or selection).`);
}
return frame;
}
/** Bind only when no live listener owns the discovery path. Never displace on timeout. */
export async function startPersistenceIpcServer(
socketPath: string,
provider: PersistenceIpcProvider,
): Promise<PersistenceIpcBinding | null> {
if (!isWriteRequestId(provider.brainId)) throw new Error('Persistence IPC requires a durable brain UUID.');
const binding = await claimLocalIpcBinding(socketPath);
if (!binding) return null;
socketPath = binding.socketPath;
if (await socketHasLiveListener(socketPath)) { await binding.release(); return null; }
try {
// Refuse to remove ordinary files or symlinks from the discovery path.
if (binding.removeStaleWindowsSocket) binding.removeStaleWindowsSocket();
else if (!isWindowsIpcPipe(socketPath)) {
if (!lstatSync(socketPath).isSocket()) throw new Error('Persistence IPC path is not a socket.');
unlinkSync(socketPath);
}
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') { await binding.release(); throw error; }
}
const sockets = new Set<Socket>();
let active = 0;
let closing = false;
const server = net.createServer(socket => {
socket.on('error', () => { /* transport loss never cancels durable work */ });
if (closing || sockets.size >= PERSISTENCE_IPC_MAX_CONNECTIONS) { socket.destroy(); return; }
sockets.add(socket);
socket.once('close', () => sockets.delete(socket));
let chunks: Buffer[] = [];
let bytes = 0;
let handled = false;
const readTimeout = setTimeout(() => socket.destroy(), 15_000);
readTimeout.unref();
socket.once('close', () => clearTimeout(readTimeout));
socket.on('data', data => {
const chunk = typeof data === 'string' ? Buffer.from(data) : data;
if (handled) return;
bytes += chunk.length;
if (bytes > PERSISTENCE_IPC_MAX_BYTES) { handled = true; socket.destroy(); return; }
const newline = chunk.indexOf(10);
chunks.push(newline === -1 ? chunk : chunk.subarray(0, newline));
if (newline === -1) return;
handled = true; // latch before async dispatch, even if another frame arrives
clearTimeout(readTimeout);
const payload = Buffer.concat(chunks).toString('utf8');
chunks = [];
void (async () => {
let admitted = false;
let mutation: { requestId: string; receipt?: WriteReceipt } | undefined;
try {
const request: unknown = JSON.parse(payload);
if (record(request) && exactKeys(request, ['version', 'kind']) && request.version === 1 && request.kind === 'capabilities') {
socket.end(responseFrame({ version: 1, ok: true, result: {
version: 1, brain_id: provider.brainId, operations: PERSISTENCE_IPC_OPERATIONS,
max_frame_bytes: PERSISTENCE_IPC_MAX_BYTES,
...(provider.administer ? { administration: PERSISTENCE_ADMIN_OPERATIONS, administration_extensions: PERSISTENCE_ADMIN_EXTENSIONS } : {}),
write_wait: true,
room: true,
} satisfies PersistenceIpcCapabilities }));
return;
}
if (record(request) && exactKeys(request, ['version', 'kind']) && request.version === 1 && request.kind === 'projection_status') {
if (!provider.projectionStatus) throw opError('unavailable', 'This owner does not report projection status.',
'The running persistence owner predates projection status reporting, so the status could not be read; nothing changed. Restart the owner on this gbrain release, or read the owner state with the command in fix instead.',
{ fix: ownerVersionsFix() });
if (active >= PERSISTENCE_IPC_MAX_CONNECTIONS) throw opError('queue_capacity', 'The persistence listener is at capacity; retry shortly.',
`All ${PERSISTENCE_IPC_MAX_CONNECTIONS} local persistence connections are busy. This status read changed nothing, so read it again in a few seconds.`);
active++;
admitted = true;
const status = await provider.projectionStatus();
if (!socket.destroyed) socket.end(responseFrame({ version: 1, ok: true, result: status }));
return;
}
if (!operationRequest(request) && !administrationRequest(request)) throw opError('invalid_params', 'Invalid persistence request envelope.',
'The owner rejected the request frame as malformed, so nothing was admitted. This usually means the CLI and the running owner are different gbrain releases: compare them with the command in fix, restart the owner on the CLI\'s release, then submit the request again.',
{ fix: ownerVersionsFix() });
if (request.brain_id !== provider.brainId) throw opError('source_changed', 'The persistence listener now serves a different brain.',
`This socket's owner serves brain ${provider.brainId}, not the brain ${request.brain_id} the request was built for, so nothing was admitted. Check which brain the command targets (its brain selection) against the owner in fix, then submit the request again.`,
{ fix: writerStatusFix('Shows the brain this host\'s owner serves and its sources, read-only.') });
if (active >= PERSISTENCE_IPC_MAX_CONNECTIONS) throw opError('queue_capacity', 'The persistence listener is at capacity; retry this request ID.',
`All ${PERSISTENCE_IPC_MAX_CONNECTIONS} local persistence connections are busy, so this request was not admitted. Submit it again in a few seconds with the same arguments and the same request_id${typeof request.params.request_id === 'string' ? ` (${request.params.request_id})` : ''}; never allocate a replacement ID.`);
active++;
admitted = true;
if (request.kind === 'administration' && !provider.administer) throw opError('unavailable', 'This owner does not support local administration.',
'The running persistence owner was started without local administration (an older release or a non-CLI owner), so nothing ran. Restart the owner on this gbrain release, or stop it and run the administration command from the gbrain CLI on this host.',
{ fix: ownerVersionsFix() });
if (request.kind === 'operation' && isPersistenceIpcMutation(request.operation)) mutation = { requestId: request.params.request_id as string };
const result = request.kind === 'administration' ? await provider.administer!(request) : await provider.dispatch(request);
if (mutation && record(result) && isWriteReceipt(result.write_request)) mutation.receipt = result.write_request;
if (!socket.destroyed) socket.end(responseFrame({ version: 1, ok: true, result }));
} catch (error) {
// #6989: a write whose reply is too large to frame may have committed; the error carries its request ID (and
// receipt, when the result held one) so the advice to inspect it is actionable. A read gets none.
if (mutation && error instanceof OperationError && error.code === 'response_too_large') {
error.requestId = mutation.requestId;
if (mutation.receipt) error.writeRequest = publicWriteReceipt(mutation.receipt);
}
if (!socket.destroyed) socket.end(responseFrame({ version: 1, ok: false, error: publicError(error, mutation?.requestId) }));
} finally {
if (admitted) active--;
}
})();
});
});
let listened = false;
server.once('close', () => { void binding.release(); });
const bound = await new Promise<boolean>((resolve, reject) => {
const onError = (error: NodeJS.ErrnoException) => {
if (error.code === 'EADDRINUSE') resolve(false);
else reject(error);
};
server.once('error', onError);
server.listen(socketPath, () => {
listened = true;
try {
if (process.platform !== 'win32') chmodSync(socketPath, 0o600);
server.off('error', onError);
server.on('error', () => {});
resolve(true);
} catch (error) {
closing = true;
server.close();
for (const socket of sockets) socket.destroy();
reject(error);
}
});
}).catch(async error => { if (!listened) await binding.release(); throw error; });
if (!bound) { await binding.release(); return null; }
return {
server, socketPath,
close() {
if (closing) return;
closing = true;
server.close(); // own socket only; never blind-unlink a replacement owner
for (const socket of sockets) socket.destroy();
},
};
}
/** No receipt is fabricated when delivery is ambiguous: the durable state is unknown. */
export class PersistenceIpcTransportError extends Error {
constructor(public sent: boolean, public requestId?: string) {
super(sent && requestId
? `The persistence response was lost. Submission state is unknown for request ${requestId}.`
: 'The local persistence owner is unavailable.');
this.name = 'PersistenceIpcTransportError';
}
toJSON() {
return {
error: 'owner_unavailable', message: this.message,
...(this.requestId ? { request_id: this.requestId } : {}),
submission_status: this.sent ? 'unknown' : 'not_sent',
suggestion: this.requestId
? `Retry the same operation and arguments with request_id ${this.requestId}; do not generate a replacement ID.`
: this.sent ? 'Inspect writer status and local registrations before repeating administration; the acknowledgment was lost.'
: 'Restart the persistence owner, then retry.',
};
}
}
/**
* GST-1387: a wire error body's recovery contract (canonical code, detail, retryable, fix) restored onto a rebuilt
* OperationError, so a refresh fence stays worktree_refreshing with fix.next wait across the owner hop. Only the fence's
* fix (read-only, no consent) is carried: a rendered fix drops `ask_user`, and a receipt's fix is rendered on this side.
*/
export function restoreRecoveryContract(error: OperationError, body: Record<string, unknown>): void {
if (typeof body.code === 'string' && body.code !== error.code) error.canonical = body.code as OperationError['canonical'];
if (typeof body.detail === 'string') error.detail = body.detail;
if (typeof body.retryable === 'boolean') error.retryable = body.retryable;
if (record(body.fix) && body.code === 'worktree_refreshing') { const { next: _next, command: _command, ...fix } = body.fix; error.fix = fix as unknown as Action; }
}
function remoteOperationError(value: unknown): OperationError {
if (!record(value) || typeof value.error !== 'string' || typeof value.message !== 'string') {
throw new Error('Malformed persistence error response.');
}
const error = new OperationError(value.error, value.message, typeof value.suggestion === 'string' ? value.suggestion : undefined,
typeof value.docs === 'string' ? value.docs : undefined);
if (typeof value.protocol_version === 'number') error.protocolVersion = value.protocol_version;
restoreRecoveryContract(error, value);
if (isWriteReceipt(value.write_request)) error.writeRequest = publicWriteReceipt(value.write_request);
if (isWriteRequestId(value.request_id)) error.requestId = value.request_id;
if (isWriteErrorCode(value.write_error)) error.writeError = value.write_error;
if (typeof value.why === 'string') error.why = value.why;
if (typeof value.reason === 'string') error.reason = value.reason;
if (value.contract_version === 1) error.contractVersion = 1;
const fix = wireAction(value.fix);
if (fix) error.fix = fix;
return error;
}
/**
* #7707, #8130: the owner sends a refusal's `fix` already rendered (`toJSON`), or as the stored Action when it never loaded the renderer.
* Back to an Action, so a delegated refusal prints the same structured fix as the direct path; a value of any other shape is dropped.
*/
function wireAction(value: unknown): Action | undefined {
if (!record(value) || !Array.isArray(value.consent) || typeof value.actor !== 'string' || typeof value.why !== 'string'
|| typeof value.requires_exclusive !== 'boolean') return undefined;
const argv = Array.isArray(value.argv) && value.argv.every(arg => typeof arg === 'string') ? value.argv as string[] : undefined;
const mcp = record(value.mcp) && typeof value.mcp.tool === 'string' && record(value.mcp.arguments) ? value.mcp as unknown as Action['mcp'] : undefined;
if (!argv && !mcp) return undefined;
const then = value.then === undefined ? undefined : wireAction(value.then);
return {
...(value.next === 'ask_user' || value.ask_user === true ? { ask_user: true as const } : {}),
...(argv ? { argv } : {}), ...(mcp ? { mcp } : {}),
consent: value.consent as Action['consent'], actor: value.actor as Action['actor'], why: value.why, requires_exclusive: value.requires_exclusive,
...(typeof value.user_message === 'string' ? { user_message: value.user_message } : {}),
...(record(value.verify) ? { verify: value.verify as Action['verify'] } : {}),
...(typeof value.docs === 'string' ? { docs: value.docs } : {}),
...(Array.isArray(value.inputs) ? { inputs: value.inputs as Action['inputs'] } : {}),
...(typeof value.plan_hash === 'string' ? { plan_hash: value.plan_hash } : {}),
...(Array.isArray(value.preview_argv) && value.preview_argv.every(arg => typeof arg === 'string') ? { preview_argv: value.preview_argv as string[] } : {}),
...(then ? { then } : {}),
};
}
/** One bounded exchange. No automatic reconnect or replay after any request bytes are sent. */
async function exchange(socketPath: string, request: unknown, timeoutMs: number, requestId?: string): Promise<unknown> {
const frame = responseFrame(request);
try { socketPath = prepareLocalIpcPath(socketPath); }
catch { throw new PersistenceIpcTransportError(false, requestId); }
return new Promise((resolve, reject) => {
const socket = net.createConnection(socketPath);
let sent = false;
let done = false;
let bytes = 0;
const chunks: Buffer[] = [];
const settle = (error?: Error, result?: unknown) => {
if (done) return;
done = true;
clearTimeout(timer);
socket.destroy();
if (error) reject(error); else resolve(result);
};
const lost = () => settle(new PersistenceIpcTransportError(sent, requestId));
const timer = setTimeout(lost, timeoutMs);
socket.once('error', lost);
socket.once('close', () => { if (!done) lost(); });
socket.once('connect', () => {
sent = true; // partial writes are ambiguous too
socket.write(frame);
});
socket.on('data', data => {
const chunk = typeof data === 'string' ? Buffer.from(data) : data;
if (done) return;
bytes += chunk.length;
if (bytes > PERSISTENCE_IPC_MAX_BYTES) { lost(); return; }
const newline = chunk.indexOf(10);
chunks.push(newline === -1 ? chunk : chunk.subarray(0, newline));
if (newline === -1) return;
try {
const value: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'));
if (!record(value) || value.version !== 1 || typeof value.ok !== 'boolean') { lost(); return; }
if (value.ok) settle(undefined, value.result);
else {
const error = remoteOperationError(value.error);
// #6989: an owner that predates the server-side ID still answers a mutation's oversized reply without it.
if (requestId && error.code === 'response_too_large' && !error.requestId) error.requestId = requestId;
settle(error);
}
} catch { lost(); }
});
});
}
export async function requestPersistenceCapabilities(socketPath: string, timeoutMs = 2_000): Promise<PersistenceIpcCapabilities> {
const value = await exchange(socketPath, { version: 1, kind: 'capabilities' }, timeoutMs);
if (!record(value) || value.version !== 1 || !isWriteRequestId(value.brain_id)
|| !Array.isArray(value.operations) || !value.operations.every(isPersistenceIpcOperation)
|| value.administration !== undefined && (!Array.isArray(value.administration) || !value.administration.every(isPersistenceAdminOperation))
|| typeof value.max_frame_bytes !== 'number' || !Number.isSafeInteger(value.max_frame_bytes)
|| value.max_frame_bytes < 1 || value.max_frame_bytes > PERSISTENCE_IPC_MAX_BYTES) {
throw new PersistenceIpcTransportError(false);
}
// #6650: an extension list is advisory: a malformed one is dropped, an entry this build does not know is ignored.
const extensions = Array.isArray(value.administration_extensions) ? value.administration_extensions.filter(isPersistenceAdminExtension) : undefined;
const { administration_extensions: _ignored, ...rest } = value;
return { ...rest, ...(extensions ? { administration_extensions: extensions } : {}) } as unknown as PersistenceIpcCapabilities;
}
/** Whether a resident owner's capabilities include an administration operation (a frozen one or an extension). */
export function ownerAdministers(capability: Pick<PersistenceIpcCapabilities, 'administration' | 'administration_extensions'>, operation: PersistenceAdminOperation): boolean {
return isPersistenceAdminExtension(operation) ? capability.administration_extensions?.includes(operation) === true : capability.administration?.includes(operation) === true;
}
function count(value: unknown): value is number {
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
}
export async function requestPersistenceProjectionStatus(socketPath: string, timeoutMs = 2_000): Promise<PersistenceProjectionStatus> {
const value = await exchange(socketPath, { version: 1, kind: 'projection_status' }, timeoutMs);
if (!record(value) || !count(value.pending) || !count(value.failed)
|| !(value.oldest_age_seconds === null || count(value.oldest_age_seconds))) throw new PersistenceIpcTransportError(false);
const classes = Object.fromEntries(PROJECTION_CLASS_KEYS.flatMap(key => count(value[key]) ? [[key, value[key]]] : []));
return { pending: value.pending, failed: value.failed, oldest_age_seconds: value.oldest_age_seconds, ...classes,
...(typeof value.as_of === 'string' ? { as_of: value.as_of } : {}) };
}
export async function requestPersistenceOperation(socketPath: string, request: PersistenceIpcRequest, timeoutMs = 30_000): Promise<unknown> {
if (!operationRequest(request)) throw clientBug('Invalid persistence request envelope.');
return exchange(socketPath, request, timeoutMs,
typeof request.params.request_id === 'string' ? request.params.request_id : undefined);
}
export async function requestPersistenceAdministration(socketPath: string, request: PersistenceIpcAdminRequest, timeoutMs = 30_000): Promise<unknown> {
if (!administrationRequest(request)) throw clientBug('Invalid local administration envelope.');
return exchange(socketPath, request, timeoutMs,
typeof request.params.request_id === 'string' ? request.params.request_id : undefined);
}