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

20.9 KB
Raw Blame
/**
 * Programmatic-I/O hooks per scheduled task type.
 *
 * Most scheduled task types are `prompt → agent → wait for the .agent-done
 * sentinel`. A few need PROGRAMMATIC steps around the agent. A hook module may
 * export either or both of:
 *
 *   - `buildTaskInput({ app, taskType, ignoreTaskId })` — runs BEFORE spawn, inside
 *     the task generator. Collects data beyond the base prompt (telemetry, open
 *     issues, …) and returns `{ prompt?, providerId?, model?, hookMetadata?, skip? }`.
 *     `ignoreTaskId` is set on the drain-on-completion refill and names the task
 *     that just finished but is still `in_progress` on disk — a hook that counts
 *     in-flight work must exclude it:
 *       • `prompt`     — a fully-rendered prompt that REPLACES the template.
 *       • `providerId` / `model` — pin the agent's provider/model (per-app choice).
 *       • `hookMetadata` — a free-form bag merged into the task's persisted
 *         `metadata`, so a value resolved pre-agent survives to `processTaskOutput`.
 *         The generator applies it only AFTER every gate that can still skip task
 *         creation has passed, so a hook can safely defer a side effect until the
 *         task really exists (a spend ledger, say — #3179) instead of
 *         performing it speculatively here. Untyped by design — a passthrough, not
 *         a schema; keep the keys namespaced to the task type. A key that collides
 *         with generator-computed metadata is DROPPED with a warning, so the bag
 *         can't overwrite `analysisType`, provider pins, or plan ids.
 *       • `skip: { reason }` — short-circuit: no agent is spawned.
 *
 *   - `processTaskOutput({ appId, success, payload, workspacePath, agentId, task }, deps?)`
 *     — runs AFTER the agent finishes, from the finalize chokepoint. `payload` is
 *     the parsed `.agent-done` sentinel payload (the agent's structured output);
 *     the hook does deterministic work on it (e.g. filing a tracker issue) and
 *     returns an outcome. `deps` is an injectable seam for tests.
 *
 *   - `isTaskOutputPayload(payload)` — pure shape check for that hook's own
 *     deliverable. Optional, but a type that omits it forfeits the transcript
 *     rescue for a payload the model printed instead of writing (#3640).
 *
 * The agent itself runs through the NORMAL path (visible in the CoS queue +
 * Active Agents, TUI-capable), so a programmatic-I/O task differs from any other
 * scheduled task only in these two slots. See
 * docs/plans/2026-07-09-programmatic-io-scheduled-tasks.md.
 *
 * Hook modules are lazy-imported (their dependency graphs are heavy) and resolved
 * by task type. `HOOK_MODULES` is the single registration point; a new
 * programmatic-I/O task type adds one entry here plus a module that exports the
 * hook(s) above. An entry may set `input: false` when input is owned by an
 * earlier coordinator phase but the type still needs an output hook. The
 * resolvers return `null` for any unregistered type without importing anything,
 * so a normal task type pays ~zero cost.
 */

import { isFalsyMeta, isTruthyMeta } from './agentState.js';
import { TRACKER_FILING_TASK_TYPES, CONCRETE_WORK_TRACKERS } from '../lib/workTracker.js';
import { isAuditTaskType } from '../lib/auditCatalog.js';
import { hasClaimFlowContract } from '../lib/claimFlowTaskTypes.js';

// taskType → { load }. `load` is the module import thunk; a module may export
// either or both hooks, and a missing export means "no hook of that kind for this
// type". Entries stay objects rather than bare thunks so a capability a caller
// must know WITHOUT paying for the import can be declared here, keeping this the
// single registration point (a parallel per-capability list would be free to drift).
const HOOK_MODULES = {
  'private-security-assessment': { load: () => import('./privateSecurityAssessment.js') },
  'issue-watcher': {
    load: () => import('./issueWatcher.js')
  },
  // pr-reviewer uses a role-aware wrapper: the eligibility stage accepts only
  // a complete binary allowlist, while the optional actions stage delegates to
  // issue-watcher's deterministic forge coordinator. Do not run a live gather
  // hook here: the preflight's exact, fingerprinted snapshot is the only
  // content allowed into the pipeline.
  'pr-reviewer': {
    load: () => import('./prReviewerPipeline.js'),
    input: false,
  },
  'layered-intelligence': {
    load: () => import('./autonomousJobs/layeredIntelligenceHooks.js')
  },
  // buildTaskInput only: skips the dispatch when the operator-action ledger is
  // empty. No output hook — the agent's deliverable is filed issues / queued
  // tasks, and registering here already exempts it from the commit criterion.
  'user-action-review': {
    load: () => import('./userActionReviewHooks.js')
  },
  // buildTaskInput only: runs the deterministic stderr triage and always
  // skips — the investigations it files are separate investigation tasks.
  'error-log-triage': {
    load: () => import('./errorLogTriageHooks.js')
  },
};
const PAYLOAD_OPTIONAL_OUTPUT_HOOKS = new Set();

