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

14.6 KB
Raw Blame
/**
 * The `.agent-done` completion sentinel — shared naming + parser.
 *
 * A finishing agent writes this file into its workspace to signal completion
 * (see agentTuiSpawning's sentinel watcher). The file is named per agent instance
 * (`.agent-done-<agentId>`, see `doneSentinelName`) because worktree-less runs
 * share one workspace and would otherwise clobber each other's signal.
 *
 * Historically it held a plain-markdown
 * task summary that gets appended to the agent's output. Programmatic-I/O task
 * types (see docs/plans/2026-07-09-programmatic-io-scheduled-tasks.md) also need
 * a STRUCTURED result back — e.g. Layered Intelligence's reasoner JSON — so the
 * sentinel may instead be a JSON object `{ summary, payload }` where `payload`
 * is the machine-readable result a `processTaskOutput` hook consumes.
 *
 * `parseSentinelPayload` is pure and back-compat: a plain-text sentinel yields
 * `{ summary: <text>, payload: null }`; a JSON object yields its `summary`
 * (string, if present) plus its `payload`. Anything that fails to shape up
 * (empty, non-object JSON like a bare array/number) degrades to text so an
 * existing markdown sentinel is never misread as structured.
 */

import { join } from 'path';
import { normalizeTaskOutcome } from './agentOutcome.js';

import { safeJSONParse, sanitizeFilename } from './fileUtils.js';

export const DONE_SENTINEL_NAME = '.agent-done';

/**
 * Heading of the briefing section that prints this run's absolute sentinel path
 * for a reasoning-only (programmatic-output) task — see
 * `buildProgrammaticOutputCompletionSection` in agentPromptBuilder.
 *
 * A task-type hook renders its prompt BEFORE spawn, so it cannot know the
 * per-instance filename (`.agent-done-<agentId>`) and must point the agent at
 * the briefing instead. That pointer only works if both sides agree on the
 * heading, hence one exported constant rather than the string typed twice.
 * Pointing POSITIVELY at this section is also the whole contract: a prompt that
 * warns against some other filename is the only place the agent would learn
 * that filename exists.
 */
export const PROGRAMMATIC_OUTPUT_COMPLETION_HEADING = 'Completion (Reasoning-Only Task)';

/**
 * The sentinel filename for one agent instance: `.agent-done-<agentId>`.
 *
 * Agents that run WITHOUT a worktree (`useWorktree: false` — e.g. the
 * issue-filing and reasoning task types) all share the primary checkout as
 * their workspace, so a single shared `.agent-done` is a cross-run hazard: two
 * concurrent agents overwrite each other's summary, and whichever poll fires
 * first finalizes the *other* agent's run on a sentinel it never wrote. Scoping
 * the filename to the agent id keeps each run's done-signal its own file.
 *
 * The id goes through the shared `sanitizeFilename` (not a private charset
 * regex) so this filename answers "is this token safe on disk" the same way the
 * rest of the repo does. Falls back to the bare name when no usable id is
 * available, so a caller without one still resolves to something readable.
 */
export function doneSentinelName(agentId) {
  const slug = typeof agentId === 'string' ? sanitizeFilename(agentId.trim()).slice(0, 64) : '';
  return slug ? `${DONE_SENTINEL_NAME}-${slug}` : DONE_SENTINEL_NAME;
}

/**
 * The names a run-scoped watcher may inspect, in canonical-first order.
 *
 * Producers have exactly one name: `doneSentinelName(agentId)`. The second
 * name is a deliberately narrow recovery for a generated agent id whose final
 * hexadecimal character was dropped while a terminal copied the path. It is
 * not a second producer contract: runtime consumers must still require a
 * fresh, unambiguous file before accepting it.
 */
export function doneSentinelCandidateNames(agentId) {
  const canonical = doneSentinelName(agentId);
  const normalizedId = typeof agentId === 'string' ? agentId.trim() : '';
  if (!/^agent-[0-9a-f]{8}$/.test(normalizedId)) return [canonical];

  const truncated = doneSentinelName(normalizedId.slice(0, -1));
  return truncated === canonical ? [canonical] : [canonical, truncated];
}

/**
 * The agent id encoded in a done-sentinel filename.
 *
 * The inverse of `doneSentinelName`, and the only place that reverses it:
 * a sweep deciding whether a leftover `.agent-done-*` belongs to a run that is
 * still alive has to get the SAME answer the producer got, or it deletes a live
 * run's completion signal.
 *
 * Returns the id for a scoped sentinel, `''` for the bare unscoped
 * `.agent-done` (a real sentinel, attributable to no run), and `null` when the
 * name is not a sentinel at all.
 */
export function doneSentinelAgentId(name) {
  if (typeof name !== 'string') return null;
  if (name === DONE_SENTINEL_NAME) return '';
  const prefix = `${DONE_SENTINEL_NAME}-`;
  return name.startsWith(prefix) && name.length > prefix.length ? name.slice(prefix.length) : null;
}

