Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.9 KB
Raw Blame
import { afterEach, describe, expect, spyOn, test } from 'bun:test';
import { OperationError } from '../src/core/ops/contract.ts';
import { PersistenceIpcTransportError } from '../src/core/persistence/ipc.ts';
import { renderCliError } from '../src/core/agent-output.ts';
import { frozenVerbWriteError, runMemoryWrite, writeFailureDiagnostic } from '../src/core/persistence/verb-errors.ts';
import type { WriteReceipt } from '../src/core/persistence/types.ts';
import { reportPersistenceCliError, runDeferredPersistenceCommand } from '../src/commands/persistence-delegate.ts';
import { _resetCliExitVerdictForTests } from '../src/core/cli-force-exit.ts';
import { printSyncResult, type SyncResult } from '../src/commands/sync.ts';
import { ERROR_SCHEMA } from '../src/core/verbs.ts';
import { validateAgainstSchema } from '../src/core/verbs/conformance.ts';

const requestId = '20000000-0000-4000-8000-000000000001';
const receipt: WriteReceipt = { request_id: requestId, state: 'conflict', retry_after_ms: null };
const driftMessage = 'The canonical file contains an uncoordinated local edit.';
afterEach(() => { _resetCliExitVerdictForTests(); process.exitCode = 0; });

test('deferred reconciliation help does not acquire an engine', async () => {
  const log = spyOn(console, 'log').mockImplementation(() => {});
  try {
    await runDeferredPersistenceCommand('sources', ['reconcile', '--help'], async () => { throw new Error('Help must not connect.'); });
    expect(log.mock.calls.flat().join('\n')).toContain('sources reconcile');
  } finally { log.mockRestore(); }
});

test('file/database drift preserves v1 vocabulary and names reviewed repair without privilege escalation', async () => {
  const cause = new OperationError('source_changed', driftMessage);
  cause.writeError = 'source_changed';
  cause.writeRequest = receipt;
  let error: OperationError | undefined;
  try { await runMemoryWrite(async () => { throw cause; }); } catch (caught) { error = caught as OperationError; }
  const body = error!.toJSON();
  expect(body).toMatchObject({ error: 'scope_denied', protocol_version: 1, write_error: 'source_changed',
    detail: 'file_database_drift', write_request: receipt });
  expect(body.message).toContain('file and database disagree');
  expect(body.suggestion).toContain('gbrain sources reconcile');
  expect(body.suggestion).toContain('--preview');
  expect(body.suggestion).toContain('new request_id');
  expect(body.suggestion).not.toMatch(/sources writer (claim|activate|transfer)/);
  expect(validateAgainstSchema(body, ERROR_SCHEMA)).toEqual([]);
  await expect(runMemoryWrite(async () => { throw error; })).rejects.toBe(error);
});

test('pre-admission drift uses the same diagnosis without inventing a receipt', async () => {
  let error: OperationError | undefined;
  try { await runMemoryWrite(async () => { throw new OperationError('source_changed', driftMessage); }); }
  catch (caught) { error = caught as OperationError; }
  expect(error!.toJSON()).toMatchObject({ error: 'scope_denied', write_error: 'source_changed', detail: 'file_database_drift' });
  expect(error!.toJSON()).not.toHaveProperty('write_request');
});

test('human output leads with source_changed, JSON stays frozen and clean, both retain the request ID', async () => {
  const error = frozenVerbWriteError(receipt, 'source_changed', driftMessage);
  const stderr = spyOn(console, 'error').mockImplementation(() => {});
  let stdout = '';
  try {
    expect(await reportPersistenceCliError(error, true, async text => { stdout += text; })).toBe(true);
    expect(JSON.parse(stdout)).toMatchObject({ error: 'scope_denied', write_error: 'source_changed', write_request: receipt });
    const lines = stderr.mock.calls.map(args => args.join(' '));
    expect(lines[0]).toStartWith('Error [source_changed]:');
    expect(lines.join('\n')).toContain(`Request: ${requestId} (conflict)`);
    expect(stdout).not.toContain('Error [');
  } finally { stderr.mockRestore(); }
});

test.each(['queued', 'running', 'recovering'] as const)('%s cannot look committed or suggest a replacement request', state => {
  const body = frozenVerbWriteError({ ...receipt, state, retry_after_ms: 1000 }, 'write_pending').toJSON();
  expect(body.message).toContain('not committed');
  expect(body.suggestion).toContain(`same arguments and request_id ${requestId}`);
  expect(body.suggestion).toContain('Do not submit a new request_id');
  expect(body.write_request).not.toHaveProperty('revision');
});

test('CLI JSON and frozen error serialization retain the same allowlisted health', async () => {
  const diagnostic = { age_ms: 120000, assessment: 'stalled' as const,
    reason: 'cause_unknown' as const, next_action: 'inspect_owner' as const };
  const error = frozenVerbWriteError({ request_id: requestId, state: 'queued', retry_after_ms: 30000,
    diagnostic: { ...diagnostic, ...{ raw_error: 'PRIVATE_DRIVER_ERROR' } } }, 'write_pending');
  const stderr = spyOn(console, 'error').mockImplementation(() => {});
  let stdout = '';
  try {
    expect(await reportPersistenceCliError(error, true, async text => { stdout += text; })).toBe(true);
    const body = JSON.parse(stdout);
    expect(body.write_request.diagnostic).toEqual(diagnostic);
    expect(body.suggestion).toContain(requestId);
    expect(body.suggestion).toContain('gbrain sources writer status');
    expect(stdout).not.toContain('PRIVATE_DRIVER_ERROR');
    expect(validateAgainstSchema(body, ERROR_SCHEMA)).toEqual([]);
  } finally { stderr.mockRestore(); }
});