async function loadHookModule(taskType) {
  if (!isProgrammaticIoTaskType(taskType)) return null;
  return HOOK_MODULES[taskType].load();
}

/**
 * Whether a task type routes through the programmatic-I/O path — i.e. its real
 * output is the `.agent-done` sentinel an output hook consumes, NOT a
 * commit. Synchronous and import-free (a bare registry lookup), so
 * it is safe to consult from hot paths like the agent finalize chain.
 *
 * This is what tells success-criteria validation that the commit criterion does
 * not apply to these tasks (see evaluateSuccessCriteria): their prompts
 * explicitly FORBID committing, so checking for a commit would mark every
 * correct run a failure. `Object.hasOwn` — not a truthiness check — so an
 * inherited key like 'constructor' can't masquerade as a registered type.
 */
export function isProgrammaticIoTaskType(taskType) {
  return typeof taskType === 'string' && Object.hasOwn(HOOK_MODULES, taskType);
}

/**
 * Whether recovery may safely run this output hook when its worktree/sentinel
 * no longer exists. Payload-dependent hooks must wait for a real sentinel
 * rather than treating recovery's missing output as an agent-produced empty
 * response.
 */
export function canRunTaskOutputHookWithoutPayload(taskType) {
  return PAYLOAD_OPTIONAL_OUTPUT_HOOKS.has(taskType);
}

/**
 * The task type a hook is keyed on, for a task record. The SCHEDULED type lives in
 * `metadata.analysisType` (the top-level `task.taskType` is the CoS queue category,
 * e.g. 'internal'). Archived agent/task projections historically called that
 * field `metadata.taskAnalysisType`, so accept it as a compatibility fallback
 * before falling back to `taskType` for a task shaped the other way.
 *
 * Single resolver on purpose (#2727): "does this task get the programmatic-I/O
 * success criterion?" and "does this task run an output hook?" must be the same
 * question. When they diverged, a task carrying only `taskType:
 * 'layered-intelligence'` ran the hook but was still commit-checked — the exact
 * #2700 bug, one shape over.
 */
export function resolveTaskHookType(task) {
  return task?.metadata?.analysisType || task?.metadata?.taskAnalysisType || task?.taskType || null;
}

/**
 * Scheduled COORDINATOR task types whose deliverable is a git/gh/external side effect —
 * a merged PR, a resolved conflict, a deleted branch, healed issue state, a status report
 * posted to Jira — NOT a commit. Their agent runs in the app's LIVE checkout
 * (no worktree, no PR), so they DO have a workspacePath at finalize, and the task-id commit
 * commit criterion would score every SUCCESSFUL run as a failure and pin their learning
 * bucket at ~0% (#2696). They declare no commit criterion (fall back to the exit code),
 * exactly like pipeline/media jobs.
 *
 * Deliberately NOT every self-improvement type: accessibility / security / code-quality
 * / jira-sprint-manager / do-replan all COMMIT (fixing tasks, or a triage that commits
 * PLAN.md), so their commit criterion is real and must stay — exempting them would
 * MASK genuine failures. The claim flows (plan-task / claim-issue / claim-issue-gitlab /
 * claim-issue-jira / claim-work) also commit, but in a worktree the agent itself cuts —
 * they are exempted from the PARENT-workspace commit probe by their own predicate
 * (`isClaimFlowDispatch` below), not by this set. Only complete tasks whose DEFAULT
 * contract is structurally no-commit belong here.
 *
 * pr-watcher is intentionally excluded on a different axis: it is a review-of-others'-PRs
 * TEMPLATE — its shipped prompt explicitly says "the operator customizes this prompt to
 * change what happens on each opened PR" (and it ships `readOnly:false`), i.e. it is
 * designed to be rewritten, commonly into a commit-pushing flow, so a type-level exemption
 * would be the wrong default for it. The coordinator types here are complete tasks that finish
 * YOUR in-flight work via a git/gh/API side effect. CAVEAT: the exemption keys on the
 * SCHEDULED TYPE, not the actual per-install prompt, so an operator who rewrites one of
 * these coordinator prompts to make source commits would have that customized run judged by exit
 * code instead of its commit (a telemetry-accuracy tradeoff, not a functional bug). A
 * per-task `noCommitCriterion` contract would remove that caveat but complicates the
 * migration's static type→bucket mapping; deferred as not worth it for the default case.
 *
 * Kept as a leaf so both agentLifecycle (the live criterion) and taskLearning's history
 * backfill (migration-durability) read ONE source of truth. Migration 198 purges the
 * buckets these already poisoned on existing installs.
 */
