Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Serve-delegated sync IPC — wire types + validation.
*
* A live `gbrain serve` holds a PGLite brain's single-writer connection for
* its lifetime, so a concurrent `gbrain sync` process cannot open the brain.
* These kinds let the sync CLI delegate the run to the serve process over the
* existing resolve-IPC socket: the lock owner does the work, the CLI polls.
* Same trust posture as turn_context — narrow typed requests, secret-gated,
* raw SQL never crosses the wire.
*
* sync_start { options, clientToken } → { ok, jobId } | { ok:false, error }
* sync_status { jobId } → job state + progress + final result
* sync_abort { jobId } → begins cooperative abort (typed partial)
*
* #6317 (managed brains, Postgres): sync_start may carry the CLI's durable
* `cli` writer registration. The serve verifies it and runs the managed
* drain (`drainManagedSync`) as that writer; sync_status then carries the
* drain's report, the `next` action and the numbered human lines the drain
* printed, so the polling CLI shows the same lines its in-process run would.
*
* This module is deliberately a LEAF: pure types + pure functions, imported by
* both the resolve-ipc client/server plumbing and the serve-sync-runner. It
* must not import resolve-ipc.ts (cycle) or any engine module.
*/
import { isValidSourceId } from '../source-id.ts';
import { syncWireFields, type SyncWireType } from '../sync-flags.ts';
import { retiredWireFields } from '../wire-skew.ts';
import type { SyncResult } from '../../commands/sync.ts';
import type { DrainNext, DrainReport } from '../persistence/sync-drain.ts';
// ── Options allowlist ──────────────────────────────────────────────────────
/**
* The single field table that drives the validator, the CLI wire-builder, and
* the serve-side SyncOpts builder — one source of truth so the three sites
* can't drift. Everything NOT in this table is rejected fail-closed: the wire
* must never smuggle repoPath / srcSubpath / exclude / skipLock / lockId /
* concurrency into the serve process. `noEmbed` here does NOT reach
* performSync — delegated jobs ALWAYS run noEmbed (the #2139 cost gate lives
* in runSync, which a delegated run never passes through); the flag records
* that the USER declined embeds, which suppresses the serve's deferred-embed
* drain (absent → the serve sweep drains them later).
*/
export const DELEGATED_SYNC_OPTION_FIELDS = {
// The flags the one sync flag table forwards through the serve (src/core/sync-flags.ts) ...
...syncWireFields('serve'),
// ... and the fields the client derives rather than parses.
sourceId: 'string',
embedDeferred: 'boolean',
timeoutSeconds: 'number',
origin: 'string',
} as const satisfies Record<string, SyncWireType>;
/** `--lanes N` bounds (`src/commands/sync/args.ts`). */
export const DELEGATED_SYNC_LANES_MAX = 16;
export type DelegatedSyncOptionField = keyof typeof DELEGATED_SYNC_OPTION_FIELDS;
/** Hard ceiling on a delegated job's runtime (24h) — matches the sync hard-deadline scale. */
export const DELEGATED_SYNC_TIMEOUT_MAX_SECONDS = 86_400;
export interface DelegatedSyncOptions {
/** Must satisfy the canonical source-id shape; validated at the boundary. */
sourceId?: string;
dryRun?: boolean;
full?: boolean;
noPull?: boolean;
/** User explicitly declined embeds — suppresses the deferred-embed drain. */
noEmbed?: boolean;
noExtract?: boolean;
noSchemaPack?: boolean;
skipFailed?: boolean;
retryFailed?: boolean;
includeGitignored?: boolean;
/** #6317: `--no-bulk` for the managed catch-up. */
noBulk?: boolean;
/** #6317: `--lanes N` / `--no-lanes` (1..DELEGATED_SYNC_LANES_MAX) for the managed catch-up. */
lanes?: number;
/** #6696 (A5): who the run's writes are for; the operator's CLI sends `interactive`, absent is `background`. */
origin?: 'interactive' | 'background';
/** #6696: the client's cost gate deferred this run's embedding; cursor adoption never lifts it. Sent only when true. */
embedDeferred?: boolean;
/**
* REQUIRED — the client always sends its resolved hard deadline so a job
* whose client died stays bounded. `0` is the single unbounded encoding
* (an explicit `--no-hard-deadline`); nonzero values clamp to
* [1, DELEGATED_SYNC_TIMEOUT_MAX_SECONDS].
*/
timeoutSeconds: number;
}
export type DelegatedSyncValidation =
/** `ignored`: retired fields an older client sent (src/core/wire-skew.ts), accepted and dropped. */
| { ok: true; options: DelegatedSyncOptions; ignored?: string[] }
| { ok: false; error: string };
/**
* Fail-closed wire validation: unknown keys reject (this is what keeps
* server-only SyncOpts fields unreachable from the socket), wrong types
* reject, sourceId must be shape-valid, timeoutSeconds must be a
* non-negative integer (0 = no server timer). Returns a NEW object built
* from the field table — never the caller's reference.
*/
export function validateDelegatedSyncOptions(raw: unknown): DelegatedSyncValidation {
if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
return { ok: false, error: 'invalid_options:options' };
}
const rec = raw as Record<string, unknown>;
const retired = retiredWireFields('serve');
const ignored: string[] = [];
for (const key of Object.keys(rec)) {
const window = retired.get(key);
if (window) {
// Accepted from an older client and ignored until its window in src/core/wire-skew.ts closes.
if (rec[key] !== undefined && !window.accepts(rec[key])) return { ok: false, error: `invalid_options:${key}` };
ignored.push(key);
continue;
}
if (!(key in DELEGATED_SYNC_OPTION_FIELDS)) {
return { ok: false, error: `invalid_options:${key}` };
}
}
const out: Record<string, unknown> = {};
for (const [key, type] of Object.entries(DELEGATED_SYNC_OPTION_FIELDS) as Array<[string, SyncWireType]>) {
const v = rec[key];
if (v === undefined) continue;
if (type === 'string[]') {
if (!Array.isArray(v) || v.some(item => typeof item !== 'string')) return { ok: false, error: `invalid_options:${key}` };
out[key] = [...v];
continue;
}
if (typeof v !== type) return { ok: false, error: `invalid_options:${key}` };
out[key] = v;
}
if (out.lanes !== undefined && (!Number.isInteger(out.lanes) || (out.lanes as number) < 1 || (out.lanes as number) > DELEGATED_SYNC_LANES_MAX)) {
return { ok: false, error: 'invalid_options:lanes' };
}
if (out.origin !== undefined && out.origin !== 'interactive' && out.origin !== 'background') {
return { ok: false, error: 'invalid_options:origin' };
}
const timeout = out.timeoutSeconds;
if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout < 0) {
return { ok: false, error: 'invalid_options:timeoutSeconds' };
}
out.timeoutSeconds = Math.min(timeout, DELEGATED_SYNC_TIMEOUT_MAX_SECONDS);
if (out.sourceId !== undefined && !isValidSourceId(out.sourceId as string)) {
return { ok: false, error: 'invalid_options:sourceId' };
}
return { ok: true, options: out as unknown as DelegatedSyncOptions, ...(ignored.length ? { ignored } : {}) };
}
// ── Progress + result shapes ───────────────────────────────────────────────
/** Fired by performSync's onProgress seam; mirrored into the job record. */
export interface SyncProgressEvent {
phase: string;
bankedFiles?: number;
}
/** pagesAffected cap so a 250K-file sync's result fits the 256KB message cap. */
export const WIRE_PAGES_AFFECTED_MAX = 50;
export interface WireSyncResult extends Omit<SyncResult, 'pagesAffected'> {
/** First WIRE_PAGES_AFFECTED_MAX slugs only — see pagesAffectedTotal. */
pagesAffected: string[];
pagesAffectedTotal: number;
}
export function toWireSyncResult(r: SyncResult): WireSyncResult {
const { pagesAffected, ...rest } = r;
return {
...rest,
pagesAffected: pagesAffected.slice(0, WIRE_PAGES_AFFECTED_MAX),
pagesAffectedTotal: pagesAffected.length,
};
}
// ── Wire request / response types ──────────────────────────────────────────
export type DelegatedSyncState = 'running' | 'aborting' | 'done' | 'error';
/**
* #6317: the CLI's durable `cli` writer registration (id + private credential,
* the same document `local-client.ts` sends over the PGLite persistence IPC).
* The serve verifies it against `persistence_local_writers` and runs the
* managed drain AS that writer, so revocation and grant checks still apply;
* the shared secret alone never authorizes a managed sync.
*/
export interface SyncStartRegistration { id: string; credential: string; lane: 'cli' }
export function isSyncStartRegistration(value: unknown): value is SyncStartRegistration {
if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
const keys = Object.keys(value);
if (keys.length !== 3 || !['id', 'credential', 'lane'].every(key => keys.includes(key))) return false;
const rec = value as Record<string, unknown>;
return typeof rec.id === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(rec.id)
&& typeof rec.credential === 'string' && /^[a-f0-9]{64}$/.test(rec.credential)
&& rec.lane === 'cli';
}
export interface SyncStartRequest {
kind: 'sync_start';
protocol: 2;
secret: string;
/**
* Client-generated idempotency token. A retry after a lost ack that gets
* `busy` with a MATCHING token is attaching to its own job; a retry whose
* token matches the RETAINED TERMINAL job gets `{ok, jobId, completed:true}`
* instead of a duplicate run.
*/
clientToken: string;
options: DelegatedSyncOptions;
/** #6317: present when the CLI asks the serve to run a managed drain as its verified writer. */
registration?: SyncStartRegistration;
}
export type SyncStartError =
| 'busy'
| 'unauthorized'
| 'unsupported_protocol'
| 'unsupported_kind'
| 'shutting_down'
| 'source_mismatch'
| string; // `invalid_options:<field>`
export interface SyncStartResponse {
ok: boolean;
protocol: 2;
jobId?: string;
/** On `busy`: the running job's clientToken so a retrying owner can attach. */
clientToken?: string;
/** True when a token retry matched the retained terminal job — poll sync_status for its result. */
completed?: boolean;
error?: SyncStartError;
/**
* #6317: the agent-operator envelope (`OperationError.toJSON()`) behind an
* authorization refusal of the registration hand-off (`permission_denied`
* for a denied, revoked or stdio registration), so the CLI renders the same
* error its in-process path would have thrown.
*/
refusal?: Record<string, unknown>;
}
export interface SyncStatusRequest {
kind: 'sync_status';
protocol: 2;
secret: string;
jobId: string;
/** #6317: return only the job's human lines after this sequence number (the client's cursor). */
afterLine?: number;
}
/** #6317: a human line the job printed (the drain's progress, stall and lanes lines), numbered so a poll resumes where it left off. */
export interface SyncStatusLine { seq: number; text: string }
export interface SyncStatusResponse {
ok: boolean;
protocol: 2;
state?: DelegatedSyncState;
sourceId?: string;
startedAt?: number;
elapsedMs?: number;
phase?: string;
bankedFiles?: number;
/** Present when state === 'done' (including typed partials). */
result?: WireSyncResult;
/** Present when state === 'error' — the job's failure message. */
jobError?: string;
/** #6317: the job's error as an agent-operator envelope when it was an OperationError (state === 'error'). */
jobErrorEnvelope?: Record<string, unknown>;
/** #6317: true when the job runs the managed drain as a verified CLI writer (its `lines` are the drain's own output). */
managed?: boolean;
/** #6317: the managed drain's report so far (final when state is terminal), when the job is a managed drain. */
drain?: DrainReport;
/** #6317: what to run next once the drain is terminal; null when it synced; absent before then. */
next?: DrainNext | null;
/** #6317: the human lines printed since the request's `afterLine` cursor, oldest first (bounded; older lines are dropped). */
lines?: SyncStatusLine[];
/** #6317: the newest line sequence the server holds (the client's next cursor). */
lineSeq?: number;
/** ok:false protocol errors: 'unauthorized' | 'unknown_job' | 'unsupported_kind' | 'unsupported_protocol'. */
error?: string;
}
export interface SyncAbortRequest {
kind: 'sync_abort';
protocol: 2;
secret: string;
jobId: string;
}
export interface SyncAbortResponse {
ok: boolean;
protocol: 2;
state?: DelegatedSyncState;
error?: string;
}
/**
* GBRA-133 PR 2a: sync_nudge (secret-gated, protocol 2, versioned by `version`). A client that cannot sync now (
* `gbrain sync trigger`, or a delegated sync the serve answered `busy`) records what it wants as a wanted marker
* through the serve that holds the PGLite brain, which acknowledges with the marker and nudges its notifier. An
* absent `intent` lets the serve pick (managed: freshness, classic: pull); a freshness marker with no `wantedHead`
* takes the checkout's HEAD as the serve reads it. An older serve answers unknown_kind:sync_nudge.
*/
export const SYNC_NUDGE_VERSION = 1;
export interface SyncNudgeRequest {
kind: 'sync_nudge';
protocol: 2;
version: number;
secret: string;
sourceId: string;
intent?: 'freshness' | 'pull' | 'full';
wantedHead?: string | null;
requestedBy: 'sync_trigger' | 'delegated_sync';
}
export interface SyncNudgeResponse {
ok: boolean;
protocol: 2;
version?: number;
acked?: boolean;
marker?: { source_id: string; intent: 'freshness' | 'pull' | 'full'; generation: number; wanted_head: string | null; first_due_at: string };
/** Whether a notifier runs in that serve (false: GBRAIN_NOTIFIER=0 there; the marker waits for a resident). */
notifier?: boolean;
resident?: string | null;
error?: string;
}