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
/**
* Shared staged-LLM runner.
*
* Single entry point for "run a named stage from `data/prompts/stages/` against
* the active (or stage-pinned) provider, with tier-aware model resolution and
* runner.js-tracked transcripts." Replaces two parallel implementations:
*
* - server/services/writersRoom/evaluator.js (callApiProvider + callCliProvider
* + buildCliInvocation — bypassed runner.js, lost transcript persistence)
* - server/services/pipeline/textStages.js#callLLM (already used runner.js but
* lacked tier-name resolution and stage.provider pinning)
*
* Both call paths now route here so a single CLI-spawn fix applies once and
* every stage call lands in `data/runs/<runId>/` for replay.
*/
import { callerModeRejection } from '../lib/callerModePolicy.js';
import { isProcessProvider } from '../lib/providerTypes.js';
import { ServerError } from '../lib/errorHandler.js';
import { findBalancedBlocks, tryParseWithRepair } from '../lib/jsonExtract.js';
import { buildRequestCapabilities, resolveEffectiveModel, runPromptThroughProvider, DEFAULT_TIMEOUT_MS, isLocalEndpoint, withObservedContextWindowsLazy } from './promptRunner.js';
import { stripCodeFences } from '../lib/llmText.js';
import { extractCodexAssistant } from '../lib/codexAssistantExtract.js';
import { getActiveProvider, getProviderById } from './providers.js';
import { buildPrompt, getStage } from './promptService.js';
import { stagePinsIgnored } from '../lib/stagePinPolicy.js';
import {
DEFAULT_LARGE_CONTEXT_WINDOW,
knownModelContextWindow,
knownProviderContextWindow,
catalogModelContextWindow,
} from '../lib/providerContextWindows.js';
// The Ollama `num_ctx` ceiling — the same module the pre-dispatch gate resolves
// it through, so the budgeter and the gate cannot disagree again (#7466). The
// dependency-free `internal/` leaf, not the toolkit barrel: that reaches `fs`
// and `child_process`, and this module is inside the server suite's import budget.
import { clampToRuntimeContextWindow } from '../lib/aiToolkit/internal/ollamaBacked.js';
// …and the rung of that ceiling the toolkit cannot resolve for itself: the
// ambient `OLLAMA_CONTEXT_LENGTH` PortOS launches the daemon with (#7472).
import { withOllamaRuntimeContextWindow } from '../lib/ollamaContext.js';
import { createRun, patchRunMetadata } from './runner.js';
import { canonicalStageModelTier, isStageModelTier } from '../lib/stageModelTiers.js';
import { resolveProviderModelTier, MIN_TIMEOUT as STAGE_TIMEOUT_MIN_MS, MAX_TIMEOUT as STAGE_TIMEOUT_MAX_MS } from '../lib/aiToolkit/constants.js';
// Every stage-config field that names a ROUTE. `withStagePinsIgnored`
// (lib/stagePinPolicy.js) strips exactly these so a run told to use ONE
// provider/model actually does — see that module for why the switch is an
// async-context flag. Enumerated HERE, once: the resolvers below then need no
// per-pin conditionals, and adding a routing pin to the stage schema means
// adding it to this list and nowhere else.
const ROUTING_PIN_FIELDS = Object.freeze(['provider', 'effort', 'judgeProvider', 'judgeModel']);
// The stage as the resolvers below should see it. Identity unless the current
// run asked to ignore pins, in which case the routing fields above are dropped.
//
// Two fields deliberately SURVIVE:
// - a `model` TIER (default/light/medium/heavy/ultra) — a per-provider mapping, not
// a pin. It already loses to `modelDefault`, and it is the right fallback
// for a run that forced a provider without naming a model. Only an explicit
// model id is dropped.
// - `timeout` — it encodes how long the stage's WORK takes (a whole-manuscript
// editorial pass vs a one-line classification), not which provider runs it.
// Dropping it to the provider default would abort the long stages, not
// rescue them; a timeout genuinely too tight for a forced local model is a
// stage-config edit, not a run option.
export function effectiveStage(stage) {
if (!stage || !stagePinsIgnored()) return stage;
const stripped = { ...stage };
for (const field of ROUTING_PIN_FIELDS) delete stripped[field];
if (stripped.model && !isStageModelTier(stripped.model)) delete stripped.model;
return stripped;
}
// First-element fallback when defaultModel is unset on a provider that
// exposes a `models` array (some toolkit-configured providers ship a model
// list but no explicit default). Without this, API-side runners that require
// an explicit model would receive `null` and 400. Mirrors the older pipeline
// fallback that the shared runner replaced.
const providerFallbackModel = (provider) =>
provider.defaultModel
|| (Array.isArray(provider.models) && provider.models[0])
|| null;
// Per-call timeout bounds come from the canonical aiToolkit/constants.js
// (imported at the top of the file). The runner, the route validator, and
// the toolkit's own provider/run validation all reject the same shapes.
// Internal callers (extractors, pipeline stages) hit the runner directly,
// so it must enforce the same bounds as the HTTP boundary or a caller
// could slip through a value the schema would reject.
// Normalize a stage- or caller-supplied timeout into a positive integer
// milliseconds value (or `undefined` to mean "fall through to provider
// default"). Reject NaN, non-integer, exponent/hex string forms, and
// anything outside [STAGE_TIMEOUT_MIN_MS, STAGE_TIMEOUT_MAX_MS] — matches
// parseTimeoutMs on the client and the route validator's preprocess. The
// digit-only string gate is critical: `Number('1e3')` is 1000 and
// `Number.isInteger(1000)` is true, so without the gate an internal caller
// passing `'1e3'` would be silently accepted here while the validator
// rejects the same shape.
function normalizeTimeout(raw) {
if (raw == null) return undefined;
let n;
if (typeof raw === 'number') {
n = raw;
} else if (typeof raw === 'string' && /^\d+$/.test(raw.trim())) {
n = Number(raw.trim());
} else {
return undefined;
}
if (!Number.isInteger(n) || n < STAGE_TIMEOUT_MIN_MS || n > STAGE_TIMEOUT_MAX_MS) return undefined;
return n;
}
export function resolveModel(provider, modelHint) {
if (!modelHint) return providerFallbackModel(provider);
if (isStageModelTier(modelHint)) {
return resolveProviderModelTier(provider, canonicalStageModelTier(modelHint)) || providerFallbackModel(provider);
}
return modelHint;
}
// Compose the model hint for a stage with soft-default awareness (#1558).
//
// The model dimension is NOT symmetric with the provider dimension. A
// `stage.provider` is opt-in — almost no stage sets one — so a run-level
// `providerDefault` applies to the common (unpinned) case and only loses to the
// rare deliberate `stage.provider` pin. But nearly every stage in the shipped
// `stage-config.json` carries a `stage.model` *tier* value (`default`/`light`/
// `medium`/`heavy`/`ultra`) — that tier is the model-dimension equivalent of "no
// provider pinned", a default mapping, NOT a deliberate per-stage model choice.
// So a run-level `modelDefault` must OVERRIDE a stage's tier (otherwise
// launching Series Autopilot with a model would be a no-op on ~every stage),
// while still LOSING to a deliberate explicit-model pin (an actual model id like
// `lmstudio:gptoss-20b`, the case #1558 set out to protect).
//
// Precedence, strongest first:
// 1. modelOverride — hard per-call model id (manual "regenerate with model X")
// 2. explicit stage.model — a deliberate pin (non-tier model id) beats the run default
// 3. modelDefault — the run-level soft default (Series Autopilot's run model)
// 4. stage.model tier — the stage's default tier mapping (default/light/medium/heavy/ultra)
// 5. provider default — resolveModel's own fallback
//
// Takes an `effectiveStage`-masked stage, so step 2 is already gone for a run
// that forced one model across every stage.
function resolveModelHint(stage, options = {}) {
const stageModel = stage?.model;
const stagePin = stageModel && !isStageModelTier(stageModel) ? stageModel : null;
const stageTier = isStageModelTier(stageModel) ? stageModel : null;
return options.modelOverride || stagePin || options.modelDefault || stageTier || null;
}
// Compose the reasoning-effort hint for a stage (#3641).
//
// Effort is symmetric with the PROVIDER dimension, not the model one: no stage
// carries a default effort the way nearly every stage carries a model *tier*,
// so `stage.effort` is always a deliberate opt-in pin and therefore beats the
// blanket run-level default.
//
// Precedence, strongest first:
// 1. effortOverride — hard per-call effort ("run THIS request at max")
// 2. stage.effort — a deliberate per-stage pin (stage-config.json)
// 3. effortDefault — the run-level soft default (Series Autopilot's run effort)
// 4. null — no flag emitted; the provider's own config decides
//
// The result is safe to pass unconditionally: `runPromptThroughProvider` clamps
// it to the provider's (and, for Antigravity, the model's) ladder and drops it
// entirely for a provider with no effort control.
//
// Takes an `effectiveStage`-masked stage, so step 2 is already gone for a run
// that forced one route across every stage.
export function resolveEffortHint(stage, options = {}) {
return options.effortOverride || stage?.effort || options.effortDefault || null;
}
// The local-backend concurrency gate (cap concurrent in-flight calls per local
// endpoint so N parallel stage calls don't thrash one GPU's VRAM) lives in
// promptRunner.js — the actual execution layer — so it covers the initially
// selected provider, a proactive createRun swap, AND a runtime fallback that
// lands on a local backend. Re-exported here for callers/tests that reference
// the gate by its historical stageRunner path. `isLocalEndpoint` is shared from
// the same module so the context-window heuristic below and the gate agree on
// what "local" means.
export { withLocalConcurrencyGate, LOCAL_LLM_MAX_CONCURRENCY } from './promptRunner.js';
export { isLocalEndpoint };
// CLI/TUI providers (Claude Code, Codex, Antigravity) are frontier models;
// non-local API providers are cloud. Local backends (ollama/lmstudio on
// localhost) are the only genuinely small-window case.
const isLikelyLargeContextProvider = (provider) => {
if (isProcessProvider(provider)) return true;
if (provider?.type === 'api') return !isLocalEndpoint(provider.endpoint);
return false;
};
// Which window this provider/model CLAIMS, before the runtime ceiling: an
// explicit `contextWindow` wins, else the window the provider's own catalog
// reported for this model, else a known model window for the resolved model,
// else a known provider-level window for configured-default process providers,
// else `numCtx`, else a large default for frontier providers, else null (the
// budgeter applies a conservative floor for unknown local backends). The rungs
// themselves live in lib/providerContextWindows.js, the pure leaf the browser's
// provider-card meter shares.
//
// `numCtx` still ends the ladder, but it only DECIDES for a non-Ollama local
// endpoint, where it is a user's hint about a window the endpoint ignores. On
// an Ollama-backed provider the clamp has already bounded every rung above it.
function claimedContextWindow(provider, model) {
if (Number(provider?.contextWindow) > 0) return Number(provider.contextWindow);
const catalogWindow = catalogModelContextWindow(provider, model);
if (catalogWindow) return catalogWindow;
const modelWindow = knownModelContextWindow(model);
if (modelWindow) return modelWindow;
const providerWindow = knownProviderContextWindow(provider);
if (providerWindow) return providerWindow;
if (Number(provider?.numCtx) > 0) return Number(provider.numCtx);
if (isLikelyLargeContextProvider(provider)) return DEFAULT_LARGE_CONTEXT_WINDOW;
return null;
}
/**
* Planning-time context window for a provider/model — the number the prompt
* budgeter chunks against: the claimed window held to what the daemon will
* actually serve. The ceiling bounds every rung, an explicit override included
* (a user preference the daemon cannot honor past its launch window). See
* {@link clampToRuntimeContextWindow} for the rule and why it is shared.
*
* The provider is projected through `withOllamaRuntimeContextWindow` first so
* the ceiling sees BOTH rungs the daemon was launched from — `numCtx` and the
* ambient `OLLAMA_CONTEXT_LENGTH`. Without it an install that configures the
* window through the env var alone budgeted at the model's catalog window and
* the call died at dispatch (#7472). The projection is in-memory and never
* persisted; `resolveStageContext` deliberately does NOT do it for us, because
* both of its branches (probe and no-probe) must get the same ceiling.
*/
export function effectiveContextWindow(provider, model) {
const runtime = withOllamaRuntimeContextWindow(provider);
return clampToRuntimeContextWindow(runtime, claimedContextWindow(runtime, model));
}
/**
* Resolve which provider/model a stage WOULD run against (without executing)
* plus its planning context window — for callers that must budget the prompt
* before building it (e.g. manuscript editorial chunking).
*
* Best-effort planning: this resolves the PRIMARY provider; a runtime fallback
* to a different (possibly smaller-window) provider is not reflected here.
*
* WHICH provider/model a stage would use is {@link resolveStageRoute}, and it
* makes no network call. Use that when the window is not what you came for.
*/
export async function resolveStageRoute(stageName, options = {}) {
const stage = effectiveStage(getStage(stageName));
const provider = await resolveProviderForStage(stage, options);
const requestedModel = resolveModel(provider, resolveModelHint(stage, options));
return { provider, model: resolveEffectiveModel(provider, requestedModel) };
}
/**
* {@link resolveStageRoute} plus the window to budget the prompt against.
*
* That window is measured against what a local daemon is SERVING right now, not
* only against what the provider record remembers. Without it the chunker
* planned to the blanket 128K assumption for a seeded local wrapper, built the
* oversized prompt, and the pre-dispatch gate (#7441, which already reads the
* live listing) refused it — a run lost to a limit the budgeter could have
* respected. The listing is TTL-cached and shared with that gate, so a chunked
* run spends at most one `/v1/models` per endpoint per 15s rather than one per
* stage; a daemon that is down or silent contributes nothing, and the ladder
* resolves exactly as it did before.
*
* `provider` is returned UNMERGED — callers read it for the record's identity,
* and observed runtime state has no business riding a provider record around.
*/
export async function resolveStageContext(stageName, options = {}) {
const { provider, model } = await resolveStageRoute(stageName, options);
// An explicit `contextWindow` already short-circuits the ladder's first rung,
// so observing one could not change the answer — skip the probe rather than
// spend a round trip (up to the probe timeout on a black-holed endpoint) on a
// result that is provably discarded. (The `numCtx` ceiling still applies: it
// reads the provider RECORD, which an observation never touches.)
if (Number(provider?.contextWindow) > 0) {
return { provider, model, contextWindow: effectiveContextWindow(provider, model) };
}
// Budget-only enrichment, so a probe or module-load failure must never turn
// planning into a new failure mode — fall back to the provider as stored.
const observed = await withObservedContextWindowsLazy(provider).catch(() => provider);
return { provider, model, contextWindow: effectiveContextWindow(observed, model) };
}
// Provider resolution precedence, strongest first:
// 1. `providerOverride` — an explicit per-call choice ("run THIS request with
// provider X right now", e.g. a route's regenerate-with-provider button).
// The most specific signal, so it beats even a stage pin. Throws if the
// requested provider is unavailable — the caller asked for it by name.
// 2. `stage.provider` — a deliberate per-stage pin (Prompts page /
// stage-config.json). Beats a blanket run-level default so a pinned stage
// keeps running on its chosen provider even when something sets a different
// default for everything else (e.g. Series Autopilot's run provider).
// 3. `providerDefault` — a blanket run-level default that applies ONLY to
// stages without their own pin. Unlike an override it is a soft preference:
// if it's unavailable we fall through to the active provider rather than
// throwing, because it was never a per-call demand.
// 4. The active provider — the system-wide fallback.
//
// Takes an `effectiveStage`-masked stage, so step 2 is already gone for a run
// that forced one provider across every stage. Because the pin is *stripped*
// rather than demoted, such a run also stops throwing STAGE_PROVIDER_UNAVAILABLE
// for a stage pinned to a provider that no longer exists.
async function resolveProviderForStage(stage, { providerOverride, providerDefault, callerPolicy } = {}) {
const permitted = (provider) => {
const rejection = callerPolicy ? callerModeRejection(provider, callerPolicy) : null;
if (rejection) throw new ServerError(`Provider "${provider.id}" ${rejection.reason}`, {
status: 422, code: 'PROVIDER_MODE_NOT_PERMITTED',
});
return provider;
};
if (providerOverride) {
const pinned = await getProviderById(providerOverride).catch(() => null);
if (pinned?.enabled) return permitted(pinned);
throw new ServerError(
`Requested provider "${providerOverride}" is not available`,
{ status: 503, code: 'PROVIDER_OVERRIDE_UNAVAILABLE' }
);
}
if (stage?.provider) {
const pinned = await getProviderById(stage.provider).catch(() => null);
if (pinned?.enabled) return permitted(pinned);
throw new ServerError(
`Stage provider "${stage.provider}" is not available — re-pick a provider in Prompts or the stage settings`,
{ status: 503, code: 'STAGE_PROVIDER_UNAVAILABLE' }
);
}
if (providerDefault) {
const fallback = await getProviderById(providerDefault).catch(() => null);
if (fallback?.enabled) return permitted(fallback);
// Soft default: an unavailable run default is not a hard error — drop to the
// active provider below instead of throwing.
}
const active = await getActiveProvider().catch(() => null);
if (active?.enabled) return permitted(active);
throw new ServerError('No AI provider available', { status: 503, code: 'NO_PROVIDER' });
}
/**
* Resolve the JUDGE provider/model for a WRITER stage — the writer/judge model
* split (#2167, CWQE Phase 3). autonovel found this essential: "the model that
* evaluates must differ from the model that writes — intentionally different to
* avoid self-congratulation." A calibrated quality judge scored by the SAME model
* that drafted the text grades itself generous.
*
* A writer stage config may carry `judgeProvider` (and optional `judgeModel`).
* When set, the judge runs on that provider/model. When UNSET, the judge falls
* back to the writer stage's own resolved provider/model — a working default that
* still scores the draft, while the UI encourages the user to configure a
* different (harsher) judge model.
*
* Returns `{ provider, model }` (model may be null → provider's own default).
* The caller passes these as `providerOverride`/`modelOverride` to
* `runStagedLLM('pipeline-judge-issue', …)` so the judge PROMPT runs against the
* resolved judge provider rather than its own stage-config default.
*/
export async function resolveJudgeForStage(stage, options = {}) {
// An explicit per-call `providerOverride` is a deliberate "judge with THIS
// provider right now" demand — it beats a stage-level judge pin (mirrors how
// resolveProviderForStage lets providerOverride beat stage.provider).
//
// The stage is masked first because this one is CALLER-supplied (pipelineJudge
// / foundationJudge / seriesGenerate hand us a writer stage they read
// themselves) rather than read from `getStage` here. A run that forced one
// route loses the stage judge pin with it and falls through to the writer
// resolution below — note that this collapses the writer/judge split for that
// stage unless the run configured its own judge route, which sets
// `providerOverride` and short-circuits above.
stage = effectiveStage(stage);
if (!options.providerOverride && stage?.judgeProvider) {
const pinned = await getProviderById(stage.judgeProvider).catch(() => null);
if (pinned?.enabled) {
return { provider: pinned, model: resolveModel(pinned, stage.judgeModel || null) };
}
throw new ServerError(
`Judge provider "${stage.judgeProvider}" is not available — re-pick a judge provider in the stage settings`,
{ status: 503, code: 'STAGE_JUDGE_PROVIDER_UNAVAILABLE' }
);
}
// No judge pin (or an explicit override): default to the writer stage's own
// resolved provider/model. Reuses the exact writer-resolution precedence so the
// judge lands on the same provider the draft ran on (self-judge fallback) until
// a distinct judge is configured — the UI encourages picking a harsher model.
const provider = await resolveProviderForStage(stage, options);
const model = resolveModel(provider, resolveModelHint(stage, options));
return { provider, model };
}
/**
* Extract the first balanced object/array from an LLM response. Some
* providers prepend explanation prose; the prompt asks for JSON only but
* we have to be defensive. Walks the same fence-stripped text as
* `lib/jsonExtract` so stages benefit from string-aware brace walking +
* Codex `}}]` and trailing-comma repairs.
*
* Picks the earliest *parseable* top-level block, regardless of whether
* it's an object or array. This is the only safe heuristic given:
* - Banner lines like `[workdir, /tmp]` precede the real JSON, so
* `indexOf('[')` is a lying delimiter peek.
* - An object response may legitimately contain an inner array field
* (e.g. `{"a":[1,2]}`), and a raw walker run with `blockType: 'array'`
* would happily return that `[1,2]` if asked.
* By gathering balanced candidates for BOTH shapes, parsing each in
* source order, and returning the first that parses, banners get
* skipped (their contents don't parse as JSON) and the wrapper shape
* is preserved (`[{"a":1}]` parses as the array; `{"a":[1,2]}` parses
* as the object because the `{` opener comes before the inner `[`).
*
* When `promptToStrip` is supplied, any verbatim occurrence of that
* string is removed from `text` BEFORE walking. This handles CLI
* runners (notably Codex) that echo the input prompt to stdout — the
* prompt itself frequently contains fenced JSON schema examples that
* would otherwise parse and win on source-order ranking. Stripping
* the echo leaves only the model's actual response in the text the
* walker sees.
*/
export function extractJson(text, { promptToStrip } = {}) {
if (!text || typeof text !== 'string') throw new Error('Empty AI response');
if (typeof promptToStrip === 'string' && promptToStrip) {
// Remove every verbatim occurrence so we don't have to guess where
// a CLI runner inserted line wrapping or trim. The prompt is fixed
// text we built ourselves a few lines up — split-join is safer
// than building a regex (which would need escaping).
text = text.split(promptToStrip).join('');
}
// Trim leading + trailing fences via stripCodeFences (note: it strips
// each side independently, so a response that only has a leading
// ```json with no closing fence will still get its opener removed —
// that's intentional and matches every other JSON-from-LLM helper in
// the codebase). What we DELIBERATELY do NOT do here is grab the
// first inner ```…``` fenced block: on Codex CLI runs the prompt
// itself can echo to stdout before the model response, and many
// stage prompts contain fenced JSON schema examples that would
// precede the real answer. Walking the whole text with
// findBalancedBlocks is safer — an echoed schema either parses
// (and gets ranked by source order) or fails parse-with-repair and
// is silently skipped in favor of the real response.
const s = stripCodeFences(text.trim());
// Collect candidates of BOTH shapes with their source-text positions.
// findBalancedBlocks returns block substrings in order; indexOf gives
// us the start so we can interleave the two shape lists.
const candidates = [];
let cursor = 0;
for (const block of findBalancedBlocks(s, { startChar: '{', endChar: '}' })) {
const idx = s.indexOf(block, cursor);
candidates.push({ block, start: idx });
cursor = idx + block.length;
}
cursor = 0;
for (const block of findBalancedBlocks(s, { startChar: '[', endChar: ']' })) {
const idx = s.indexOf(block, cursor);
candidates.push({ block, start: idx });
cursor = idx + block.length;
}
candidates.sort((a, b) => a.start - b.start);
// Fall back to the raw text if neither shape walker found anything —
// the response might still be parseable JSON (e.g. a bare number or
// string literal). tryParseWithRepair handles those too.
if (!candidates.length) candidates.push({ block: s, start: 0 });
let lastError;
for (const { block } of candidates) {
const parsed = tryParseWithRepair(block);
if (!parsed.error) return parsed.value;
lastError = parsed.error;
}
// No fallback to jsonExtract.extractJson here: that helper grabs the
// first inner ```…``` fenced block, which is exactly the prompt-echo
// failure mode this implementation was rewritten to avoid. Surface
// the last parse error from the candidate loop so callers see the
// concrete reason instead of a generic "no JSON block found".
throw new Error(`Invalid JSON in AI response: ${lastError?.message || 'no JSON block found'}`);
}
/**
* Run a named stage end-to-end. Returns `{ content, model, providerId, runId }`
* (or the parsed JSON in the `content` field when `returnsJson` is true).
*
* Options:
* - providerOverride: explicit per-call provider id, beats stage.provider
* - providerDefault: blanket run-level provider id used ONLY when the stage has
* no pin of its own; loses to stage.provider and falls through to the active
* provider if unavailable (see resolveProviderForStage)
* - modelOverride: explicit model id (hard), beats everything
* - modelDefault: blanket run-level model id (Series Autopilot's run model,
* #1558). Soft: it OVERRIDES a stage's tier value (default/light/medium/heavy/ultra)
* but LOSES to a deliberate explicit-model pin (a non-tier model id) and to a
* hard modelOverride. See resolveModelHint for the full precedence — the model
* dimension is deliberately NOT symmetric with providerDefault because nearly
* every stage carries a tier value while stage.provider is opt-in.
* - effortOverride: explicit per-call reasoning effort (hard), beats a stage pin
* - effortDefault: blanket run-level reasoning effort (Series Autopilot's run
* effort, #3641). Soft: it applies only to stages with no `stage.effort` pin.
* Clamped to the provider's ladder and dropped for effort-incapable providers
* by the runner, so it is safe to pass unconditionally. See resolveEffortHint.
* - timeoutOverride: explicit ms timeout, beats stage.timeout and the provider default
* - maxTokens: API output cap, when the caller budgets an output reserve
* - callerPolicy: server-selected execution-mode policy, enforced on pins and every fallback
* - returnsJson: parse `content` via `extractJson` before returning
* - source: free-form tag persisted on the run record (e.g. 'pipeline-text-stage',
* 'writers-room-evaluate') so /runs is filterable
*/
export async function runStagedLLM(stageName, variables, options = {}) {
const stage = effectiveStage(getStage(stageName));
const prompt = await buildPrompt(stageName, variables);
return executeStagePrompt({ stage, label: stageName, prompt, options });
}
/**
* Run an INLINE (caller-supplied) prompt end-to-end — no named stage template.
* Same provider/model resolution, runner.js transcript persistence, runtime
* fallback, and JSON extraction as `runStagedLLM`, but the prompt body is passed
* directly. With no stage there is no stage-pinned provider/model/timeout, so it
* resolves to `options.providerOverride` (or the active provider). Used by
* user-defined editorial checks (#1346) whose prompt is authored from the UI.
*
* Same options as runStagedLLM (providerOverride / modelOverride /
* timeoutOverride / returnsJson / source / allowFallback). Set
* `allowFallback: false` when the caller budgeted an already-rendered prompt
* against the resolved provider and a smaller fallback could not accept it.
*/
export async function runInlineLLM(prompt, options = {}) {
if (typeof prompt !== 'string' || !prompt.trim()) {
throw new ServerError('runInlineLLM requires a non-empty prompt', { status: 400, code: 'INLINE_PROMPT_REQUIRED' });
}
return executeStagePrompt({ stage: null, label: options.source || 'inline-llm', prompt, options });
}
/**
* Run a caller-supplied (inline) prompt but resolve the provider/model/timeout
* from a NAMED STAGE's pin — not just the active/overridden provider. Use this for
* an inline helper call that SUPPORTS a stage-pinned check (e.g. a cross-chunk
* setup summary for an editorial stage pinned to a private local provider): the
* helper then runs on the SAME provider as the stage, so manuscript text is never
* silently routed to a different (e.g. cloud) provider than the stage chose. The
* prompt body is still caller-supplied (no stage template is rendered). With a
* falsy `stageName` this is identical to `runInlineLLM` (active/overridden provider).
*
* That routing guarantee is only as strong as the stage pin behind it: a run
* inside `withStagePinsIgnored` has asked for ONE provider everywhere, so this
* follows the run's provider rather than the stage's. The Autopilot Options copy
* warns at the checkbox; see lib/stagePinPolicy.js.
*
* Same options as runStagedLLM (providerOverride / modelOverride /
* timeoutOverride / returnsJson / source).
*/
export async function runStageScopedInlineLLM(stageName, prompt, options = {}) {
if (typeof prompt !== 'string' || !prompt.trim()) {
throw new ServerError('runStageScopedInlineLLM requires a non-empty prompt', { status: 400, code: 'INLINE_PROMPT_REQUIRED' });
}
const stage = stageName ? effectiveStage(getStage(stageName)) : null;
return executeStagePrompt({ stage, label: options.source || stageName || 'inline-llm', prompt, options });
}
/**
* Shared execution body for runStagedLLM / runInlineLLM. Takes an already-built
* prompt + an optional resolved stage (null for inline), resolves the provider/
* model/timeout, creates the run record, executes through the shared runner
* (with runtime fallback reconciliation), and returns
* `{ content, model, providerId, runId }`. `label` is the free-form name used in
* the log line (the stage name, or the inline source tag).
*/
async function executeStagePrompt({ stage, label, prompt, options }) {
const provider = await resolveProviderForStage(stage, options);
const resolvedModel = resolveModel(provider, resolveModelHint(stage, options));
const effectiveEffort = resolveEffortHint(stage, options);
// resolveEffectiveModel gates the override per provider type and, for
// CLI providers with a baked --model/-m flag in args, extracts the
// args-pinned model id so the run record + log line reflect what
// truly executes (rather than guessing from defaultModel, which can
// diverge from the args-baked value).
let effectiveProvider = provider;
let effectiveModel = resolveEffectiveModel(effectiveProvider, resolvedModel);
// Per-stage timeout override; timeoutOverride from the caller beats
// stage.timeout, which beats the provider default. `normalizeTimeout`
// coerces via `Number(...)` (so legacy stringified values from
// pre-validation installs still resolve), rejects non-finite or ≤0
// (so a stray "0" can't silently instant-cancel), and caps at
// STAGE_TIMEOUT_MAX_MS — applied to BOTH stage.timeout and the caller
// override, since `runPromptThroughProvider`/`executeCliRun` treat `0`
// as "no timeout" and would happily run unbounded if we forwarded a
// garbage override.
const stageTimeout = normalizeTimeout(stage?.timeout);
const overrideTimeout = normalizeTimeout(options.timeoutOverride);
const effectiveTimeout = overrideTimeout ?? stageTimeout;
// createRun may pick a fallback provider when the requested one is marked
// unavailable by providerStatusService. Capture the full result and
// reconcile, mirroring the promptRunner.js#createRun caller-runId path —
// otherwise execution would proceed against the original provider while
// /runs metadata claims the fallback ran. Pass `timeout` with a fallback
// to `provider.timeout` so the run record's persisted timeout reflects
// what executeXxxRun actually enforces (the runner falls back to
// `effectiveProvider.timeout` when no override is set — mirror that here
// so the recorded value isn't a misleading `undefined`).
const runResult = await createRun({
providerId: provider.id,
// The staged runner pre-creates records; constrain that proactive swap too.
...(options.callerPolicy ? { requestCapabilities: buildRequestCapabilities({ prompt, callerPolicy: options.callerPolicy }) } : {}),
model: effectiveModel,
prompt,
source: options.source || 'staged-llm',
effort: effectiveEffort,
allowFallback: options.allowFallback !== false,
// createRun.timeout is returned but not persisted into metadata.json
// by the toolkit (only providerId/model/source/etc. are written at
// creation time). We always patch below to record the effective
// timeout so /runs can show what executeXxxRun actually enforced.
timeout: effectiveTimeout ?? provider.timeout ?? DEFAULT_TIMEOUT_MS,
});
const { runId } = runResult;
const fellBack = runResult.provider && runResult.provider.id !== provider.id;
if (fellBack) {
effectiveProvider = runResult.provider;
// Re-resolve against the FALLBACK provider. Do NOT pass `resolvedModel` —
// that was resolved against the PRIMARY (e.g. codex's
// `codex-configured-default`) and forwarding it leaks a model id the
// fallback can't run. Prefer the configured `fallbackModel`; null falls
// through to the fallback provider's own default / args-baked model.
effectiveModel = resolveEffectiveModel(effectiveProvider, runResult.fallbackModel ?? null);
}
// Always patch metadata with the effective timeout (the toolkit doesn't
// persist `timeout` in its initial metadata.json write). On fallback we
// also patch provider id/name/model so /runs attribution matches the
// provider that actually ran. Best-effort: attribution, not load-bearing.
const recordedTimeout = effectiveTimeout ?? effectiveProvider.timeout ?? DEFAULT_TIMEOUT_MS;
const metadataPatch = { timeout: recordedTimeout, effort: effectiveEffort };
if (fellBack) {
metadataPatch.model = effectiveModel;
metadataPatch.providerId = effectiveProvider.id;
metadataPatch.providerName = effectiveProvider.name;
}
patchRunMetadata(runId, metadataPatch).catch(() => { /* best-effort */ });
console.log(`📝 stage: ${effectiveProvider.id} / ${effectiveModel || '(default)'} / ${label} → ${runId.slice(0, 8)}`);
// Stage runs pre-create the run record (so the runId can be logged BEFORE
// the LLM call starts), then thread that id through the shared runner.
// On runtime fallback (primary attempted + failed, fallback retried + won)
// `runPromptThroughProvider` ignores our pre-created `runId` and creates
// a fresh one for the fallback's record — so the successful output lives
// at `result.runId`, NOT the `runId` we passed in. The pre-created record
// stays as the failed-primary entry. Capture the post-fallback attribution
// (runId / model / providerId) here so the persisted stage result points
// at the run that actually produced the text — otherwise pipeline history
// / restore links land on a failed record.
// The local-backend concurrency gate is applied INSIDE runPromptThroughProvider
// (around each actual execution — primary, proactive swap, and runtime
// fallback), so we do NOT wrap here: a second gate on the same local endpoint
// would deadlock against the inner one (outer holds the only slot, inner waits
// forever).
const runResult2 = await runPromptThroughProvider({
provider: effectiveProvider, model: effectiveModel, prompt, source: options.source || 'staged-llm', runId,
timeout: effectiveTimeout,
maxTokens: options.maxTokens,
callerPolicy: options.callerPolicy,
// Reasoning effort (#3641). Always passed: the runner clamps it to the
// provider's ladder and omits the flag entirely for a provider with no
// effort control, so no capability check is needed here.
effort: effectiveEffort,
allowFallback: options.allowFallback !== false,
onRunCreated: options.onRunCreated,
onRunReady: options.onRunReady,
onRunSettled: options.onRunSettled,
});
const { text } = runResult2;
let finalRunId = runId;
let finalProvider = effectiveProvider;
let finalModel = effectiveModel;
if (runResult2.usedFallback && runResult2.fallbackProvider) {
finalRunId = runResult2.runId;
finalProvider = runResult2.fallbackProvider;
finalModel = runResult2.model ?? finalModel;
console.log(`⚡ stage fallback succeeded: ${finalProvider.id} / ${finalModel || '(default)'} / ${label} → ${finalRunId.slice(0, 8)}`);
}
// Codex CLI dumps the full transcript (banner + metadata + echoed prompt +
// `codex\n<reply>` + token-stats footer). Carve out the assistant reply
// before either parsing JSON or returning text. Idempotent for non-Codex
// providers — returns input unchanged when the banner isn't present.
const cleaned = extractCodexAssistant(text);
const content = options.returnsJson ? extractJson(cleaned, { promptToStrip: prompt }) : cleaned;
return { content, model: finalModel || null, providerId: finalProvider.id, runId: finalRunId,
...(runResult2.finishReason ? { finishReason: runResult2.finishReason } : {}),
};
}