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.5 KB
Raw Blame
/**
 * Quota-burn PROVENANCE carried on an on-demand scheduled-task request, and the
 * metadata an on-demand engine stamps from it.
 *
 * A burn step no longer queues its own synthesized task: it asks the schedule to
 * run a task the user already owns (`quotaBurnInvoke.js` →
 * `taskSchedule.triggerOnDemandTask` with `origin: 'quota-burn'`). Acceptance is
 * therefore ASYNCHRONOUS — the request lands on the schedule now and one of the
 * two on-demand engines (`cos.js#spawnDequeuePriority0OnDemand`,
 * `cosTaskGenerator.js#spawnPriority0OnDemand`) generates the task later — so
 * the "which burn was this?" facts have to ride ON the request and be stamped
 * onto the task the engine produces.
 *
 * Pure, and deliberately import-light (`objects.js` only): `taskScheduleConstants.js`
 * declares the origin strings and is reached by a large share of the server suite,
 * so this module must never pull the quota-burn config graph in behind it
 * (server/AGENTS.md, "Import scoping"). That is also why `onDemandOrigin` below
 * is copied through as an opaque string rather than validated against the enum.
 *
 * These are the same provenance keys the retired `quotaBurnJobs/agentPrompt.js`
 * executor stamped, on purpose: `cosTaskGenerator.js#isCooldownExemptTask`, the
 * runner's completion continuation, and `quotaBurnDenials.js` all read them off
 * the finished agent, and they had to keep arriving unchanged when the burn's
 * origin moved (#6381) or a burn would have stopped being cooldown-exempt and a
 * refusal would have been credited to nobody. `QUOTA_BURN_PROVENANCE_FIELDS` below is the one place they
 * are named.
 */

import { isPlainObject, POLLUTING_KEYS } from './objects.js';
import { trimTo } from './textUtils.js';

/**
 * The `origin` a quota-burn on-demand request carries. Declared here rather
 * than in `taskScheduleConstants.js` so the stamp below can gate on it without
 * importing upward out of `lib/`; that module re-exports it as
 * `ON_DEMAND_ORIGINS.QUOTA_BURN`, so there is still exactly one literal.
 */
export const QUOTA_BURN_REQUEST_ORIGIN = 'quota-burn';

/** Explicit runs bypass cadence switches; automated burns and refills do not. */
export function isManualOnDemandRequest(request) {
  return (request.origin ?? 'user') === 'user'
    || (request.origin === QUOTA_BURN_REQUEST_ORIGIN && Boolean(normalizeQuotaBurnProvenance(request.burn)?.maintenanceRunId));
}

const MAX_FIELD = 64;

/**
 * THE quota-burn provenance block: the facts that say which burn a task is, in
 * one place. Every hop that persists or projects them derives from this table
 * rather than naming keys, so a fifth fact is one row here instead of four
 * hand-written lines that can each be forgotten independently — which is exactly
 * how `quotaBurnStepId` came to reach disk but never reach the agent (#6406).
 *
 * The three hops:
 *   - `onDemandRequestMetadata` below (raw path — the on-demand engines).
 *   - `cosTaskStore.js#addTask` (non-raw path — the synchronous custom-job lane).
 *   - `agentLifecycle.js` (the agent projection the runner and the denial
 *     ledger read a finished run back out of).
 *
 * The PERSISTED and cross-peer shape stays FLAT (`quotaBurnFamily`, …), not a
 * nested `quotaBurn` object. CoS tasks federate as markdown replicated between
 * peers that upgrade independently (`cosTaskMerge.js`), and `metadata.quotaBurnFamily`
 * is what makes a burn cooldown-exempt and what credits a refusal to a family —
 * so a nested-only write would make a burn queued on a new peer read as an
 * ordinary task on an older one, for no functional gain. `quotaBurnProvenance`
 * still ACCEPTS a nested block, so a producer may hand its provenance over as a
 * unit and a task that ever arrives in that shape resolves identically.
 *
 * Readers coerce, because a COS-TASKS.md round-trip hands every scalar back as a
 * string: a task written by a previous release must still read as burn-provenanced.
 */