export const NON_COMMITTING_COORDINATOR_TASK_TYPES = new Set([
  'app-checkout-recovery', 'branch-reconcile', 'issue-reconcile', 'branch-cleanup', 'jira-status-report', 'do-release',
  'stash-cleanup', 'repo-sync', 'pr-reviewer', 'model-comparison-refresh',
  // Pre-rename name of do-release (migration 417): queued and archived tasks
  // still carry it, and their buckets must keep the coordinator exemption.
  'release-check',
]);

/**
 * Whether a task declares NO commit criterion because it is a gh/git
 * coordinator (see NON_COMMITTING_COORDINATOR_TASK_TYPES).
 *
 * Resolves the type the SAME way extractTaskType (taskLearning/store.js) computes the
 * learning bucket — `metadata.analysisType || metadata.taskAnalysisType || taskType` — NOT
 * via resolveTaskHookType (which reads only `analysisType`). This matters for the archived
 * agent shape: a LIVE queue task carries `metadata.analysisType`, but agentLifecycle stamps
 * the run's type onto the AGENT record as `metadata.taskAnalysisType` (agentLifecycle.js),
 * and that archived form is exactly what the history backfill re-processes. Keying on
 * `analysisType` alone made this predicate DISAGREE with the bucket for archived agents, so
 * the backfill sanitizer skipped them and the migration's purge could be undone (#2696,
 * codex review). Matching extractTaskType keeps the criterion, the bucket, and the sanitizer
 * consistent across both task shapes.
 *
 * PR follow-ups (`metadata.reviewLoopFollowUp`, spawned by agentWorktreeCleanup)
 * are the same shape without being a scheduled type: they deliver a reviewed
 * and/or merged PR as a side effect, and the happy path makes NO commit at all —
 * a merge-only follow-up on an already-green PR just merges it, and even a review
 * follow-up commits nothing when every reviewer comes back clean. Commit-checking
 * them would record each successful run as a failure, the #2696 artifact again.
 *
 * PR remediation follow-ups (`metadata.prRemediationFollowUp`, spawned by
 * prRemediationFollowUp.js when pr-reviewer reviewed an external PR it could not
 * merge) are the same shape one step further out: their commits land on the
 * CONTRIBUTOR's branch inside a throwaway worktree, so this app's checkout is
 * clean by construction even on the run that fixed and merged the PR.
 */
export function isNonCommittingCoordinatorTask(task) {
  if (isTruthyMeta(task?.metadata?.reviewLoopFollowUp)) return true;
  if (isTruthyMeta(task?.metadata?.prRemediationFollowUp)) return true;
  const type = task?.metadata?.analysisType || task?.metadata?.taskAnalysisType || task?.taskType || null;
  return NON_COMMITTING_COORDINATOR_TASK_TYPES.has(type);
}

