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

6.9 KB
Raw Blame
/**
 * Story Builder — SSE runner for step generate / refine.
 *
 * `generateStep` / `refineStep` in storyBuilder.js are a single LLM call plus a
 * record persist. Run synchronously they block the HTTP request — a long
 * arc-overview leaves the button spinning with no signal. This runner mirrors
 * the pipeline auto-runner (server/services/pipeline/autoRunner.js): the POST
 * kicks the work off in the background and returns immediately; progress and
 * the terminal result land on attached SSE clients.
 *
 * SSE: a single in-memory `runs` map keyed by `${sessionId}::${stepId}` so two
 * different steps can stream concurrently while a second click on the same step
 * coalesces onto the in-flight run. Late-connecting clients receive the last
 * broadcast frame via attachSseClient's replay grace window in lib/sseUtils.js.
 *
 * Frame shapes (consumed by client/src/hooks/useStoryStepRuns.jsx):
 *   { type: 'start',    runId, stepId, op }
 *   { type: 'progress', label, phase }        // phase labels during the run
 *   { type: 'complete', runId, stepId, op, changes, rationale, providerId, model }
 *   { type: 'error',    runId, stepId, op, error }
 * The completed content lives in the universe/series records — the client
 * refetches the session view on `complete` rather than carrying the payload in
 * the frame (matches the pipeline auto-run's refetch-on-terminal pattern).
 */

import { createSseRunner } from '../lib/sseUtils.js';
import { generateStep, refineStep } from './storyBuilder.js';

// Shared SSE run-lifecycle keyed by `${sessionId}::${stepId}`. This runner uses
// the factory's OPTIONAL signature-based coalescing (a `refine` of a different
// target is different work and must not bind onto an in-flight `generate`), and
// keeps its own error frame inside `work` (it carries `stepId`/`op`), so the
// factory's generic catch is only the safety net.
const runner = createSseRunner({ logLabel: 'story-builder' });

const runKey = (sessionId, stepId) => `${sessionId}::${stepId}`;

export function isStepRunActive(sessionId, stepId) {
  return runner.isActive(runKey(sessionId, stepId));
}

export function attachClient(sessionId, stepId, res) {
  return runner.attachClient(runKey(sessionId, stepId), res);
}

// Bounded discovery projection of a session's in-flight step runs, for a client
// that lost its run slot (full reload, second tab). Read-only: it inspects the
// in-memory run map and never starts provider work. Deliberately omits the
// request signature, feedback text, clients and abort controller — only the
// identity a client needs to re-attach to the existing progress stream.
export function listActiveStepRuns(sessionId) {
  const prefix = runKey(sessionId, '');
  return runner.listActive(prefix).map(({ key, runId, startedAt, phase, meta }) => ({
    stepId: key.slice(prefix.length),
    runId,
    op: meta.op,
    startedAt,
    phase,
    ...(meta.entryId ? { entryId: meta.entryId } : {}),
  }));
}

/**
 * Kick off a step generate (op: 'generate') or refine (op: 'refine') for a
 * session. Returns the runId immediately; progress lands via SSE. Re-calling
 * while a run is in flight for the same step resolves to the existing runId.
 *
 * `options` is forwarded verbatim to generateStep/refineStep (providerId,
 * model, fromDownstream for generate; feedback, entryId, providerId, model for
 * refine) plus an `onProgress` callback the conductor uses to emit phase frames.
 */
// Identity of a kickoff request: what work it would actually do. Two clicks
// with the same signature run the same work, so the second can safely attach to
// the first's in-flight run; a different signature would do different work, so
// it must NOT bind onto the running one (else its success handler fires off
// another request's terminal frame — e.g. refining character B while character
// A's refine is in flight would toast "Refined B" for A's run).
const requestSig = (op, { entryId, feedback, fromDownstream } = {}) =>
  JSON.stringify({ op, entryId: entryId ?? null, feedback: feedback ?? null, fromDownstream: !!fromDownstream });

export function startStepRun(sessionId, stepId, { op = 'generate', ...options } = {}) {
  const key = runKey(sessionId, stepId);
  const sig = requestSig(op, options);
  // The factory coalesces a second click onto the in-flight run only when the
  // signatures match (a reload mid-run re-attaching to its own request). A
  // different signature (different op, or a refine of a different target/note)
  // does different work, so it reports `conflict` + the live run's `op` (via
  // `meta`) instead — the client then refuses to bind its success handler to the
  // running request's frame. A finished run lingering in the replay grace window
  // does NOT block: the factory starts a fresh run that replaces it.
  return runner.start(key, async ({ runId, broadcast, record }) => {
    broadcast({ type: 'start', runId, stepId, op });
    // Best-effort phase emitter handed to the conductor; an onProgress throw
    // must never break the run.
    const onProgress = (frame) => {
      try {
        // Latest phase label, so a client that attaches mid-run (reload / second
        // tab) can be told what the run is doing via listActiveStepRuns.
        if (typeof frame?.label === 'string' && frame.label) record.phase = frame.label.slice(0, 200);
        broadcast({ type: 'progress', runId, ...frame });
      } catch (err) {
        console.error(`❌ story-builder progress emit failed: ${err?.message || err}`);
      }
    };

    // Own the error frame here (and swallow) so the factory's generic catch
    // doesn't double-emit; this frame carries `stepId`/`op` the client reads.
    try {
      const result = op === 'refine'
        ? await refineStep(sessionId, stepId, { ...options, onProgress })
        : await generateStep(sessionId, stepId, { ...options, onProgress });
      broadcast({
        type: 'complete',
        runId,
        stepId,
        op,
        // Surface the refine attribution the client toast + UI read; generate
        // returns these only on some steps, so guard each.
        changes: Array.isArray(result?.changes) ? result.changes : undefined,
        rationale: typeof result?.rationale === 'string' ? result.rationale : undefined,
        providerId: result?.providerId,
        model: result?.model,
        completedAt: new Date().toISOString(),
      });
      console.log(`✅ story-builder ${op} complete — session=${sessionId.slice(0, 8)} step=${stepId} runId=${runId.slice(0, 8)}`);
    } catch (err) {
      const message = (err?.message || String(err)).slice(0, 1000);
      console.error(`❌ story-builder ${op} failed — session=${sessionId.slice(0, 8)} step=${stepId} ${message}`);
      broadcast({ type: 'error', runId, stepId, op, error: message, failedAt: new Date().toISOString() });
    }
  }, { sig, meta: { op, ...(options.entryId ? { entryId: options.entryId } : {}) } });
}

// Export internals for tests.
export const __testing = { runs: runner.runs, runKey };