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
/**
* Writers Room — Phase 5 live Creative Director feedback.
*
* On an explicit, throttled client request (NOT on every keystroke — the
* editor debounces and only asks while live-mode is opted in), take the prose
* window around the writer's cursor and propose a few short continuation
* options. Stateless: nothing is persisted except the per-work daily budget
* counter (`recordLiveModeUsage`), so a suggestion the writer ignores leaves
* no trace. This is the spine the later live-render-preview and Creative
* Director beat/scene bridge build on.
*
* Budget + opt-in are enforced server-side here, not just in the UI — a client
* that ignores the toggle or the debounce still can't run unbounded LLM calls.
*/
import { ServerError } from '../../lib/errorHandler.js';
import { runStagedLLM } from '../stageRunner.js';
import {
getWork, resolveLiveMode, recordLiveModeUsage, recordLiveModeRenderUsage, utcDayKey,
linkToCreativeDirector, renderWorkVoiceGuide,
} from './local.js';
import { createProject, setTreatment, deleteProject, updateProject } from '../creativeDirector/local.js';
import { deleteCollection } from '../mediaCollections.js';
import { defaultVideoModelId } from '../videoGen/local.js';
import { badRequest } from './_shared.js';
const STAGE = 'writers-room-continue';
// Exported so other conductors that mint a CD project from prose — the
// pipeline→CD "produce video from issue" bridge (CDO Phase 3, #2185) — reuse the
// SAME stage + proposal shaper rather than duplicating the treatment-from-prose
// contract.
export const CD_BRIDGE_STAGE = 'writers-room-cd-bridge';
const MAX_OPTIONS = 4;
// CD-bridge proposal bounds. The prompt asks for 2–6 filmable scenes; we clamp
// to that range (and the LLM may overshoot, so MAX is a hard cap) — well under
// creativeDirectorTreatmentSchema's 1..120, so a sent proposal always validates.
const MIN_BRIDGE_SCENES = 2;
const MAX_BRIDGE_SCENES = 6;
// Surface the two soft-failure modes as typed codes so the route can map them
// to the right HTTP status (live-mode off → 409 conflict; budget spent → 429).
export const ERR_LIVE_MODE_OFF = 'LIVE_MODE_OFF';
export const ERR_BUDGET_EXCEEDED = 'LIVE_BUDGET_EXCEEDED';
// Shared opt-in + daily-budget gate for the live paths. Throws the coded
// 409 (live mode off) / 429 (budget spent) ServerErrors the route maps to a
// status. `usage` is the relevant per-day counter, `budget` its cap (0 =
// unlimited), `label` names the budget in the 429 message. A counter whose
// stored date isn't today counts as 0 spent-today (it rolls over on write), so
// yesterday's count can't block today. utcDayKey() is the same boundary the
// recordLiveMode*Usage writers roll over on, so the check can't drift.
function assertLiveBudget(live, { usage, budget, label }) {
if (!live.enabled) {
throw new ServerError('Live mode is off for this work', { status: 409, code: ERR_LIVE_MODE_OFF });
}
const today = utcDayKey();
const spentToday = usage.date === today ? usage.count : 0;
if (budget > 0 && spentToday >= budget) {
throw new ServerError(
`Live ${label} budget reached (${budget}/day) — resets at UTC midnight`,
{ status: 429, code: ERR_BUDGET_EXCEEDED },
);
}
}
function shapeOptions(parsed) {
const raw = Array.isArray(parsed?.options) ? parsed.options : [];
return raw
.filter((o) => o && typeof o === 'object')
.map((o) => ({
kind: ['beat', 'prose', 'dialogue'].includes(o.kind) ? o.kind : 'beat',
label: typeof o.label === 'string' ? o.label.trim() : '',
text: typeof o.text === 'string' ? o.text.trim() : '',
rationale: typeof o.rationale === 'string' ? o.rationale.trim() : '',
}))
.filter((o) => o.text)
.slice(0, MAX_OPTIONS);
}
/**
* Generate live continuation suggestions from the cursor context.
* Throws a coded ServerError when live mode is off or the daily budget is
* spent (the route translates the code to a status). On success returns
* `{ options, usage, budget }` so the client can render remaining budget.
*/
export async function suggestContinuation(workId, { before = '', after = '', selection = '' } = {}) {
const manifest = await getWork(workId); // 404s if the work is missing
const live = resolveLiveMode(manifest);
assertLiveBudget(live, { usage: live.usage, budget: live.dailyCallBudget, label: 'suggestion' });
if (!before.trim() && !after.trim() && !selection.trim()) {
throw badRequest('Need some prose around the cursor to suggest a continuation');
}
const variables = {
work: { title: manifest.title, kind: manifest.kind, status: manifest.status },
before, after, selection,
// Voice exemplars (#2179) — the "tuning fork" passages anchor the drafted
// continuation to the chosen voice far better than the template's generic
// "match the established voice" line. Empty string when the work carries no
// passages, so the continue template's {{#voiceGuide}} section renders
// nothing (no per-call overhead for works that never set a voice).
voiceGuide: renderWorkVoiceGuide(manifest),
returnsJson: true,
};
const { content } = await runStagedLLM(STAGE, variables, {
source: 'writers-room-continue',
returnsJson: true,
});
const options = shapeOptions(content);
// Charge the budget for every call that reached the LLM — the provider cost
// is incurred whether or not the response parsed into usable options. Only
// sparing a zero-option call would let a model that reliably returns garbage
// (or a prompt that always parses empty) run unbounded calls and never hit
// the 429 cap. recordLiveModeUsage returns the full resolved config; we
// surface just the usage sub-object.
const usage = (await recordLiveModeUsage(workId)).usage;
return {
options,
usage,
budget: live.dailyCallBudget,
};
}
/**
* Reserve one live render preview against the per-work render budget. The
* actual image render reuses the existing image-gen route + media job queue on
* the client — this is purely the server-side opt-in + budget gate so a client
* that ignores the toggle still can't run unbounded renders. Throws the same
* coded errors as suggestContinuation (live-mode off → 409, budget spent → 429)
* and bumps the distinct daily render counter on success. Returns
* `{ renderUsage, renderBudget }` so the client can render remaining budget.
*
* Budget is charged at reservation time (before the render kicks off) rather
* than on completion: the GPU/provider cost is incurred the moment the job is
* enqueued, and a client that fires-and-forgets must still hit the cap.
*/
export async function reserveRenderPreview(workId) {
const manifest = await getWork(workId); // 404s if the work is missing
const live = resolveLiveMode(manifest);
assertLiveBudget(live, { usage: live.renderUsage, budget: live.dailyRenderBudget, label: 'render' });
const renderUsage = (await recordLiveModeRenderUsage(workId)).renderUsage;
return { renderUsage, renderBudget: live.dailyRenderBudget };
}
// Coerce one raw LLM scene into the shape the CD-bridge proposal carries.
// Returns null for an unusable scene (no intent/prompt) so the caller can drop
// it before clamping to the 2–6 range.
function shapeBridgeScene(raw) {
if (!raw || typeof raw !== 'object') return null;
const intent = typeof raw.intent === 'string' ? raw.intent.trim() : '';
const prompt = typeof raw.prompt === 'string' ? raw.prompt.trim() : '';
if (!intent || !prompt) return null;
// durationSeconds: round into the CD scene's 1..10 integer range; default to
// a mid 5s when the model omits or fumbles it.
const rawDur = Number(raw.durationSeconds);
const durationSeconds = Number.isFinite(rawDur)
? Math.min(10, Math.max(1, Math.round(rawDur)))
: 5;
return { intent: intent.slice(0, 1000), prompt: prompt.slice(0, 8000), durationSeconds };
}
// Shape a raw LLM response into a CD treatment proposal. Trims the text fields
// to the CD treatment schema caps and clamps scenes to the 2–6 prompt range.
// Returns null when the response can't yield at least MIN_BRIDGE_SCENES usable
// scenes — the route surfaces that as an empty proposal, not a crash.
export function shapeProposal(parsed) {
const scenes = (Array.isArray(parsed?.scenes) ? parsed.scenes : [])
.map(shapeBridgeScene)
.filter(Boolean)
.slice(0, MAX_BRIDGE_SCENES);
if (scenes.length < MIN_BRIDGE_SCENES) return null;
const logline = typeof parsed?.logline === 'string' ? parsed.logline.trim().slice(0, 500) : '';
const synopsis = typeof parsed?.synopsis === 'string' ? parsed.synopsis.trim().slice(0, 5000) : '';
// logline + synopsis are REQUIRED by the send schema (and CD's treatment
// schema) with min(1). Returning a proposal missing either would render a
// live "Send" button that then 400s — so treat a missing-headline response
// as "no usable treatment" (null), the same as too-few scenes.
if (!logline || !synopsis) return null;
return {
logline,
synopsis,
styleSpec: typeof parsed?.styleSpec === 'string' ? parsed.styleSpec.trim().slice(0, 5000) : '',
scenes,
};
}
/**
* Generate a Creative Director treatment proposal from the cursor context.
* Unlike suggestContinuation (which returns inline prose options), this returns
* a reviewable mini-treatment — logline, synopsis, visual treatment (styleSpec),
* and 2–6 filmable scenes — that the writer can send into a new CD project.
*
* Reuses the SAME daily call budget + opt-in gate as the text-suggest path
* (both are text LLM calls). Throws the coded 409 (live mode off) / 429 (budget
* spent) ServerErrors the route maps to a status. On success returns
* `{ proposal, usage, budget }`; `proposal` is null when the model couldn't
* produce a usable treatment.
*/
export async function suggestCdBridge(workId, { before = '', after = '', selection = '' } = {}) {
const manifest = await getWork(workId); // 404s if the work is missing
const live = resolveLiveMode(manifest);
assertLiveBudget(live, { usage: live.usage, budget: live.dailyCallBudget, label: 'suggestion' });
if (!before.trim() && !after.trim() && !selection.trim()) {
throw badRequest('Need some prose around the cursor to propose a treatment');
}
const variables = {
work: { title: manifest.title, kind: manifest.kind, status: manifest.status },
before, after, selection,
returnsJson: true,
};
const { content } = await runStagedLLM(CD_BRIDGE_STAGE, variables, {
source: 'writers-room-cd-bridge',
returnsJson: true,
});
const proposal = shapeProposal(content);
// Charge the shared text-suggest budget for every call that reached the LLM —
// same rationale as suggestContinuation: the provider cost is incurred whether
// or not the response parsed into a usable proposal.
const usage = (await recordLiveModeUsage(workId)).usage;
return { proposal, usage, budget: live.dailyCallBudget };
}
/**
* Assign the CD scene runtime fields the treatment schema requires but a raw
* CD-bridge LLM proposal doesn't carry: a stable sceneId, render order, and the
* continuation flag (every scene after the first continues from its prior).
* Exported so the pipeline→CD bridge (CDO Phase 3, #2185) maps proposal scenes
* into a treatment identically to the writers-room send path.
*/
export function bridgeScenesToTreatmentScenes(scenes) {
return (Array.isArray(scenes) ? scenes : []).map((s, i) => ({
sceneId: `sc-${i + 1}`,
order: i,
intent: s.intent,
prompt: s.prompt,
durationSeconds: s.durationSeconds,
useContinuationFromPrior: i > 0,
}));
}
/**
* Send a reviewed CD-bridge proposal into a NEW Creative Director project.
* Non-destructive (never clobbers an existing project's treatment): it mints a
* fresh CD project seeded with the work's title + the proposal's styleSpec, then
* writes the treatment (logline/synopsis/scenes), then records the bridge link
* on the WR manifest so the editor can show an "Open in Creative Director" CTA.
*
* No LLM, no budget — the proposal was already generated + charged by
* suggestCdBridge; this is the cheap commit half. createProject + setTreatment
* are wrapped so a setTreatment/link failure rolls back the orphaned project
* (mirrors promoteToPipeline's orphan-cleanup rationale — multi-step write that
* re-throws the original error after best-effort cleanup). Returns `{ project }`.
*/
export async function sendToCreativeDirector(workId, { proposal } = {}) {
const manifest = await getWork(workId); // 404s if the work is missing
// Assign the CD scene runtime fields the schema requires but the LLM proposal
// doesn't carry: a stable sceneId, render order, and the continuation flag.
const scenes = bridgeScenesToTreatmentScenes(proposal.scenes);
// CD render defaults — match the client New-Project form (16:9 / standard /
// 60s) and resolve the default video model server-side so a bridged project
// doesn't start on a legacy backend.
const project = await createProject({
name: manifest.title,
aspectRatio: '16:9',
quality: 'standard',
modelId: defaultVideoModelId(),
targetDurationSeconds: 60,
styleSpec: proposal.styleSpec || '',
});
// setTreatment returns the full project with the treatment applied — capture
// it so the route can return the seeded project without a re-read.
let withTreatment;
try {
await setTreatment(project.id, {
logline: proposal.logline,
synopsis: proposal.synopsis,
scenes,
});
// setTreatment flips a fresh project to 'rendering', but nothing here
// enqueues a render — the orchestrator only runs on an explicit
// POST /:id/start. A 'rendering' project also hides the detail page's
// "Start" button (it shows only for 'draft'/'failed'), which would strand
// the bridged project as "active" with no way to kick it off. Reset to
// 'draft' so the user reviews it in Creative Director and starts rendering
// deliberately (no surprise GPU/provider spend from the bridge itself).
withTreatment = await updateProject(project.id, { status: 'draft' });
await linkToCreativeDirector(workId, { projectId: project.id });
} catch (err) {
// Roll back the orphaned project AND its auto-created media collection so a
// setTreatment/link failure doesn't leave a treatment-less project or a
// dangling empty collection behind with no manifest link. Best-effort —
// swallow cleanup errors so the original cause reaches the caller.
await deleteProject(project.id).catch(() => {});
if (project.collectionId) await deleteCollection(project.collectionId).catch(() => {});
throw err;
}
return { project: withTreatment };
}