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

18.8 KB
Raw Blame
import { isTruthyMeta } from './metadataFlags.js';
import { processAuditRecoveryOriginSchema } from './persistentMindProcessAudit.js';
/**
 * The agent record a spawn registers, projected from the task it is running.
 *
 * `agent.metadata` is a HAND-PICKED projection of `task.metadata`, never a
 * spread — every consumer downstream (the run cards, `perpetualRefillPlan`,
 * `declaresNoCommitCriterion`, the quota-burn continuation, `featureAgents`)
 * reads the agent record alone, so a field that is not listed here simply does
 * not survive the spawn. That is the whole reason this is one explicit literal
 * and not a merge: adding a task field is supposed to be a deliberate decision
 * about whether the agent needs it, and `quotaBurnStepId` shipped persisted but
 * unprojected (#6406) precisely because the list was being maintained inline in
 * the middle of a 900-line orchestrator.
 *
 * Pure and synchronous: everything it needs is already resolved by the caller.
 * `primaryCheckoutBaseline` and `providerEndpoint` arrive as VALUES rather than
 * being read here (both were `await`/service calls inline), which keeps this
 * leaf out of the agent-state and local-endpoint graphs.
 */

// From the module that DECLARES it, not the `validation.js` catch-all barrel:
// that barrel drags 123 modules into every suite this leaf reaches, for one
// pure helper (server/AGENTS.md, "Import scoping").
import { normalizeReviewers } from './reviewerConfig.js';
import { quotaBurnAgentMetadata } from './quotaBurnOrigin.js';
import { claimOwnershipBinding, reconcileAssignmentForTask } from './claimContinuation.js';
import { explicitPrCompletion } from './prDisposition.js';
import { repositoryCleanupMergeTarget } from './recoveryMergeTarget.js';

/**
 * How this run is dispatched, as one closed vocabulary rather than the nested
 * ternary chain it replaced: a headless run is `direct` or `runner`, and an
 * interactive PTY session is `tui` or `runner-tui`, with the `runner-` prefix
 * meaning the durable CoS runner owns the child instead of this process.
 */
export function resolveExecutionMode({ spawnHeadless, useRunner }) {
  if (spawnHeadless) return useRunner ? 'runner' : 'direct';
  return useRunner ? 'runner-tui' : 'tui';
}