const asId = (value) => (typeof value === 'string' && value.trim() ? value.trim() : undefined);
const asEpochMs = (value) => {
  const numeric = typeof value === 'number' ? value : (asId(value) === undefined ? NaN : Number(value));
  return Number.isFinite(numeric) ? numeric : undefined;
};

export const QUOTA_BURN_PROVENANCE_FIELDS = Object.freeze([
  // Which provider family's window this run is spending, and the key the denial
  // ledger and the plan walk attribute a finished run by. ABSENT — never a
  // placeholder — on a manual maintenance run pinned to a provider outside every
  // subscription family, which spends no window at all; `maintenanceRunId` below
  // is that run's attribution instead (see `normalizeQuotaBurnProvenance`).
  { field: 'family', taskKey: 'quotaBurnFamily', agentKey: 'taskQuotaBurnFamily', read: asId },
  // The reset of the SHORT rolling window that will refuse first, so a refused
  // run blocks the family until that window rolls rather than re-dispatching
  // into the same wall. See quotaBurnDenials.js.
  { field: 'limitingResetAt', taskKey: 'quotaBurnLimitingResetAt', agentKey: 'taskQuotaBurnLimitingResetAt', read: asEpochMs },
  // Which STEP of the burn plan asked.
  { field: 'stepId', taskKey: 'quotaBurnStepId', agentKey: 'taskQuotaBurnStepId', read: asId },
  // The on-demand REQUEST this task was generated for. Absent — never null, never
  // synthesized — on the synchronous custom-job lane, which queues the task itself
  // and has no request to name; a fake id would make a join over it silently wrong.
  { field: 'requestId', taskKey: 'quotaBurnRequestId', agentKey: 'taskQuotaBurnRequestId', read: asId },
  // The MANUAL maintenance run that asked (`services/maintenanceRun.js`), absent
  // on an automatic burn. It is what lets the quota-burn runner leave a manual
  // run's agents alone — the run walks its own ladder, outside the family's
  // plan, its completion ledger and its window gates — while the family
  // attribution above still credits a refusal to the window it actually spent.
  // It is also the ONLY attribution a family-less manual run has, which is why
  // `hasQuotaBurnProvenance` accepts either key.
  { field: 'maintenanceRunId', taskKey: 'quotaBurnMaintenanceRunId', agentKey: 'taskQuotaBurnMaintenanceRunId', read: asId },
].map(Object.freeze));

/**
 * Read the provenance block off anything carrying it — task metadata, an
 * `addTask` payload, or a producer's own `quotaBurn` block. A field the source
 * does not carry (or carries unreadably) is ABSENT from the result, so callers
 * can tell "not recorded" from a legitimate value without a sentinel of their own.
 */
export function quotaBurnProvenance(source) {
  const block = {};
  if (!isPlainObject(source)) return block;
  const nested = isPlainObject(source.quotaBurn) ? source.quotaBurn : null;
  for (const { field, taskKey, read } of QUOTA_BURN_PROVENANCE_FIELDS) {
    const value = read(nested?.[field] ?? source[taskKey]);
    if (value !== undefined) block[field] = value;
  }
  return block;
}

/** The flat metadata keys a block persists as. Absent fields stay absent. */
export function quotaBurnTaskMetadata(block) {
  const metadata = {};
  if (!isPlainObject(block)) return metadata;
  for (const { field, taskKey, read } of QUOTA_BURN_PROVENANCE_FIELDS) {
    const value = read(block[field]);
    if (value !== undefined) metadata[taskKey] = value;
  }
  return metadata;
}

/**
 * The provenance projection `agentLifecycle` stamps onto the agent record.
 * agent.metadata is a hand-picked projection of task.metadata, so EVERY
 * persisted field is listed here by construction — a field that reaches disk
 * cannot fail to reach the runner's completion continuation or the denial ledger.
 * `null` (not absent) for a field the task never carried, matching the rest of
 * that projection's "not recorded" convention.
 */
