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

fix: keep hosted FableLoom narration on direct API providers (#10667)

Adam Eivy16954ef6bce0
diff --git a/server/services/fableLoom/hostedSession.js b/server/services/fableLoom/hostedSession.js
index bdbf05fa19..8c5ac6f8dc 100644
--- a/server/services/fableLoom/hostedSession.js
+++ b/server/services/fableLoom/hostedSession.js
@@ -37,6 +37,7 @@ import {
import {
publicNode,
playTurn,
+ resolvePlayRoute,
} from './weave.js';
import { getUniverse } from '../universeBuilder.js';
import { parseVoiceId } from '../pipeline/audio.js';
@@ -184,11 +185,18 @@ export async function checkHostedSessionReadiness({ loomId, episodeId, loom: cus
}
}
+ // An audience token authorizes story participation, never a host harness.
+ // Keep authored narration available even if the configured narrator is unsafe.
+ const llm = await resolvePlayRoute(loom, { callerPolicy: 'direct-api' })
+ .then(() => ({ ok: true }))
+ .catch(err => ({ ok: false, error: err.message, code: err.code || 'NO_PROVIDER' }));
+ if (!llm.ok) warnings.push(`AI narrator unavailable; using authored narration: ${llm.error}`);
+
const checks = {
https: { ok: isHttps, ...(isHttps ? {} : { error: 'HTTPS required' }) },
host: { ok: !!startNode, ...(startNode ? {} : { error: 'Missing start scene' }) },
stt: { ok: sttReady },
- llm: { ok: true },
+ llm,
tts: { ok: ttsReady, voice: resolvedVoice?.voiceId || 'default' },
playback: { ok: playbackReady },
};
@@ -747,6 +755,7 @@ export async function processHostedUtterance(sessionId, {
nodeId: session.currentNodeId,
message,
signal: turn.abortController.signal,
+ callerPolicy: 'direct-api',
transcript: session.transcript.map((t) => ({
role: t.role === 'audience' ? 'reader' : 'narrator',
text: t.text,
diff --git a/server/services/fableLoom/weave.js b/server/services/fableLoom/weave.js
index b7a4b3ceb9..134c77a29a 100644
--- a/server/services/fableLoom/weave.js
+++ b/server/services/fableLoom/weave.js
@@ -15,7 +15,7 @@
import { randomUUID } from 'crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { startAIOp } from '../aiStatusEvents.js';
-import { runStagedLLM } from '../stageRunner.js';
+import { resolveStageRoute, runStagedLLM } from '../stageRunner.js';
import { resolveLlmRoutePin } from '../../lib/llmRoutePin.js';
import { renderStoryCanonDigest } from '../../lib/universePromptRenderers.js';
import { renderCharacterEvolutionListForPrompt } from '../../lib/characterEvolution.js';
@@ -137,6 +137,11 @@ const runLoomAi = (stage, variables, route, {
*/
const playRouting = (loom, perCall) => resolveLlmRoutePin(loom.playSettings, perCall);
+/** Resolve narrator eligibility without a provider call, using play's exact pins. */
+export const resolvePlayRoute = (loom, { callerPolicy } = {}) => resolveStageRoute(
+ 'fableloom-play-turn', { ...llmOptions(playRouting(loom), 'fableloom-play'), callerPolicy },
+);
+
/**
* Render the linked universe's canon as a prompt digest via the shared
* composer (field precedence, per-kind caps, the "+ N more" truncation footer,
@@ -1274,7 +1279,7 @@ const transcriptDigest = (transcript) =>
* and an abort landing inside it means the provider call is never made.
*/
export async function playTurn(loomId, episodeId, {
- nodeId, message, transitionId, transcript = [], providerId, model, effort, signal,
+ nodeId, message, transitionId, transcript = [], providerId, model, effort, signal, callerPolicy,
} = {}) {
const loom = await requireLoom(loomId);
const episode = findEpisode(loom, episodeId);
@@ -1326,7 +1331,7 @@ export async function playTurn(loomId, episodeId, {
transcriptDigest: transcriptDigest(transcript) || '(start of the read-through)',
readerMessage: trimTo(message, 1000),
narrationFormatContract: narrationFormatContract(loom.format),
- }, llmOptions(playRouting(loom, { providerId, model, effort }), 'fableloom-play'));
+ }, { ...llmOptions(playRouting(loom, { providerId, model, effort }), 'fableloom-play'), callerPolicy });
const narration = trimTo(content?.narration, 4000);
const chosen = content?.action === 'move'
diff --git a/server/services/promptRunner.test.js b/server/services/promptRunner.test.js
index db50a402e3..0252cd0573 100644
--- a/server/services/promptRunner.test.js
+++ b/server/services/promptRunner.test.js
@@ -1,5 +1,8 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// Usage-limit tests exercise routing, not the install's persisted usage ledger.
+vi.mock('./usage.js', () => ({ recordLimitBlock: vi.fn().mockResolvedValue(undefined) }));
+
vi.mock('./runner.js', () => ({
createRun: vi.fn(),
executeApiRun: vi.fn(),
diff --git a/server/services/stageRunner.js b/server/services/stageRunner.js
index f24948d64d..c8471bbd19 100644
--- a/server/services/stageRunner.js
+++ b/server/services/stageRunner.js
@@ -14,10 +14,11 @@
* 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 { resolveEffectiveModel, runPromptThroughProvider, DEFAULT_TIMEOUT_MS, isLocalEndpoint, withObservedContextWindowsLazy } from './promptRunner.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';
@@ -305,10 +306,17 @@ export async function resolveStageContext(stageName, options = {}) {
// 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 } = {}) {
+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 pinned;
+ if (pinned?.enabled) return permitted(pinned);
throw new ServerError(
`Requested provider "${providerOverride}" is not available`,
{ status: 503, code: 'PROVIDER_OVERRIDE_UNAVAILABLE' }
@@ -316,7 +324,7 @@ async function resolveProviderForStage(stage, { providerOverride, providerDefaul
}
if (stage?.provider) {
const pinned = await getProviderById(stage.provider).catch(() => null);
- if (pinned?.enabled) return pinned;
+ 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' }
@@ -324,12 +332,12 @@ async function resolveProviderForStage(stage, { providerOverride, providerDefaul
}
if (providerDefault) {
const fallback = await getProviderById(providerDefault).catch(() => null);
- if (fallback?.enabled) return fallback;
+ 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 active;
+ if (active?.enabled) return permitted(active);
throw new ServerError('No AI provider available', { status: 503, code: 'NO_PROVIDER' });
}
@@ -496,6 +504,7 @@ export function extractJson(text, { promptToStrip } = {}) {
* 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
@@ -596,6 +605,8 @@ async function executeStagePrompt({ stage, label, prompt, options }) {
// 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',
@@ -651,6 +662,7 @@ async function executeStagePrompt({ stage, label, prompt, options }) {
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.
diff --git a/server/sockets/fableLoomHosted.test.js b/server/sockets/fableLoomHosted.test.js
index e133e4d61d..30101162e5 100644
--- a/server/sockets/fableLoomHosted.test.js
+++ b/server/sockets/fableLoomHosted.test.js
@@ -16,6 +16,13 @@ import * as weave from '../services/fableLoom/weave.js';
import * as networkExposure from '../lib/networkExposure.js';
import * as tts from '../services/voice/tts.js';
import * as stt from '../services/voice/stt.js';
+import * as providers from '../services/providers.js';
+import * as prompts from '../services/promptService.js';
+import * as runner from '../services/runner.js';
+import * as toolkitState from '../lib/aiToolkitState.js';
+import * as autoFixer from '../services/autoFixer.js';
+import * as tuiRunner from '../services/tuiPromptRunner.js';
+import { createProviderStatusService } from '../lib/aiToolkit/providerStatus.js';
describe('fableLoomHosted Socket.IO namespace', () => {
const mockLoom = {
@@ -36,7 +43,7 @@ describe('fableLoomHosted Socket.IO namespace', () => {
protagonistPresence: 'offscreen',
isEnding: false,
playbackAssets: { holdLoopVideoHistoryIds: ['vid-1'] },
- transitions: [{ id: 'tr-1', targetNodeId: 'node-2', intent: 'go next' }],
+ transitions: [{ id: 'tr-1', targetNodeId: 'node-2', intent: 'go next', triggers: [] }],
}, {
id: 'node-2',
title: 'Next',
@@ -137,6 +144,124 @@ describe('fableLoomHosted Socket.IO namespace', () => {
expect(connectionHandler).toBeDefined();
});
+ describe('audience narrator execution boundary', () => {
+ const api = { id: 'narrator-api', name: 'Narrator API', type: 'api', enabled: true, defaultModel: 'example-model' };
+ const cli = { id: 'narrator-cli', name: 'Narrator CLI', type: 'cli', enabled: true };
+ const tui = { id: 'narrator-tui', name: 'Narrator TUI', type: 'tui', enabled: true };
+ let selected;
+ let playStage;
+ let loom;
+ let status;
+
+ beforeEach(() => {
+ selected = api;
+ playStage = {};
+ loom = structuredClone(mockLoom);
+ records.getLoom.mockImplementation(async () => loom);
+ vi.spyOn(providers, 'getActiveProvider').mockImplementation(async () => selected);
+ vi.spyOn(providers, 'getProviderById').mockImplementation(async id => [api, cli, tui].find(p => p.id === id));
+ vi.spyOn(providers, 'getAllProviders').mockImplementation(async () => ({ providers: [selected, cli, tui] }));
+ vi.spyOn(prompts, 'getStage').mockImplementation(() => playStage);
+ vi.spyOn(prompts, 'buildPrompt').mockResolvedValue('Synthetic audience request');
+ vi.spyOn(runner, 'createRun').mockResolvedValue({ runId: 'guest-run' });
+ vi.spyOn(runner, 'patchRunMetadata').mockResolvedValue();
+ vi.spyOn(runner, 'executeApiRun').mockImplementation(async ({ onData, onComplete }) => {
+ onData(JSON.stringify({ action: 'stay', narration: 'API narration.' }));
+ onComplete({ success: true });
+ });
+ vi.spyOn(runner, 'executeCliRun').mockImplementation(() => { throw new Error('Forbidden CLI dispatch'); });
+ vi.spyOn(tuiRunner, 'executeTuiRun').mockImplementation(() => { throw new Error('Forbidden TUI dispatch'); });
+ // Use the production fallback selector, with persistence/health writes stubbed.
+ status = createProviderStatusService({ defaultFallbackPriority: [cli.id, tui.id] });
+ vi.spyOn(status, 'markUnavailable').mockResolvedValue();
+ vi.spyOn(status, 'getFallbackProvider');
+ vi.spyOn(toolkitState, 'getAIToolkitInstance').mockReturnValue({ services: { providerStatus: status } });
+ for (const name of ['noteFallbackStarted', 'noteFallbackHandled', 'noteFallbackFailed', 'escalateProviderFailure']) {
+ vi.spyOn(autoFixer, name).mockResolvedValue();
+ }
+ });
+
+ async function guestTurn(input) {
+ const { session, token, preflight } = await createHostedSession('loom-1', 'ep-1');
+ const audience = makeSocket({ role: 'audience', sessionId: session.id });
+ audience.handshake = { auth: { role: 'audience', sessionId: session.id, token } };
+ const next = vi.fn();
+ await middleware(audience, next);
+ expect(next).toHaveBeenCalledWith();
+ connectionHandler(audience);
+ await audience.listeners['hosted:mic:start']();
+ if (input === 'audio') await audience.listeners['hosted:mic:stop'](Buffer.from('synthetic audio'));
+ else await audience.listeners['hosted:turn:text']({ text: 'go next', callerPolicy: 'any-text', providerId: cli.id });
+ expect(runner.executeCliRun).not.toHaveBeenCalled();
+ expect(tuiRunner.executeTuiRun).not.toHaveBeenCalled();
+ return { preflight, session: getHostedSession(session.id) };
+ }
+
+ it.each([
+ ['play', 'text', cli], ['stage', 'audio', tui], ['active', 'text', tui],
+ ])('refuses %s process pins through authenticated %s turns', async (pin, input, provider) => {
+ if (pin === 'play') loom.playSettings = { providerId: provider.id };
+ if (pin === 'stage') playStage = { provider: provider.id };
+ if (pin === 'active') selected = provider;
+ const { preflight, session } = await guestTurn(input);
+ expect(preflight.checks.llm).toMatchObject({ ok: false, code: 'PROVIDER_MODE_NOT_PERMITTED' });
+ expect(session.transcript.at(-1).text).toBe('Opening prose');
+ expect(runner.createRun).not.toHaveBeenCalled();
+ expect(runner.executeApiRun).not.toHaveBeenCalled();
+ if (input === 'audio') expect(stt.transcribe).toHaveBeenCalled();
+ });
+
+ it.each(['text', 'audio'])('narrates %s with an API and carries the policy into proactive selection', async input => {
+ const { preflight, session } = await guestTurn(input);
+ expect(preflight.checks.llm.ok).toBe(true);
+ expect(session.transcript.at(-1).text).toBe('API narration.');
+ expect(runner.createRun).toHaveBeenCalledWith(expect.objectContaining({
+ requestCapabilities: expect.objectContaining({ allowedModes: ['api'] }),
+ }));
+ expect(runner.executeApiRun).toHaveBeenCalledTimes(1);
+ });
+
+ it('refuses proactive process substitution and retains authored narration', async () => {
+ selected = { ...api, fallbackProvider: cli.id };
+ runner.createRun.mockImplementation(async ({ requestCapabilities }) => {
+ const fallback = status.getFallbackProvider(selected.id, { [selected.id]: selected, [cli.id]: cli, [tui.id]: tui }, null, null, requestCapabilities);
+ if (!fallback) throw new Error('No eligible narrator fallback');
+ return { runId: 'fallback-run', provider: fallback.provider };
+ });
+ const { session } = await guestTurn('text');
+ expect(session.transcript.at(-1).text).toBe('Opening prose');
+ expect(runner.executeApiRun).not.toHaveBeenCalled();
+ });
+
+ it('keeps API failure recovery off configured and priority process fallbacks', async () => {
+ selected = { ...api, fallbackProvider: cli.id };
+ runner.executeApiRun.mockImplementation(async ({ onComplete }) => onComplete({ success: false, error: 'Synthetic narrator unavailable' }));
+ const { session } = await guestTurn('audio');
+ expect(session.transcript.at(-1).text).toBe('Opening prose');
+ expect(status.getFallbackProvider).toHaveBeenCalledWith(selected.id, expect.any(Object), null, null,
+ expect.objectContaining({ allowedModes: ['api'] }));
+ });
+
+ it('preserves process narration for operator play calls without the guest policy', async () => {
+ selected = cli;
+ runner.executeCliRun.mockImplementation(async ({ onData, onComplete }) => {
+ onData(JSON.stringify({ action: 'stay', narration: 'Operator narration.' }));
+ onComplete({ success: true });
+ });
+ const result = await weave.playTurn('loom-1', 'ep-1', { nodeId: 'node-1', message: 'go next' });
+ expect(result.narration).toBe('Operator narration.');
+ expect(runner.executeCliRun).toHaveBeenCalledTimes(1);
+ expect(runner.createRun.mock.calls[0][0].requestCapabilities).toBeUndefined();
+ });
+
+ it('keeps tapped transitions deterministic with a process narrator configured', async () => {
+ selected = cli;
+ const result = await weave.playTurn('loom-1', 'ep-1', { nodeId: 'node-1', transitionId: 'tr-1', callerPolicy: 'direct-api' });
+ expect(result).toMatchObject({ action: 'move', resolvedBy: 'choice', node: { id: 'node-2' } });
+ expect(runner.createRun).not.toHaveBeenCalled();
+ });
+ });
+
describe('handshake auth middleware', () => {
it('rejects connection without sessionId', async () => {
const socket = { handshake: { auth: {} } };