Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.2 KB
Raw Blame
import { createHash } from 'node:crypto';
import { OperationError, opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { isWriteReceipt } from '../persistence/types.ts';
import { isPersistenceIpcMutation } from '../persistence/ipc.ts';
import { replayWhilePending, WRITE_ADMISSION_HEADROOM_MS } from '../persistence/write-wait.ts';
import { WIRE_WRITE_WAIT_MAX_MS } from '../persistence/params.ts';
import { MaintenanceWriteWait } from '../persistence/maintenance-wait.ts';
import { abortableSleep, RetryAbortError } from '../retry.ts';

/** Bind a durable write to its persisted tool execution, including crash replay. */
export function retainToolWriteRequestId(input: unknown, jobId: number, messageIdx: number, ordinal: number, toolUseId: string, toolName: string): void {
  if (!isPersistenceIpcMutation(toolName.replace(/^brain_/, '')) || !input || typeof input !== 'object' || Array.isArray(input)) return;
  const params = input as Record<string, unknown>;
  if (params.request_id !== undefined || params.dry_run === true) return;
  const hex = createHash('sha256').update(JSON.stringify(['gbrain-tool-write-v1', jobId, messageIdx, ordinal, toolUseId])).digest('hex');
  // UUIDv8 uses the persisted execution coordinates as the application identity.
  params.request_id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-${((parseInt(hex[16], 16) & 3) | 8).toString(16)}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
}

/** A queued mutation is durable work, never a completed tool-side write. */
export function assertToolWriteCommitted(output: unknown, toolName: string): void {
  if (!isPersistenceIpcMutation(toolName.replace(/^brain_/, '')) || !isWriteReceipt(output) || output.state === 'committed') return;
  const pending = ['queued', 'running', 'recovering'].includes(output.state);
  const code = pending ? 'write_pending' : 'storage_error';
  const error = opError(code, `Tool write ${output.request_id} is ${output.state}; inspect its durable receipt before retrying.`,
    pending ? `The tool write is accepted and still ${output.state}; read its receipt until it is terminal. Do not repeat the tool call: the same request id replays it.`
      : `The tool write ended ${output.state}; its receipt holds the recorded error. Read it before deciding whether a new write (with a new request id) is needed.`,
    { fix: readFix(`Reads tool write ${output.request_id}'s durable receipt, read-only.`, { argv: ['gbrain', 'write-request', '--', output.request_id] }) });
  error.writeRequest = output; error.writeError = code; throw error;
}

/** What a subagent tool dispatch needs from its job to bound a pending write. */
export interface ToolWriteJob { deadlineAtMs: number | null; signal?: AbortSignal }

/**
 * #5474: dispatch a subagent tool and, while its accepted write is still
 * pending, replay the same request id (nothing new is admitted, no model turn)
 * instead of failing the attempt. The replays stop when the write is terminal,
 * when the job is aborted, or once the job's deadline is closer than one more
 * longest tool wait plus admission headroom, so a retry still fits before the
 * runner times the job out. A job with no deadline gets the maintenance write
 * wait. Whatever is still pending then leaves as `write_pending` with its tool
 * row pending, exactly as before.
 */
export async function awaitCommittedToolWrite(job: ToolWriteJob, toolName: string, dispatch: () => Promise<unknown>): Promise<unknown> {
  const windowMs = job.deadlineAtMs == null ? new MaintenanceWriteWait().ms()
    : Math.max(0, job.deadlineAtMs - Date.now() - WIRE_WRITE_WAIT_MAX_MS - WRITE_ADMISSION_HEADROOM_MS);
  let lastFailure: unknown;
  const attempt = () => dispatch()
    .then(output => { assertToolWriteCommitted(output, toolName); return output; })
    .catch((failure: unknown) => { lastFailure = failure; throw failure; });
  try {
    return await replayWhilePending(attempt, windowMs, ms => abortableSleep(ms, job.signal));
  } catch (error) {
    throw error instanceof RetryAbortError && lastFailure !== undefined ? lastFailure : error;
  }
}

export function isPendingToolWrite(error: unknown): error is OperationError {
  return error instanceof OperationError && error.code === 'write_pending' && error.writeRequest !== undefined;
}