const STARTUP_SENTINEL_REASONS = new Set(['paste-not-rendered', 'tui-not-ready', 'command-not-found', 'prompt-not-submitted']);

/**
 * The operator line for a TUI that ended without its completion sentinel.
 *
 * A startup failure never received the prompt, so the missing file is a
 * consequence, not a second fault. Naming it as "finalized with no sentinel"
 * reads as an agent that finished the task and skipped the done-signal.
 */
export function missingSentinelLogMessage({ agentId, reason, sentinelPath, mergeGateReprompted = false, command, providerId }) {
  if (STARTUP_SENTINEL_REASONS.has(reason)) {
    // The TUI identity lets a stderr fingerprint separate one provider's
    // handshake stall from another's (#12877).
    const tui = [command && `tui=${command}`, providerId && `provider=${providerId}`].filter(Boolean).join(' ');
    return `${agentId} startup failed (${reason}${tui ? ` ${tui}` : ''}) before a completion sentinel could be written`;
  }
  if (mergeGateReprompted) {
    return `${agentId} finalized (${reason}) without re-writing its sentinel after the merge-gate nudge — expected ${sentinelPath}`;
  }
  return `${agentId} finalized (${reason}) with no completion sentinel — expected ${sentinelPath}`;
}

/**
 * The one canonical path this run's sentinel lives at — `null` without a
 * workspace. Producers and normal consumers resolve it here: the prompt the
 * agent is given, the canonical TUI watcher, the CLI exit check, and the
 * output-hook payload read. The TUI runtime may additionally use
 * `doneSentinelCandidateNames` for its bounded terminal-copy recovery; this
 * function remains the producer's one canonical path and is pure.
 */
export function doneSentinelPath(workspacePath, agentId) {
  if (!workspacePath || typeof workspacePath !== 'string') return null;
  return join(workspacePath, doneSentinelName(agentId));
}

/**
 * Parse `.agent-done` contents into `{ summary, payload }`.
 *   - `summary`: human-readable text for the agent output/card (never null;
 *     falls back to the raw trimmed contents).
 *   - `payload`: the structured result for a task-type output hook, or null
 *     when the sentinel carried no JSON object (the common legacy case).
 * Pure — no I/O. `contents` may be null/undefined (missing file).
 */
export function parseSentinelPayload(contents) {
  const trimmed = typeof contents === 'string' ? contents.trim() : '';
  if (!trimmed) return { summary: '', payload: null };

  // Only a JSON OBJECT counts as structured. `safeJSONParse` with allowArray:false
  // rejects a root array and returns null for malformed content, but still parses
  // a bare scalar (`"42"`, `"true"`) — so guard for a genuine object here too, or
  // a legacy sentinel that happens to be a lone number/string/bool would crash on
  // the `'payload' in parsed` check below instead of round-tripping as text.
  const parsed = safeJSONParse(trimmed, null, { allowArray: false });
  if (parsed && typeof parsed === 'object') {
    const summary = typeof parsed.summary === 'string' ? parsed.summary : '';
    const payload = 'payload' in parsed ? parsed.payload : null;
    const taskOutcome = normalizeTaskOutcome(parsed.taskOutcome);
    return { summary, payload, ...(taskOutcome ? { taskOutcome } : {}) };
  }

  return { summary: trimmed, payload: null };
}

/**
 * Lenient fallback for a STRUCTURED sentinel that the strict
 * `parseSentinelPayload` couldn't read. A less-capable model (notably a local
 * one) commonly emits an almost-valid `{ summary, payload }` envelope — wrapped
 * in ```json fences, trailed by prose, or with raw newlines/tabs pasted into
 * the long markdown `body` string — which `JSON.parse` rejects, silently
 * dropping a real proposal as "unparseable-response". This runs the shared
 * robust LLM-JSON extractor (`jsonExtract.extractJson`: strips fences, walks
 * balanced blocks, repairs trailing commas / orphan braces / raw control
 * chars) over the raw contents and, ONLY when it recovers the documented
 * envelope shape (a `{ ..., "payload": ... }` object), surfaces its payload.
 *
 * Deliberately narrow: it requires the `payload` key so a legacy plain-markdown
 * sentinel that merely happens to contain a `{...}` block is never misread as
 * structured — that stays text (payload null). Async + a LAZY import of
 * jsonExtract so the barrel re-export of this module doesn't statically pull
 * jsonExtract's transitive services chain into every lib consumer / mocked
 * suite. Callers use it as a second tier after `parseSentinelPayload` returns a
 * null payload (see agentLifecycle's dispatchTaskOutputHook).
 *
 * @param {string|null|undefined} contents — raw `.agent-done` contents
 * @returns {Promise<{ summary: string, payload: unknown }>}
 */
