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
/**
* Universe cast integrity — the review and repair half of #6415.
*
* Three operations over one contract (`server/lib/characterIntegrity.js`):
*
* 1. `getUniverseCastIntegrity` — the DETERMINISTIC pass. Zero provider
* calls, so a page load may run it. It also reports the `reviewScope`:
* the provider, model and character count a semantic review WOULD spend,
* resolved without executing anything, so the UI can name the cost before
* the user opts in (AGENTS.md: no cold-bootstrap LLM calls).
* 2. `reviewUniverseCast` — the SEMANTIC pass, only ever from an explicit
* user action. One call per batch; the model's findings are validated back
* into the contract, and characters the batch didn't reach are reported
* `truncated` rather than silently passing.
* 3. `proposeCharacterAugmentation` / `applyCharacterAugmentation` — the
* augment-POPULATED-fields action the existing expand deliberately can't
* do. Propose writes NOTHING and returns before/after per field; apply
* takes back only the paths the user selected. Both are thin wrappers over
* `characterAugmentation.js`, which Writers Room shares (#6417) — this
* module contributes only the universe read/write.
*
* Reports are derived, never stored, so "invalidate stale reports on relevant
* edits" is a fingerprint comparison rather than a cache: `applyCharacterAugmentation`
* refuses a proposal whose character changed underneath it (409), the same way
* the expand runner re-derives its merge inside the write queue.
*/
import { getUniverse, updateUniverse } from './universeBuilder.js';
import { runPromptRefineRaw } from './pipeline/refineHelpers.js';
import { resolveStageRoute } from './stageRunner.js';
import { ServerError } from '../lib/errorHandler.js';
import { shortId } from '../lib/fileUtils.js';
import {
acceptedAugmentFields,
applyAugmentationToCharacter,
augmentationIsStale,
characterForReview,
noAugmentSelectionError,
proposeAugmentation,
staleAugmentError,
} from './characterAugmentation.js';
import {
buildCastIntegrityReport,
characterFingerprint,
mergeSemanticFindings,
} from '../lib/characterIntegrity.js';
import { INTEGRITY_DIMENSIONS } from '../lib/characterIntegrityVocabulary.js';
const REVIEW_STAGE = 'universe-cast-integrity-review';
/**
* How many characters one semantic review call covers. A cast larger than this
* is reviewed in a bounded batch and the remainder is reported `truncated` —
* the alternative (silently fanning out N provider calls from one click) is
* exactly the runaway spend AGENTS.md forbids.
*/
export const CAST_REVIEW_BATCH_MAX = 12;
const notFound = (entryId) => new ServerError(`Character ${entryId} not found in universe`, {
status: 404, code: 'UNIVERSE_CANON_NOT_FOUND',
});
const castOf = (universe) => (Array.isArray(universe?.characters) ? universe.characters.filter((c) => c?.id) : []);
/**
* Ids the caller asked about, narrowed to ids that actually exist. `null` (the
* default) means the whole cast — distinct from `[]`, which is an explicit
* empty selection and reviews nobody.
*/
const resolveScopeIds = (cast, characterIds) => {
if (!Array.isArray(characterIds)) return cast.map((c) => c.id);
const live = new Set(cast.map((c) => c.id));
return characterIds.filter((id) => live.has(id));
};
/**
* The deterministic report plus the cost of the semantic review that would
* follow. Makes NO provider call and no network call: `resolveStageRoute` only resolves which
* provider/model the stage would use.
*/
export async function getUniverseCastIntegrity(universeId, { characterIds = null } = {}) {
const universe = await getUniverse(universeId);
const cast = castOf(universe);
const scopeIds = resolveScopeIds(cast, characterIds);
const report = buildCastIntegrityReport(cast, { characterIds: scopeIds });
// Best-effort: a universe with no provider configured yet must still be able
// to render its deterministic report, so a resolution failure degrades to an
// unnamed scope rather than failing the whole request.
const resolved = await resolveStageRoute(REVIEW_STAGE).catch(() => null);
return {
...report,
reviewScope: {
characterIds: scopeIds.slice(0, CAST_REVIEW_BATCH_MAX),
characterCount: Math.min(scopeIds.length, CAST_REVIEW_BATCH_MAX),
// What the batch cap leaves for a second pass — surfaced so "review the
// cast" never looks like it covered more than it did.
remainingCount: Math.max(scopeIds.length - CAST_REVIEW_BATCH_MAX, 0),
batchMax: CAST_REVIEW_BATCH_MAX,
providerId: resolved?.provider?.id || null,
providerName: resolved?.provider?.name || null,
model: resolved?.model || null,
},
};
}
/**
* Run the semantic review over a bounded batch. Explicit user action only.
*/
export async function reviewUniverseCast(universeId, { characterIds = null, providerId, model } = {}) {
const universe = await getUniverse(universeId);
const cast = castOf(universe);
const scopeIds = resolveScopeIds(cast, characterIds);
if (scopeIds.length === 0) {
throw new ServerError('No characters selected for review', {
status: 400, code: 'UNIVERSE_CAST_REVIEW_EMPTY',
});
}
const batchIds = scopeIds.slice(0, CAST_REVIEW_BATCH_MAX);
const truncated = scopeIds.length > batchIds.length;
const batch = cast.filter((c) => batchIds.includes(c.id));
const { content, rationale, runId, providerId: usedProvider, model: usedModel } = await runPromptRefineRaw({
templateName: REVIEW_STAGE,
variables: {
castJson: JSON.stringify(batch.map(characterForReview), null, 2),
dimensionsJson: JSON.stringify(INTEGRITY_DIMENSIONS, null, 2),
},
options: { providerId, model },
source: REVIEW_STAGE,
logTag: null,
emptyError: {
code: 'UNIVERSE_CAST_REVIEW_EMPTY_RESPONSE',
message: 'LLM returned an empty cast integrity review',
},
});
const base = buildCastIntegrityReport(cast, { characterIds: scopeIds });
const report = mergeSemanticFindings(base, {
characters: cast,
findings: Array.isArray(content.findings) ? content.findings : [],
reviewedIds: batchIds,
truncated,
});
console.log(`🧭 Cast integrity review — universe=${shortId(universeId)} reviewed=${batchIds.length} findings=${report.findings.length} runId=${shortId(runId)}`);
return {
...report,
rationale,
runId,
truncated,
reviewScope: {
characterIds: batchIds,
characterCount: batchIds.length,
remainingCount: scopeIds.length - batchIds.length,
batchMax: CAST_REVIEW_BATCH_MAX,
providerId: usedProvider || null,
providerName: null,
model: usedModel || null,
},
};
}
/**
* Propose sharper values for POPULATED fields of one universe character.
* Storage is all this layer adds — the call, the field filtering and the
* fingerprint live in `characterAugmentation.js`, shared with Writers Room.
*/
export async function proposeCharacterAugmentation(universeId, entryId, {
fields, providerId, model,
} = {}) {
const universe = await getUniverse(universeId);
const cast = castOf(universe);
const target = cast.find((c) => c.id === entryId);
if (!target) throw notFound(entryId);
return proposeAugmentation({
entry: target,
peers: cast.filter((c) => c.id !== entryId),
fields,
providerId,
model,
});
}
/**
* Apply the subset of a proposal the author accepted.
*
* Refuses — rather than silently overwriting — when the character was locked,
* deleted, or edited since the proposal was generated. All three are checked
* INSIDE the write queue against the freshest record, for the same reason the
* expand runner re-derives its merge there.
*/
export async function applyCharacterAugmentation(universeId, entryId, { fields = [], fingerprint } = {}) {
const accepted = acceptedAugmentFields(fields);
if (accepted.length === 0) throw noAugmentSelectionError();
let outcome = { locked: false, stale: false, missing: false, appliedFields: [] };
const updated = await updateUniverse(universeId, (latest) => {
const list = Array.isArray(latest.characters) ? latest.characters : [];
const idx = list.findIndex((c) => c.id === entryId);
if (idx < 0) {
outcome = { ...outcome, missing: true };
return null;
}
const current = list[idx];
if (current.locked === true) {
outcome = { ...outcome, locked: true };
return null;
}
if (augmentationIsStale(current, fingerprint)) {
outcome = { ...outcome, stale: true };
return null;
}
const { next, appliedFields } = applyAugmentationToCharacter(current, accepted);
outcome = { ...outcome, appliedFields };
return { characters: list.map((c, i) => (i === idx ? next : c)) };
});
if (outcome.missing) throw notFound(entryId);
if (outcome.stale) throw staleAugmentError();
const universe = updated || await getUniverse(universeId);
const entry = castOf(universe).find((c) => c.id === entryId) || null;
if (outcome.locked) return { locked: true, entry, universe, appliedFields: [] };
console.log(`🩹 Character augment applied — universe=${shortId(universeId)} entry=${shortId(entryId)} fields=${outcome.appliedFields.length}`);
return {
universe,
entry,
appliedFields: outcome.appliedFields,
fingerprint: entry ? characterFingerprint(entry) : null,
};
}