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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Is a completed agent record an OUTCOME, or a handoff to its own continuation?
*
* `resumeAgent` (and `relaunchAgent`, which composes a pause with a resume)
* retires the old record with `success: false` and requeues the SAME task — most
* often because the user swapped providers after a CLI hit a usage limit, not
* because the work failed. Every consumer that read `result.success` as the
* verdict therefore booked a phantom failure per swap: a red "Failed" card in the
* history, a failed task in the daily report and the weekly digest, a dented
* success rate, a quota-burn denial recorded against "Relaunched by user", a
* feature agent flipped to `error`.
*
* The rule task-learning already applied (`initTaskLearning`, #4540: "a record
* retired by resumeAgent is a CONTINUATION, not an outcome") belongs to all of
* them, so it lives here once instead of being restated — or forgotten — per
* consumer.
*
* Keyed on `result.resumed`, which `resumeAgent` has always stamped, so ALREADY
* ARCHIVED relaunches are reclassified retroactively: no migration, and an
* install's existing history stops reporting swaps as failures the moment it
* upgrades. Mirrored, with the same contract, at `client/src/lib/agentOutcome.js`
* and pinned to it by `agentOutcome.parity.test.js`.
*
* Pure and dependency-free — read from report builders, event listeners, and the
* learning writer alike, none of which should drag in the agent-state graph for
* one predicate.
*/
/**
* True when this record was retired to hand its task to a continuation run
* (resume / relaunch) rather than because the run reached a verdict.
*
* Takes the whole record, but reads only `result`, so the stats writer inside
* `completeAgent` — which has the result in hand before any record exists — can
* ask the same question with `isAgentHandoff({ result })`.
*
* STRICT equality on purpose. A truthy check would also swallow a future
* `resumed: 'partial'` or a round-tripped string, silently dropping a real
* outcome from every count that now filters on this.
*/
export function isAgentHandoff(agent) {
return agent?.result?.resumed === true;
}
/**
* True only when a handoff record proves a continuation was actually QUEUED —
* `resumedTaskId` is the field `resumeAgent`/`relaunchAgent` stamp when they
* requeue the same task. `isAgentHandoff` alone is not proof: it also reads
* true for `retireStrandedPausedAgents` (`server/services/agentManagement.js`),
* which stamps `resumed: true` on a pause whose task is gone or moved on,
* with nothing requeued.
*
* Use this — not the bare predicate — anywhere the caller is about to SKIP its
* own completion handling because it believes a continuation run will fire the
* completion instead. Skipping on the bare predicate strands the chain when
* the retirement was actually terminal (#7469: a quota-burn family's
* continuation cycle, and a maintenance run's step evaluation, both stalled
* this way until the next scheduled tick).
*
* Consumers that only ask "was this a genuine success/failure" (reports,
* the activity calendar, task learning) should keep using `isAgentHandoff` — a
* stranded retirement isn't a genuine outcome either, so folding it in there
* is correct.
*/
export function isQueuedContinuation(agent) {
return isAgentHandoff(agent) && !!agent?.result?.resumedTaskId;
}
/**
* The one line a handoff card should show: WHAT THE USER CHANGED.
*
* When a continuation was actually queued (`resumedTaskId`), `metadata.pauseReason`
* wins: on a Relaunch that is the sentence the user is looking for ("Relaunched by
* user on codex / gpt-5"), while `result.error` holds `resumeAgent`'s summary,
* which says where the TASK went rather than why this run stopped.
*
* With no continuation the order flips. `retireStrandedPausedAgents` also stamps
* `resumed: true` — on a pause whose task was deleted or moved on — and there the
* pause reason is the ORIGINAL one ("Paused by user"), which would read as a
* deliberate provider swap for a run that was simply abandoned. `result.error`
* ("Pause retired — its task … no longer exists") is the honest line.
*
* Lives here beside the predicate even though only the client renders it: this is
* the file the client re-exports, and splitting the pair would put half the
* contract back in a copy.
*/
export function agentHandoffReason(agent) {
const error = agent?.result?.error;
const pauseReason = agent?.metadata?.pauseReason;
const handedOn = !!agent?.result?.resumedTaskId;
return (handedOn ? pauseReason || error : error || pauseReason) || 'Handed off to a new run';
}
/** Explicit delivery evidence, separate from a process ending normally. */
export function normalizeTaskOutcome(value) {
if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
if (!['completed', 'no-action-needed', 'blocked', 'incomplete'].includes(value.status)) return null;
if (typeof value.reason !== 'string' || !value.reason.trim()) return null;
const outcome = { status: value.status, reason: value.reason.trim() };
if (['blocked', 'incomplete'].includes(value.status)) {
if (value.recovery?.mode === 'runtime') outcome.recovery = { mode: 'runtime',
prUrl: typeof value.recovery.prUrl === 'string' ? value.recovery.prUrl : '',
requiredCommit: typeof value.recovery.requiredCommit === 'string' ? value.recovery.requiredCommit : '' };
if (value.recovery?.mode === 'cleanup') outcome.recovery = { mode: 'cleanup' };
if (value.recovery?.mode === 'approval') {
const options = Array.isArray(value.recovery.options)
? value.recovery.options.filter(option => typeof option === 'string' && option.trim()).map(option => option.trim()) : [];
// Malformed approval requests fail closed, with concrete default choices.
outcome.recovery = { mode: 'approval', options: options.length >= 2 ? options : [
'Address the named prerequisite, then retry the retained work.',
'Keep the task stopped and preserve its work.',
] };
}
}
return outcome;
}
/** Only evidenced delivery may resolve external work; legacy exits are unknown. */
export function isTaskDeliveryComplete(agent) {
const outcome = normalizeTaskOutcome(agent?.result?.taskOutcome);
return !isAgentHandoff(agent) && agent?.result?.success === true
&& agent.result.validationPassed !== false
&& ['completed', 'no-action-needed'].includes(outcome?.status);
}
export function resolveTaskOutcome({ reported, success, validationPassed, branchProvenEmpty, noChangeAllowed, noCommitDeclared = false }) {
if (reported && ['blocked', 'incomplete'].includes(reported.status)) return reported;
if (!success) return { status: 'incomplete', reason: 'Delivery checks did not pass.' };
// Legacy learning criteria include commit probes that are not delivery gates
// (for example, an audit may save its report without a code change). Keep
// those runs unverified unless the agent supplied a delivery contract.
if (validationPassed === false) return reported
? { status: 'incomplete', reason: 'Delivery checks did not pass.' } : null;
if (branchProvenEmpty && noChangeAllowed) return { status: 'no-action-needed', reason: 'The permitted no-change result was verified against the repository.' };
// Coordinators and the other no-commit shapes leave validation null on
// purpose: nothing was supposed to be committed, and the exit code already
// judged the run. A reported no-action is that run's delivery contract.
// Null means undeclared, not failed — an explicit false already lost above.
// A committing task must not take this branch; its null means the no-op was
// never checked against the repository.
if (reported?.status === 'no-action-needed' && validationPassed !== true) {
if (noCommitDeclared && validationPassed == null) return reported;
return { status: 'incomplete', reason: 'The reported no-action-needed result was not verified.' };
}
if (reported) return reported;
return validationPassed === true ? { status: 'completed', reason: 'The task delivery criteria passed.' } : null;
}