test('unrecognized errors cannot echo private content, absolute paths, or credentials', () => {
  const privateMessage = '/private/source/example.md contains secret private fixture content with credential=redacted';
  for (const code of ['source_changed', 'storage_error', 'invalid_params', 'unknown_error']) {
    const detail = writeFailureDiagnostic(code, privateMessage);
    expect(JSON.stringify(detail)).not.toContain(privateMessage);
    expect(JSON.stringify(detail)).not.toContain('/private');
    expect(JSON.stringify(detail)).not.toContain('credential');
  }
  expect(writeFailureDiagnostic('source_changed', 'Newer working-tree bytes and the current page disagree with this pinned Git import.').reason)
    .toBe('pinned_git_worktree_conflict');
  expect(writeFailureDiagnostic('owner_unavailable').reason).toBe('owner_unavailable');
  expect(writeFailureDiagnostic('permission_denied').reason).toBe('permission_denied');
});

test.each(['blocked_by_failures', 'partial'] as const)('managed %s rendering uses the receipt instead of generic parse/skip advice', status => {
  const pending = status === 'partial';
  const result: SyncResult = { status, fromCommit: null, toCommit: '0123456789', added: 0, modified: 0, deleted: 0,
    renamed: 0, chunksCreated: 0, embedded: 0, pagesAffected: [], failedFiles: pending ? 0 : 1,
    managedWrite: { source_id: 'example-source', path: 'notes/example.md', slug: 'notes/example',
      write_error: pending ? 'write_pending' : 'source_changed', reason: pending ? 'write_pending' : 'file_database_drift',
      message: pending ? 'The accepted write is not committed.' : 'The file and database disagree.',
      suggestion: pending ? 'Resume this request.' : 'Review gbrain sources reconcile before retrying.',
      write_request: pending ? { ...receipt, state: 'queued', retry_after_ms: 1000 } : receipt, ledger_recorded: false } };
  let output = '';
  printSyncResult(result, { write: (text: string) => { output += text; return true; } } as NodeJS.WriteStream);
  expect(output).toContain('example-source');
  expect(output).toContain('notes/example.md');
  expect(output).toContain(requestId);
  expect(output).toContain('remains authoritative');
  expect(output).not.toContain('frontmatter validate');
  expect(output).not.toContain('sync --skip-failed');
  if (pending) { expect(output).toContain('not committed'); expect(output).not.toContain('First sync complete'); }
});

describe('delegated CLI JSON carries the v1 envelope fields beside the legacy keys', () => {
  async function report(error: unknown): Promise<Record<string, any>> {
    const stderr = spyOn(console, 'error').mockImplementation(() => {});
    let stdout = '';
    try {
      expect(await reportPersistenceCliError(error, true, async text => { stdout += text; })).toBe(true);
      return JSON.parse(stdout);
    } finally { stderr.mockRestore(); }
  }

  test('an OperationError keeps error/message/suggestion values and gains code, fix, docs_cmd, class and contract_version', async () => {
    const e = new OperationError('source_changed', driftMessage, 'Read the receipt first.');
    e.writeError = 'source_changed';
    e.writeRequest = receipt;
    const legacy = e.toJSON() as Record<string, unknown>;
    const doc = await report(e);
    for (const [key, value] of Object.entries(legacy)) expect(doc[key], key).toEqual(value);
    const rendered = JSON.parse(renderCliError(e, { json: true, command: 'capture', tty: false }).stdout!);
    expect(doc.code).toBe(rendered.code);
    expect(doc.fix).toEqual(rendered.fix);
    expect(doc.docs_cmd).toEqual(['gbrain', 'errors', doc.code]);
    expect(typeof doc.class).toBe('string');
    expect(typeof doc.retryable).toBe('boolean');
    expect(doc.contract_version).toBe(1);
  });

  test('a lost IPC acknowledgment is owner_unavailable with a receipt read, never a bare internal_error', async () => {
    const doc = await report(new PersistenceIpcTransportError(true, requestId));
    expect(doc).toMatchObject({ error: 'owner_unavailable', code: 'owner_unavailable', submission_status: 'unknown', request_id: requestId, contract_version: 1 });
    expect(doc.fix.argv.slice(0, 2)).toEqual(['gbrain', 'write-request']);
    expect(doc.fix.argv.slice(-2)).toEqual(['--', requestId]);
    expect(doc.retryable).toBe(false);
    const unsent = await report(new PersistenceIpcTransportError(false));
    expect(unsent).toMatchObject({ error: 'owner_unavailable', code: 'owner_unavailable', submission_status: 'not_sent' });
    expect(unsent.fix.argv.slice(0, 4)).toEqual(['gbrain', 'sources', 'writer', 'status']);
  });
});