export function quotaBurnAgentMetadata(taskMetadata) {
  const block = quotaBurnProvenance(taskMetadata);
  return Object.fromEntries(
    QUOTA_BURN_PROVENANCE_FIELDS.map(({ field, agentKey }) => [agentKey, block[field] ?? null]),
  );
}

/**
 * Whether a task carries attributable burn provenance at all.
 *
 * EITHER attribution key is enough. A family says which subscription window the
 * run spends; a `maintenanceRunId` says which manual ladder asked. A manual run
 * pinned to a provider that belongs to no subscription family (an OpenCode TUI,
 * a local-model wrapper) carries only the second — it is fully attributable,
 * just not to a window — and it must still be cooldown-exempt, or the ladder's
 * own steps queue behind the app cooldown every other CoS task re-stamps.
 */
export const hasQuotaBurnProvenance = (taskMetadata) => {
  const block = quotaBurnProvenance(taskMetadata);
  return Boolean(block.family || block.maintenanceRunId);
};

/**
 * Whether the family's burn PLAN owns this task: burn-provenanced, and not a
 * manual maintenance run's. The one rule the plan's sequence walk and its
 * completion continuation both apply — a manual run spends the family's
 * window (so the denial ledger still hears about it) but walks its own ladder,
 * so the plan neither advances on it nor waits for it. `burnPlanOwnsAgent` is
 * the same rule over the agent projection (`quotaBurnAgentMetadata`).
 */
export function burnPlanOwnsTask(taskMetadata) {
  const block = quotaBurnProvenance(taskMetadata);
  return Boolean(block.family) && !block.maintenanceRunId;
}
export const burnPlanOwnsAgent = (agent) => Boolean(agent?.metadata?.taskQuotaBurnFamily) && !agent.metadata.taskQuotaBurnMaintenanceRunId;

const nullable = (value, max = MAX_FIELD) => trimTo(value, max) || null;

const scalarParams = (raw) => {
  if (!isPlainObject(raw)) return {};
  const clean = {};
  for (const [key, value] of Object.entries(raw)) {
    if (POLLUTING_KEYS.has(key)) continue;
    if (typeof value === 'string' || typeof value === 'boolean' || value === null) clean[key] = value;
    else if (typeof value === 'number' && Number.isFinite(value)) clean[key] = value;
  }
  return clean;
};

/**
 * Normalize the `burn` block of an on-demand request. Returns `null` unless it
 * names the burn step that asked AND an attribution for the run — without both,
 * nothing downstream can attribute it, and an unattributable burn is worse than
 * no burn: `isCooldownExemptTask` would treat an ordinary task as burn-exempt,
 * and the denial ledger would credit a refusal to the wrong family.
 *
 * Attribution is the family whose window is being spent OR the manual
 * maintenance run that asked. An AUTOMATIC burn never carries a run id, so for
 * it the family stays strictly required, exactly as before — it exists to draw
 * down one named window and a family-less automatic burn would spend whatever
 * the daemon picked. A MANUAL run pinned to a provider outside every
 * subscription family (`services/maintenanceRun.js`) has no window to name and
 * says so by omitting `family` rather than borrowing a real one: `null` here is
 * "this run spends no subscription", not "we could not work it out". That is
 * what keeps `recordBurnAgentCompletion` and the quota-burn plan walk from
 * crediting its refusals and completions to a subscription it never touched.
 *
 * `overrides` carries the three per-invocation settings the generated task can
 * absorb AFTER generation — the provider, model and reasoning effort the spawner
 * reads straight off `task.metadata` — plus the step's run `params`.
 *
 * The params are here for a reason the other three are not: they have to reach
 * the PROMPT, so they cannot ride the post-generation
 * `onDemandRequestMetadata` stamp below. Both on-demand engines pull them off
 * the request and hand them to `prepareManagedAppImprovementTask` as
 * `runOverrides`, which layers them over the task's saved `taskMetadata` BEFORE
 * the mode banner is chosen and the prompt is rendered. That is what lets a step
 * migrated from an issues-only burn preset pin `fileIssues: true` explicitly and
 * keep filing even against an audit type whose shipped scheduled default is
 * `false` (#6381) — without it a migrated burn would silently run the task's
 * saved mode and start writing code.
 *
 * Shallow scalars only, and validated for real one hop later: the generator
 * sanitizes them through `sanitizeTaskMetadata`'s allowlist, the same door a
 * stored override passes. Copied here rather than imported from
 * `quotaBurnTaskRef.js` so this module keeps its one-import budget — it is
 * reached by a large share of the server suite.
 */
