Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

15.2 KB
Raw Blame
import { describe, it, expect } from 'vitest';
import { join } from 'path';
import { DONE_SENTINEL_NAME, doneSentinelAgentId, doneSentinelCandidateNames, doneSentinelName, doneSentinelPath, extractSentinelPayloadFromTranscript, missingSentinelLogMessage, parseSentinelPayload, salvageSentinelPayload } from './agentSentinel.js';

describe('missingSentinelLogMessage', () => {
  it('names a startup failure as the reason the sentinel was never written', () => {
    const message = missingSentinelLogMessage({
      agentId: 'agent-1',
      reason: 'paste-not-rendered',
      sentinelPath: '/work/.agent-done-agent-1',
    });
    expect(message).toContain('startup failed (paste-not-rendered)');
    expect(message).not.toContain('finalized');
  });

  it('names the TUI command and provider on a startup failure, and only there', () => {
    const base = { agentId: 'agent-1', reason: 'paste-not-rendered', sentinelPath: '/work/.agent-done-agent-1' };
    expect(missingSentinelLogMessage({ ...base, command: 'codex', providerId: 'codex-tui' }))
      .toBe('agent-1 startup failed (paste-not-rendered tui=codex provider=codex-tui) before a completion sentinel could be written');
    expect(missingSentinelLogMessage({ ...base, reason: 'idle-timeout', command: 'codex', providerId: 'codex-tui' }))
      .toBe('agent-1 finalized (idle-timeout) with no completion sentinel — expected /work/.agent-done-agent-1');
  });

  it('reads a missing TUI binary as a startup failure too', () => {
    // `command-not-found` exits before the prompt was sent — the login-shell
    // path printing "command not found" — so it is the same no-prompt shape.
    expect(missingSentinelLogMessage({
      agentId: 'agent-1',
      reason: 'command-not-found',
      sentinelPath: '/work/.agent-done-agent-1',
    })).toContain('startup failed (command-not-found)');
  });

  it('keeps the expected path when a run that was working exits without the sentinel', () => {
    expect(missingSentinelLogMessage({
      agentId: 'agent-1',
      reason: 'idle-timeout',
      sentinelPath: '/work/.agent-done-agent-1',
    })).toContain('expected /work/.agent-done-agent-1');
  });
});

