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
import { z } from 'zod';
import { partialWithoutDefaults, optionalBooleanMap } from './zodCompat.js';
import { REPO_INTAKE_KEYS } from './repoIntakeActions.js';
import { EFFORT_LEVELS } from './providerModels.js';
import { canonicalThreadRefKind } from './threadRefKinds.js';
import { THREAD_STATUSES, THREAD_PRIORITIES } from './brainThreads.js';
import { MAX_QUALITY } from './spacedRepetition.js';
// Destination enum. `links` is reachable only from the bare-URL capture
// short-circuit (a pasted URL is filed straight to the links collection) — the
// classifier never picks it and the manual resolve/fix paths exclude it, since
// filing an arbitrary note as a bookmark needs a URL it doesn't have.
export const destinationEnum = z.enum(['people', 'projects', 'ideas', 'admin', 'memories', 'links', 'unknown']);
// Destinations the classifier may pick — everything but `links`, which needs a
// URL no model extracted. A hallucinated one falls to needs_review instead of
// reaching fileToDestination.
export const classifierDestinationEnum = destinationEnum.exclude(['links']);
// Destinations a user can file to by hand from the inbox (see fileToDestination).
export const manualDestinationEnum = classifierDestinationEnum.exclude(['unknown']);
// Project status enum
export const projectStatusEnum = z.enum(['active', 'waiting', 'blocked', 'someday', 'done']);
// Idea status enum
export const ideaStatusEnum = z.enum(['active', 'done']);
// Admin status enum
export const adminStatusEnum = z.enum(['open', 'waiting', 'done']);
// Inbox log status enum
export const inboxStatusEnum = z.enum(['classifying', 'filed', 'needs_review', 'corrected', 'done', 'error']);
// AI configuration schema
export const aiConfigSchema = z.object({
providerId: z.string(),
modelId: z.string(),
promptTemplateId: z.string(),
temperature: z.number().min(0).max(2).optional(),
maxTokens: z.number().int().positive().optional()
});
// Classification result schema
export const classificationSchema = z.object({
destination: destinationEnum,
confidence: z.number().min(0).max(1),
title: z.string().min(1).max(200),
cleanedUp: z.string().max(10000).optional(),
thoughts: z.string().max(2000).optional(),
extracted: z.record(z.unknown()),
reasons: z.array(z.string()).max(5).optional()
});
// Filed info schema
export const filedSchema = z.object({
destination: destinationEnum.exclude(['unknown']),
destinationId: z.string().guid()
});
// Correction schema
export const correctionSchema = z.object({
correctedAt: z.string().datetime(),
previousDestination: destinationEnum,
newDestination: manualDestinationEnum,
note: z.string().max(500).optional()
});
// Error schema
export const errorSchema = z.object({
message: z.string(),
stack: z.string().optional()
});
// Inbox Log Record schema
export const inboxLogRecordSchema = z.object({
id: z.string().guid(),
capturedText: z.string().min(1).max(10000),
capturedAt: z.string().datetime(),
source: z.literal('brain_ui'),
ai: aiConfigSchema.optional(),
classification: classificationSchema.optional(),
status: inboxStatusEnum,
filed: filedSchema.optional(),
correction: correctionSchema.optional(),
error: errorSchema.optional(),
// User-marked creative note (see captureInputSchema.creative). Drives the
// "Send creative notes to Catalog" batch action in the inbox.
creative: z.boolean().optional(),
// ISO timestamp stamped once this creative note's catalog ingest COMMITS
// (not on mere navigation). Drives the inbox's "already consumed" filter so a
// batch-sent note drops out of the "ready to become ingredients" banner and
// can't be accidentally re-sent. Absent ⇒ still re-sendable.
sentToCatalogAt: z.string().datetime().optional()
});
// People Record schema
export const peopleRecordSchema = z.object({
id: z.string().guid(),
name: z.string().min(1).max(200),
context: z.string().max(2000).optional().default(''),
followUps: z.array(z.string().max(500)).optional().default([]),
lastTouched: z.string().datetime().optional(),
tags: z.array(z.string().max(50)).optional().default([]),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime()
});
// Project Record schema
export const projectRecordSchema = z.object({
id: z.string().guid(),
name: z.string().min(1).max(200),
status: projectStatusEnum,
nextAction: z.string().min(1).max(500),
notes: z.string().max(5000).optional(),
tags: z.array(z.string().max(50)).optional().default([]),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime()
});
// Idea Record schema
export const ideaRecordSchema = z.object({
id: z.string().guid(),
title: z.string().min(1).max(200),
status: ideaStatusEnum.default('active'),
oneLiner: z.string().min(1).max(500),
notes: z.string().max(5000).optional(),
tags: z.array(z.string().max(50)).optional().default([]),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime()
});
// Admin Record schema
export const adminRecordSchema = z.object({
id: z.string().guid(),
title: z.string().min(1).max(200),
status: adminStatusEnum,
dueDate: z.string().datetime().optional(),
nextAction: z.string().max(500).optional(),
notes: z.string().max(5000).optional(),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime()
});
// Meta/Settings schema
export const brainSettingsSchema = z.object({
version: z.number().int().positive().default(1),
confidenceThreshold: z.number().min(0).max(1).default(0.6),
dailyDigestTime: z.string().regex(/^\d{2}:\d{2}$/).default('00:00'),
weeklyReviewTime: z.string().regex(/^\d{2}:\d{2}$/).default('00:00'),
weeklyReviewDay: z.enum(['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']).default('sunday'),
defaultProvider: z.string().default('lmstudio'),
defaultModel: z.string().default('gptoss-20b'),
scheduledReviewsEnabled: z.boolean().default(false),
lastDailyDigest: z.string().datetime().optional(),
lastWeeklyReview: z.string().datetime().optional()
});
// --- Input schemas for API endpoints ---
// Opt-in post-clone agent actions for a captured repository URL. Keys derive
// from REPO_INTAKE_KEYS so the wire contract can't drift from the normalizer
// that reads it (server/lib/repoIntakeActions.js).
export const repoIntakeSchema = z.object(optionalBooleanMap(REPO_INTAKE_KEYS)).extend({
targetAppId: z.string().trim().min(1).max(200).optional(),
studyContext: z.string().trim().max(5000).optional(),
// These pins apply only to the opt-in repo-study CoS task. Empty values are
// the UI's "use the configured default" sentinel and are omitted before
// the link stores the intake request.
providerId: z.string().trim().min(1).max(120).optional(),
model: z.string().trim().min(1).max(200).optional(),
effort: z.preprocess(
value => typeof value === 'string' ? (value.trim().toLowerCase() || undefined) : value,
z.enum(EFFORT_LEVELS).optional()
)
});
const repoIntakeInputSchema = repoIntakeSchema.optional();
/**
* Body of `POST /api/brain/links/:id/study` — an on-demand re-study of an
* already-cloned repo. Same study knobs as the capture-time opt-in (that is the
* point: the client renders one shared form for both), minus the action
* booleans, plus `pull` so the user can refresh the clone in the same click.
*/
export const linkStudyInputSchema = repoIntakeSchema
.omit(Object.fromEntries(REPO_INTAKE_KEYS.map(key => [key, true])))
.extend({ pull: z.boolean().optional().default(true) });
// Capture input schema
export const captureInputSchema = z.object({
text: z.string().min(1).max(10000),
providerOverride: z.string().optional(),
modelOverride: z.string().optional(),
// Optional context for a bare URL capture. It is stored on the link rather
// than treated as classifier input, so a saved link keeps why it matters.
note: z.string().max(2000).optional(),
// Opt-in flag: the user marked this note as a creative idea at capture time
// (vs a todo/reference). Creative notes are later batch-sendable into the
// creative catalog as ingredients (see catalog brain-bridge ingest).
creative: z.boolean().optional(),
// Post-clone agent actions for a bare repository URL. `targetAppId` selects
// the managed app whose tracker receives repo-study issues; omitted means
// PortOS for backward compatibility. Ignored for every other capture.
repoIntake: repoIntakeInputSchema
});
// Resolve review input schema
export const resolveReviewInputSchema = z.object({
inboxLogId: z.string().guid(),
destination: manualDestinationEnum,
editedExtracted: z.record(z.unknown()).optional()
});
// Fix classification input schema
export const fixInputSchema = z.object({
inboxLogId: z.string().guid(),
newDestination: manualDestinationEnum,
updatedFields: z.record(z.unknown()).optional(),
note: z.string().max(500).optional()
});
// Update inbox entry input schema
export const updateInboxInputSchema = z.object({
capturedText: z.string().min(1).max(10000)
});
// Batch mark a set of creative inbox notes as consumed by a catalog ingest that
// just committed. Bounded to keep a malformed/runaway payload from stamping the
// whole inbox in one call.
export const markInboxSentToCatalogSchema = z.object({
ids: z.array(z.string().guid()).min(1).max(200)
}).strict();
// Create/Update People input schema
export const peopleInputSchema = z.object({
name: z.string().min(1).max(200),
context: z.string().max(2000).optional(),
followUps: z.array(z.string().max(500)).optional(),
lastTouched: z.string().datetime().optional(),
tags: z.array(z.string().max(50)).optional()
});
// Create/Update Project input schema
export const projectInputSchema = z.object({
name: z.string().min(1).max(200),
status: projectStatusEnum.optional().default('active'),
nextAction: z.string().min(1).max(500),
notes: z.string().max(5000).optional(),
tags: z.array(z.string().max(50)).optional()
});
// Create/Update Idea input schema
export const ideaInputSchema = z.object({
title: z.string().min(1).max(200),
status: ideaStatusEnum.optional().default('active'),
oneLiner: z.string().min(1).max(500),
notes: z.string().max(5000).optional(),
tags: z.array(z.string().max(50)).optional()
});
// IdeaLoom lists are intentionally distinct from native Brain ideas. They are
// machine-local list documents, so neither their shape nor their sync metadata
// belongs to the federated Brain entity schemas above.
export const ideaLoomListStatusEnum = z.enum(['draft', 'completed']);
export const ideaLoomListInputSchema = z.object({
prompt: z.string().min(1).max(10000),
title: z.string().min(1).max(200),
category: z.string().min(1).max(100),
status: ideaLoomListStatusEnum.optional().default('draft'),
help: z.string().max(5000).optional(),
ideas: z.array(z.string().trim().min(1).max(2000)).max(500)
}).strict();
// Settings deliberately contain only integration switches and a vault id.
// Paths and note hashes stay on local list records and never cross this API.
export const ideaLoomSettingsInputSchema = z.object({
enabled: z.boolean().optional(),
obsidianVaultId: z.string().uuid().nullable().optional(),
autoSync: z.boolean().optional()
}).strict();
export const ideaLoomImportInputSchema = z.preprocess((value) => value ?? {}, z.object({}).strict());
// `recreateMissing` is the explicit recovery switch for a vault note the user
// deleted. It is only ever reachable from a user-initiated sync request —
// automatic sync omits it, so it can never resurrect a deleted note on its own.
export const ideaLoomSyncInputSchema = z.preprocess((value) => value ?? {}, z.object({
listId: z.string().uuid().optional(),
recreateMissing: z.boolean().optional().default(false)
}).strict());
// Create/Update Admin input schema
export const adminInputSchema = z.object({
title: z.string().min(1).max(200),
status: adminStatusEnum.optional().default('open'),
dueDate: z.string().datetime().optional(),
nextAction: z.string().max(500).optional(),
notes: z.string().max(5000).optional()
});
// Create/Update Memory input schema
export const memoryInputSchema = z.object({
title: z.string().min(1).max(200),
content: z.string().max(10000).optional(),
mood: z.string().max(50).optional(),
tags: z.array(z.string().max(50)).optional(),
// Provenance fields stamped by importers (e.g. chatgptImport) — kept on the
// create/update payload shape so schema validation matches what createMemoryEntry
// persists. `sourceCreatedAt`/`sourceUpdatedAt` drive the recency sort in the
// memory list (see memoryRecencyMs in brainStorage.js).
source: z.string().max(100).optional(),
sourceRef: z.string().max(300).optional(),
sourceCreatedAt: z.string().datetime().nullable().optional(),
sourceUpdatedAt: z.string().datetime().nullable().optional()
});
// Settings update input schema
// partialWithoutDefaults (not .partial()) so a PATCH that touches only one
// setting doesn't inject the other fields' defaults (e.g. defaultProvider:
// 'lmstudio') and overwrite the stored values — Zod 4's .partial() keeps inner
// defaults (see zodCompat.js).
export const settingsUpdateInputSchema = partialWithoutDefaults(brainSettingsSchema).omit({ version: true, lastDailyDigest: true, lastWeeklyReview: true });
// Inbox query schema
export const inboxQuerySchema = z.object({
status: inboxStatusEnum.optional(),
search: z.string().max(500).optional(),
cursor: z.preprocess((val) => (val === '' || val === null || val === 'null' ? undefined : val), z.string().max(512).optional()),
limit: z.coerce.number().int().min(1).max(100).optional().default(50),
offset: z.coerce.number().int().min(0).optional().default(0)
});
// Entity collection query schema (people, projects, ideas, admin, memories)
export const entityQuerySchema = z.object({
status: z.string().max(50).optional(),
search: z.string().max(500).optional(),
cursor: z.preprocess((val) => (val === '' || val === null || val === 'null' ? undefined : val), z.string().max(512).optional()),
limit: z.coerce.number().int().min(1).max(100).optional().default(25),
offset: z.coerce.number().int().min(0).optional().default(0),
includeArchived: z.preprocess(
(value) => (typeof value === 'string'
? value === 'true' ? true : value === 'false' ? false : value
: value),
z.boolean()
).optional().default(false)
});
// --- Extracted field schemas for AI classification ---
// Extracted People fields
export const extractedPeopleSchema = z.object({
name: z.string().min(1).max(200),
context: z.string().max(2000).optional().default(''),
followUps: z.array(z.string().max(500)).optional().default([]),
lastTouched: z.string().datetime().nullable().optional(),
tags: z.array(z.string().max(50)).optional().default([])
});
// Extracted Project fields
export const extractedProjectSchema = z.object({
name: z.string().min(1).max(200),
status: projectStatusEnum.optional().default('active'),
nextAction: z.string().min(1).max(500),
notes: z.string().max(5000).optional().default(''),
tags: z.array(z.string().max(50)).optional().default([])
});
// Extracted Idea fields
export const extractedIdeaSchema = z.object({
title: z.string().min(1).max(200),
status: ideaStatusEnum.optional().default('active'),
oneLiner: z.string().min(1).max(500),
notes: z.string().max(5000).optional().default(''),
tags: z.array(z.string().max(50)).optional().default([])
});
// Extracted Admin fields
export const extractedAdminSchema = z.object({
title: z.string().min(1).max(200),
status: adminStatusEnum.optional().default('open'),
dueDate: z.string().datetime().nullable().optional(),
nextAction: z.string().max(500).nullable().optional(),
notes: z.string().max(5000).optional().default('')
});
// Extracted Memory fields
export const extractedMemorySchema = z.object({
title: z.string().min(1).max(200),
content: z.string().max(10000).optional().default(''),
mood: z.string().max(50).nullable().optional(),
tags: z.array(z.string().max(50)).optional().default([])
});
// AI Classifier output schema (what we expect from the AI)
export const classifierOutputSchema = z.object({
destination: classifierDestinationEnum,
confidence: z.number().min(0).max(1),
title: z.string().min(1).max(200),
cleanedUp: z.string().max(10000).optional().default(''),
thoughts: z.string().max(2000).optional().default(''),
extracted: z.record(z.unknown()),
reasons: z.array(z.string()).max(5).optional().default([])
});
// Daily digest AI output schema
export const digestOutputSchema = z.object({
digestText: z.string(),
topActions: z.array(z.string()).max(3),
stuckThing: z.string(),
smallWin: z.string()
});
// Weekly review AI output schema
export const reviewOutputSchema = z.object({
reviewText: z.string(),
whatHappened: z.array(z.string()).max(5),
biggestOpenLoops: z.array(z.string()).max(3),
suggestedActionsNextWeek: z.array(z.string()).max(3),
recurringTheme: z.string()
});
// =============================================================================
// LINKS SCHEMAS
// =============================================================================
// Link type enum. `github` predates multi-host repo support and is retained so
// links stored (or federated from a peer) before migration 330 still validate;
// `repo` is what new links are written with.
export const linkTypeEnum = z.enum(['repo', 'github', 'article', 'documentation', 'tool', 'reference', 'other']);
// Link Record schema
export const linkRecordSchema = z.object({
id: z.string().guid(),
url: z.string().url(),
title: z.string().min(1).max(500),
description: z.string().max(2000).optional().default(''),
note: z.string().max(2000).optional().default(''),
linkType: linkTypeEnum.default('other'),
tags: z.array(z.string().max(50)).optional().default([]),
// Repository fields. `repoOwner` may be a GitLab `group/subgroup` path.
isRepo: z.boolean().default(false),
repoHost: z.string().max(253).nullable().optional(),
repoOwner: z.string().max(200).nullable().optional(),
repoName: z.string().max(100).nullable().optional(),
// Legacy GitHub-only mirror, still written so a peer on older code keeps
// recognising a captured GitHub repo — see lib/repoLinkFields.js.
isGitHubRepo: z.boolean().default(false),
gitHubOwner: z.string().max(100).nullable().optional(),
gitHubRepo: z.string().max(100).nullable().optional(),
localPath: z.string().max(500).optional(),
cloneStatus: z.enum(['pending', 'cloning', 'cloned', 'failed', 'none']).default('none'),
cloneError: z.string().max(500).optional(),
// The instance currently responsible for an in-flight clone. This differs
// from immutable originInstanceId when a peer retries a shared link.
cloneInstanceId: z.string().nullable().optional(),
// True only when boot recovery observed an interrupted attempt. Retry uses
// this to replace a legacy direct-to-destination partial checkout safely.
cloneInterrupted: z.boolean().optional().default(false),
malwareScan: z.object({
reportId: z.string().uuid(),
taskId: z.string().optional(),
// `queued` is stamped when the capture-time checkbox dispatches the scan
// right after the clone; finalizeMalwareScan replaces it on completion.
status: z.enum(['queued', 'completed', 'failed']).optional(),
verdict: z.enum(['CLEAN', 'CAUTION', 'DANGEROUS']).nullable().optional(),
completedAt: z.string().datetime().optional()
}).optional(),
// What the user asked to happen after the clone lands (capture-time checkboxes).
repoIntake: repoIntakeSchema.optional(),
// The queued `repo-study` run, once dispatched.
repoStudy: z.object({
taskId: z.string().optional(),
queuedAt: z.string().datetime().optional(),
// The brief the last study was dispatched with, so the re-study form opens
// pre-filled instead of blank.
studyContext: z.string().max(5000).optional()
}).optional(),
// Bucket grouping (nullable = ungrouped)
bucketId: z.string().guid().nullable().optional(),
bucketOrder: z.number().int().optional(),
// Metadata
createdAt: z.string().datetime(),
updatedAt: z.string().datetime()
});
// Create/Update Link input schema
export const linkInputSchema = z.object({
url: z.string().url(),
title: z.string().min(1).max(500).optional(),
description: z.string().max(2000).optional(),
note: z.string().max(2000).optional(),
linkType: linkTypeEnum.optional(),
tags: z.array(z.string().max(50)).optional(),
bucketId: z.string().guid().nullable().optional(),
bucketOrder: z.number().int().optional(),
autoClone: z.boolean().optional().default(true),
// Post-clone agent actions, same contract as the capture box's checkboxes.
repoIntake: repoIntakeInputSchema
});
// Update Link input schema (partial)
export const linkUpdateInputSchema = z.object({
url: z.string().url().optional(),
title: z.string().min(1).max(500).optional(),
description: z.string().max(2000).optional(),
note: z.string().max(2000).optional(),
linkType: linkTypeEnum.optional(),
tags: z.array(z.string().max(50)).optional(),
bucketId: z.string().guid().nullable().optional(),
bucketOrder: z.number().int().optional()
});
// Links query schema
export const linksQuerySchema = z.object({
linkType: linkTypeEnum.optional(),
// Query params arrive as strings; z.coerce.boolean() treats any non-empty
// string (including "false") as true, so parse the string value explicitly.
isRepo: z.preprocess(
v => (typeof v === 'string' ? v === 'true' : v),
z.boolean()
).optional(),
// Legacy peers and clients still use the GitHub-only name. Keep accepting it
// while the route normalizes it to the host-neutral filter above.
isGitHubRepo: z.preprocess(
v => (typeof v === 'string' ? v === 'true' : v),
z.boolean()
).optional(),
// LinksTab does its own filtering, search, and bucket assignment client-side
// over the full set — so the upper cap has to be large enough to return every
// saved link in one round-trip. 5000 is plenty of headroom for a single-user
// bookmark collection without being unbounded.
limit: z.coerce.number().int().min(1).max(5000).optional().default(50),
offset: z.coerce.number().int().min(0).optional().default(0)
});
// =============================================================================
// BUCKET SCHEMAS (bookmark groups for links)
// =============================================================================
// A small preset palette keyed to the port design tokens (plus a neutral default)
export const bucketColorEnum = z.enum([
'accent', 'success', 'warning', 'error', 'purple', 'pink', 'cyan', 'slate'
]);
// Create Bucket input schema
export const bucketInputSchema = z.object({
name: z.string().min(1).max(100),
color: bucketColorEnum.optional(),
icon: z.string().max(50).optional()
});
// Update Bucket input schema (partial)
export const bucketUpdateInputSchema = z.object({
name: z.string().min(1).max(100).optional(),
color: bucketColorEnum.optional(),
icon: z.string().max(50).optional(),
order: z.number().int().optional()
});
// Reorder buckets input schema (ordered list of bucket ids)
export const bucketReorderSchema = z.object({
ids: z.array(z.string().guid()).min(1)
});
// Batch link reorder (POST /api/brain/links/reorder) — applies a dense
// bucketOrder renumbering for one drag gesture in a single atomic write, so a
// multi-chip reorder can't lose-update the shared links store the way N
// concurrent single-record PUTs can.
export const linkReorderSchema = z.object({
updates: z.array(z.object({
id: z.string().guid(),
bucketId: z.string().guid().nullable(),
bucketOrder: z.number().int()
})).min(1)
});
// =============================================================================
// SYNC SCHEMAS
// =============================================================================
// Brain sync query schema (GET /api/brain/sync?since=N&limit=100)
export const brainSyncQuerySchema = z.object({
since: z.coerce.number().int().min(0).default(0),
limit: z.coerce.number().int().min(1).max(1000).optional().default(100)
});
// Brain parity check body (POST /api/brain/reconcile/parity). `peerId` is the
// LOCAL peer-registry id (the same id `/api/instances/peers/:id/sync` takes, so
// the Instances card can pass the peer it already holds). Omitted runs the sweep
// across every federating peer.
export const brainParityCheckSchema = z.object({
peerId: z.string().min(1).max(200).optional()
});
// Brain bridge-sync body (POST /api/brain/bridge-sync). `refresh` forces a
// re-embed of already-mapped records — the recovery path for memory entries
// that diverged before the per-record sync:applied signal existed (issue
// #1080). `onlyMissing` is the cheap targeted backfill: embed just the records
// that lack an embedding (unmapped, or mapped to a NULL-embedding memory) and
// skip everything healthy. Both optional + default-false so the existing
// no-body call is unchanged.
export const brainBridgeSyncSchema = z.object({
refresh: z.boolean().optional().default(false),
onlyMissing: z.boolean().optional().default(false)
});
// Brain graph query (GET /api/brain/graph?focus=<id>&limit=<n>). No `focus`
// returns the bounded overview; a `focus` returns that node's neighborhood.
export const brainGraphQuerySchema = z.object({
focus: z.string().min(1).optional(),
limit: z.coerce.number().int().min(1).max(250).optional()
});
// Daily log settings schema (PUT /api/brain/daily-log/settings body).
// Only these three keys are persisted — strict() rejects unknown keys so
// a typo or stray payload field can't corrupt the settings file.
export const dailyLogSettingsSchema = z.object({
obsidianVaultId: z.string().nullable().optional(),
obsidianFolder: z.string().optional(),
autoSync: z.boolean().optional()
}).strict();
// Activity-digest (daily-log auto-drafts, #2155) settings. Managed fields
// (lastRunDate/lastRunAt) are server-owned and intentionally NOT accepted here —
// the service strips anything but these client-settable keys. Empty-string
// provider/model (UI "None" sentinel) coerces to null so the non-LLM path runs.
const emptyToNull = (v) => (v === '' ? null : v);
export const activityDigestSettingsSchema = z.object({
enabled: z.boolean().optional(),
provider: z.preprocess(emptyToNull, z.string().nullable().optional()),
model: z.preprocess(emptyToNull, z.string().nullable().optional()),
runTime: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, 'Expected HH:MM (24h)').optional(),
catchUpDays: z.number().int().min(0).max(30).optional()
}).strict();
// POST /api/brain/{digest,review}/run — manual trigger with optional provider /
// model overrides (both absent = use configured defaults).
export const brainDigestRunSchema = z.object({
providerOverride: z.string().optional(),
modelOverride: z.string().optional()
});
// =============================================================================
// SONGBOOK SCHEMAS (Brain entity type `songs` — guitar tabs / chord sheets)
// =============================================================================
// Learning stage for a repertoire song
export const songStageEnum = z.enum(['new', 'learning', 'learned', 'memorized']);
// Instrument the sheet is written for. ADDITIVE only — brain records sync raw
// (LWW, no Zod re-validation on receive), so an older peer already stores an
// unknown instrument fine; removing a value would 400 an edit of a synced song.
export const songInstrumentEnum = z.enum(['guitar', 'piano', 'ukulele', 'bass', 'voice', 'drums', 'other']);
// Content notation format (drives the client-side parser/renderer). `drum` is
// the kit-grid DSL parsed by client/src/lib/drumNotation.js and drawn by
// <DrumSheetView> — everything else goes through tabNotation/<TabSheetView>.
export const songContentFormatEnum = z.enum(['chordpro', 'tab', 'plain', 'drum']);
// The SHAPES the write endpoints accept for those two fields — the enum above,
// OR any other short slug. Deliberately wider than the enum, because brain songs
// sync raw between installs on independent upgrade schedules (LWW, no Zod on
// receive): a peer running a newer version can hand this install an instrument or
// format it has never heard of, and that value is already sitting in the record.
// If a write then rejected it, the user could not edit that song AT ALL — every
// save would 400 on a field they never touched — and the client's own
// "keep an unknown stored value in the select" behavior (see
// `withStoredOption` in client/src/components/songbook/constants.js) would be
// unable to round-trip what it preserved.
//
// The enum stays the source of truth for what the UI OFFERS and what the client
// mirrors; this is only the acceptance boundary. The slug pattern keeps it from
// becoming a free-text field: lowercase alphanumerics plus `-`/`_`, ≤32 chars,
// which is what every value either side has ever used.
const songForwardCompatSlug = z.string().trim().regex(/^[a-z0-9][a-z0-9_-]{0,31}$/);
const songInstrumentValue = z.union([songInstrumentEnum, songForwardCompatSlug]);
const songContentFormatValue = z.union([songContentFormatEnum, songForwardCompatSlug]);
// Cross-links from a song to the OTHER music record kinds in PortOS (#4103):
// a Round (`/rounds/:id`) or a generated/imported music Track
// (`/music/tracks/:id`). MIDI is deliberately absent — there is no MIDI record
// in PortOS; MIDI is a file (already a songbook attachment, see
// SONGBOOK_ATTACHMENT_EXTENSIONS) or `referenceAudio.midiFilename` on a Round,
// which the `round` link already reaches.
export const songLinkTypeEnum = z.enum(['round', 'track']);
// Same enum-OR-slug acceptance boundary as instrument/format above, for the
// same reason: brain records sync raw (LWW, no Zod on receive), so a song
// arriving from a NEWER peer can carry a link type this install has never heard
// of. Rejecting it would make that song uneditable — every save 400ing on a
// field the user never touched.
const songLinkTypeValue = z.union([songLinkTypeEnum, songForwardCompatSlug]);
// One cross-link. `label` is the target's title DENORMALIZED at link time:
// Rounds and Tracks are not brain records and do not necessarily exist on every
// federated machine, so a link that resolves to nothing locally still renders a
// name instead of a bare id.
const songLinkSchema = z.object({
type: songLinkTypeValue,
id: z.string().trim().min(1).max(200),
label: z.string().trim().max(300).optional().default(''),
});
// Nested content object — named so the update schema below can rebuild it
// defaults-free (partialWithoutDefaults only strips TOP-LEVEL field defaults).
const songContentSchema = z.object({
format: songContentFormatValue.optional().default('tab'),
text: z.string().max(200000).optional().default('')
});
// Create/Update Song input schema. Attachment metadata ({ filename, label,
// mime, size, sha256 }) is server-managed — synced in the record, mutated only
// by the attachment endpoints, never client-suppliable (no schema key here, so
// Zod's unknown-key stripping drops it).
export const songInputSchema = z.object({
title: z.string().trim().min(1).max(300),
artist: z.string().trim().max(300).optional().default(''),
instrument: songInstrumentValue.optional().default('guitar'),
stage: songStageEnum.optional().default('new'),
tags: z.array(z.string().trim().min(1).max(50)).max(50).optional().default([]),
key: z.string().trim().max(20).optional().default(''),
capo: z.number().int().min(0).max(12).optional().default(0),
tuning: z.string().trim().max(40).optional().default(''),
sourceUrl: z.string().trim().max(2000).optional().default(''),
// Cross-links to Rounds / music Tracks (#4103). On a PATCH the top-level
// default is stripped, so an OMITTED key preserves the stored links while an
// explicit `[]` clears them (the absent-vs-empty rule).
links: z.array(songLinkSchema).max(20).optional().default([]),
content: songContentSchema.optional().default({ format: 'tab', text: '' }),
notes: z.string().max(5000).optional().default(''),
// "Fit to duration" autoscroll target: how many seconds the play view should
// take to scroll the sheet top-to-bottom. Stored per song and federated with
// the record; the px/s it implies is derived CLIENT-side at click time from
// the rendered scroll height (which depends on font size, transpose, and the
// viewport), so nothing server-side reads this — the bounds only keep it sane
// (15s … 1h).
//
// `null` is the explicit "no target set" value, and it must stay reachable on
// a PATCH: songUpdateSchema strips the default, so an OMITTED key preserves
// the stored target while an explicit `null` clears it (the absent-vs-empty
// rule). A create with no target lands as null rather than undefined so the
// field exists in the synced record.
scrollDurationSec: z.number().int().min(15).max(3600).nullable().optional().default(null)
});
// PATCH /api/brain/songbook/:id — defaults-free partial. partialWithoutDefaults
// only strips top-level defaults (see the zodCompat docstring): a
// present-but-partial `content` object would still inflate its inner defaults
// — `{ content: { text } }` resetting format to 'tab', `{ content: { format } }`
// wiping the whole text (and the wipe federates). The nested content field is
// rebuilt defaults-free too; the route deep-merges `data.content` over the
// stored song's content so an omitted inner key preserves the stored value.
export const songUpdateSchema = partialWithoutDefaults(songInputSchema).extend({
content: partialWithoutDefaults(songContentSchema).optional()
});
// POST /api/brain/songbook/:id/practice — log one practice run (#4102).
//
// `quality` is the SM-2 self-grade for the run: 0 = couldn't play it, 5 = clean.
// It is the ONLY input; the resulting schedule and stage are computed
// server-side from the stored record (see lib/songPractice.js), because an
// SM-2 advance needs the previous schedule and a client-computed one would both
// race and put the scheduler in the browser.
//
// The `practice` object itself is deliberately absent from songInputSchema /
// songUpdateSchema: like `attachments`, it is server-managed, so Zod's
// unknown-key stripping drops a client-supplied value and only this endpoint
// can move it.
// The ceiling reads from lib/spacedRepetition.js rather than restating `5`, so
// the accepted grade range can never drift from the scale the scheduler grades on.
export const songPracticeInputSchema = z.object({
quality: z.number().int().min(0).max(MAX_QUALITY)
});
// POST /api/brain/songbook/import/url
export const songImportUrlSchema = z.object({
url: z.string().url().max(2000)
});
// POST /api/brain/songbook/:id/attachments — base64 upload body
export const songAttachmentUploadSchema = z.object({
filename: z.string().min(1).max(300),
data: z.string().min(1),
label: z.string().max(300).optional().default('')
});
// =============================================================================
// THREAD SCHEMAS (/api/brain/threads/*)
// =============================================================================
//
// A Brain *thread* is one tracked topic or commitment — an open loop in the
// bullet-journal sense, NOT a message thread (see server/lib/threadRefKinds.js).
//
// `source`, `externalState` and `closedAt` are SERVER-managed: they have no key
// in the write schemas below, so Zod's unknown-key stripping drops a
// client-supplied value. `source` records where an auto-discovered thread came
// from, `externalState` what the tracker last said, and `closedAt` is stamped by
// the route when the status enters a terminal state. `remindedFor` is the
// `dueAt` a scheduled human action's reminder was sent for
// (services/humanActionReminders.js), so a restart never repeats it.
// Vocabularies live in the pure leaf (`lib/brainThreads.js`) so the client
// renders its pickers from the same arrays these enums validate against.
export const threadStatusEnum = z.enum(THREAD_STATUSES);
export const threadPriorityEnum = z.enum(THREAD_PRIORITIES);
// A ref's `kind` is validated as a SHAPE, not against THREAD_REF_KIND_IDS. A
// peer running newer code can sync a thread naming a kind this build has never
// heard of, and a strict enum would reject the user's own record on the next
// local edit; `resolveThreadRefs` degrades an unrecognized kind to
// `{ resolved: false, reason: 'unknown-kind' }` instead. The pattern still
// rejects a typo'd free-text kind and anything that could confuse a route param.
// Canonicalized BEFORE the shape check so a legacy spelling a catalog ref row
// still carries (`writersRoom`) is accepted and STORED canonically, rather than
// 400ing on the slug pattern and stranding the attach.
const threadRefKindValue = z.preprocess(
(value) => canonicalThreadRefKind(value),
z.string().trim().min(1).max(40)
.regex(/^[a-z0-9]+([-.][a-z0-9]+)*$/, 'kind must be a lowercase dot/dash slug'),
);
// An external ref's id IS its URL (up to 2000 chars), which is why this is not
// bounded to an id-sized string.
export const threadRefSchema = z.object({
kind: threadRefKindValue,
id: z.string().trim().min(1).max(2000),
// Cached display string so rendering a list of threads never fans out to N
// resolvers. Advisory only — `resolveThreadRefs` prefers what the live target
// says and falls back to this.
label: z.string().trim().max(300).optional().default('')
}).strict();
export const threadInputSchema = z.object({
title: z.string().trim().min(1).max(200),
status: threadStatusEnum.optional().default('open'),
priority: threadPriorityEnum.optional().default('normal'),
// The ONE concrete next step. Empty is meaningful ("nothing to do right now"),
// so it is a default rather than a required field.
nextAction: z.string().trim().max(500).optional().default(''),
notes: z.string().max(20000).optional().default(''),
waitingOn: z.string().trim().max(200).optional().default(''),
// Null is the explicit "no due date" value and must stay reachable on a PUT:
// threadUpdateSchema strips the default, so an OMITTED key preserves the
// stored date while an explicit `null` clears it (the absent-vs-empty rule).
dueAt: z.string().datetime().nullable().optional().default(null),
tags: z.array(z.string().trim().min(1).max(50)).max(50).optional().default([]),
pinned: z.boolean().optional().default(false),
// Bounded: a thread is a tracked topic, not a graph. 100 is the same ceiling
// the resolver's per-tuple probing is sized for.
refs: z.array(threadRefSchema).max(100).optional().default([])
});
// PUT /api/brain/threads/:id — defaults-free partial, so an omitted key
// preserves the stored value instead of resetting it to its default.
export const threadUpdateSchema = partialWithoutDefaults(threadInputSchema);
// GET /api/brain/threads — list filters. `limit`/`offset` are absent on purpose:
// `isPaginationRequested`/`paginateArray` read them straight off req.query, and
// coercing them here would make every request look paginated.
export const threadQuerySchema = z.object({
// One status, or a comma list (`?status=open,waiting,someday`) so the working
// set is one request rather than the whole archive filtered client-side.
// Always an array after parsing.
status: z.preprocess(
(value) => (typeof value === 'string' ? value.split(',').map((s) => s.trim()).filter(Boolean) : value),
z.array(threadStatusEnum).min(1).max(THREAD_STATUSES.length),
).optional(),
priority: threadPriorityEnum.optional(),
tag: z.string().trim().min(1).max(50).optional(),
refKind: threadRefKindValue.optional(),
// Tri-state on purpose: absent = don't filter, 'true'/'false' = filter to that
// value. A bare `?pinned` (empty string) reads as true, matching how the UI
// would emit a flag-shaped param.
pinned: z.enum(['true', 'false', '']).optional(),
q: z.string().trim().max(200).optional()
});
// On-demand discovery of assigned GitHub issues for one saved managed app.
export const threadSyncInputSchema = z.object({
appId: z.string().trim().min(1).max(128),
pinned: z.boolean().optional().default(false),
}).strict();
// POST /api/brain/threads/:id/refs — attach one ref to an existing thread.
export const threadRefInputSchema = threadRefSchema;
// POST /api/brain/threads/attach — attach a ref to an existing thread, or mint
// one and attach, in a single call. `threadId` picks the target; without it a
// new thread is created titled `title` (falling back to the ref's label).
export const threadAttachSchema = z.object({
ref: threadRefSchema,
threadId: z.string().trim().min(1).max(128).optional(),
title: z.string().trim().min(1).max(200).optional()
}).strict();
// =============================================================================
// YOUTUBE INGEST SCHEMAS (POST /api/brain/youtube/*)
// =============================================================================
// POST /api/brain/youtube/ingest. The URL host/shape allowlist lives in the
// service (assertYoutubeIngestUrl) so the error names the supported URL forms;
// the schema guards the payload shape and the bounds.
//
// The three capture switches are independently optional — the service rejects
// an all-false request with NOTHING_TO_INGEST rather than silently doing work
// the user didn't ask for. `agentPrompt` is what turns an ingest into a queued
// CoS task; absent/empty means "just store it".
export const youtubeIngestSchema = repoIntakeSchema.pick({ targetAppId: true, providerId: true, model: true, effort: true }).extend({
workMode: z.enum(['issues', 'implement']).optional(),
url: z.string().url().max(2048),
captureTranscript: z.boolean().optional(),
downloadVideo: z.boolean().optional(),
ingestAudio: z.boolean().optional(),
note: z.string().max(2000).optional(),
agentPrompt: z.string().max(10000).optional(),
tags: z.array(z.string().min(1).max(60)).max(20).optional(),
priority: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']).optional()
});
// GET /api/brain/youtube/ingests — query-less callers keep the legacy
// `{ ingests }` full-history array. Passing `limit` opts into a page ordered
// by `ingestedAt` desc with `videoId` as a deterministic tie-breaker (#8267);
// `cursor` is the opaque key of the last record on the prior page.
export const youtubeIngestsQuerySchema = z.object({
limit: z.preprocess((v) => (v === undefined || v === '' ? undefined : Number(v)), z.number().int().min(1).max(100).optional()),
cursor: z.preprocess((v) => (v === undefined || v === '' ? undefined : v), z.string().trim().min(1).max(4096).optional()),
}).strict();
// PUT /api/brain/youtube/settings. strict() rejects unknown keys so a typo
// can't quietly accumulate in the settings file.
export const youtubeIngestSettingsSchema = z.object({
obsidianVaultId: z.string().nullable().optional(),
obsidianFolder: z.string().max(300).optional(),
autoSync: z.boolean().optional(),
defaultCaptureTranscript: z.boolean().optional(),
defaultDownloadVideo: z.boolean().optional(),
defaultIngestAudio: z.boolean().optional(),
taskPriority: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']).optional()
}).strict();