/**
 * Whether a task runs a CLAIM flow — plan-task / claim-issue / claim-issue-gitlab /
 * claim-issue-jira / claim-work — whose prompt owns its OWN claim/<item> worktree
 * and forge lifecycle (worktree, PR/MR, merge, cleanup) while CoS keeps
 * `useWorktree`/`openPR` false so it never provisions a nested worktree.
 *
 * NOT a `declaresNoCommitCriterion` shape, on purpose. A claim run's deliverable
 * IS a commit — but it lands in the claim worktree the AGENT cut, not in the
 * workspace `evaluateSuccessCriteria` probes (the app's live checkout for a
 * first-run claim, or the claim tree only on a `claimResumeInPlace` continuation).
 * The run-window commit probe is workspace-scoped, so on the common path it sees
 * nothing and a declared `validationPassed: false` OVERRIDES the exit code in
 * task-learning — scoring every successful claim run a failure and pinning the
 * type's bucket at ~0% (the #2696 artifact arriving by a new route). The
 * goal-fidelity gate still judges claim runs against the claimed issue's
 * requirements (its claimFlow branch), so this exemption trades a redundant
 * commit probe for the exit code without losing the fidelity review.
 *
 * Resolved the same way `evaluateGoalFidelity` resolves claimFlow (and the same
 * analysisType → taskAnalysisType → taskType chain the learning bucket uses), so
 * a LIVE queue task, the archived agent projection, and the bucket agree. The
 * explicit `claimFlow` marker covers a schedule queued before the marker existed
 * and a manually marked claim (a dependency task also marked claimFlow); the
 * type set is the backstop for records carrying only the scheduled type.
 */
export function isClaimFlowDispatch(task) {
  return hasClaimFlowContract(task);
}

/**
 * Whether a task declares NO commit criterion: the static
 * coordinator set above, a NO-CODE-OUTPUT task (its deliverable is an action —
 * an HTTP PATCH, a filed issue — and its prompt never asks for a commit), OR a
 * TRACKER-FILING task whose dispatch derived
 * `worktreeChangesExpected: false` (cosTaskGenerator.js#resolveTrackerFilingBlock,
 * referenceRepos.js#triggerReferenceAnalysis).
 *
 * A type-keyed set alone cannot express the tracker-filing shape: the SAME task
 * type legitimately commits on a `plan`-tracker app (it appends + commits
 * PLAN.md checklist items) and legitimately commits NOTHING on a
 * github/gitlab/jira app (it files issues/tickets out of band). Reading the
 * already-derived per-task flag gets both right, and retro-fixes the same latent
 * #2696-class artifact `reference-watch` has on non-`plan` trackers today —
 * every successful run scoring as a failure and pinning the type's learning
 * bucket at ~0% (#3273).
 *
 * The flag alone is NOT sufficient, hence the type gate in front of it:
 * `worktreeChangesExpected` is a user-settable per-app taskMetadata override
 * accepted for EVERY task type (`cosValidation.js` ALLOWED keys → `POST
 * /api/apps/:id/task-types` → merged into `metadata` in
 * cosTaskGenerator.js#prepareManagedAppImprovementTask). It exists to
 * mark a run's deliverable as outside the worktree; someone setting it there is
 * not asking to disable success validation. Ungated, a `security` task
 * carrying it would exit 0 having committed nothing and be recorded as a pass
 * instead of the honest miss it is.
 *
 * Accepts the `'false'` string form for parity with the spawn-side gate
 * (agentTuiSpawning.js's `isFalsyMeta`), since task metadata round-trips through
 * TASKS.md as text. `true`/absent falls through to the commit check unchanged.
 */
export function declaresNoCommitCriterion(task) {
  if (isNonCommittingCoordinatorTask(task)) return true;
  // A discarded worktree cannot leave a commit behind by
  // construction — cleanup removes it without merging, and the prompt forbids
  // committing at all. Scoring the commit check against it marks every
  // SUCCESSFUL run a validation miss and drags that provider/model's learning
  // bucket toward 0% — the #2696/#3273 artifact, arriving by a third route.
  if (isTruthyMeta(task?.metadata?.discardWorktree)) return true;
  // `noCodeOutput` tasks deliver something the agent DOES — an HTTP PATCH, a filed
  // issue, an API call — and their prompt routes through
  // agentPromptBuilder#buildActionOutputCompletionSection, which explicitly does
  // NOT tell them to commit or open a PR. Creative Director tasks are the shipped
  // instance of that shape (their deliverable is `PATCH /api/creative-director/…`),
  // and they run with `useWorktree: false` against the live checkout — so
  // workspacePath IS set and the commit criterion scored every SUCCESSFUL run as a
  // miss, the #2696/#3273 artifact reaching CD by a fourth route (#4146). Resolved
  // exactly as agentPromptBuilder resolves it (flag OR the creativeDirector
  // metadata block) so the criterion and the prompt can't disagree about whether a
  // commit was ever asked for. Their REAL deliverable is verified in the CD
  // completion hook, which is the only place the project record is visible.
  if (isTruthyMeta(task?.metadata?.noCodeOutput) || task?.metadata?.creativeDirector) return true;
  if (!isTrackerFilingDispatch(task)) return false;
  return isFalsyMeta(task?.metadata?.worktreeChangesExpected);
}

