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
/**
* Programmatic scheduled-task handlers.
*
* A handler is one unit of work PortOS performs ITSELF — no agent is spawned,
* no CoS task is queued, and no spawn slot is consumed. Each module exports:
*
* countPending({ params, job, family }) → { count, detail, context? }
* run({ params, job, family, context, force }) → { dispatched, summary?, reason?, detail? }
*
* `countPending` must be side-effect free — the Quota Burn config page calls it
* for every configured job on every load, and the Schedule page may probe a
* handler to show its backlog. It writes nothing, enqueues nothing, and makes NO
* AI provider call (AGENTS.md: no cold-bootstrap LLM calls). It may return an
* opaque `context` (whatever it already computed) which the caller hands straight
* back to `run`, so a probe that scanned every universe bible doesn't make `run`
* repeat the scan. `run` must still work with `context: undefined` — the manual
* "Run Now" path and Quota Burn's force path both call it without a probe.
*
* `run` is the only thing that may spend, and reports `dispatched: false` with a
* `reason` when it declines (nothing to do, misconfigured target) so a quota
* caller does NOT charge its window's dispatch cap for work that never happened.
*
* ONE implementation serves both invocation paths:
*
* - The ordinary scheduled-task manual path (CoS → Schedule → Run Now) drains
* an on-demand request for the task type and calls `runScheduledHandler`
* with the task's saved `taskMetadata` as its params and NO `family`.
* - Quota Burn's runner reaches the same modules through
* `quotaBurnInvoke.js`, passing the burning `family` so the work stays
* pinned to that subscription (see `providerPick.js` /
* `universeBibleImages.resolveRenderMode`).
*
* `family` is therefore the discriminator between the two: present means "a burn
* is spending THIS family's window, never another's", absent means "an ordinary
* scheduled run — resolve the provider/backend the way any other task does".
*
* Modules are lazy-imported: `universeBibleImages` pulls the whole universe
* store + media job queue and `universeBibleDescribe` the expand services, so
* listing the registered types (or probing a type that isn't registered) must
* not load either.
*/
/**
* Task type → module import thunk. The single registration point.
*
* The matching TASK-TYPE list lives in `taskScheduleRegistry.js`
* (`PROGRAMMATIC_SCHEDULED_TASK_TYPES`) rather than being derived from these
* keys, because that registry is reached by a large share of the server suite
* and must not take on an import for a two-string list (server/AGENTS.md,
* "Import scoping"). `taskScheduleRegistry.programmatic.test.js` asserts the two
* agree, so the split cannot drift.
*/
export const SCHEDULED_HANDLER_MODULES = {
'development-watchdog': () => import('./developmentWatchdog.js'),
'music-video-autopilot': () => import('./musicVideoAutopilot.js'),
'universe-bible-describe': () => import('./universeBibleDescribe.js'),
'universe-bible-images': () => import('./universeBibleImages.js'),
};
// `Object.hasOwn`, not a truthiness check, so an inherited key like
// 'constructor' can't resolve to a module.
const load = async (taskType) =>
(typeof taskType === 'string' && Object.hasOwn(SCHEDULED_HANDLER_MODULES, taskType)
? SCHEDULED_HANDLER_MODULES[taskType]()
: null);
/**
* Pending-work probe for one handler. Never throws: a handler whose backing
* store is unavailable reports zero pending with the error as its detail, so one
* broken handler can't wedge a burn family's whole plan or blank a status page.
*/
export async function countScheduledHandlerPending({ taskType, params, job, family } = {}) {
// Include lazy module initialization and synchronous handler throws in the
// same failure boundary as rejected handler promises.
return load(taskType)
.then((mod) => mod
? mod.countPending({ params, job, family })
: { count: 0, detail: `unknown scheduled handler: ${taskType}` })
.catch((err) => ({ count: 0, detail: `probe failed: ${err.message}` }));
}
/**
* Run one handler. Throws are converted to a non-dispatch: the caller treats it
* as "this handler declined", moves on, and logs the reason — work that failed
* to start must not charge a quota window's cap.
*/
export async function runScheduledHandler({ taskType, params, job, family, context, force = false } = {}) {
return load(taskType)
.then((mod) => mod
? mod.run({ params, job, family, context, force })
: { dispatched: false, reason: `unknown scheduled handler: ${taskType}` })
.catch((err) => ({ dispatched: false, reason: `handler failed: ${err.message}` }));
}