export async function salvageSentinelPayload(contents) {
  const trimmed = typeof contents === 'string' ? contents.trim() : '';
  if (!trimmed || !trimmed.includes('{')) return { summary: trimmed, payload: null };

  // The documented sentinel envelope: a plain object carrying a `payload` key.
  const isEnvelope = (v) => v && typeof v === 'object' && !Array.isArray(v) && 'payload' in v;

  // skipInnerFence: the reasoner's `payload.proposal.body` is markdown that
  // routinely contains its own ```code``` fence; without this, extractJson's
  // inner-fence heuristic would lock onto that body fence and discard the whole
  // envelope. Balanced-block walking is string-aware, so a fence inside the
  // JSON string value can't derail it.
  const { extractJson } = await import('./jsonExtract.js');
  const { value } = extractJson(trimmed, { shapePredicate: isEnvelope, skipInnerFence: true });
  // Re-verify the shape: extractJson falls back to the first block that merely
  // PARSED (ignoring the predicate) when none matched, so an incidental
  // non-envelope object must not be adopted as a payload.
  if (!isEnvelope(value)) return { summary: trimmed, payload: null };

  const summary = typeof value.summary === 'string' ? value.summary : '';
  return { summary, payload: value.payload };
}

/**
 * Last-resort rescue for a programmatic-I/O deliverable the agent PRINTED into
 * its terminal instead of writing to `.agent-done` (#3640).
 *
 * For these task types the sentinel JSON *is* the product of the run — a
 * Layered Intelligence proposal becomes a filed tracker issue. A weaker model
 * (typically a local one) commonly answers in the TUI rather than through the
 * tool call, and the run is then discarded with `payload: undefined` even
 * though the reasoning completed. Scanning the transcript recovers it.
 *
 * Deliberately predicate-gated and scoped to programmatic-I/O callers: for
 * every other task type the sentinel is a COMPLETION SIGNAL, not a deliverable,
 * and scraping a transcript for one would let an agent that merely *discussed*
 * finishing be treated as finished. `isPayload` is the owning hook's own shape
 * check (see taskTypeHooks' `getTaskOutputPayloadPredicate`), so a transcript
 * that only contains chatter, a schema example, or partial JSON yields nothing
 * rather than a garbage payload.
 *
 * Blocks are walked in REVERSE closing order — the model's final answer wins
 * over an earlier prompt echo of the same schema, and an enclosing object wins
 * over its own nested children. Each candidate goes through
 * `tryParseWithRepair` rather than a bare strict parse: for a tool-free
 * programmatic-I/O stage (e.g. pr-reviewer's no-filesystem-access review role),
 * the transcript print IS the committed deliverable — there is no `.agent-done`
 * file to fall back to — so it deserves the same trailing-comma / orphan-brace
 * repair tolerance `salvageSentinelPayload` already applies to a written
 * sentinel. The repairs are conservative and string-aware (never touch content
 * that already parses, never fix unquoted keys or other non-JSON prose), so a
 * genuinely non-JSON block (an object-literal echo, truncated prose) still
 * fails to parse and is skipped.
 *
 * Async + LAZY imports for the same reason as `salvageSentinelPayload` — the
 * barrel re-export of this module must not statically pull jsonExtract's
 * transitive chain into every lib consumer / mocked suite.
 *
 * @param {string|null|undefined} transcript — ANSI-bearing raw PTY text
 * @param {(payload:unknown)=>boolean} isPayload — the hook's shape predicate
 * @returns {Promise<{ summary: string, payload: unknown }>}
 */
export async function extractSentinelPayloadFromTranscript(transcript, isPayload) {
  const none = { summary: '', payload: null };
  if (typeof transcript !== 'string' || !transcript.includes('{')) return none;
  if (typeof isPayload !== 'function') return none;

  const { stripAnsi } = await import('./ansiStrip.js');
  const { findAllBalancedBlocks, tryParseWithRepair } = await import('./jsonExtract.js');
  const blocks = findAllBalancedBlocks(stripAnsi(transcript));

  for (let i = blocks.length - 1; i >= 0; i -= 1) {
    const { value: parsed, error } = tryParseWithRepair(blocks[i]);
    // `typeof` guard, not just truthiness: the `in` check below throws on a
    // primitive, and a best-effort salvage must never be the thing that breaks
    // finalize.
    if (error || !parsed || typeof parsed !== 'object' || Array.isArray(parsed)) continue;
    // Two shapes reach a transcript: the documented `{ summary, payload }`
    // envelope the agent should have written to the sentinel, and the BARE
    // payload object — what a model answering in the terminal actually prints.
    // Unwrap only when the inner value is ITSELF a valid payload: a bare
    // deliverable that merely happens to carry a `payload` key would otherwise
    // be discarded in favour of a nested value the hook can't use.
    const unwrap = 'payload' in parsed && isPayload(parsed.payload);
    const candidate = unwrap ? parsed.payload : parsed;
    if (!isPayload(candidate)) continue;
    const summary = typeof parsed.summary === 'string' ? parsed.summary : '';
    return { summary, payload: candidate };
  }
  return none;
}