/** The `registerAgent` payload for one spawn. See the module note above. */
export function buildAgentRegistration({
  task,
  provider,
  instanceId,
  workspacePath,
  sourceWorkspace,
  repoIssueUrl,
  primaryCheckoutBaseline,
  auditSourceEvidence = null,
  worktreeInfo,
  explicitWorktree,
  jiraBranchName,
  providerEndpoint,
  localPromptBudget,
  leanMode,
  prOpenedBy,
  mergesOwnPr = false,
  claimFlowTask,
  selectedModel,
  effort = null,
  modelSelection,
  runId,
  dispatchUseRunner,
  executionMode,
  publicReviewPosture,
  resolvedAppName,
  injectedMemories = [],
}) {
  return {
    instanceId,
    workspacePath,
    sourceWorkspace,
    // Branch-jack baseline (#3680): the primary checkout's branch + HEAD at the
    // instant this worktree agent started. finalizeAgent re-reads it at the end
    // of the run — every spawn mode funnels through that one chokepoint — and
    // fails the run when the primary moved, instead of recording a silent
    // "completed" for an agent that wrote unreviewed commits outside its
    // worktree. Non-throwing: an unreadable checkout yields null, which the
    // detector reads as "nothing to check".
    primaryCheckoutBaseline,
    // Trusted launch capture only; never project a task/model-supplied claim.
    auditSourceEvidence,
    ...(Number(task.metadata?.auditDispositionVersion) === 1 ? { auditDispositionVersion: 1 } : {}),
    // The issue-tracker base URL of the repository this run worked in, already
    // shaped for its forge (`repoIssueUrlBase`) so the browser appends a number
    // and knows nothing about forges. It is what a bare `#7640` in the agent's
    // own completion summary refers to, so the run card renders that reference
    // as a link without the agent having to build a URL it has no reliable way
    // to know.
    //
    // Stamped rather than resolved at render time for the two reasons the
    // baseline above is: it is immutable run provenance (re-pointing an app at
    // a different origin later must not silently relabel finished runs), and
    // the alternative is a `git` shell-out per card render. A record written
    // before this shipped carries null, which the card reads as plain text.
    repoIssueUrl,
    worktreeBranch: worktreeInfo?.branchName || null,
    // Keep explicit handoffs after task archival; omitted policy is not a grant.
    prCompletionPolicy: explicitPrCompletion(task),
    isWorktree: !!worktreeInfo,
    isPersistentWorktree: !!worktreeInfo?.isPersistentWorktree,
    isRecovery: isTruthyMeta(task.metadata?.isRecovery),
    recoveryOrigin: processAuditRecoveryOriginSchema.safeParse(task.metadata?.recoveryOrigin).data || null,
    taskDescription: task.description,
    taskType: task.taskType,
    priority: task.priority,
    providerId: provider.id,
    // Immutable, non-secret route provenance for the active/completed cards.
    // Keep this as individual fields rather than copying the provider record:
    // envVars, endpoints, args and credentials are execution details, not run
    // metadata that should be persisted or rendered in the card.
    providerName: provider.name || null,
    providerType: provider.type || null,
    providerMethod: provider.method || provider.type || null,
    harnessId: provider.harnessId || null,
    serviceId: provider.serviceId || null,
    servicePlan: provider.servicePlan || null,
    providerCredentialBootstrapId: provider.credentialBootstrapId || null,
    providerHasCredentialBootstrap: Boolean(provider.credentialBootstrap),
    // Persisted alongside the id because the cleanup path's `agentOpensOwnPr`
    // gate must derive from the SAME `canTypeSlashCommands` predicate the prompt
    // used to decide whether the agent opens its own PR (#3114). An id alone
    // can't answer that — a path-configured `claude` under a custom id is
    // slashdo-capable, and a lean `--bare` session is not.
    providerCommand: provider.command || null,
    // The endpoint this agent's inference actually lands on, stamped for the
    // same reason as the command above: the per-local-endpoint spawn cap
    // (#4834) must know which GPU a RUNNING agent is occupying, and an id
    // alone can't answer that once the provider record is edited or deleted
    // mid-run. Pre-#4834 agent records have no value here, so the counter
    // falls back to resolving the id against the live provider list.
    //
    // Resolved through the SAME helper the counter reads with, so writer and
    // reader can't drift — a CLI provider records its daemon in envVars or an
    // OpenCode config, not in `endpoint`. Stamped as the RAW url, never the
    // slot key: a slot key is null for a cloud provider, and stamping null
    // would re-open the mid-run-edit hole this exists to close.
    providerEndpoint,
    // What this run's prompt costs to prefill on a LOCAL endpoint, and the
    // duration estimate raised by it (#6117). `null` for a cloud provider and
    // for a run with nothing assembled to measure — the card must read that as
    // "no estimate", never as a small one, so it stays absent rather than 0.
    localPromptBudget,
    leanMode,
    // WHO opens this run's PR (`agent-slashdo` / `agent-inline` / `portos`),
    // per the prompt this run was actually given. Persisted rather than
    // re-derived at cleanup time: the two must agree exactly or PortOS
    // double-fires `gh pr create`. A pre-upgrade record has no value here, so
    // `resolvePrOpenedBy` maps whatever it does carry.
    //
    // Stamped from `promptOpensOwnPr`, the SAME predicate that decided what the
    // completion section above says — NOT from `provider.type` alone. It
    // depends on the task shape (read-only, no-code-output, discard-worktree,
    // JIRA/leave-open and no-worktree runs are all told PortOS owns the PR),
    // and a provider-only stamp claimed ownership for every one of them —
    // routing a Creative Director reasoning run into the did-you-open-it net,
    // which then opened a PR for it and filed a HIGH notification blaming the
    // agent for skipping a step it was never given.
    //
    // It ALSO depends on whether the host can type a slash command, and that is
    // the half the predecessor got backwards (#6869). The stamp used to be
    // `inlinePrLifecycleSection(…) !== null`, which is FALSE for a slashdo-
    // capable Claude TUI/CLI — the host that most often opens its own PR, via
    // `/do:pr`. Those runs read as PortOS-owned, so cleanup pushed the branch
    // again and re-created a PR that already existed. `agent-slashdo` is that
    // case; `agent-inline` is the codex/grok/agy harness handed the plain
    // `git`/`gh` steps, and it is the only value that owes the #5876 merge-gate
    // check, because it is the only prompt carrying a Merge Gate section.
    //
    // Three values rather than the boolean because that is what separates them:
    // the retired `false` conflated "a `/do:pr` run" with "a run PortOS owns",
    // which is why `resolvePrOpenedBy` can only pass a legacy record's boolean
    // straight through instead of correcting it.
    prOpenedBy,
    model: selectedModel,
    // The resolved run effort, including an inherited provider default and any
    // capability suppression. Resume and the run card must describe the same
    // setting handed to the launch builders.
    effort,
    modelTier: modelSelection.tier,
    modelReason: modelSelection.reason,
    // Set only when the learning system substituted a weaker model than the
    // provider's configured default for a task that never pinned one — the
    // run card needs to distinguish "ran on the configured default" from a
    // silent downgrade (#8148).
    ...(modelSelection.downgradedFromDefault && {
      modelDowngradedFromDefault: true,
      modelConfiguredDefault: modelSelection.configuredDefault
    }),
    runId,
    phase: 'initializing',
    useRunner: dispatchUseRunner,
    executionMode,
    // The public-review posture this run executes under (null for an ordinary
    // task). Projected beside `executionMode` because the UI cannot otherwise
    // explain why the card has no "Open Shell" link: a public-review stage is
    // forced headless (`spawnHeadless` above) unless it is the sandboxed-
    // actions stage on a TUI provider whose vendor declares an attachable
    // recipe, so without this the card is indistinguishable from an agent
    // whose PTY failed to attach.
    publicReviewPosture,
    // The run this one TOOK OVER, stamped on the task by `resolveTaskResumePatch`
    // when a Resume or a provider Relaunch requeues a paused task in place. Same
    // hand-picked-projection reason as the keys around it: the predecessor is
    // retired as a HANDOFF rather than a failure (`lib/agentOutcome.js`), and
    // without this the card that took over its worktree has no way to say what it
    // is continuing — leaving the pair looking like two unrelated runs, one of
    // which mysteriously stopped.
    resumedFromAgentId: task.metadata?.resumedFromAgentId || null,
    // Preserve privacy after the task becomes an archived agent.
    machineLocal: isTruthyMeta(task.metadata?.machineLocal),
    taskAnalysisType: task.metadata?.analysisType || null,
    taskReviewType: task.metadata?.reviewType || null,
    taskApp: task.metadata?.app || null,
    // Marks a run dispatched by an explicit "Run Now" (on-demand) trigger, so
    // the perpetual drain-on-completion refill (perpetualRefillPlan in cos.js)
    // continues a MANUAL drain in the user-initiated on-demand lane rather than
    // the auto-run-gated queue lane. `isTruthyMeta` accepts the boolean set at
    // spawn AND the string `"true"` a COS-TASKS.md round-trip yields.
    taskOnDemand: isTruthyMeta(task.metadata?.onDemand),
    // WHO asked for that on-demand run. `perpetualRefillPlan` needs it to tell
    // a human Run (which keeps draining) from an automated origin such as a
    // quota burn (which is one unit and stops).
    taskOnDemandOrigin: task.metadata?.onDemandOrigin || null,
    // The single PR a pr-reviewer run was narrowed to. Same hand-picked-projection
    // reason as the keys around it: perpetualRefillPlan must see from the AGENT
    // record that this run was scoped, or its untargeted re-issue silently widens
    // a per-row click back into a sweep of every open PR.
    taskTargetPullRequest: task.metadata?.targetPullRequest || null,
    // LI hand-off provenance (#2765): projected onto the agent so the completion
    // hook (recordTaskCompletion) can attribute the run's success/failure back to
    // the proposal's domain. agent.metadata is a hand-picked projection of
    // task.metadata (not a full spread), so this must be listed explicitly.
    taskLiProposal: task.metadata?.liProposal || null,
    // Quota-burn provenance. Same hand-picked-projection reason as
    // `taskLiProposal`: the runner listens for `agent:completed` and dispatches
    // the NEXT job in this family's burn plan when the previous one finishes,
    // so it must be able to tell a burn run from any other agent from the
    // agent record alone. Spread from the ONE block definition
    // (`lib/quotaBurnOrigin.js`) so every field that reaches disk reaches the
    // runner's continuation and the denial ledger — naming them here one at a
    // time is how `quotaBurnStepId` ended up persisted but unprojected (#6406).
    // Values are coerced on the way through: a COS-TASKS.md round-trip hands
    // every scalar back as a string.
    ...quotaBurnAgentMetadata(task.metadata),
    ...(task.metadata?.auditDepth === 'deep' ? { taskAuditDepth: 'deep', ...(task.metadata.auditWorkflow ? { auditWorkflow: task.metadata.auditWorkflow } : {}) } : {}),
    // Same reason as taskLiProposal — a hand-picked projection, so this must be
    // listed explicitly. `declaresNoCommitCriterion` (taskTypeHooks.js) reads it
    // to decide whether a run declared a commit criterion at all,
    // and taskLearning's history backfill re-processes the ARCHIVED agent shape
    // through that same predicate. Without the projection an archived
    // tracker-filing run (reference-watch/ux on a github/gitlab/jira app) looks
    // like a committing task during backfill, so its stale `validationPassed:
    // false` fossil survives the sanitizer (#3273). `?? null` — not `|| null` —
    // because `false` is the load-bearing value here.
    worktreeChangesExpected: task.metadata?.worktreeChangesExpected ?? null,
    taskAppName: resolvedAppName,
    selfImprovementType: task.metadata?.selfImprovementType || null,
    jobId: task.metadata?.jobId || null,
    jiraTicketId: task.metadata?.jiraTicketId || null,
    jiraTicketUrl: task.metadata?.jiraTicketUrl || null,
    jiraBranch: task.metadata?.jiraBranch || null,
    jiraInstanceId: task.metadata?.jiraInstanceId || null,
    jiraCreatePR: task.metadata?.jiraCreatePR ?? null,
    configOpenPR: isTruthyMeta(task.metadata?.openPR),
    // Claim prompts own their external claim/<item> worktree and forge
    // lifecycle even though CoS must keep configOpenPR/configUseWorktree off
    // to avoid provisioning a nested worktree. Preserve that distinction in
    // the run record so completion diagnostics cannot mistake the claim path
    // for the generic commit-only handoff.
    // Which memories steered this run's prompt ([{ id, version, relevance }]).
    // Empty for a run whose prompt carried none; absent only on a pre-#10495 record.
    injectedMemories,
    configClaimFlow: claimFlowTask,
    // The claim branch this run owns (or `claimPicksOwnBranch` when it picks one
    // itself, as a swarm orchestrator does). The `claim-*` tree is cut by the
    // agent, so `workspacePath` never names it; a later relaunch of that claim
    // reads these at launch to see that a live owner holds the checkout.
    ...claimOwnershipBinding(task),
    // Snapshot the assigned follow-up target at registration. Admission also
    // checks the persisted internal task and checkout; a prompt is never a grant.
    reviewLoopMergeTarget: task.taskType === 'internal'
      && isTruthyMeta(task.metadata?.reviewLoopFollowUp)
      && !isTruthyMeta(task.metadata?.reviewLoopLeaveOpen)
      ? { url: task.metadata.reviewLoopPRUrl, branch: task.metadata.reviewLoopPRBranch,
        ...(worktreeInfo?.detached === true && !task.metadata.forkHead ? {
          workspacePath,
          detached: { version: 1, headSha: worktreeInfo.headSha },
        } : {}),
        ...(task.metadata.forkHead ? {
          workspacePath,
          fork: task.metadata.reviewLoopForkTarget ? structuredClone(task.metadata.reviewLoopForkTarget) : null,
        } : {}) }
      : null,
    // Generic PR delivery (#11435): the worktree PortOS just provisioned and its
    // head branch, stamped only when this run's prompt carries the merge
    // admission section for its own PR. Admission re-verifies the live task and
    // checkout against it; neither the request nor PR prose can supply it.
    prDeliveryTarget: mergesOwnPr && worktreeInfo?.branchName && workspacePath
      ? { branch: worktreeInfo.branchName, workspacePath }
      : null,
    // Repository-cleanup recovery (#12251): the parent PR this run was filed to
    // land, snapshotted so a later task edit reads as a changed target.
    recoveryMergeTarget: repositoryCleanupMergeTarget(task),
    reconcileAssignment: reconcileAssignmentForTask(task),
    configSimplify: isTruthyMeta(task.metadata?.simplify),
    configReviewLoop: isTruthyMeta(task.metadata?.reviewLoop),
    configReviewers: normalizeReviewers(task.metadata),
    configUseWorktree: !!worktreeInfo,
    configWorktreeAutoDetected: !!worktreeInfo && !explicitWorktree,
    // A read-only run is given no worktree on purpose (agentWorkspacePrep) and
    // commits nothing, so it is not "coding on main" either. Projected as its own
    // key because the card has no other way to tell it from a commit-only handoff.
    configReadOnly: isTruthyMeta(task.metadata?.readOnly),
    // Coding on the default branch is the LEFTOVER posture: no CoS worktree, no
    // JIRA feature branch, no claim worktree of its own, and not read-only. Each
    // new branch-owning or non-committing flow has to be excluded here, or its
    // card wears a warning badge that is simply false — which is how every issue
    // claimed from the Issues page came to be badged "main" while the claim
    // command was working in its own `claim/<item>` worktree.
    configCodingOnMain: !worktreeInfo && !jiraBranchName && !claimFlowTask
      && !isTruthyMeta(task.metadata?.readOnly),
    // Feature-agent provenance must survive the in-memory runner handoff and
    // server restarts so featureAgents can clear currentAgentId and record the
    // run when the shared CoS lifecycle emits agent:completed.
    featureAgentId: task.metadata?.featureAgentId || null,
    featureAgentRun: isTruthyMeta(task.metadata?.featureAgentRun)
  };
}