describe('agentSentinel', () => {
  it('exposes the sentinel filename', () => {
    expect(DONE_SENTINEL_NAME).toBe('.agent-done');
  });

  describe('doneSentinelName', () => {
    it('scopes the filename to the agent instance', () => {
      expect(doneSentinelName('agent-1a2b3c')).toBe('.agent-done-agent-1a2b3c');
    });

    it('gives two concurrent agents distinct filenames', () => {
      expect(doneSentinelName('agent-aaa')).not.toBe(doneSentinelName('agent-bbb'));
    });

    it('falls back to the shared name when no id is available', () => {
      expect(doneSentinelName(null)).toBe('.agent-done');
      expect(doneSentinelName('   ')).toBe('.agent-done');
      expect(doneSentinelName(42)).toBe('.agent-done');
    });

    it('sanitizes path separators out of the id so the name stays one file in the workspace', () => {
      // A traversal-shaped id must not escape the workspace directory.
      expect(doneSentinelName('../../etc/passwd')).toBe('.agent-done-passwd');
      expect(doneSentinelName('a b/c')).toBe('.agent-done-c');
    });
  });

  describe('doneSentinelCandidateNames', () => {
    it('keeps the canonical name first and bounds recovery to one dropped hex suffix', () => {
      expect(doneSentinelCandidateNames('agent-ded2dccb')).toEqual([
        '.agent-done-agent-ded2dccb',
        '.agent-done-agent-ded2dcc',
      ]);
    });

    it('does not broaden recovery for non-generated or non-hex ids', () => {
      expect(doneSentinelCandidateNames('agent-1a2b3c')).toEqual(['.agent-done-agent-1a2b3c']);
      expect(doneSentinelCandidateNames('agent-1234567g')).toEqual(['.agent-done-agent-1234567g']);
      expect(doneSentinelCandidateNames(null)).toEqual(['.agent-done']);
    });
  });

  describe('doneSentinelPath', () => {
    it('resolves the run-scoped file inside the workspace', () => {
      // Worktree-less agents share the primary checkout: a bare `.agent-done`
      // there may be a sibling run's, and must never finalize this one.
      // join(), not a '/'-joined literal: doneSentinelPath composes with path.join,
      // so the separator is '\' on Windows and the contract under test is the
      // COMPOSITION, not the separator.
      expect(doneSentinelPath('/repo', 'agent-1')).toBe(join('/repo', '.agent-done-agent-1'));
    });

    it('degrades to the shared name when no agent id is available', () => {
      expect(doneSentinelPath('/repo', null)).toBe(join('/repo', '.agent-done'));
    });

    it('returns null without a workspace path', () => {
      expect(doneSentinelPath(null, 'agent-1')).toBeNull();
    });
  });

  describe('doneSentinelAgentId', () => {
    it('round-trips every id doneSentinelName produces', () => {
      for (const id of ['agent-1a2b3c', 'agent-aaa', 'a-b.c_d']) {
        expect(doneSentinelAgentId(doneSentinelName(id))).toBe(id);
      }
    });

    it('reports the bare sentinel as belonging to no agent', () => {
      expect(doneSentinelAgentId(DONE_SENTINEL_NAME)).toBe('');
    });

    it('rejects names that are not sentinels', () => {
      // `.agent-done-` with nothing after it is a truncated name, not an id of ''
      // — treating it as the bare sentinel would delete it on the wrong rule.
      expect(doneSentinelAgentId('.agent-done-')).toBeNull();
      expect(doneSentinelAgentId('.agent-doneish')).toBeNull();
      expect(doneSentinelAgentId('README.md')).toBeNull();
      expect(doneSentinelAgentId(null)).toBeNull();
    });
  });

  describe('parseSentinelPayload', () => {
    it('returns empty summary + null payload for missing/blank contents', () => {
      expect(parseSentinelPayload(null)).toEqual({ summary: '', payload: null });
      expect(parseSentinelPayload(undefined)).toEqual({ summary: '', payload: null });
      expect(parseSentinelPayload('   \n ')).toEqual({ summary: '', payload: null });
    });

    it('treats a plain-markdown sentinel as text (legacy back-compat)', () => {
      const md = '## Done\n\n- Fixed the bug\n- Opened PR #42';
      expect(parseSentinelPayload(md)).toEqual({ summary: md, payload: null });
    });

    it('does NOT misread a bare JSON array or scalar as structured', () => {
      expect(parseSentinelPayload('[1, 2, 3]')).toEqual({ summary: '[1, 2, 3]', payload: null });
      expect(parseSentinelPayload('42')).toEqual({ summary: '42', payload: null });
    });

    it('extracts summary + payload from a JSON object sentinel', () => {
      const contents = JSON.stringify({
        summary: 'Proposed one improvement',
        payload: { proposal: { slug: 'add-telemetry', title: 'Add telemetry' } }
      });
      expect(parseSentinelPayload(contents)).toEqual({
        summary: 'Proposed one improvement',
        payload: { proposal: { slug: 'add-telemetry', title: 'Add telemetry' } }
      });
    });

    it('tolerates a JSON object missing summary (payload still surfaces)', () => {
      const contents = JSON.stringify({ payload: { proposal: null } });
      expect(parseSentinelPayload(contents)).toEqual({ summary: '', payload: { proposal: null } });
    });

    it('surfaces an explicit null payload as null (not absent)', () => {
      const contents = JSON.stringify({ summary: 'nothing to file', payload: null });
      expect(parseSentinelPayload(contents)).toEqual({ summary: 'nothing to file', payload: null });
    });

    it('degrades malformed JSON that opens with { to text', () => {
      const broken = '{ not valid json';
      expect(parseSentinelPayload(broken)).toEqual({ summary: broken, payload: null });
    });
  });

  describe('salvageSentinelPayload', () => {
    const envelope = {
      summary: 'Proposed one improvement',
      payload: { analysis: 'a', proposal: { slug: 'add-telemetry', title: 'Add telemetry' } }
    };

    it('returns null payload for blank / brace-free contents', async () => {
      expect(await salvageSentinelPayload(null)).toEqual({ summary: '', payload: null });
      expect(await salvageSentinelPayload('nothing structured here')).toEqual({ summary: 'nothing structured here', payload: null });
    });

    it('recovers an envelope wrapped in ```json fences', async () => {
      const fenced = '```json\n' + JSON.stringify(envelope) + '\n```';
      const { payload } = await salvageSentinelPayload(fenced);
      expect(payload).toEqual(envelope.payload);
    });

    it('recovers an envelope with leading/trailing prose', async () => {
      const noisy = `Here is my result:\n${JSON.stringify(envelope)}\nDone.`;
      const { summary, payload } = await salvageSentinelPayload(noisy);
      expect(payload).toEqual(envelope.payload);
      expect(summary).toBe('Proposed one improvement');
    });

    it('recovers an envelope with raw newlines inside a string value', async () => {
      // A local model pastes a multi-line markdown body verbatim (literal \n,
      // not the escaped \\n JSON requires) — strict JSON.parse rejects it.
      const raw = '{"summary":"s","payload":{"proposal":{"slug":"x","body":"line one\nline two\ttabbed"}}}';
      expect(parseSentinelPayload(raw).payload).toBeNull(); // strict parse fails
      const { payload } = await salvageSentinelPayload(raw);
      expect(payload).toEqual({ proposal: { slug: 'x', body: 'line one\nline two\ttabbed' } });
    });

    it('recovers an envelope whose proposal body contains a markdown code fence', async () => {
      // A reasoner proposing code writes a ```-fenced snippet into the body
      // string. The inner-fence heuristic would otherwise lock onto that body
      // fence and discard the envelope — salvage must skip it.
      const withCodeBody = {
        summary: 's',
        payload: { proposal: { slug: 'x', body: 'Change this:\n```js\nconst a = 1;\n```\ndone' } }
      };
      // Both a fenced-wrapper form and a raw (unwrapped) form must recover.
      const fenced = '```json\n' + JSON.stringify(withCodeBody) + '\n```';
      expect((await salvageSentinelPayload(fenced)).payload).toEqual(withCodeBody.payload);
      expect((await salvageSentinelPayload(JSON.stringify(withCodeBody))).payload).toEqual(withCodeBody.payload);
    });

    it('does NOT misread a legacy markdown summary as structured', async () => {
      const md = '## Done\n\nRefactored `foo()` to return `{ ok: true }` on success.';
      expect(await salvageSentinelPayload(md)).toEqual({ summary: md, payload: null });
    });

    it('does NOT adopt an incidental non-envelope JSON object as payload', async () => {
      const md = 'Summary of work:\n{"unrelated": "config", "count": 3}';
      expect((await salvageSentinelPayload(md)).payload).toBeNull();
    });

    it('surfaces an explicit null payload from a fenced envelope', async () => {
      const fenced = '```json\n{"summary":"nothing to file","payload":null}\n```';
      expect(await salvageSentinelPayload(fenced)).toEqual({ summary: 'nothing to file', payload: null });
    });
  });
describe('extractSentinelPayloadFromTranscript', () => {
    const isReasonerPayload = (p) => !!p && typeof p === 'object' && !Array.isArray(p)
      && ['analysis', 'proposal', 'pause'].some(k => Object.hasOwn(p, k));
    const ANSWER = '{"analysis":"quiet cycle","proposal":null,"pause":null}';

    it('recovers a bare payload object the model printed, ANSI and all', async () => {
      const transcript = `\u001b[32m\u25cf\u001b[0m ${ANSWER}\u001b[0m\r\n`;
      const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
      expect(payload).toEqual({ analysis: 'quiet cycle', proposal: null, pause: null });
    });

    it('unwraps the documented { summary, payload } envelope when that is what was printed', async () => {
      const transcript = 'done: {"summary":"nothing to file","payload":{"proposal":null}}';
      expect(await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload))
        .toEqual({ summary: 'nothing to file', payload: { proposal: null } });
    });

    it('takes the LAST matching object, so the final answer beats an earlier prompt echo', async () => {
      const transcript = `schema: {"analysis":"<example>","proposal":null}\nanswer: ${ANSWER}`;
      const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
      expect(payload.analysis).toBe('quiet cycle');
    });

    it('prefers the enclosing object over its own nested children', async () => {
      const transcript = '{"analysis":"a","proposal":{"scope":"self-improve","title":"t"}}';
      const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
      expect(payload.proposal.title).toBe('t');
    });

    it('survives a truncated repaint that leaves an unmatched brace before the answer', async () => {
      const { payload } = await extractSentinelPayloadFromTranscript(`{ half a redraw ${ANSWER}`, isReasonerPayload);
      expect(payload).not.toBeNull();
    });

    it('keeps a bare deliverable that merely carries its own \`payload\` key', async () => {
      // Unwrapping unconditionally would hand the hook the nested value and drop
      // the answer the model actually printed.
      const transcript = '{"analysis":"a","proposal":null,"payload":"unrelated"}';
      const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
      expect(payload).toEqual({ analysis: 'a', proposal: null, payload: 'unrelated' });
    });

    it('yields no payload for malformed or partial JSON', async () => {
      expect(await extractSentinelPayloadFromTranscript('{"analysis":"cut off mid-thoug', isReasonerPayload))
        .toEqual({ summary: '', payload: null });
      expect(await extractSentinelPayloadFromTranscript('{analysis: not json}', isReasonerPayload))
        .toEqual({ summary: '', payload: null });
    });

    it('recovers a printed deliverable that has a trailing comma before a closing brace', async () => {
      // Observed in the wild: a no-tool review stage printed a well-formed
      // verdict, but one nested array item had a trailing comma before its
      // closing `}` — strict JSON.parse rejected the whole block and the
      // review was discarded as "no output" even though it approved the PR.
      const transcript = '```json\n{"analysis":"a","proposal":{"scope":"self-improve","title":"t",}}\n```';
      const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
      expect(payload.proposal.title).toBe('t');
    });

    it('recovers the answer even when an earlier line left an unmatched quote', async () => {
      const { payload } = await extractSentinelPayloadFromTranscript(`\u2502 renaming "foo\n${ANSWER}`, isReasonerPayload);
      expect(payload).not.toBeNull();
    });

    it('yields no payload for JSON that is not the hook deliverable', async () => {
      expect((await extractSentinelPayloadFromTranscript('{"tokens":1200}', isReasonerPayload)).payload).toBeNull();
    });

    it('yields no payload without a predicate, or for empty/brace-free text', async () => {
      expect((await extractSentinelPayloadFromTranscript(ANSWER, null)).payload).toBeNull();
      expect((await extractSentinelPayloadFromTranscript('no json here', isReasonerPayload)).payload).toBeNull();
      expect((await extractSentinelPayloadFromTranscript(null, isReasonerPayload)).payload).toBeNull();
    });
  });
});