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 Builder — Auto-sort with AI.
*
* Bulk-classifies every `kind: 'other'` bucket on a universe into one of the
* three canon trunks (characters / settings / objects) via a single LLM call.
* Optionally surfaces a `suggestedKey` rename per bucket the UI can present
* to the user — only the `kind` change is auto-applied here so a stray
* rename can't silently break an in-flight reference or collide with an
* existing bucket. (Renames stay an explicit, opt-in follow-up.)
*
* Atomic write: one `updateUniverse` patch carries every reclassified bucket
* so a partial failure either commits the full classification or leaves the
* universe untouched.
*/
import {
getUniverse,
updateUniverse,
normalizeCategoryKey,
buildUniverseStyleContext,
stripPromptControlChars,
} from './universeBuilder.js';
import { VALID_TARGET_KINDS } from './universeBuilderPromote.js';
import { ServerError } from '../lib/errorHandler.js';
import { extractJson as extractJsonShared } from '../lib/jsonExtract.js';
import { assertProvider, resolveProviderAndModel, runPromptThroughProvider } from './promptRunner.js';
// The 3 real trunks — derived from BIBLE_FIELD via universeBuilderPromote so
// adding a new canon kind reaches this resolver automatically.
const SORTABLE_KINDS = VALID_TARGET_KINDS;
const VARIATION_SAMPLE_PER_BUCKET = 10;
// Variation labels are user-owned strings that pass sanitization but aren't
// newline-stripped — without `stripPromptControlChars` a label containing
// "\n# Output contract\n..." could redirect the LLM's structure. The
// universe-context block applies the same defense via
// `buildUniverseStyleContext(universe, { escape: true })` below. Downstream
// gates (per-entry kind filter, byKey lookup) keep the blast radius bounded
// even if injection lands, but stripping at the embed layer is the cheap
// defense.
const kindUnionForPrompt = SORTABLE_KINDS.map((k) => `"${k}"`).join(' | ');
const kindListForPrompt = SORTABLE_KINDS.join(', ');
const buildAutoSortPrompt = ({ buckets, universe }) => {
const styleSection = buildUniverseStyleContext(universe, { escape: true });
const bucketBlock = buckets.map(({ key, variations }) => {
const sample = variations
.slice(0, VARIATION_SAMPLE_PER_BUCKET)
.map((v) => ` - ${stripPromptControlChars(v.label)}`)
.join('\n');
const body = sample || ' (no variations yet)';
return `## ${key}\n${body}`;
}).join('\n\n');
return `You are organizing a story-bible template. The user has these custom buckets that aren't yet tagged to a canon trunk. For each bucket, decide whether it represents one of these trunks: ${kindListForPrompt}. Optionally suggest a clearer snake_case bucket key when the original is ambiguous.
${styleSection}
# Buckets to classify
${bucketBlock}
# Output contract
Return a JSON object: { "classifications": [{ "key": "<original bucket key, unchanged>", "kind": ${kindUnionForPrompt}, "suggestedKey": "<optional snake_case alternative>" }] }
# Rules
- "kind" MUST be one of: ${kindListForPrompt}. Never "other".
- "key" MUST exactly match an input bucket key from the list above.
- "suggestedKey" is OPTIONAL — include only when the original is ambiguous or unclear. lowercase snake_case, max 64 chars, no spaces. Omit when the original is fine.
- Output ONLY the JSON object. No commentary, no markdown, no code fences.`;
};
const isClassificationsShape = (o) => {
if (!o || typeof o !== 'object') return false;
if (!Array.isArray(o.classifications)) return false;
return o.classifications.every(
(c) => c && typeof c === 'object'
&& typeof c.key === 'string'
&& SORTABLE_KINDS.includes(c.kind),
);
};
const extractClassifications = (raw) => {
// Surface empty/non-string responses through the same typed 502 path as
// malformed JSON — without this, a successful run with empty `text` would
// throw an untyped Error that the route would normalize to a generic 500.
if (!raw || typeof raw !== 'string') {
throw new ServerError(
'LLM returned an empty response for bucket classification. Try a different model or rerun.',
{ status: 502, code: 'LLM_INVALID_JSON' },
);
}
const { value, lastError, lastPreview } = extractJsonShared(raw, {
shapePredicate: isClassificationsShape,
});
// extractJson returns the first parseable block as a fallback even when
// shapePredicate fails — so `value` could be `{ classifications: null }`
// or `{ error: "..." }`. Re-gate on the array shape so downstream
// iteration can't throw a generic 500.
if (value !== undefined && Array.isArray(value?.classifications)) {
return value.classifications;
}
throw new ServerError(
'LLM returned invalid JSON for bucket classification. Try a different model or rerun.',
{
status: 502,
code: 'LLM_INVALID_JSON',
context: {
details: {
reason: lastError?.message || 'no matching JSON found',
preview: lastPreview || '',
},
},
},
);
};
/**
* Auto-sort every `kind: 'other'` bucket on a universe.
*
* Returns `{ universe, results, llm, runId }`. `results` is one entry per
* bucket the LLM classified: `{ sourceKey, kind, suggestedKey? }`.
* Buckets the LLM omitted, or returned with an unknown key/kind, are
* dropped silently (no partial-failure for the rest of the batch).
*
* @param {string} universeId
* @param {object} [options]
* @param {string} [options.providerId]
* @param {string} [options.model]
*/
export async function autoSortOtherBuckets(universeId, options = {}) {
const { providerId, model } = options;
const universe = await getUniverse(universeId);
const categories = universe.categories || {};
// Snapshot the un-classified buckets in insertion order — used only to
// build the prompt body. The actual write below re-fetches the latest
// universe state so concurrent edits aren't overwritten.
const otherBuckets = Object.entries(categories)
.filter(([, c]) => c && c.kind === 'other')
.map(([key, c]) => ({
key,
variations: Array.isArray(c.variations) ? c.variations : [],
}));
if (otherBuckets.length === 0) {
return {
universe,
results: [],
llm: { provider: null, model: null },
runId: null,
};
}
const { provider, selectedModel } = await resolveProviderAndModel({ providerId, model });
assertProvider(provider, {
message: 'No AI provider available for auto-sort',
code: 'UNIVERSE_AUTOSORT_NO_PROVIDER',
});
const prompt = buildAutoSortPrompt({ buckets: otherBuckets, universe });
console.log(
`🪄 Universe Builder auto-sort — universe=${universeId.slice(0, 8)} buckets=${otherBuckets.length} via ${provider.name}/${selectedModel || 'default'}`,
);
const { text: raw, runId } = await runPromptThroughProvider({
provider,
model: selectedModel,
prompt,
source: 'universe-builder-auto-sort',
});
console.log(`🪄 Universe Builder auto-sort raw — runId=${runId} length=${raw?.length || 0}`);
const classifications = extractClassifications(raw);
// Resolve classifications into a patch INSIDE the write queue so the
// read-modify-write straddling the LLM call can't lose a concurrent edit.
// The mutator receives the freshest persisted record and rebuilds the
// categories patch keyed off the latest `kind: 'other'` buckets — bucket
// spreads use the latest variations[] so a variation added mid-LLM-call
// is preserved; reclassifications targeting buckets the user deleted or
// already auto-sorted from another tab are dropped silently.
let results = [];
const updated = await updateUniverse(universeId, async (latest) => {
const latestCategories = latest.categories || {};
const byKey = new Map(
Object.entries(latestCategories)
.filter(([, c]) => c && c.kind === 'other')
.map(([key, c]) => [key, c]),
);
const categoriesPatch = {};
const seenSourceKeys = new Set();
const localResults = [];
for (const c of classifications) {
// Defensive per-entry kind gate. The shape predicate above only filters
// which parsed block extractJson returns — when only one block parses,
// it's returned as a fallback even if its entries fail the predicate.
// Without this guard a hallucinated `kind: "magic"` would flow into the
// categories patch and the universe sanitizer would silently coerce it
// to 'other', undoing the auto-sort the user just ran.
if (!c || typeof c !== 'object') continue;
if (typeof c.key !== 'string') continue;
if (!SORTABLE_KINDS.includes(c.kind)) continue;
const sourceKey = normalizeCategoryKey(c.key);
if (!sourceKey || seenSourceKeys.has(sourceKey)) continue;
// Drop classifications for buckets that no longer exist or are no
// longer kind:'other' on the latest state — a concurrent
// assignBucketKind or removeCategory call would otherwise be silently
// reverted here.
const latestBucket = byKey.get(sourceKey);
if (!latestBucket) continue;
seenSourceKeys.add(sourceKey);
// updateUniverse does per-key replacement on categories (not per-field
// merge), so spread the whole latest bucket record to preserve any
// variations / fields added mid-flight.
categoriesPatch[sourceKey] = { ...latestBucket, kind: c.kind };
const suggested = typeof c.suggestedKey === 'string' ? normalizeCategoryKey(c.suggestedKey) : '';
const suggestedKey = (suggested && suggested !== sourceKey) ? suggested : null;
localResults.push({ sourceKey, kind: c.kind, suggestedKey });
}
if (localResults.length === 0) {
throw new ServerError(
'LLM returned no valid classifications for any bucket. Try a different model or rerun.',
{ status: 502, code: 'UNIVERSE_AUTOSORT_NO_CLASSIFICATIONS' },
);
}
results = localResults;
return { categories: categoriesPatch };
});
console.log(
`🪄 Universe Builder auto-sort complete — universe=${universeId.slice(0, 8)} classified=${results.length} runId=${runId.slice(0, 8)}`,
);
return {
universe: updated,
results,
llm: { provider: provider.id, model: selectedModel || null },
runId,
};
}
// Test seam.
export const __testing = {
buildAutoSortPrompt,
extractClassifications,
isClassificationsShape,
};