export function normalizeQuotaBurnProvenance(raw) {
  if (!isPlainObject(raw)) return null;
  const family = trimTo(raw.family, MAX_FIELD);
  const stepId = trimTo(raw.stepId, MAX_FIELD);
  const maintenanceRunId = nullable(raw.maintenanceRunId);
  if (!stepId || (!family && !maintenanceRunId)) return null;
  const limitingResetAt = Number(raw.limitingResetAt);
  const overrides = isPlainObject(raw.overrides) ? raw.overrides : {};
  return {
    ...(family ? { family } : {}),
    stepId,
    limitingResetAt: Number.isFinite(limitingResetAt) ? limitingResetAt : null,
    ...(maintenanceRunId ? { maintenanceRunId } : {}),
    overrides: {
      providerId: nullable(overrides.providerId),
      model: nullable(overrides.model),
      effort: nullable(overrides.effort),
      params: scalarParams(overrides.params),
    },
  };
}

/**
 * The metadata BOTH on-demand engines merge onto the task they just generated
 * for a request — `cos.js#spawnDequeuePriority0OnDemand` and
 * `cosTaskGenerator.js#spawnPriority0OnDemand`, either of which may drain any
 * given request. One helper rather than the expression written out twice: the
 * engines are an exact mirror, and a rule repeated in two places is a rule that
 * eventually holds in one.
 *
 * `onDemand` says the task came out of the request queue at all; `onDemandOrigin`
 * says WHO asked, and is what `perpetualRefillPlan` reads to decide whether the
 * completed run may continue its perpetual drain. They are separate keys because
 * they are separate facts — folding "a human asked" into `onDemand` is what made
 * a burn indistinguishable from a Run Now, and forced the exclusion to be
 * re-asserted as a second key-specific rule in `cos.js`.
 *
 * `null` origin means "not recorded", which every reader treats as a human Run:
 * that is what a request queued before the field existed is.
 *
 * The burn keys are gated on the ORIGIN, not merely on a `burn` block that
 * parses. `triggerOnDemandTask` refuses to persist one on any other origin, so
 * the two can only disagree in a hand-edited schedule — and stamping there would
 * be the worst of both: `isCooldownExemptTask` would treat an ordinary human Run
 * as burn-exempt and the denial ledger would credit its refusal to a family that
 * never dispatched it, while the refill planner still drained it as a human Run.
 */
export function onDemandRequestMetadata(request) {
  const burn = request?.origin === QUOTA_BURN_REQUEST_ORIGIN
    ? normalizeQuotaBurnProvenance(request.burn)
    : null;
  const requestId = trimTo(request?.id, 128);
  return {
    onDemand: true,
    onDemandOrigin: nullable(request?.origin),
    ...(burn ? {
      // One spread of the shared block, so this path cannot carry a different
      // set of provenance keys than the non-raw `addTask` mapping does. An
      // unreadable reset (and an unnamed request) drops out rather than being
      // written as null — see QUOTA_BURN_PROVENANCE_FIELDS.
      ...quotaBurnTaskMetadata({ ...burn, requestId }),
      ...(burn.overrides.providerId ? { provider: burn.overrides.providerId } : {}),
      ...(burn.overrides.model ? { model: burn.overrides.model } : {}),
      ...(burn.overrides.effort ? { effort: burn.overrides.effort } : {}),
    } : {}),
  };
}