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
/**
* The ONE path a quota-burn step takes to run its work.
*
* A burn step is a REFERENCE to a scheduled task the user already owns
* (`lib/quotaBurnTaskRef.js`), so "running" it means invoking that task the way
* anything else invokes it — never re-implementing it. That is the whole point
* of the reference model: the retired `quotaBurnJobs/agentPrompt.js` executor
* called `cosTaskStore.addTask` directly with a synthesized free-form task,
* which walked past canonical task generation and every gate that lives in it.
* #6381 converted the plans that used it and removed it, so this is now the ONLY
* way a burn spends quota — a step still carrying a legacy `jobType` resolves to
* `LEGACY_UNMIGRATED` here and is refused, never executed.
*
* Three reference shapes, three canonical invocations — and no fourth:
*
* built-in AGENT task → `taskSchedule.triggerOnDemandTask(type, appId,
* { origin: QUOTA_BURN, burn })`. The on-demand
* engines generate the task; acceptance is
* ASYNCHRONOUS, and the burn provenance rides on the
* request (`lib/quotaBurnOrigin.js`).
* built-in PROGRAMMATIC → `scheduledHandlers.runScheduledHandler` directly,
* with the burning `family`. That registry documents
* the burn as its second sanctioned caller precisely
* so the render backend stays pinned to the
* subscription being drained; routing it through the
* request queue would drop `family` on the floor
* (`cosTaskGenerator#drainProgrammaticOnDemandRequests`
* passes none) and spend the wrong provider.
* CUSTOM app job → `autonomousJobs.generateTaskFromJob` + `addTask`,
* the same pair the scheduled fire uses.
*
* **This is not the manual endpoint.** `routes/cosJobRoutes.js`'s
* `POST /jobs/:id/trigger` deliberately hands a human three privileges an
* unattended burn must never inherit — `approvalRequired: false` regardless of
* the job's autonomy level, `forceSpawnTask` past the autonomous scheduling
* gates, and `reviveBlockedTask` on a failure-blocked twin. A burn queues the
* task and stops: the daemon decides when it spawns, a blocked twin stays
* blocked, and a job that would need a human to approve it is REFUSED rather
* than parked awaiting approval — parking one would consume the family's
* dispatch budget for work that spends nothing.
*
* `force` reaches here already meaning "the user clicked ▶". It bypasses the
* QUOTA gates in `quotaBurn.js#evaluateFamily`, and it is threaded into a
* programmatic handler so that handler can relax its OWN in-flight cooldown —
* which is the whole point of the button on a `universe-bible-images` row whose
* probe reports zero for entries that are merely already queued. What it never
* relaxes: task eligibility, approval, target scope, enabled state, the master
* Improve gate, and the duplicate checks below. Those are facts about whether
* the work may run at all, not about this window's budget — and a duplicate in
* particular is not "declined because of a gate", it is the same work twice.
*/
import {
QUOTA_BURN_TASK_REF_KIND,
QUOTA_BURN_UNAVAILABLE,
enabledAppIdsByTaskType,
resolveQuotaBurnStepAvailability,
} from '../lib/quotaBurnTaskRef.js';
import { isAuditTaskType } from '../lib/auditCatalog.js';
import { generatedJobTaskFields } from '../lib/autonomousJobTask.js';
import { isProgrammaticScheduledTaskType } from '../lib/taskTargetScope.js';
import { ON_DEMAND_ORIGINS } from './taskScheduleConstants.js';
/** The autonomy level a custom job must carry for an UNATTENDED burn to run it. */
const UNATTENDED_AUTONOMY_LEVEL = 'yolo';
const declined = (reason) => ({ dispatched: false, reason });
/** What a log line calls the thing being spent — a family, or nothing at all. */
const burnLabel = (family) => family?.id || 'no subscription family';
const noWork = (detail) => ({ count: 0, detail });
// `Object.hasOwn`, not a truthiness check, so a reference naming an inherited
// key like `constructor` cannot resolve to anything.
const entryOf = (map, key) => (map && Object.hasOwn(map, key) ? map[key] : null);
/**
* The live task catalog `resolveQuotaBurnStepAvailability` resolves a reference
* against: `{ builtin: { [taskType]: { enabled, featureEnabled, feature,
* eligible, appIds } }, custom: { [jobId]: { enabled, eligible, appId } },
* improvementEnabled }`.
*
* The built-in entry is exactly the `entry` shape `evaluateOnDemandEligibility`
* reads, so the page's verdict is produced by the same ladder that decides the
* dispatch — every rung is filled here and judged there, never re-derived. That
* is why the instance-FEATURE gate is a field of its own rather than folded into
* `enabled`: the ladder can then say which of the two switches is off.
* `eligible` is the picker restriction: a type another automation owns
* (`userInvokable: false`) and a custom job that is not an agent job — a shell
* command or a built-in script handler — are not things a burn may invoke.
*
* `appIds` per built-in type is the set of ACTIVE managed apps that have the
* type switched on, so a reference to an app that was removed (or had the type
* turned off) resolves as wrong-scope instead of silently dispatching nothing.
*
* `improvementEnabled` is the master CoS Improve switch, `null` when the state
* could not be read — which fails CLOSED, because "we could not check" is not
* "it is on".
*
* Each entry also carries the record it was derived from — the task's schedule
* config, the custom job — and the catalog carries the `queued` set of on-demand
* requests already waiting, all read off the SAME schedule/app/job snapshot.
* `loadSchedule()` is uncached (a disk read plus a deep merge over every default
* interval), so going back to the stores per step made the status page's probe
* pay that whole cost once per configured step. The pure resolver ignores every
* key it does not know. Manual maintenance catalogs bypass built-in cadence
* switches without changing saved settings or the automatic burn catalog.
*/
export async function getQuotaBurnTaskCatalog({ manual = false } = {}) {
const [{ loadSchedule }, { getTaskTypeInvocation }, { getActiveApps }, { createFeatureGate }, { getAllJobs }, { isImprovementEnabled, loadState }] =
await Promise.all([
import('./taskScheduleStore.js'),
import('./taskScheduleRegistry.js'),
import('./apps.js'),
import('./taskSchedule.js'),
import('./autonomousJobs.js'),
import('./cosState.js'),
]);
const [schedule, apps, jobs, state] = await Promise.all([
loadSchedule(),
getActiveApps().catch(() => []),
getAllJobs().catch(() => []),
loadState().catch(() => null),
]);
// The overrides come off the app records `getActiveApps` already returned.
// `getAppTaskTypeOverrides(id)` would re-enter the app store twice per app to
// produce the same answer for this filter — the legacy migration it also runs
// only ever synthesizes `{ enabled: false }` entries, which are exactly what
// gets discarded here. Other callers still perform that migration.
const appIdsByTaskType = enabledAppIdsByTaskType(apps);
// The schedule's own memoized gate, not a second copy: the burn catalog's
// feature verdict has to agree with the one `triggerOnDemandTask` applies,
// and two implementations of one rule drift silently.
const featureEnabled = createFeatureGate();
const builtin = {};
await Promise.all(Object.entries(schedule?.tasks || {}).map(async ([taskType, config]) => {
builtin[taskType] = {
enabled: manual || config?.enabled === true,
featureEnabled: await featureEnabled(config),
feature: config?.feature || null,
eligible: getTaskTypeInvocation(taskType).userInvokable !== false,
appIds: manual ? undefined : appIdsByTaskType.get(taskType) || [],
config,
};
}));
const custom = Object.fromEntries((jobs || []).map((job) => [job.id, {
enabled: job.enabled === true,
eligible: isBurnEligibleCustomJob(job),
appId: job.appId || null,
job,
}]));
return {
builtin,
custom,
improvementEnabled: state ? isImprovementEnabled(state) : null,
queued: queuedOnDemandKeys(schedule),
};
}
/** `taskType` + app scope of every on-demand request already waiting to drain. */
const onDemandKey = (taskType, appId) => `${taskType}::${appId ?? ''}`;
const queuedOnDemandKeys = (schedule) =>
new Set((schedule?.onDemandRequests || []).map((request) => onDemandKey(request.taskType, request.appId)));
/**
* Whether a custom app job is something a burn may invoke at all.
*
* A `shell` job runs an allowlisted command and a `script` job runs a built-in
* handler — neither spends provider quota, which is the only thing a burn is
* for. Everything else is an agent job (`type` is absent on jobs written before
* the field existed, and those are agent jobs).
*/
export function isBurnEligibleCustomJob(job) {
return Boolean(job) && (!job.type || job.type === 'agent');
}
/**
* Resolve a step against the live catalog into everything an invocation needs,
* or the `unavailable` verdict that stops it.
*
* `effective` is the settings the invocation will actually run with: the step's
* per-invocation overrides layered over the referenced task's SAVED settings.
* An unset override inherits; nothing here writes back to the schedule or the
* job record.
*/
export async function resolveQuotaBurnStep(step, catalog = null, { explicit = false } = {}) {
const resolvedCatalog = catalog || await getQuotaBurnTaskCatalog();
const unavailable = resolveQuotaBurnStepAvailability(step, resolvedCatalog);
if (unavailable) return { unavailable };
const ref = step.taskRef;
if (ref.kind === QUOTA_BURN_TASK_REF_KIND.CUSTOM) {
// An EMPTY catalog (the caller's read failed) answers no existence question,
// so the resolver above passed the step through. Display can afford that;
// dispatch cannot — with no record to read there are no saved settings to
// inherit, and running on the overrides alone would silently change the work.
const job = entryOf(resolvedCatalog.custom, ref.jobId)?.job;
if (!job) {
return { unavailable: { code: QUOTA_BURN_UNAVAILABLE.DANGLING_JOB, reason: `custom scheduled job "${ref.jobId}" could not be read` } };
}
return { kind: 'custom', catalog: resolvedCatalog, ref, job, effective: effectiveSettings(step, job) };
}
const interval = entryOf(resolvedCatalog.builtin, ref.taskType)?.config;
if (!interval) {
return { unavailable: { code: QUOTA_BURN_UNAVAILABLE.UNKNOWN_TASK, reason: `scheduled task "${ref.taskType}" could not be read` } };
}
const effective = effectiveSettings(step, interval);
// Here rather than at invoke, so the status page's probe and the runner agree
// that an audit which cannot apply to its app is not ready work, and so a
// maintenance run can complete it as skipped from the same verdict.
const notApplicable = explicit ? null : await notApplicableReason(ref, effective.params);
if (notApplicable) return { unavailable: { code: QUOTA_BURN_UNAVAILABLE.NOT_APPLICABLE, reason: notApplicable } };
return {
kind: isProgrammaticScheduledTaskType(ref.taskType) ? 'programmatic' : 'builtin',
// Handed back so a caller that resolved through a catalog keeps reading that
// one snapshot instead of going back to the (uncached) schedule store.
catalog: resolvedCatalog,
ref,
interval,
effective,
};
}
/** Why an audit step cannot apply to its app, or null — honoring the user's explicit override. */
async function notApplicableReason(ref, params) {
if (!ref.appId || params?.runInapplicableAudit === true || !isAuditTaskType(ref.taskType)) return null;
const { inapplicableAuditReason } = await import('./appQualitySchedule.js');
const reason = await inapplicableAuditReason(ref.appId, ref.taskType);
return reason ? `"${ref.taskType}" does not apply to this app: ${reason}` : null;
}
/**
* Layer a step's overrides over a task's saved settings.
*
* Presence, not truthiness: `normalizeQuotaBurnJob` already reduces an unset
* override to `null`, so `??` is the correct join — a step that pins nothing
* inherits, and a step that pins something wins. `params` MERGE key-by-key
* rather than replacing the bag, so overriding one run parameter does not blank
* every other saved one.
*/
export function effectiveSettings(step, saved) {
const overrides = step?.overrides || {};
return {
providerId: overrides.providerId ?? saved?.providerId ?? null,
model: overrides.model ?? saved?.model ?? null,
effort: overrides.effort ?? saved?.effort ?? null,
params: { ...(saved?.taskMetadata || {}), ...(overrides.params || {}) },
};
}
/**
* `countPending(reference) → { count, detail, context? }` — the shared probe
* contract the runner's ordered selection and the status page both read.
*
* Side-effect free, always: it writes nothing, enqueues nothing, and makes no
* AI provider call (AGENTS.md — no cold-bootstrap LLM calls; the status page
* calls this for every configured step on every load).
*
* - an eligible AI agent task (built-in or custom) reports ONE ready unit —
* a task is one unit of work, and there is no backlog to count;
* - an ineligible, disabled, dangling or ALREADY-ACTIVE task reports zero
* with the reason, so the runner skips it and the page can say why;
* - a programmatic handler reports its own domain backlog count, and may hand
* back the opaque `context` its scan produced for `run` to reuse.
*/
export async function countQuotaBurnStepPending({ step, family, catalog = null } = {}) {
const resolved = await resolveQuotaBurnStep(step, catalog);
if (resolved.unavailable) return noWork(resolved.unavailable.reason);
if (resolved.kind === 'programmatic') {
const { countScheduledHandlerPending } = await import('./scheduledHandlers/index.js');
return countScheduledHandlerPending({
taskType: resolved.ref.taskType,
params: resolved.effective.params,
job: resolved.effective,
family,
});
}
// Approval outranks the provider check, matching the order `runCustomJobStep`
// applies — a job the burn may never run at all should say so rather than
// report a provider problem the user would then go and "fix".
const approval = resolved.kind === 'custom' ? unattendedApprovalRefusal(resolved.job) : null;
if (approval) return noWork(approval);
// Both agent lanes need a provider in the burning family before they can
// report a ready unit — a step whose family has none is not "one unit of work
// waiting", it is unrunnable, and the runner has to move to the next step
// rather than dispatch onto some other subscription.
const picked = await resolveStepProvider(resolved.effective, family);
if (picked.error) return noWork(picked.error);
if (resolved.kind === 'custom') {
const active = await activeCustomJobReason(resolved.job);
return active ? noWork(active) : { count: 1, detail: `ready to queue "${resolved.job.name}" via ${picked.provider.id}` };
}
const queued = await queuedOnDemandReason(resolved.catalog?.queued, resolved.ref.taskType, resolved.ref.appId);
return queued
? noWork(queued)
: { count: 1, detail: `ready to run scheduled task "${resolved.ref.taskType}" via ${picked.provider.id}` };
}
/**
* The provider a burn will actually spend, or a refusal.
*
* A burn exists to draw down ONE family's window, so this is not optional
* plumbing: without it a step whose family has no enabled CLI/TUI provider would
* queue on whatever the daemon picks and spend a different subscription
* entirely, and a pin naming another family's provider would do the same on
* purpose. `providerForFamily` honors an explicit pin WITHOUT re-checking its
* family (by design — the pin is how you name a specific binary), so the family
* check is made here, against the resolved provider record rather than its id:
* the command basename is what identifies a family (`antigravity-cli` is
* `agy`), and an id-substring rule strands whole families.
*
* Programmatic handlers do NOT come through here — each resolves its own
* backend from the `family` it is handed (`prefer: 'cli'`, and the render
* backend is not always a provider at all).
*
* An UNFAMILIED run is the one case with no family to check against, and it is
* not an exception to the rule above so much as the absence of its premise: a
* manual maintenance run pinned to a provider outside every subscription family
* spends no window, so there is no wrong window for it to spend. Only
* `maintenanceRun.js` can construct that identity, and `providerForFamily`
* still requires the pin to name an ENABLED, process-capable provider — so the
* resolved provider is always exactly the one the user picked.
*/
async function resolveStepProvider(effective, family) {
const { noProviderReason, matchesFamily, isUnfamiliedBurn, resolveBurnProvider } = await import('./scheduledHandlers/providerPick.js');
const provider = await resolveBurnProvider({ job: { providerId: effective.providerId }, family });
if (!provider) {
return {
error: effective.providerId
? `pinned provider "${effective.providerId}" is not an enabled CLI/TUI provider`
: noProviderReason(family),
};
}
if (!isUnfamiliedBurn(family) && !matchesFamily(provider, family.id)) {
return { error: `pinned provider "${provider.id}" does not belong to the ${family.id} family` };
}
return { provider };
}
/**
* Why an unattended burn may not run this custom job, or null.
*
* `autonomyLevel` is the job's own statement about whether it may run without a
* human confirming it (`generateTaskFromJob` turns `yolo` into `autoApprove`).
* Anything below that needs an approval a burn cannot give, and the manual
* endpoint's `approvalRequired: false` is exactly the bypass this path must not
* inherit — so it refuses instead, with the level named so the row is
* actionable.
*/
function unattendedApprovalRefusal(job) {
return job.autonomyLevel === UNATTENDED_AUTONOMY_LEVEL
? null
: `custom scheduled job "${job.name}" needs approval to run (autonomy level "${job.autonomyLevel || 'manager'}") — a quota burn cannot approve it`;
}
/**
* Whether an equivalent invocation of this custom job is already in flight.
*
* `cosJobScheduler.isJobFireInFlight` is the scheduler's OWN admission check,
* shared rather than copied: half of it (`spawningJobIds`) is process-local
* state a re-implementation here could not see at all, which would leave the
* whole spawn window open for a burn to double-queue a job the clock just fired.
*/
async function activeCustomJobReason(job) {
const [{ loadState }, { isJobFireInFlight }] = await Promise.all([
import('./cosState.js'),
import('./cosJobScheduler.js'),
]);
const state = await loadState().catch(() => null);
if (!state) return null;
return isJobFireInFlight(job.id, state) ? `a run of "${job.name}" is already in flight` : null;
}
/**
* Whether this built-in task already has an on-demand request waiting.
*
* Two burn cycles can otherwise stack requests for the same task faster than the
* engines drain them: the second would spend the family's budget on a task the
* first already asked for. `addTask`'s duplicate detection catches the collision
* one step later, but only after the cap was already charged.
*/
async function queuedOnDemandReason(queued, taskType, appId) {
const pending = queued instanceof Set
? queued.has(onDemandKey(taskType, appId))
// No snapshot (a caller passed a bare catalog, or the read failed): ask the
// schedule directly rather than reporting "nothing queued", which would let
// a second cycle stack a duplicate request onto the family's budget.
: (await import('./taskSchedule.js')
.then(({ getOnDemandRequests }) => getOnDemandRequests())
.catch(() => []))
.some((request) => onDemandKey(request.taskType, request.appId) === onDemandKey(taskType, appId));
return pending ? `an on-demand run of "${taskType}" is already queued` : null;
}
/**
* Invoke one burn step. Returns the registry's dispatch shape —
* `{ dispatched, summary?, reason?, detail?, awaiting? }` — so the runner's
* accounting, run log and skip reporting read identically whichever reference
* shape ran.
*
* A decline is reported, never thrown: work that failed to start must not
* charge the window's cap. `awaiting` says the opposite thing about a dispatch
* that DID go out: the work is not accepted yet, so the runner reserves the
* step's place instead of charging it (see `quotaBurnAcceptance.js`).
*
* The master Improve switch is refused HERE, in the shared resolution, for all
* three lanes: the catalog carries the switch, so the page reports it on the
* same step the dispatch would refuse — and a burn cannot be the one path that
* spends a subscription while the user has CoS improvement switched off.
*/
export async function invokeQuotaBurnStep({ step, family, candidate, context, force = false, catalog = null, maintenanceRunId = null } = {}) {
// A forced run is the user clicking this one step: like a manual Run, it is an
// explicit choice and is not refused as not-applicable.
const resolved = await resolveQuotaBurnStep(step, catalog, { explicit: force });
// The code rides along so a caller can tell "does not apply" (a maintenance
// run completes that step as skipped) from a refusal it must hold on.
if (resolved.unavailable) return { ...declined(resolved.unavailable.reason), code: resolved.unavailable.code };
if (resolved.kind === 'programmatic') return runProgrammaticStep({ resolved, family, context, force });
if (resolved.kind === 'custom') return runCustomJobStep({ resolved, step, family, candidate, maintenanceRunId });
return runBuiltinTaskStep({ resolved, step, family, candidate, maintenanceRunId });
}
/**
* A programmatic handler runs INLINE — PortOS performs the work itself, spawns
* no agent and consumes no slot, so there is nothing to generate and nothing to
* wait for. `family` is what keeps the render backend pinned to the window being
* drained (see `scheduledHandlers/index.js`).
*/
async function runProgrammaticStep({ resolved, family, context, force }) {
const { runScheduledHandler } = await import('./scheduledHandlers/index.js');
return runScheduledHandler({
taskType: resolved.ref.taskType,
params: resolved.effective.params,
job: resolved.effective,
family,
context,
force,
});
}
/**
* A built-in agent task goes through the schedule's own on-demand lane, so the
* master Improve gate, the enabled + instance-feature gates, target scope, the
* per-app switch and invocation eligibility are all enforced by
* `triggerOnDemandTask` itself rather than restated here — and it reaches them
* through `evaluateOnDemandEligibility`, the same ladder `resolveQuotaBurnStep`
* already ran against the catalog. One ladder, two consumers.
*
* `force` is NOT passed through: it means "past the quota gates", and the
* schedule's gates are not quota gates.
*/
async function runBuiltinTaskStep({ resolved, step, family, candidate, maintenanceRunId }) {
// Re-checked HERE, not left to the probe: a forced run of a named step skips
// the probe entirely (the click IS the selection), and `triggerOnDemandTask`
// appends unconditionally — so without this, two forced clicks queue the same
// task twice and charge the window's cap twice for one piece of work. The
// legacy executor never had this hole because `addTask` deduplicated one step
// further down; a request has no such backstop.
const queued = await queuedOnDemandReason(resolved.catalog?.queued, resolved.ref.taskType, resolved.ref.appId);
if (queued) return declined(queued);
const picked = await resolveStepProvider(resolved.effective, family);
if (picked.error) return declined(picked.error);
const { triggerOnDemandTask } = await import('./taskSchedule.js');
const request = await triggerOnDemandTask(resolved.ref.taskType, resolved.ref.appId, {
origin: ON_DEMAND_ORIGINS.QUOTA_BURN,
burn: {
// Omitted, not null, when the run spends no subscription window at all —
// `normalizeQuotaBurnProvenance` accepts `maintenanceRunId` as the
// attribution instead, and a placeholder here would credit this run's
// refusals to a family it never touched.
...(family.id ? { family: family.id } : {}),
stepId: step.id,
limitingResetAt: candidate?.limitingResetAt ?? null,
// Set only by a MANUAL maintenance run (`maintenanceRun.js`): the mark
// that keeps the quota-burn loop from walking its plan on this agent's
// completion. Omitted, not null, on an automatic burn.
...(maintenanceRunId ? { maintenanceRunId } : {}),
overrides: {
// The RESOLVED provider, not the step's pin: an unpinned step must still
// land on this family's provider rather than the daemon's active one, or
// the burn spends a window nobody asked it to.
providerId: picked.provider.id,
model: resolved.effective.model,
effort: resolved.effective.effort,
// The step's run params, which the on-demand engines hand to the
// generator as `runOverrides` — layered over the task's saved
// `taskMetadata` BEFORE the mode banner and the prompt are built. This
// is what carries a migrated issues-only burn's explicit
// `fileIssues: true` (#6381); without it the burn would run the
// referenced task's SAVED mode and start writing code.
// The canonical generator merges saved global and app metadata itself.
// Re-sending the global defaults here would overwrite app-specific claim filters.
params: step.overrides?.params || {},
},
},
});
if (request?.error) return declined(request.error);
// Attribution, not decoration: this shared path serves BOTH the quota-burn
// loop and MANUAL maintenance runs (`maintenanceRunId` is set only by
// maintenanceRun.js). An unconditional 🔥 line makes a maintenance dispatch
// read as quota-burn activity on an install where quota burn is disabled —
// the operator cannot tell a feature they turned off from the maintenance
// ladder they clicked. Key the wording on the provenance, and name the run.
console.log(maintenanceRunId
? `🧹 Maintenance run ${maintenanceRunId} requested scheduled task ${resolved.ref.taskType} (${request.id})`
: `🔥 Quota-burn requested scheduled task ${resolved.ref.taskType} for ${burnLabel(family)} (${request.id})`);
return {
dispatched: true,
// The ONLY lane whose acceptance is asynchronous: the request is recorded
// now and an on-demand engine generates the task later — or refuses it. The
// runner reserves against this instead of charging, and settles the charge
// when the request is joined to the task it produced
// (`quotaBurnAcceptance.js`). The two synchronous lanes below return no
// `awaiting`, because their work is accepted the moment they return.
awaiting: { requestId: request.id },
summary: `Requested "${resolved.ref.taskType}"${resolved.ref.appId ? ` for ${resolved.ref.appId}` : ''}`,
detail: {
requestId: request.id,
taskType: resolved.ref.taskType,
appId: resolved.ref.appId,
providerId: picked.provider.id,
model: resolved.effective.model,
effort: resolved.effective.effort,
},
};
}
/**
* A custom app job is generated by the job's own generator and queued with
* `addTask` — the same pair the scheduled fire uses — carrying the step's
* provider/model/effort overrides and the burn provenance.
*
* `approvalRequired` follows the job's autonomy level (already gated to `yolo`
* above, so it lands `false` legitimately rather than by bypass); no
* `forceSpawnTask`, and a blocked twin is reported as a decline instead of
* revived. See this module's header for why each of those matters.
*/
async function runCustomJobStep({ resolved, step, family, candidate, maintenanceRunId }) {
const approval = unattendedApprovalRefusal(resolved.job);
if (approval) return declined(approval);
// `addTask`'s duplicate detection catches an identical QUEUED twin below, but
// not one already mid-spawn — and a forced run reaches here with no probe.
const active = await activeCustomJobReason(resolved.job);
if (active) return declined(active);
const picked = await resolveStepProvider(resolved.effective, family);
if (picked.error) return declined(picked.error);
const [{ generateTaskFromJob }, { addTask }] = await Promise.all([
import('./autonomousJobs.js'),
import('./cosTaskStore.js'),
]);
const generated = await generateTaskFromJob(resolved.job);
const persisted = await addTask({
// The generator's own field projection, shared with the manual endpoint so
// a key added to `generateTaskFromJob` cannot reach one lane and not the
// other. Everything below OVERRIDES it — that is where the two legitimately
// differ.
...generatedJobTaskFields(generated),
// The queued task's context names who asked for it — a maintenance run's
// dispatch must not read as a quota-burn spend on the task card.
context: maintenanceRunId
? `Maintenance run ${maintenanceRunId}: ${resolved.job.name}`
: `Quota burn (${burnLabel(family)}): ${resolved.job.name}`,
approvalRequired: !generated.autoApprove,
// The step's overrides win over the job's saved pins (see effectiveSettings),
// and an unpinned step still lands on THIS family's provider.
provider: picked.provider.id,
model: resolved.effective.model || undefined,
effort: resolved.effective.effort || undefined,
// The attribution keys the built-in lane stamps via its request, so
// `isCooldownExemptTask`, the completion continuation and the denial ledger
// cannot tell the two lanes apart. There is deliberately no
// `quotaBurnRequestId`: this lane queues the task synchronously, so no
// request ever exists to name — that key records the ASYNC hop, and minting
// a fake one would make a join over it silently wrong.
// Same "omit, never placeholder" rule as the built-in lane's burn block.
...(family.id ? { quotaBurnFamily: family.id } : {}),
quotaBurnLimitingResetAt: candidate?.limitingResetAt ?? null,
quotaBurnStepId: step.id,
...(maintenanceRunId ? { quotaBurnMaintenanceRunId: maintenanceRunId } : {}),
}, 'internal', { suppressDequeue: true });
if (!persisted?.id) return declined(`"${resolved.job.name}" was not queued`);
// A blocked twin stays blocked: reviving it is the manual endpoint's explicit
// retry, and an unattended burn has no such intent to express.
if (persisted.duplicate) return declined(`an identical "${resolved.job.name}" task is already ${persisted.status}`);
// Same attribution rule as the built-in lane above: a maintenance run's
// custom-job dispatch must not wear the 🔥 quota-burn wording.
console.log(maintenanceRunId
? `🧹 Maintenance run ${maintenanceRunId} queued custom job ${resolved.job.id} as task ${persisted.id}`
: `🔥 Quota-burn queued custom job ${resolved.job.id} as task ${persisted.id} for ${burnLabel(family)}`);
return {
dispatched: true,
summary: `Queued "${resolved.job.name}" via ${picked.provider.id}`,
detail: {
taskId: persisted.id,
jobId: resolved.job.id,
providerId: picked.provider.id,
model: resolved.effective.model,
effort: resolved.effective.effort,
},
};
}