Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The op-descriptor protocol between the crash-robot driver (`validate.ts`)
* and its workers (`worker.ts`). A descriptor is plain JSON: it names one
* logical operation, the actor that submits it, the source it targets, a
* fixed request id and op-specific arguments. Values only known after an
* earlier op ran (a fact id, a take row, a page revision) are `{ $ref }`
* pointers into earlier observations, so a recorded schedule replays exactly.
*
* Every op runs through its real admission wrapper: the registered operation
* handler with a real OperationContext, a local CLI principal or an
* authenticated remote principal whose grant lives in `oauth_clients`.
* Nothing here calls a preparer or `tx.*` directly.
*/
import { randomUUID } from 'node:crypto';
import { mkdirSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import type { BrainEngine } from '../../src/core/engine.ts';
import type { GBrainConfig } from '../../src/core/config.ts';
import type { AuthInfo, OperationContext } from '../../src/core/ops/contract.ts';
import { operationsByName } from '../../src/core/operations.ts';
import { toAgentError } from '../../src/core/agent-output.ts';
import { dispatchRenderContext, type DispatchOpts } from '../../src/mcp/dispatch.ts';
import { GBrainOAuthProvider } from '../../src/core/oauth-provider.ts';
import { sqlQueryForEngine } from '../../src/core/sql-query.ts';
import { revokeLegacyTokenById } from '../../src/core/token-mint.ts';
export const OP_KINDS = ['put_page', 'edit_page', 'remember', 'forget', 'takes_add', 'takes_supersede',
'add_timeline_entry', 'delete_page', 'restore_page', 'revoke_access', 'sync', 'connector_publish'] as const;
export type OpKind = typeof OP_KINDS[number];
/** Read surfaces the oracle checks; they never mutate. */
export const READ_KINDS = ['get_page', 'recall', 'takes_list'] as const;
/**
* A value produced by an earlier op: `{ $ref: 'op-3', field: 'fact_id' }`.
* The string `'$current'` as `expected_revision` reads the page's revision
* (tombstones included) right before submission, as an agent reads first.
*/
export interface OpRef { $ref: string; field: 'fact_id' | 'row_num' | 'revision' }
export type OpArg = string | number | boolean | null | OpRef | OpArg[] | { [key: string]: OpArg };
export interface OpDescriptor {
v: 1;
/** Logical id, unique within a schedule ("op-17"). */
id: string;
kind: OpKind;
/** 'local' (trusted CLI) or a remote agent name declared in the world ("agent-0"). */
actor: string;
source: string;
/** Fixed per descriptor so a replayed schedule resubmits the same request. */
requestId: string;
args: Record<string, OpArg>;
/** Ops whose observations this one reads through `$ref`; shrinking keeps them. */
deps?: string[];
/** Replay of an earlier descriptor's request id (same or different actor/intent). */
replayOf?: string;
}
export type OpStatus = 'committed' | 'pending' | 'refused';
export interface OpObservation {
id: string;
kind: OpKind;
actor: string;
source: string;
requestId: string;
status: OpStatus;
/** Typed error code for a refusal or a non-committed receipt. */
code?: string;
/** The durable receipt the caller saw, when one was returned. */
receipt?: { request_id: string; state: string; revision?: string | null; principal_kind?: string; principal_id?: string; source_id?: string };
/** Values later ops can `$ref`. */
values: { fact_id?: string; row_num?: number; revision?: string };
/** The page bytes the caller could read right after a committed op on a page (for stale republication). */
pageContent?: string;
/** The raw handler result or error fields, JSON-safe. */
raw?: unknown;
/** For a failure: the code of the agent-contract envelope an MCP caller receives (`toAgentError`). */
agentCode?: string;
}
/**
* One authenticated remote agent: an OAuth client or legacy access token whose
* bearer token the real verifier (`GBrainOAuthProvider.verifyAccessToken`)
* turns into the AuthInfo every remote op runs under. Tokens are synthetic,
* minted into the fixture's own scratch database.
*/
export interface RemoteActor { name: string; kind: 'oauth_client' | 'legacy_token'; sourceId: string; token: string }
export interface World {
engine: BrainEngine;
config: GBrainConfig;
remotes: RemoteActor[];
/** AuthInfo per remote actor, from the real token verifier. */
auth: Map<string, AuthInfo>;
observations: Map<string, OpObservation>;
/** Descriptors by id, and the exact parameters each was submitted with (a same-intent replay resends them). */
descriptors?: Map<string, OpDescriptor>;
submitted?: Map<string, Record<string, unknown>>;
/** Called with the exact parameters right before submission (a crash worker persists them). */
onSubmit?: (d: OpDescriptor, params: Record<string, unknown>) => void;
/** Checkout roots by source id: `sync` edits and commits files there as a user would. */
roots?: Record<string, string>;
/** The connector source, when the topology has one. */
connector?: { sourceId: string; root: string };
/** Session drops this robot injects (the pooler_disconnect fault); absent in every other run. */
sessionDrops?: SessionDrops;
/** Write reply wait every op context carries; absent = the operation default (a probe shortens it to force `write_pending`). */
writeWaitMs?: number;
/** `consumer:claiming` passes a counting or crashing worker's fault hook saw; `finish` waits for one after its probe (#6957). */
claimPasses?: number;
}
/**
* The robot's own session drops. A harness read treats a closed connection as
* injected only once a drop round that began before the error terminated at
* least one session; any other close is unexpected and fails the run.
*/
export class SessionDrops {
private killed = 0;
private readonly inFlight = new Set<Promise<number>>();
/** Run one drop round; resolves to the number of sessions it terminated (0 when the round itself failed). */
inject(terminate: () => Promise<number>): Promise<number> {
const round: Promise<number> = terminate().catch(() => 0).then(n => { this.killed += n; this.inFlight.delete(round); return n; });
this.inFlight.add(round);
return round;
}
/** Whether a round started before this call terminated a session. */
async injectedBefore(): Promise<boolean> {
if (!this.killed) await Promise.all([...this.inFlight]);
return this.killed > 0;
}
}
// CONNECT_TIMEOUT: a backend the fault killed mid-handshake surfaces to the client as a connect timeout, not a close.
const DROPPED_CONNECTION = /CONNECTION_CLOSED|CONNECTION_ENDED|CONNECTION_DESTROYED|CONNECT_TIMEOUT|ECONNRESET|57P01|08P01|08006|server conn crashed|terminating connection|Connection terminated/i;
const DROP_RETRIES = 8;
/**
* Run a harness read (an oracle check, a drain poll, an argument lookup) across
* a session drop the robot injected; only the system under test is judged on
* such errors. A close the robot did not inject, or one that outlasts the
* retries, fails the run with the next step.
*/
export async function retryingRead<T>(world: Pick<World, 'sessionDrops'>, read: () => Promise<T>): Promise<T> {
for (let attempt = 0; ; attempt++) {
try { return await read(); } catch (error) {
const code = (error as { code?: string }).code;
const seen = `${code ?? 'error'}: ${String((error as Error).message).slice(0, 200)}`;
if (!DROPPED_CONNECTION.test(seen)) throw error;
if (!(await world.sessionDrops?.injectedBefore())) {
throw new Error(`crash robot: a harness read lost its database connection (${seen}), but the robot had dropped no session `
+ 'before it, so the database, the pooler or the code under test closed it. Check the Postgres and PgBouncer logs for a restart '
+ 'at that time, then re-run the crash robot: bun --no-env-file scripts/persistence/validate.ts --engine=postgres --schedules=0 '
+ '--operations=0 --no-crashes. Docs: scripts/persistence/README.md#crash-robot', { cause: error });
}
if (attempt >= DROP_RETRIES) {
throw new Error(`crash robot: a harness read still lost its connection after ${DROP_RETRIES + 1} attempts across injected session `
+ `drops (${seen}), so the database stayed unreachable between drop rounds. Check that Postgres and PgBouncer are up, then re-run `
+ 'the crash robot: bun --no-env-file scripts/persistence/validate.ts --engine=postgres --schedules=0 --operations=0 --no-crashes. '
+ 'Docs: scripts/persistence/README.md#crash-robot', { cause: error });
}
await Bun.sleep(150 * (attempt + 1));
}
}
}
/** The GitHub item the connector fixture serves; its page is `CONNECTOR_SLUG` in the connector source. */
export const CONNECTOR_SLUG = 'gh/acme-example/app/1';
const CONNECTOR_CONFIG = { kind: 'github', gh_scope: 'repos', gh_repos: 'acme-example/app', gh_token_env: 'CRASH_ROBOT_CONNECTOR_TOKEN' };
export function connectorSourceConfig(): Record<string, string> { return { ...CONNECTOR_CONFIG }; }
/** Git's refusal while another Git process (a gbrain Git effect committing a page) holds the checkout's index or a ref lock. */
const GIT_LOCK_BUSY = /\.lock'?: File exists|cannot lock ref/;
const USER_COMMIT_RETRY_MS = 20_000;
/**
* A user edits a page file in the checkout and commits it with their own `git add` and `git commit`. The commit has
* landed only when Git reports every file clean at HEAD (a resubmission after a crash finds it already committed). A
* lock another Git process holds is retried, as a person retries; any other failure, or a lock held past the bound,
* throws out of `executeOp` and fails the run, so the model is never told of a sync whose user commit does not exist.
*/
async function userEdit(world: World, d: OpDescriptor): Promise<void> {
const root = world.roots?.[d.source];
if (!root) throw new Error(`op descriptor ${d.id}: source ${d.source} has no checkout`);
const slug = String(d.args.slug);
const path = join(root, `${slug}.md`);
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, String(d.args.content));
// `extra` sibling files make a backlog, so a managed Postgres sync publishes in bulk groups.
const files = [`${slug}.md`];
for (let i = 0; i < Number(d.args.extra ?? 0); i++) {
const sibling = `${slug}-batch-${i}.md`; files.push(sibling);
writeFileSync(join(root, sibling), `---\ntype: note\ntitle: batch ${i}\n---\n\nBatch page ${i} of ${slug}.\n`);
}
const git = (...args: string[]) => Bun.spawnSync(['git', '-C', root, ...args], { stdout: 'pipe', stderr: 'pipe' });
const deadline = Date.now() + USER_COMMIT_RETRY_MS;
for (;;) {
const add = git('add', '--', ...files);
const commit = add.exitCode === 0 ? git('-c', 'user.name=Crash Robot', '-c', '[email protected]', 'commit', '-q', '-m', `edit ${slug}`, '--', ...files) : add;
const status = git('--no-optional-locks', 'status', '--porcelain', '--untracked-files=all', '--', ...files);
if (status.exitCode === 0 && status.stdout.length === 0) return;
const stderr = commit.stderr.toString().trim();
if (!GIT_LOCK_BUSY.test(stderr) || Date.now() > deadline) {
throw new Error(`op descriptor ${d.id}: the user's commit of ${slug} did not land (git ${commit === add ? 'add' : 'commit'} exit ${commit.exitCode}): ${stderr || status.stderr.toString().trim() || status.stdout.toString().trim()}`);
}
await Bun.sleep(100);
}
}
/** The owner syncs the user's commit through the real `sync_brain` handler. */
async function runSync(world: World, d: OpDescriptor): Promise<Record<string, unknown>> {
return await operationsByName.sync_brain.handler(contextFor(world, 'local', d.source),
{ source_id: d.source, no_pull: true, no_embed: true }) as Record<string, unknown>;
}
/** The connector fetches one issue whose body carries the descriptor's marker and publishes it through the coordinator. */
async function runConnector(world: World, d: OpDescriptor): Promise<Record<string, unknown>> {
if (!world.connector) throw new Error(`op descriptor ${d.id}: the topology has no connector source`);
const { runGitHubSync } = await import('../../src/core/github-source.ts');
const { parseGitHubSourceConfig } = await import('../../src/core/github-source-config.ts');
const issue = { number: 1, title: 'Robot issue', state: 'open', body: String(d.args.body), created_at: '2026-09-01T00:00:00Z',
updated_at: String(d.args.updated_at ?? '2026-09-02T00:00:00Z'), labels: [], assignees: [], user: { login: 'example-user' },
html_url: 'https://github.com/acme-example/app/issues/1' };
const json = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
const fetchImpl = async (url: string) => {
const path = new URL(url).pathname;
if (path.endsWith('/issues/1')) return json(issue);
if (path.endsWith('/issues')) return json([issue]);
if (path.endsWith('/pulls') || path.endsWith('/comments')) return json([]);
if (path === '/repos/acme-example/app') return json({ full_name: 'acme-example/app', private: true, default_branch: 'main' });
throw new Error(`crash-robot connector fixture: unexpected route ${path}`);
};
process.env.CRASH_ROBOT_CONNECTOR_TOKEN ??= 'synthetic-local-fixture';
return await runGitHubSync(world.engine, world.connector.sourceId, parseGitHubSourceConfig(CONNECTOR_CONFIG, world.connector.root),
{ noEmbed: true, noExtract: true, noSchemaPack: true, githubItem: { repo: 'acme-example/app', number: 1, kind: 'issue' } } as never, fetchImpl as never) as unknown as Record<string, unknown>;
}
export function descriptor(id: string, kind: OpKind, actor: string, source: string, args: Record<string, OpArg>,
extra: Partial<Pick<OpDescriptor, 'deps' | 'replayOf' | 'requestId'>> = {}): OpDescriptor {
return { v: 1, id, kind, actor, source, requestId: extra.requestId ?? randomUUID(), args,
...(extra.deps?.length ? { deps: extra.deps } : {}), ...(extra.replayOf ? { replayOf: extra.replayOf } : {}) };
}
/** Rejects anything that is not a well-formed descriptor; the worker trusts nothing it reads from the driver. */
export function parseDescriptor(value: unknown): OpDescriptor {
const d = value as OpDescriptor;
if (!d || typeof d !== 'object' || d.v !== 1) throw new Error('op descriptor: unsupported version');
if (typeof d.id !== 'string' || !d.id) throw new Error('op descriptor: id required');
if (!(OP_KINDS as readonly string[]).includes(d.kind)) throw new Error(`op descriptor ${d.id}: unknown kind ${String(d.kind)}`);
for (const key of ['actor', 'source', 'requestId'] as const) if (typeof d[key] !== 'string' || !d[key]) throw new Error(`op descriptor ${d.id}: ${key} required`);
if (!d.args || typeof d.args !== 'object' || Array.isArray(d.args)) throw new Error(`op descriptor ${d.id}: args must be an object`);
if (d.deps !== undefined && (!Array.isArray(d.deps) || d.deps.some(dep => typeof dep !== 'string'))) throw new Error(`op descriptor ${d.id}: deps must be ids`);
return d;
}
/** Verify every remote actor's bearer token through the production verifier. */
export async function authenticateRemotes(world: World): Promise<void> {
const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(world.engine) });
for (const remote of world.remotes) world.auth.set(remote.name, await provider.verifyAccessToken(remote.token) as unknown as AuthInfo);
}
/** Re-verify one actor's bearer token, as a remote transport does on every request. */
async function reauthenticate(world: World, actor: string): Promise<void> {
const remote = world.remotes.find(r => r.name === actor);
if (!remote) return;
const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(world.engine) });
// The transport's own verification retries an injected session drop; only the operation is under test.
world.auth.set(actor, await retryingRead(world, () => provider.verifyAccessToken(remote.token)) as unknown as AuthInfo);
}
/** Revoke a remote actor's credential through the owner's real revocation path. */
async function revokeAccess(world: World, actor: string): Promise<void> {
const remote = world.remotes.find(r => r.name === actor);
if (!remote) throw new Error(`op descriptor: revoke_access names unknown actor ${actor}`);
const auth = world.auth.get(actor);
const sql = sqlQueryForEngine(world.engine);
if (remote.kind === 'oauth_client') {
await new GBrainOAuthProvider({ sql, transaction: fn => world.engine.transaction(tx => fn(sqlQueryForEngine(tx))) }).revokeClient(auth!.clientId);
} else await revokeLegacyTokenById(sql, auth!.principal!.id);
}
export function contextFor(world: World, actor: string, sourceId: string): OperationContext {
const base = { engine: world.engine, config: world.config, dryRun: false, sourceId,
logger: { info() {}, warn() {}, error() {} }, ...(world.writeWaitMs !== undefined ? { writeWaitMs: world.writeWaitMs } : {}) };
if (actor === 'local') return { ...base, remote: false };
const auth = world.auth.get(actor);
if (!auth) throw new Error(`op descriptor: actor ${actor} is not an authenticated remote`);
return { ...base, remote: true, transport: 'http', auth };
}
function resolveArg(world: World, value: OpArg): unknown {
if (Array.isArray(value)) return value.map(v => resolveArg(world, v));
if (value && typeof value === 'object') {
if ('$ref' in value && typeof value.$ref === 'string') {
const ref = value as unknown as OpRef;
const seen = world.observations.get(ref.$ref);
const resolved = seen?.values[ref.field];
// An unresolvable reference is still submitted (as a value the real op refuses),
// so a shrunk sequence that drops the producer stays executable.
return resolved ?? (ref.field === 'row_num' ? 999_999 : ref.field === 'fact_id' ? '999999999' : 'unresolved-revision');
}
return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveArg(world, v as OpArg)]));
}
return value;
}
/** Map a descriptor to the operation's own parameter shape. */
export async function paramsFor(world: World, d: OpDescriptor): Promise<{ op: string; params: Record<string, unknown> }> {
const original = d.replayOf ? world.descriptors?.get(d.replayOf) : undefined;
const resent = original && original.actor === d.actor && original.kind === d.kind && JSON.stringify(original.args) === JSON.stringify(d.args)
? world.submitted?.get(original.id) : undefined;
if (resent) return { op: d.kind, params: resent };
// A resubmission after a crash sends exactly what the interrupted caller sent.
const interrupted = world.submitted?.get(d.id);
if (interrupted) return { op: d.kind, params: interrupted };
const a = resolveArg(world, d.args as OpArg) as Record<string, unknown>;
if (a.content === '$stale_content') a.content = world.observations.get(String(a.stale_of))?.pageContent ?? 'missing stale content';
if (a.expected_revision === '$current') {
const snapshot = await retryingRead(world, () => world.engine.readPageSnapshot(String(a.slug), { sourceId: d.source, includeDeleted: true }));
a.expected_revision = snapshot?.revision ?? 'missing-page';
}
const revision = a.expected_revision === undefined ? {} : { expected_revision: a.expected_revision };
const base = { request_id: d.requestId, ...(d.actor === 'local' ? { source_id: d.source } : {}) };
switch (d.kind) {
case 'put_page': return { op: 'put_page', params: { ...base, ...revision, slug: a.slug, content: a.content } };
case 'edit_page': return { op: 'edit_page', params: { ...base, ...revision, slug: a.slug, edits: a.edits } };
case 'remember': return { op: 'remember', params: { ...base, fact: a.fact, provenance: a.provenance ?? 'crash-robot fixture',
...(a.entity ? { entity: a.entity } : {}), infer_entity: false, ...(a.visibility ? { visibility: a.visibility } : {}) } };
case 'forget': return { op: 'forget', params: { request_id: d.requestId, id: a.fact_id, ...(a.reason ? { reason: a.reason } : {}) } };
case 'takes_add': return { op: 'takes_add', params: { ...base, slug: a.slug, claim: a.claim, kind: a.kind ?? 'take', holder: a.holder ?? 'world', weight: a.weight ?? 0.5 } };
case 'takes_supersede': return { op: 'takes_supersede', params: { ...base, slug: a.slug, row_num: a.row_num, claim: a.claim } };
case 'add_timeline_entry': return { op: 'add_timeline_entry', params: { ...base, slug: a.slug, date: a.date, summary: a.summary } };
case 'delete_page': return { op: 'delete_page', params: { ...base, ...revision, slug: a.slug } };
case 'restore_page': return { op: 'restore_page', params: { ...base, ...revision, slug: a.slug } };
case 'revoke_access': return { op: 'revoke_access', params: { actor: a.actor } };
case 'sync': return { op: 'sync', params: { slug: a.slug, content: a.content, ...(a.extra ? { extra: a.extra } : {}) } };
case 'connector_publish': return { op: 'connector_publish', params: { body: a.body, updated_at: a.updated_at } };
}
}
function jsonSafe(value: unknown): unknown {
try { return JSON.parse(JSON.stringify(value ?? null)); } catch { return String(value); }
}
function receiptOf(value: Record<string, unknown> | undefined): OpObservation['receipt'] {
const r = (value?.write_request ?? value?.writeRequest ?? value) as Record<string, unknown> | undefined;
if (!r || typeof r.request_id !== 'string') return undefined;
const outcome = r.outcome as Record<string, unknown> | undefined;
return { request_id: r.request_id, state: String(r.state),
revision: (r.revision ?? outcome?.revision ?? null) as string | null,
principal_kind: r.principal_kind as string | undefined, principal_id: r.principal_id as string | undefined,
source_id: r.source_id as string | undefined };
}
/** The code of the agent-contract envelope an MCP caller receives for this failure. */
function agentEnvelopeCode(error: unknown, op: string): string {
return toAgentError(error, { transport: 'http', op, mutating: true, idempotent: true, outcome: 'unknown',
render: dispatchRenderContext({ transport: 'http', remote: true } as DispatchOpts) }).code;
}
/** Run one descriptor through its real handler and record what the caller observed. */
export async function executeOp(world: World, d: OpDescriptor): Promise<OpObservation> {
const base = { id: d.id, kind: d.kind, actor: d.actor, source: d.source, requestId: d.requestId };
if (d.kind === 'revoke_access') {
await revokeAccess(world, String(d.args.actor));
const observation: OpObservation = { ...base, status: 'committed', values: {} };
world.observations.set(d.id, observation);
return observation;
}
if (d.kind === 'sync' || d.kind === 'connector_publish') {
const { params } = await paramsFor(world, d);
(world.submitted ??= new Map()).set(d.id, params);
world.onSubmit?.(d, params);
const run = { ...d, args: params as OpDescriptor['args'] };
if (d.kind === 'sync') await userEdit(world, run);
let observation: OpObservation;
try {
const result = d.kind === 'sync' ? await runSync(world, run) : await runConnector(world, run);
const status = String(result.status);
observation = { ...base, status: ['synced', 'first_sync', 'up_to_date'].includes(status) ? 'committed' : status === 'partial' ? 'pending' : 'refused',
...(['synced', 'first_sync', 'up_to_date', 'partial'].includes(status) ? {} : { code: status }), values: {}, raw: jsonSafe({ status, reason: result.reason, fromCommit: result.fromCommit, toCommit: result.toCommit, added: result.added, modified: result.modified }) };
} catch (error) {
const e = error as { code?: string; message?: string };
observation = { ...base, status: 'refused', code: e.code ?? 'uncoded_error', agentCode: agentEnvelopeCode(error, 'sync_brain'),
values: {}, raw: { code: e.code, name: (error as Error).name, message: e.message?.slice(0, 400) } };
}
world.observations.set(d.id, observation);
return observation;
}
const { op, params } = await paramsFor(world, d);
(world.submitted ??= new Map()).set(d.id, params);
world.onSubmit?.(d, params);
const handler = operationsByName[op]?.handler;
if (!handler) throw new Error(`op descriptor ${d.id}: operation ${op} is not registered`);
let observation: OpObservation;
try {
await reauthenticate(world, d.actor);
const ctx = contextFor(world, d.actor, d.source);
const result = await handler(ctx, params) as Record<string, unknown>;
const receipt = receiptOf(result);
const state = receipt?.state ?? 'committed';
observation = { ...base, status: state === 'committed' ? 'committed' : 'pending', receipt, values: {}, raw: jsonSafe(result) };
if (result?.fact_id !== undefined) observation.values.fact_id = String(result.fact_id);
else if (result?.id !== undefined && d.kind === 'remember') observation.values.fact_id = String(result.id);
const row = (result?.row_num ?? result?.new_row ?? result?.row) as number | undefined;
if (typeof row === 'number') observation.values.row_num = row;
if (receipt?.revision) observation.values.revision = receipt.revision;
} catch (error) {
const e = error as { code?: string; name?: string; writeRequest?: Record<string, unknown>; message?: string };
// The HTTP transport answers a token the verifier rejects with 401 invalid_token.
if (!e.code && e.name === 'InvalidTokenError') e.code = 'invalid_token';
const receipt = receiptOf(e.writeRequest);
// A memory verb reports an accepted, unfinished write as `unavailable` carrying its pending receipt.
const pending = e.code === 'write_pending' || (receipt !== undefined && !['committed', 'failed', 'conflict', 'cancelled'].includes(receipt.state));
// A token the verifier rejects never reaches an operation: the HTTP transport answers 401 invalid_token.
const agentCode = e.name === 'InvalidTokenError' ? 'http:401' : agentEnvelopeCode(error, op);
observation = { ...base, status: pending ? 'pending' : 'refused', code: e.code ?? 'uncoded_error', agentCode,
receipt, values: {}, raw: { code: e.code, message: e.message?.slice(0, 400) } };
}
const slug = typeof params.slug === 'string' ? params.slug : typeof params.entity === 'string' ? params.entity : null;
if (observation.status === 'committed' && slug) {
try {
const page = await retryingRead(world, () => operationsByName.get_page.handler(contextFor(world, 'local', d.source),
{ slug, include_content: true, source_id: d.source })) as Record<string, unknown>;
if (typeof page?.content === 'string') observation.pageContent = page.content;
} catch { /* deleted or not a page */ }
}
world.observations.set(d.id, observation);
return observation;
}
/** Read the current revision of a page the way an agent does (get_page with content). */
export async function currentRevision(world: World, actor: string, sourceId: string, slug: string): Promise<string | null> {
try {
const page = await operationsByName.get_page.handler(contextFor(world, actor, sourceId),
{ slug, include_content: true, ...(actor === 'local' ? { source_id: sourceId } : {}) }) as Record<string, unknown>;
return typeof page?.revision === 'string' ? page.revision : null;
} catch { return null; }
}