/**
 * Whether this task was dispatched by a TRACKER-FILING path — the gate in front
 * of the `worktreeChangesExpected` read above (see that doc comment for why the
 * flag alone is not enough).
 *
 * Two shapes qualify, because tracker-filing runs arrive two ways:
 *
 *   1. A SCHEDULED type in `TRACKER_FILING_PRESETS` (`reference-watch`, `ux`).
 *      Resolved the same way isNonCommittingCoordinatorTask (and the learning
 *      bucket) resolves it, so a LIVE queue task (`analysisType`) and the
 *      archived agent projection (`taskAnalysisType`) agree.
 *   2. A one-off task whose dispatch stamped `metadata.workTracker` — the
 *      concrete tracker the `{trackerInstructions}` block told the agent to file
 *      into. Only a tracker-filing dispatch writes it (repoIntake.js's
 *      `repo-study`, referenceRepos.js#triggerReferenceAnalysis), and it is NOT
 *      in cosValidation's per-app `taskMetadata` ALLOWED keys, so unlike
 *      `worktreeChangesExpected` a user cannot set it on an unrelated task type.
 *
 * Without (2), a hand-queued tracker-filing run could only reach this gate by
 * masquerading as a scheduled type — which would also enroll it in
 * taskSchedule's per-type consecutive-failure ledger (agentFinalization.js) and
 * auto-park a "type" no schedule owns.
 */
function isTrackerFilingDispatch(task) {
  const type = task?.metadata?.analysisType || task?.metadata?.taskAnalysisType || task?.taskType || null;
  // Explicit fileIssues on an audit type wins — including turning ux (which
  // still lives in TRACKER_FILING_TASK_TYPES for back-compat) into do-work.
  if (isTruthyMeta(task?.metadata?.fileIssues)) return true;
  if (isFalsyMeta(task?.metadata?.fileIssues) && isAuditTaskType(type)) return false;
  if (TRACKER_FILING_TASK_TYPES.has(type)) return true;
  return CONCRETE_WORK_TRACKERS.includes(task?.metadata?.workTracker);
}

/**
 * Resolve the pre-agent input hook for a task type, or null if it has none.
 * `buildTaskInput({ app, taskType })` → `{ prompt?, providerId?, model?, hookMetadata?, skip? }`
 * (see the module header for each field's contract).
 */
export async function getTaskInputHook(taskType) {
  if (HOOK_MODULES[taskType]?.input === false) return null;
  const mod = await loadHookModule(taskType);
  return mod && typeof mod.buildTaskInput === 'function' ? mod.buildTaskInput : null;
}

/**
 * Resolve the post-agent output hook for a task type, or null if it has none.
 * `processTaskOutput({ appId, success, payload, workspacePath, agentId, task })` → outcome.
 */
export async function getTaskOutputHook(taskType) {
  const mod = await loadHookModule(taskType);
  return mod && typeof mod.processTaskOutput === 'function' ? mod.processTaskOutput : null;
}

/**
 * Resolve the hook's own payload SHAPE predicate, or null if it declares none.
 * `isTaskOutputPayload(payload)` → boolean.
 *
 * Only the hook knows what its deliverable looks like, so the transcript rescue
 * in `agentFinalization` (#3640) — which recovers a payload the model printed to
 * the terminal instead of writing to `.agent-done` — asks the hook rather than
 * guessing. A type that exports no predicate simply gets no rescue: without a
 * shape to check against, any JSON-ish blob in the transcript would qualify.
 */
export async function getTaskOutputPayloadPredicate(taskType) {
  const mod = await loadHookModule(taskType);
  return mod && typeof mod.isTaskOutputPayload === 'function' ? mod.isTaskOutputPayload : null;
}