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 { federatedSourceAudioSchema } from './federatedMediaWire.js';
import { MAX_IMAGE_EDGE, MAX_IMAGE_PIXELS } from './imageLimits.js';
export { MAX_IMAGE_EDGE, MAX_IMAGE_PIXELS } from './imageLimits.js';
import { CREDENTIALS } from './credentialRegistry.js';
import { DEFAULT_BACKUP_CRON, MIN_RETENTION_COUNT, MAX_RETENTION_COUNT } from './backupConfig.js';
import { z } from 'zod';
import { NOTIFICATION_TYPES } from './notificationTypes.js';
import { POLLUTING_KEYS } from './objects.js';
import { pipelineEditorialChecksSettingsSchema } from './pipelineValidation.js';
import { loraTrainingConfigSchema } from './mediaValidation.js';
import { ServerError } from './errorHandler.js';
import { isSafeGitRef } from './gitArgs.js';
import { partialWithoutDefaults, emptyToUndefined, emptyToNull, optionalBooleanMap, presetProviderIdSchema, providerRefSchema } from './zodCompat.js';
import { WORK_TRACKERS } from './workTracker.js';
import { LAYERED_INTELLIGENCE_SOURCE_KEYS } from './layeredIntelligenceSourceKeys.js';
import { PROVIDER_FAMILY_IDS } from './providerFamilies.js';
import { APP_FEATURE_IDS, INSTANCE_FEATURE_IDS, INSTANCE_FEATURE_GROUP_IDS } from './instanceFeatureRegistry.js';
import { MAX_MONTHLY_COST } from './subscriptionSavings.js';
import { MAX_PLAN_TIER_LENGTH } from './subscriptionPlanTiers.js';
import { IMAGE_GEN_MODES, QUEUEABLE_IMAGE_MODES, VIDEO_GEN_MODES } from './generationModes.js';
import { RUNWAY_IMAGE_MODEL_IDS, RUNWAY_IMAGE_RESOLUTIONS } from './runwayImageModels.js';
import { FAL_IMAGE_MODEL_IDS } from './falImageModels.js';
import { RENDER_TARGETS, RENDER_TARGET_BACKEND_AUTO } from './renderTargets.js';
import {
grokVideoDurationSchema, cloudModelIdString, recordRenderPinFields, isSafeSnapshotSource, isSafeSubdirFilter, csvIdsParam,
EXCLUDE_PATTERN_MAX_LENGTH, isSafeExcludePattern,
AUTO_UPDATE_CHANNELS, AUTO_UPDATE_MIN_INTERVAL_HOURS_MIN, AUTO_UPDATE_MIN_INTERVAL_HOURS_MAX,
} from './sharedSchemas.js';
import { PR_COMPLETION_VALUES } from './prDisposition.js';
import { EFFORT_LEVELS } from './providerModels.js';
import { knownFilmStyleIdSchema } from './filmStyleGrammars.js';
import { MODEL_ALIAS_LIMITS } from './providerModelAliases.js';
import { PROVIDER_HARNESS_IDS, ROUTE_MODES } from './providerHarnesses.js';
import { parseProviderRef } from './providerRef.js';
import { SERVICE_CREDENTIAL_VIAS, SERVICE_PLANS, SERVICE_SLUG_RE } from './serviceDefinitions.js';
import { MAX_TIMEOUT as AI_RUN_TIMEOUT_MAX_MS, MIN_TIMEOUT as AI_RUN_TIMEOUT_MIN_MS } from './aiToolkit/constants.js';
import {
FEDERATED_MEDIA_ASSET_MAX_COUNT,
FEDERATED_MEDIA_MAX_VIDEO_FRAMES,
federatedMediaInputAssetRefSchema,
isFederatedMediaAudioPrompt,
} from './federatedMediaWire.js';
import { isPlainObject } from './objects.js';
import { isValidCronExpression, isCronShaped } from './cronValidation.js';
import { USER_ACTION_ACTORS, USER_ACTION_TYPES } from './userActionTypes.js';
import { MIND_BUNDLE_GROUP_CHOICES, MIND_BUNDLE_MAX_CHARS, MIND_BUNDLE_PASSPHRASE_MAX_CHARS, MIND_BUNDLE_PASSPHRASE_MIN_CHARS, PERSISTENT_MIND_BUNDLE_GROUPS, PERSISTENT_MIND_BUNDLE_SCOPES } from './mindBundleFormat.js';
// ---- Git write-route bodies (#9154) -----------------------------------------
// Refs and files become argv entries for git, so a leading "-" would be parsed
// as an option; the ref grammar rejects that plus git's own invalid-ref forms.
export const gitRefNameSchema = z.string().min(1).max(255).refine(isSafeGitRef, {
message: 'not a valid git ref name',
});
const gitPathField = z.string().min(1);
export const gitPathBodySchema = z.object({ path: gitPathField });
export const gitStageBodySchema = z.object({
path: gitPathField,
files: z.array(z.string().min(1)).min(1).max(500),
});
export const gitCommitBodySchema = z.object({
path: gitPathField,
message: z.string().min(1).max(10000),
});
export const gitBranchBodySchema = z.object({ path: gitPathField, branch: gitRefNameSchema });
export const gitOptionalBranchBodySchema = z.object({
path: gitPathField,
branch: gitRefNameSchema.nullish(),
});
export const gitBranchComparisonBodySchema = z.object({
path: gitPathField,
base: gitRefNameSchema.nullish(),
head: gitRefNameSchema.nullish(),
});
export const gitDiffBodySchema = z.object({ path: gitPathField, staged: z.boolean().default(false) });
export const gitCommitsBodySchema = z.object({
path: gitPathField,
limit: z.number().int().min(1).max(100).default(10),
});
export const gitRemoteBranchesBodySchema = z.object({ path: gitPathField, force: z.boolean().default(false) });
export const gitDeleteBranchBodySchema = z.object({
path: gitPathField,
branch: gitRefNameSchema,
local: z.boolean().default(false),
remote: z.boolean().default(false),
}).refine(({ local, remote }) => local || remote, {
message: 'at least one of local or remote must be true',
});
export const imageEdgeSchema = z.number().int().min(64).max(MAX_IMAGE_EDGE).optional();
export const refineImagePixelCap = (d) =>
!(d.width && d.height) || d.width * d.height <= MAX_IMAGE_PIXELS;
export const PIXEL_CAP_MESSAGE = `Total pixels (width × height) must be ≤ ${MAX_IMAGE_PIXELS.toLocaleString()}`;
// Reject a record id that isn't a bare filename segment. Use before a
// peer-supplied / externally-sourced id is interpolated into a filesystem path
// (e.g. the sharing importer's raw `join(bucket, …, `${id}.json`)` reads, or
// the conflict journal's `recordDir(id)`), so a `../`-bearing id can't turn the
// read/delete into a path-traversal oracle. Records persisted through a
// collectionStore are already gated by its `idPattern`; this guards the raw
// path sites that don't go through a store.
export const isSafeRecordId = (id) =>
typeof id === 'string' && id.length > 0
&& id !== '.' && id !== '..'
&& !id.includes('/') && !id.includes('\\') && !id.includes('\0');
// `optionalBooleanMap` now lives in zodCompat.js (so per-domain schema files can
// use it without a cycle through this module) — re-exported for deep imports.
export { optionalBooleanMap };
// Cross-domain Zod fragments now live in sharedSchemas.js for the same
// no-cycle reason (spriteValidation.js and this module both need them) —
// re-exported so every existing `import { … } from '../lib/validation.js'`
// keeps working unchanged.
export {
grokVideoDurationSchema, cloudModelIdString, recordRenderPinFields, isSafeSnapshotSource, isSafeSubdirFilter,
};
// =============================================================================
// EXISTING SCHEMAS
// =============================================================================
// `ports` is an open-ended label→port map so app-specific keys derived from
// *_PORT env vars (coinbaseIpc, geminiIpc, etc.) survive validation alongside
// the well-known labels (api, ui, devUi, cdp, health).
export const processListQuerySchema = z.object({ appId: z.string().min(1).optional() });
// Reject option-shaped names before PM2 interprets positional arguments.
export const pm2ProcessNameSchema = z.string().min(1).max(120)
.regex(/^[A-Za-z0-9_][A-Za-z0-9._-]*$/, 'Must start with an alphanumeric character or underscore');
export const logsQuerySchema = z.object({
lines: z.coerce.number().int().min(1).max(5000).default(100),
follow: z.enum(['true', 'false']).optional(),
});
export const processActionSchema = z.object({
action: z.enum(['start', 'stop', 'restart']),
appId: z.string().min(1).optional()
});
export const processSchema = z.object({
name: z.string().min(1),
port: z.number().int().min(1).max(65535).nullable().optional(),
ports: z.record(z.number().int().min(1).max(65535)).optional(),
description: z.string().optional()
});
// JIRA integration config for apps
export const jiraConfigSchema = z.object({
enabled: z.boolean().default(false),
instanceId: z.string().optional(),
projectKey: z.string().optional(),
boardId: z.string().optional(),
issueType: z.string().optional().default('Task'),
labels: z.array(z.string()).optional().default([]),
assignee: z.string().optional(),
epicKey: z.string().optional(),
createPR: z.boolean().optional().default(true)
});
// DataDog integration config for apps
export const datadogConfigSchema = z.object({
enabled: z.boolean().default(false),
instanceId: z.string().optional(),
serviceName: z.string().optional(),
environment: z.string().optional()
});
// Per-managed-app feature participation. An absent key or null means inherit
// the install-wide Settings > Features value; true/false is an app override.
// The app-level list intentionally excludes POST, which has no managed-app tab.
export const appFeatureOverridesSchema = z.object(
Object.fromEntries(APP_FEATURE_IDS.map((id) => [id, z.boolean().nullable().optional()]))
).strict();
// POST /api/datadog/instances. API keys may be empty when updating an
// existing instance because the route preserves the stored secret in that
// case.
export const datadogInstanceRequestSchema = z.object({
// Preserve the exact key for updates. Older installs may have stored IDs
// outside the current preferred length/whitespace convention, and changing
// the lookup key here would make those instances impossible to edit.
id: z.string().min(1),
// Existing installs may have stored names longer than the current preferred
// display length, and updates should not make those records uneditable.
name: z.string().trim().min(1),
site: z.string().trim().min(1).max(253),
apiKey: z.string().max(512).optional(),
appKey: z.string().max(512).optional(),
});
// POST /api/datadog/instances/:id/search-errors.
export const datadogSearchErrorsRequestSchema = z.object({
serviceName: z.string().trim().min(1),
environment: z.string().trim().optional(),
fromTime: z.preprocess(emptyToUndefined, z.string().trim().refine(value => !Number.isNaN(Date.parse(value)), {
message: 'fromTime must be a valid ISO 8601 date string',
}).optional()),
});
// App schema for registration/update
// Workspace Context (#902) — the only input is an app id (the apps-registry
// key, or the fixed 'portos-default' baseline). Mirrors the apps-registry id
// shape: uuid-style ids plus the literal baseline id, so a hand-crafted path
// segment can't reach the service with a junk id.
export const workspaceContextParamsSchema = z.object({
appId: z.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/, 'invalid app id')
});
// Layered Intelligence per-app config (the self-improvement loop). Off by
// default; the loop is a user-enabled scheduled automation. `lastRunAt` is
// server-managed run bookkeeping (cadence, not issue memory) but accepted here
// so a round-tripped config doesn't 400. See server/services/layeredIntelligence.js.
export const LAYERED_INTELLIGENCE_SCOPES = ['app-improvement', 'app-data-gap', 'loop-meta', 'portos-self'];
export const layeredIntelligenceConfigSchema = z.object({
enabled: z.boolean().optional(),
intervalMs: z.number().int().min(60_000).optional(),
providerId: providerRefSchema.nullable().optional(),
model: z.string().nullable().optional(),
sources: z.object({
// One optional toggle per built-in Layer-1 source; the ordered key list (and
// what each source means) lives in layeredIntelligenceSources.js.
...Object.fromEntries(LAYERED_INTELLIGENCE_SOURCE_KEYS.map(key => [key, z.boolean().optional()])),
// Custom Layer-1 sources. Discriminated on `type`: a repo-relative `file`,
// an `http`(s) URL, or a shell `cmd`. All three carry an optional display
// `label`. gatherSources also re-enforces the file confinement + the
// http scheme + a cmd timeout at read time (defense in depth).
custom: z.array(z.discriminatedUnion('type', [
z.object({
type: z.literal('file'),
// A safe repo-relative path — reject absolute paths and `..` traversal so a
// custom source can't read files outside the app repo into the LLM prompt.
ref: z.string().min(1).max(500)
.refine(r => !r.startsWith('/') && !r.split(/[/\\]/).includes('..'), {
message: 'ref must be a repo-relative path (no leading / and no ".." segments)'
}),
label: z.string().max(120).optional()
}),
z.object({
type: z.literal('http'),
// Only http/https — gatherSources rejects any other scheme at read time too.
url: z.string().url().max(2000)
.refine(u => /^https?:\/\//i.test(u), { message: 'url must be http(s)' }),
label: z.string().max(120).optional()
}),
z.object({
type: z.literal('cmd'),
cmd: z.string().min(1).max(2000),
label: z.string().max(120).optional()
})
])).optional()
}).optional(),
rules: z.string().max(8000).optional(),
allowedScopes: z.array(z.enum(LAYERED_INTELLIGENCE_SCOPES)).optional(),
// Engine-A hand-off: when enabled, a reasoner-marked trivial+safe proposal is
// also enqueued as an approval-gated CoS coding-agent task. Off by default.
handoff: z.object({
enabled: z.boolean().optional()
}).optional(),
lastRunAt: z.string().nullable().optional()
});
// Install-level Layered Intelligence settings (data/settings.json, distinct from
// the per-app config above). `trustShellSources` unlocks full-shell custom `cmd`
// sources for the whole install — off by default; when false/absent, custom cmd
// sources are restricted to the allowlisted-binary + shell:false runner. See the
// threat-model comment on runShellCommand in server/services/layeredIntelligence.js
// (issue #2515).
export const layeredIntelligenceSettingsSchema = z.object({
trustShellSources: z.boolean().optional()
});
export const nativeLaunchSchema = z.object({
label: z.string().trim().min(1).max(40),
command: z.string().trim().min(1).max(500),
processName: z.string().regex(/^[a-zA-Z0-9._-]+$/).max(120)
});
export const appSchema = z.object({
name: z.string().min(1).max(100),
repoPath: z.string().min(1),
companionRepoPaths: z.array(z.string().min(1)).max(8).optional(),
type: z.string().optional().default('express'),
uiPort: z.number().int().min(1).max(65535).nullable().optional(),
devUiPort: z.number().int().min(1).max(65535).nullable().optional(),
apiPort: z.number().int().min(1).max(65535).nullable().optional(),
// Optional HTTPS port — set by the "Upgrade to TLS" action. When present,
// the Launch button prefers `https://<host>:<tlsPort>/` over the plain
// uiPort. See lib/tailscale-https.js for the helper apps use.
tlsPort: z.number().int().min(1).max(65535).nullable().optional(),
buildCommand: z.string().max(200).optional(),
// Explicit lifecycle hook for managed-app updates. PortOS runs its own
// update.sh/update.ps1; other apps must opt in instead of inheriting that
// lifecycle from their package.json.
updateCommand: z.string().trim().min(1).max(500).optional(),
uiUrl: z.string().url().optional(),
startCommands: z.array(z.string()).optional(),
pm2ProcessNames: z.array(z.string()).optional(),
// Optional native/GUI action shown alongside the standard browser Launch.
// Its PM2 process exits normally when the user closes the app window.
nativeLaunch: nativeLaunchSchema.nullable().optional(),
processes: z.array(processSchema).optional(), // Per-process port configs from ecosystem.config
envFile: z.string().optional(),
icon: z.string().nullable().optional(),
appIconPath: z.string().nullable().optional(), // Absolute path to detected app icon image
editorCommand: z.string().optional(),
description: z.string().optional(),
archived: z.boolean().optional(),
pm2Home: z.string().optional(), // Custom PM2_HOME path for apps that run in their own PM2 instance
disabledTaskTypes: z.array(z.string()).optional(), // Legacy: migrated to taskTypeOverrides
taskTypeOverrides: z.record(z.object({
enabled: z.boolean().optional(),
// A cron-SHAPED override must also be in range, or this generic PUT would
// persist an enabled schedule the walker can never match (#6634). A
// non-cron-shaped string is a named/legacy cadence the route decodes, and
// null clears the override back to inherit — both pass through untouched.
interval: z.string().refine(
(v) => !isCronShaped(v) || isValidCronExpression(v),
'interval must be a valid 5-field cron expression'
).nullable().optional(),
// Per-app scheduling fields for handler-backed tasks (e.g. layered-intelligence);
// persisted by updateAppTaskTypeOverride. Nullable = "clear back to inherit/default".
// Declared here so a generic PUT /api/apps/:id can't silently strip them (Zod drops
// unknown keys and updateApp replaces taskTypeOverrides wholesale).
intervalMs: z.number().positive().nullable().optional(),
// PRESET-ONLY: an app pin is read straight off `providers.json` by the task
// walker, so a composite (`harness.method@service`) would name a record
// that never exists there (#7564).
providerId: presetProviderIdSchema.nullable().optional(),
model: z.string().nullable().optional(),
taskMetadata: z.record(z.any()).nullable().optional()
})).optional(), // Per-task overrides: { [taskType]: { enabled, interval, intervalMs, providerId, model, taskMetadata } }
defaultUseWorktree: z.boolean().optional(),
defaultOpenPR: z.boolean().optional(),
// Omitted inherits reviewed PortOS auto-merge for new tasks; PATCH must not
// inject a default over an existing explicit draft/leave-open preference.
defaultPrCompletion: z.enum(PR_COMPLETION_VALUES).optional(),
// After a CoS agent completes against this app, audit the repo for the state the
// task asked for (worktree removed, branch deleted, PR merged) and file a recovery
// task when it diverges. See lib/repoStateExpectations.js. Unset = ON: an install
// that never hears about a leaked branch just accumulates them.
verifyRepoStateOnCompletion: z.boolean().optional(),
mergeHandoffMinQueuedRuns: z.number().int().min(1).max(10000).nullable().optional(),
// Unset/false = off (default); true = land a `.quality.json` quality snapshot through an immediately-merged PR after each audit.
publishQualitySnapshot: z.boolean().optional(),
featureOverrides: appFeatureOverridesSchema.optional(),
jira: jiraConfigSchema.optional().nullable(),
datadog: datadogConfigSchema.optional().nullable(),
// Where this app's autonomous work items live (single source per app).
// 'auto' (default) resolves to a concrete tracker from the git origin host
// — see server/lib/workTracker.js + the `claim-work` router in
// cosTaskGenerator.js. WORK_TRACKERS is the single source of truth for the
// value set.
workTracker: z.enum(WORK_TRACKERS).optional(),
// The `gh` account login PortOS authenticates AND commits as for this app's
// repo — how one install drives repos belonging to several GitHub accounts.
// Unset (the default) keeps the owner-match inference in services/forgeAuth.js
// and leaves commit authorship to the machine's ambient git config; setting it
// pins both the token and the GIT_AUTHOR/GIT_COMMITTER identity to that
// account. Empty string clears the pin.
forgeAccount: z.string().trim().max(120).optional(),
// Layered Intelligence per-app config (the self-improvement loop). Full config
// accepted on create/update; the dedicated updateAppLayeredIntelligence merge
// (server/services/apps.js) preserves untouched fields on partial PATCHes.
layeredIntelligence: layeredIntelligenceConfigSchema.optional()
// referenceRepos is INTENTIONALLY not part of the create/update API
// surface. createApp() doesn't persist it and updateApp() (via the
// omit() in appUpdateSchema) ignores it — the dedicated
// /api/apps/:appId/reference-repos endpoints own the lifecycle so
// server-managed fields (status, lastError, createdAt) can't be
// clobbered through the generic apps API.
});
// Used by routes that POST a NEW reference repo (id/createdAt are server-
// assigned, lastReviewedSha/lastCheckedAt populate after the first check).
// `.trim()` runs before `min(1)` so a name/repoUrl that's just whitespace
// fails validation rather than slipping through and producing confusing
// git failures downstream — matches the project convention used elsewhere
// in this file.
// Reference-repo entry. Each app can list upstream repos it watches for
// clean-room reimplementation; the `reference-watch` scheduled task fetches
// each one, finds commits since `lastReviewedSha`, and files proposals in the
// app's configured tracker (PLAN.md checklist IDs or forge issue numbers) for
// `/claim` / `plan-task` / `claim-issue*` to pick up. `notes` is the free-text
// "what we use from this repo" field, fed into the review prompt so the agent
// knows which features in our app are load-bearing for the watch. `repoUrl` is
// either a clonable URL (https://github.com/owner/repo or scp-style
// user@host:owner/repo.git) or a local filesystem path; the service detects
// remote URLs by matching
// `scheme://` or scp-style `user@host:path` (see isLocalPath in
// services/referenceRepos.js) and treats anything else as a local path.
// The persisted record's server-owned fields (id, status, lastError,
// lastCheckedAt, lastKnownGoodSnapshot, createdAt) are stamped by
// services/referenceRepos.js and never accepted from a request body.
export const referenceRepoCreateSchema = z.object({
name: z.string().trim().min(1).max(120),
repoUrl: z.string().trim().min(1).max(500),
branch: z.string().trim().max(120).optional(),
notes: z.string().max(4000).optional()
});
// Patch schema — every field optional. `lastReviewedSha` is also accepted
// here so the UI's "mark as reviewed" button (and the post-check service
// path) can pin a SHA. Same trim-before-min-length convention as the
// create schema. lastReviewedSha is hex-validated so a bad PATCH can't
// persist a non-SHA into apps.json.
export const referenceRepoUpdateSchema = z.object({
name: z.string().trim().min(1).max(120).optional(),
repoUrl: z.string().trim().min(1).max(500).optional(),
branch: z.string().trim().max(120).optional(),
notes: z.string().max(4000).optional(),
lastReviewedSha: z.string().regex(/^[0-9a-f]{40}$/i, 'must be a 40-char hex SHA').nullable().optional()
});
// Partial schema for updates. referenceRepos is intentionally absent
// from appSchema (see comment there) so it can't sneak in via PUT
// either — all ref CRUD goes through /api/apps/:appId/reference-repos.
export const appUpdateSchema = partialWithoutDefaults(appSchema);
const standardizePlanFileSchema = z.string().trim().min(1).max(500)
.refine((file) => {
const segments = file.split(/[/\\]/);
return !file.startsWith('/')
&& !file.startsWith('\\')
&& !/^[A-Za-z]:/.test(file)
&& !segments.includes('..');
}, { message: 'file must be a repo-relative path without parent traversal' });
const standardizePlanProcessSchema = z.object({
name: z.string().trim().min(1).max(120)
}).passthrough();
const standardizePlanStrayPortSchema = z.object({
file: standardizePlanFileSchema,
variable: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/).max(120),
value: z.number().int().min(1).max(65535),
line: z.number().int().positive(),
action: z.enum(['remove', 'keep'])
}).passthrough();
export const standardizePlanSchema = z.object({
currentState: z.object({
hasGit: z.boolean()
}).passthrough(),
proposedChanges: z.object({
createEcosystem: z.boolean(),
ecosystemContent: z.string().min(1).max(1_000_000),
processes: z.array(standardizePlanProcessSchema).max(100),
strayPorts: z.array(standardizePlanStrayPortSchema).max(500)
}).passthrough()
}).passthrough();
export const standardizeApplySchema = z.object({
repoPath: z.string().trim().min(1).max(4096).optional(),
appId: z.string().trim().min(1).max(200).optional(),
plan: standardizePlanSchema,
overwriteEcosystem: z.boolean().optional().default(false)
});
// Game studio (#3177): managed-app binding, reusable asset bindings, bundle
// compile, and user-triggered AI feedback.
const gameNameSchema = z.string().trim().min(1).max(120);
const gameAppIdSchema = z.string().trim().min(1).max(128);
const gameAssetIdSchema = z.string().trim().min(1).max(128);
export const gameCreateSchema = z.object({
appId: gameAppIdSchema,
name: gameNameSchema,
}).strict();
export const gameUpdateSchema = z.object({
appId: gameAppIdSchema.optional(),
name: gameNameSchema.optional(),
}).strict().refine((patch) => Object.keys(patch).length > 0, {
message: 'at least one field is required',
});
export const gameSpriteBindingSchema = z.object({
spriteId: gameAssetIdSchema,
}).strict();
// Repo-relative publish destination inside the managed app repository. The
// extension gate is per-lane (PNG artwork vs library audio); the traversal
// refinements are shared so the two lanes can't drift.
const gameDestinationSchema = (extensionPattern, extensionMessage) => z.string()
.trim()
.min(1)
.max(500)
.regex(extensionPattern, extensionMessage)
.refine((value) => !value.startsWith('/') && !value.includes('\\'), 'must be a repo-relative path')
.refine((value) => !value.split('/').includes('..'), 'must not traverse outside the app repository');
const gameMusicDestinationSchema = gameDestinationSchema(
/\.(?:mp3|wav|m4a|ogg|flac)$/i,
'must end in a supported audio extension',
);
const gamePublishOptionsSchema = z.object({
acknowledgeOverwrite: z.boolean().optional(),
}).strict();
export const gameMusicBindingSchema = z.object({
trackId: gameAssetIdSchema,
destinationPath: gameMusicDestinationSchema.optional(),
}).strict();
export const gameMusicBindingUpdateSchema = z.object({
destinationPath: gameMusicDestinationSchema,
}).strict();
export const gameMusicPublishSchema = gamePublishOptionsSchema;
export const GAME_ARTWORK_ROLES = [
'title-key-art',
'game-logo',
'biome-luminous-wilds',
'biome-mineral-steppe',
'biome-tide-meadow',
'loading-screen',
'other',
];
const gameArtworkFilenameSchema = z.string()
.trim()
.regex(/^[A-Za-z0-9][A-Za-z0-9._-]*\.png$/i, 'must be a gallery PNG filename')
.max(255);
const gameArtworkDestinationSchema = gameDestinationSchema(/\.png$/i, 'must end in .png');
export const gameArtworkBindingSchema = z.object({
imageFilename: gameArtworkFilenameSchema,
label: z.string().trim().min(1).max(120),
role: z.enum(GAME_ARTWORK_ROLES),
destinationPath: gameArtworkDestinationSchema,
}).strict();
export const gameArtworkBindingUpdateSchema = z.object({
label: z.string().trim().min(1).max(120).optional(),
role: z.enum(GAME_ARTWORK_ROLES).optional(),
destinationPath: gameArtworkDestinationSchema.optional(),
}).strict().refine((patch) => Object.keys(patch).length > 0, {
message: 'at least one field is required',
});
export const gameArtworkPublishSchema = gamePublishOptionsSchema;
export const gameFeedbackSchema = z.object({
providerId: z.string().trim().min(1).max(128),
model: z.string().trim().min(1).max(256).optional(),
effort: z.enum(EFFORT_LEVELS).nullable().optional(),
prompt: z.string().trim().min(1).max(4_000),
}).strict();
// Provider schema
const providerHardwareRequirementsSchema = z.object({
platforms: z.array(z.string().trim().min(1).max(32)).min(1).max(8).optional(),
architectures: z.array(z.string().trim().min(1).max(32)).min(1).max(8).optional(),
requiresAppleSilicon: z.boolean().optional(),
requiresNvidiaGpu: z.boolean().optional(),
minMemoryGb: z.number().positive().max(4096).optional(),
minVramGb: z.number().positive().max(4096).optional(),
minCudaComputeCapability: z.number().positive().max(20).optional(),
}).strict();
/** A service or bootstrap slug on a preset (#7565), clearable with `null`. */
const presetSlugField = z.string().trim().min(1).max(64).regex(SERVICE_SLUG_RE).nullable().optional();
export const providerSchema = z.object({
name: z.string().min(1).max(100),
type: z.enum(['cli', 'api', 'tui']),
command: z.string().optional(),
args: z.array(z.string()).optional(),
endpoint: z.string().url().optional(),
apiKey: z.string().optional(),
models: z.array(z.string()).optional(),
hardwareRequirements: providerHardwareRequirementsSchema.optional(),
modelHardwareRequirements: z.record(providerHardwareRequirementsSchema).optional(),
defaultModel: z.string().nullable().optional(),
timeout: z.number().int().min(AI_RUN_TIMEOUT_MIN_MS).max(AI_RUN_TIMEOUT_MAX_MS).optional(),
enabled: z.boolean().optional(),
// Marks a harness wrapper whose backend is the LM Studio server on this
// machine. Unlike the containers below, its context window and reasoning are
// chosen when the model instance is LOADED, so PortOS forwards neither.
lmstudioBacked: z.boolean().optional(),
// Kept in schema parity with aiToolkit's provider schema. Marks OpenCode
// wrappers for a separately started local MTPLX native-MTP server.
mtplxBacked: z.boolean().optional(),
// Marks an OpenCode CLI/TUI wrapper for a separately started local llama.cpp
// server (e.g. DFlash 2 speculative decoding).
llamaBacked: z.boolean().optional(),
// Marks an OpenCode CLI/TUI wrapper for a separately started local vLLM
// container (the Qwen3.8-27B DFlash 2 stack on an RTX 3090).
vllmBacked: z.boolean().optional(),
// Marks an OpenCode CLI/TUI wrapper for a separately started local SGLang
// container (Qwen3.8-27B on a Hopper/Blackwell card).
sglangBacked: z.boolean().optional(),
// Marks an OpenCode CLI/TUI wrapper for a hosted OpenAI-compatible gateway
// ('orcarouter', 'openrouter', 'nvidia-nim' — see server/lib/providerGateways.js). The
// sibling API record whose id equals this value owns the key.
gatewayBacked: z.string().optional(),
// Legacy per-gateway marker, superseded by `gatewayBacked`. Still accepted and
// still READ (providerGateways.js resolves it), because records written before
// the registry existed are never rewritten — installs upgrade on their own
// schedule.
orcarouterBacked: z.boolean().optional(),
// Explicit opt-in to attach the API key to an arbitrary (non-local,
// non-allowlisted) endpoint — mirrors the aiToolkit providerSchema. Guards
// SSRF / key exfiltration (server/lib/aiToolkit/endpointGuard.js).
allowCustomEndpoint: z.boolean().optional(),
// Kept in schema parity with aiToolkit's provider schema. Marks a CLI/TUI
// provider whose harness auth is provisioned by an external CLI at spawn
// time (a short-lived token for a proxy) rather than a static apiKey.
// `setupCommand` is advisory only — PortOS never executes it. Nullable so
// the editor can explicitly clear a previously-set bootstrap.
credentialBootstrap: z.object({
setupCommand: z.string().trim().max(500).optional(),
command: z.string().trim().min(1).max(200),
args: z.array(z.string().max(200)).max(20).optional(),
envCommand: z.array(z.string().min(1).max(500)).min(1).max(21).optional(),
harnessId: z.string().trim().min(1).max(100).optional(),
argsSeparator: z.string().trim().max(20).optional(),
}).strict().nullable().optional(),
envVars: z.record(z.string()).optional(),
headlessArgs: z.array(z.string()).optional(),
tuiPromptDelayMs: z.number().int().min(250).max(60000).optional(),
tuiIdleTimeoutMs: z.number().int().min(1000).max(86400000).optional(),
// Kept in schema parity with aiToolkit's provider schema. This opt-in applies
// only to interactive Claude TUI runs after the session-limit banner.
lowPriorityOnUsageLimit: z.boolean().optional(),
// Preset structure (#7565), in parity with the toolkit schema: the harness,
// method and service slug a DERIVED preset is materialized from, the
// optional catalog narrowing, and the bootstrap app it spawns through.
harnessId: z.enum(PROVIDER_HARNESS_IDS).nullable().optional(),
method: z.enum(ROUTE_MODES).nullable().optional(),
serviceId: presetSlugField,
catalogNarrowing: z.array(z.string().trim().min(1).max(512)).max(1000).nullable().optional(),
credentialBootstrapId: presetSlugField,
});
// POST /api/providers/:id/test-vision.
export const providerVisionTestSchema = z.object({
imagePath: z.string().trim().min(1).max(255),
prompt: z.string().max(8_000).optional(),
expectedContent: z.preprocess(emptyToUndefined, z.union([
z.string().trim().min(1).max(128),
z.array(z.string().trim().min(1).max(128)).max(50),
]).optional()),
model: z.preprocess(emptyToUndefined, z.string().trim().min(1).max(256).optional()),
});
// POST /api/providers/codex/account/login/cancel. The id is minted by the Codex
// app-server and only ever echoed back, so this bounds the shape and nothing
// more — the service still refuses an id that isn't the pending login's.
export const codexLoginCancelSchema = z.object({
loginId: z.string().trim().min(1).max(200),
});
// POST /api/providers/codex/account/login. `deviceCode` picks the device-code
// flow (a URL plus a short code) over opening a browser URL directly.
export const codexLoginStartSchema = z.object({
deviceCode: z.boolean().optional().default(false),
});
// POST /api/providers/model-pins/clear (#7315) — clear ONE stored model pin
// back to "inherit" by the id `GET /model-pins` reported. Addressed by pin id
// rather than a "clear everything stale" verb so an audit landing between the
// user's click and this write cannot widen what they approved. The id is
// resolved against a freshly collected pin list, so this bounds the shape only.
export const modelPinClearSchema = z.object({
pinId: z.string().trim().min(1).max(300),
});
// POST /api/providers/bindings/:id/link (and /link/preview).
//
// Every revision the caller reviewed is named explicitly. Omitting one is
// allowed for a PREVIEW (there is nothing to be stale against yet), but the
// service refuses to APPLY a link whose named revisions have moved -- a link is
// a decision about a specific difference, so a changed row invalidates it.
export const providerBindingLinkSchema = z.object({
targetConnectionId: z.string().uuid(),
expectedRevisions: z.object({
binding: z.number().int().positive().optional(),
sourceConnection: z.number().int().positive().optional(),
targetConnection: z.number().int().positive().optional(),
}).strict().optional().default({}),
}).strict();
// POST /api/providers/bindings/:id/unlink. No target: unlink clones the
// connection this binding already uses, so only the binding and its source
// participate.
export const providerBindingUnlinkSchema = z.object({
expectedRevisions: z.object({
binding: z.number().int().positive().optional(),
sourceConnection: z.number().int().positive().optional(),
}).strict().optional().default({}),
}).strict();
// POST /api/providers/connections (#6369) — a NEW backend.
//
// This schema bounds the SHAPE only. Which backend kinds and transport
// protocols are real is checked by `connectionBlocker` in the service, which
// already owns the harness/transport registries — importing them here would
// pull that subtree into the one module nearly every route validates through
// (`lib/importScoping.test.js`), for two enum lists and no extra safety.
//
// Exactly ONE transport, and this is the load-bearing rule: a provider record
// names one endpoint, so the profile a minted route reports always declares one
// transport. A connection declaring two would not be the connection its own
// routes describe, and reconciliation would clone each binding onto a fresh
// single-transport row on the next pass — silently undoing the create.
//
// Credentials take no `null` here, unlike the PATCH above: there is nothing yet
// to clear, so a null would only be a typo with a destructive reading.
export const providerConnectionCreateSchema = z.object({
kind: z.string().trim().min(1).max(64),
label: z.string().trim().min(1).max(200),
transports: z.record(
z.string().trim().min(1).max(64),
z.object({ baseUrl: z.string().trim().min(1).max(2048) }).strict(),
).refine((value) => Object.keys(value).length === 1, {
message: 'Declare exactly one transport protocol for this backend',
}),
credentials: z.record(
z.string().trim().min(1).max(128),
z.string().min(1).max(4096),
).optional().default({}),
}).strict();
// POST /api/providers/bindings (#6369) — a NEW harness configuration on an
// existing backend, and the executable routes it owns.
//
// `harnessId` accepts every registry id, not only the creatable ones: a harness
// with no command recipe gets the service's explanation of WHY it cannot be
// pointed at a backend, which is more useful than a schema enum error. `null`
// is the direct API binding and is spelled explicitly rather than by omission,
// because "no harness" is a real choice here, not a missing field.
export const providerBindingCreateSchema = z.object({
connectionId: z.string().uuid(),
harnessId: z.enum(PROVIDER_HARNESS_IDS).nullable(),
modes: z.array(z.enum(ROUTE_MODES)).min(1).max(ROUTE_MODES.length)
.refine((value) => new Set(value).size === value.length, { message: 'Name each mode once' }),
label: z.string().trim().min(1).max(200).optional(),
}).strict();
// PATCH /api/providers/connections/:id (#6369).
//
// `expectedRevision` is REQUIRED, unlike the link schemas where a preview may
// omit it: this endpoint always writes, and a shared backend edit that lands on
// a row the human never saw is exactly the silent overwrite the graph exists to
// prevent.
//
// Credentials are three-valued on purpose — absent preserves, `null` clears, a
// string sets — so a client that never received the secret (the DTO carries
// only `hasCredentials`) can edit a label without wiping the key.
export const providerConnectionUpdateSchema = z.object({
expectedRevision: z.number().int().positive(),
label: z.string().trim().max(200).optional(),
transports: z.record(
z.string().trim().min(1).max(64),
z.object({ baseUrl: z.string().trim().min(1).max(2048) }).strict(),
).optional(),
credentials: z.record(z.string().trim().min(1).max(128), z.string().max(4096).nullable()).optional(),
}).strict();
// --- service instances (#7563) ------------------------------------------------
// The vocabulary comes from `serviceDefinitions.js`, a zero-import leaf this
// module already reaches, so nothing here can drift from the definitions.
export const serviceSlugSchema = z.string().trim().min(1).max(64).regex(SERVICE_SLUG_RE, {
message: 'A service slug is lowercase letters, digits and dashes, starting with a letter or digit',
});
export const servicePlanSchema = z.enum(SERVICE_PLANS);
export const serviceCredentialViaSchema = z.enum(SERVICE_CREDENTIAL_VIAS);
const serviceTransportsSchema = z.record(
z.string().trim().min(1).max(64),
z.object({ baseUrl: z.string().trim().min(1).max(2048) }).strict(),
);
// POST /api/providers/services — a NEW instance of a definition. The
// definition decides which transports and plans are legal (`resolveServiceInstance`
// in the service), so this bounds shape only. Credentials take no `null`, as
// on the connection create: nothing exists yet to clear.
export const providerServiceCreateSchema = z.object({
definitionId: z.string().trim().min(1).max(64),
slug: serviceSlugSchema.optional(),
label: z.string().trim().min(1).max(200).optional(),
plan: servicePlanSchema.optional(),
enabled: z.boolean().optional(),
transports: serviceTransportsSchema.optional(),
credentials: z.record(z.string().trim().min(1).max(128), z.string().min(1).max(4096)).optional().default({}),
credentialVia: serviceCredentialViaSchema.optional(),
}).strict();
// PATCH /api/providers/services/:slug — the connection update plus the
// instance's own plan / enabled / credential mode. Same three-valued
// credential rule, same required `expectedRevision`.
export const providerServiceUpdateSchema = providerConnectionUpdateSchema.extend({
plan: servicePlanSchema.optional(),
enabled: z.boolean().optional(),
credentialVia: serviceCredentialViaSchema.optional(),
}).strict();
// PATCH /api/providers/bindings/:id (#6369). Management state only: no
// `enabled`, because route enablement is an executable-record field that
// PATCH /api/providers/:id owns and a binding toggle must never grant it.
export const providerBindingUpdateSchema = z.object({
expectedRevision: z.number().int().positive(),
label: z.string().trim().max(200).optional(),
selectedModels: z.array(z.string().trim().min(1).max(512)).max(1000).optional(),
}).strict();
// PATCH /api/providers/routes/:providerId (#6369) — ONE route's mode overrides.
//
// Deliberately not `providerSchema.partial()`: that would reopen the whole
// executable record, including the connection-owned endpoint/key the graph
// projects and the `enabled` flag that grants execution consent. The accepted
// keys are exactly the route-owned table in `providerRouteSettings.js`;
// `providerRouteSettings.test.js` fails if the two ever drift.
//
// `expectedRevision` is a FINGERPRINT of the values on disk, not a row counter
// — these fields live in providers.json, which the route editor and a model
// refresh also write. An empty patch is refused rather than written: it would
// rewrite the provider file to say nothing.
//
// `timeout` takes no `null`. The executable record's own schema has no null
// timeout, so storing one here would 400 the next save from the route editor;
// clearing a custom timeout stays that editor's job.
const nullableModelPin = z.preprocess(emptyToNull, z.string().trim().max(512).nullable());
export const providerRouteSettingsUpdateSchema = z.object({
expectedRevision: z.string().trim().min(1).max(64),
settings: z.object({
args: z.array(z.string().trim().min(1).max(2048)).max(200).optional(),
timeout: z.number().int().min(AI_RUN_TIMEOUT_MIN_MS).max(AI_RUN_TIMEOUT_MAX_MS).optional(),
effort: z.preprocess(emptyToNull, z.enum(EFFORT_LEVELS).nullable()).optional(),
defaultModel: nullableModelPin.optional(),
lightModel: nullableModelPin.optional(),
mediumModel: nullableModelPin.optional(),
heavyModel: nullableModelPin.optional(),
ultraModel: nullableModelPin.optional(),
}).strict().refine((value) => Object.keys(value).length > 0, {
message: 'Name at least one setting to change',
}),
}).strict();
// PATCH /api/providers/routes/:providerId/model-aliases (#6369) — ONE route's
// HAND-AUTHORED canonical→executable model aliases.
//
// Three-valued like the connection credentials above, and for the same reason:
// a panel that read three aliases and changed one must be able to send one. An
// absent key is preserved, a string sets, and `null` DELETES — the only way an
// override is ever removed, because a refresh must never delete a correction.
//
// The keys are model names, so the record is not enumerable and each key is
// length-checked. `expectedRevision` is a FINGERPRINT of the current override
// map (`ai_route_bindings` has no revision column), and an empty patch is
// refused rather than written: it would rewrite a row to say nothing.
export const providerRouteModelAliasSchema = z.object({
expectedRevision: z.string().trim().min(1).max(64),
aliases: z.record(
z.string().trim().min(1).max(MODEL_ALIAS_LIMITS.maxLength),
z.string().trim().min(1).max(MODEL_ALIAS_LIMITS.maxLength).nullable(),
).refine((value) => Object.keys(value).length > 0, { message: 'Name at least one alias to change' })
.refine((value) => Object.keys(value).length <= MODEL_ALIAS_LIMITS.maxEntries, {
message: `At most ${MODEL_ALIAS_LIMITS.maxEntries} aliases at a time`,
}),
}).strict();
// POST /api/providers/:id/vision-suite.
export const providerVisionSuiteSchema = z.object({
model: z.preprocess(emptyToUndefined, z.string().trim().min(1).max(256).optional()),
});
// POST /api/harnesses/action. Both values are TABLE KEYS, not free text: the
// service rejects a `runtime` that names no row and an `action` outside this
// enum before any child is spawned. This bounds the shape at the HTTP boundary
// so a malformed query fails as a 400 rather than as a lookup miss mid-stream.
export const harnessActionSchema = z.object({
runtime: z.string().trim().min(1).max(64),
action: z.enum(['install', 'update', 'uninstall']).optional().default('install'),
});
// POST /api/harnesses/models/refresh.
export const harnessRefreshSchema = z.object({
runtime: z.string().trim().min(1).max(64),
});
// POST /api/uploads and POST /api/attachments. The shared upload helper
// enforces decoded-byte limits and extension allowlists; this schema bounds
// the JSON shape before the helper receives it.
export const base64FileUploadSchema = z.object({
data: z.string().trim().min(1, 'data is required (base64)').max(64 * 1024 * 1024),
// The upload helper prefixes the sanitized name with a 9-byte UUID marker.
filename: z.string().min(1, 'filename is required').max(246),
});
export const uploadRequestSchema = base64FileUploadSchema;
export const attachmentUploadRequestSchema = base64FileUploadSchema;
// Run command schema
export const runSchema = z.object({
type: z.enum(['ai', 'command']),
providerId: providerRefSchema.optional(),
model: z.string().optional(),
workspaceId: z.string(),
command: z.string().optional(),
prompt: z.string().optional(),
timeout: z.number().int().min(AI_RUN_TIMEOUT_MIN_MS).max(AI_RUN_TIMEOUT_MAX_MS).optional()
});
// =============================================================================
// SOCIAL ACCOUNT SCHEMAS (Digital Twin)
// =============================================================================
export const socialPlatformSchema = z.enum([
'github', 'instagram', 'facebook', 'linkedin', 'x',
'substack', 'medium', 'youtube', 'tiktok', 'reddit',
'bluesky', 'mastodon', 'threads', 'other'
]);
export const socialAccountSchema = z.object({
platform: socialPlatformSchema,
username: z.string().min(1).max(200),
displayName: z.string().max(200).optional(),
url: z.string().url().optional(),
bio: z.string().max(2000).optional().default(''),
contentTypes: z.array(z.string().max(50)).optional().default([]),
ingestionEnabled: z.boolean().optional().default(false),
notes: z.string().max(2000).optional().default('')
});
// Bulk create: each entry is validated per-account (a bad one is reported, not fatal).
export const socialAccountBulkBodySchema = z.object({ accounts: z.array(z.unknown()).min(1, 'accounts array is required') });
export const socialAccountUpdateSchema = partialWithoutDefaults(socialAccountSchema);
// =============================================================================
// GITHUB REPOS SCHEMAS
// =============================================================================
export const githubRepoUpdateSchema = z.object({
flags: z.record(z.boolean()).optional(),
managedSecrets: z.array(z.string().min(1)).optional()
});
export const githubSecretSchema = z.object({
value: z.string().min(1)
});
// GitHub notifications manager accounts (#12869). A bare hostname (optional
// :port) whose first character also rules out a value `gh` would parse as a flag.
export const GITHUB_ACCOUNT_HOST_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?::\d{1,5})?$/;
// github.com logins are [A-Za-z0-9-]; Enterprise Managed Users add `_shortcode`.
export const GITHUB_ACCOUNT_LOGIN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
export const GITHUB_ACCOUNT_TRUST_LEVELS = Object.freeze(['public', 'private']);
export const GITHUB_ACCOUNT_MODES = Object.freeze(['disabled', 'observe', 'assist', 'autopilot']);
// Per-repo automation rules for the GitHub inbox (#13192): what Assist and
// Autopilot do with a kind of notification, in one repo (`owner/repo`), an
// account/org (`owner/*`) or every repo (`*`), and on which provider/model/effort
// when it starts an agent. Repo > owner > all. Mirrors AGENT_RULE_KINDS and
// AGENT_RULE_ACTIONS in lib/githubNotificationTriage.js.
export const GITHUB_AGENT_RULE_KINDS = Object.freeze(['review-request', 'security-alert', 'issue-activity', 'ci-activity', 'own-pr', 'dependabot-pr', 'pull-request', 'mention', 'release', 'other']);
export const GITHUB_AGENT_RULE_ACTIONS = Object.freeze(['agent', 'done', 'mute', 'leave', 'do-review', 'untrusted-review', 'merge']);
export const GITHUB_AGENT_RULE_REPO_RE = /^(?:\*|[A-Za-z0-9_.-]{1,100}\/(?:\*|[A-Za-z0-9_.-]{1,100}))$/;
const emptyToNullString = (value) => (value === '' ? null : value);
// A legacy `agent: true/false` (rules saved before #13192) is accepted and
// stored as `action: 'agent' / 'leave'`; `action` wins when both are sent.
export const githubAgentRuleSchema = z.object({
id: z.string().regex(/^[A-Za-z0-9-]{1,64}$/),
kind: z.enum(GITHUB_AGENT_RULE_KINDS),
repo: z.string().trim().regex(GITHUB_AGENT_RULE_REPO_RE, 'Use owner/repo, owner/* for an account or organization, or * for every repo'),
agent: z.boolean().optional(),
action: z.enum(GITHUB_AGENT_RULE_ACTIONS).optional(),
mergeMethod: z.enum(['merge', 'squash', 'rebase']).optional(),
deleteBranch: z.boolean().optional(),
provider: z.preprocess(emptyToNullString, z.string().trim().min(1).max(128).nullable()).optional(),
model: z.preprocess(emptyToNullString, z.string().trim().min(1).max(200).nullable()).optional(),
effort: z.preprocess(emptyToNullString, z.enum(EFFORT_LEVELS).nullable()).optional(),
}).strict().superRefine((rule, ctx) => {
const action = rule.action ?? (typeof rule.agent === 'boolean' ? (rule.agent ? 'agent' : 'leave') : null);
if (!action) ctx.addIssue({ code: 'custom', path: ['action'], message: 'Choose what to do with these notifications' });
else if (rule.kind === 'security-alert' && action !== 'agent' && action !== 'leave') {
ctx.addIssue({ code: 'custom', path: ['action'], message: 'Security alerts are never marked done or muted by a rule' });
}
if (['do-review', 'untrusted-review', 'merge'].includes(action) && !['dependabot-pr', 'pull-request', 'own-pr', 'review-request'].includes(rule.kind)) {
ctx.addIssue({ code: 'custom', path: ['action'], message: 'PR actions require a pull-request notification rule' });
}
if (action === 'merge' && rule.kind !== 'dependabot-pr') {
ctx.addIssue({ code: 'custom', path: ['action'], message: 'Automatic merge is available for verified Dependabot pull requests' });
}
}).transform(({ agent, ...rule }) => ({ ...rule, action: rule.action ?? (agent ? 'agent' : 'leave') }));
export const githubAgentRulesSchema = z.array(githubAgentRuleSchema).max(200).superRefine((rules, ctx) => {
const seen = new Set();
rules.forEach((rule, index) => {
const key = `${rule.kind}#${rule.repo.toLowerCase()}`;
if (seen.has(key)) ctx.addIssue({ code: 'custom', path: [index, 'repo'], message: `There is already a ${rule.kind} rule for ${rule.repo}` });
seen.add(key);
});
});
// The provider/model/effort an agent run starts from (#13191): the account's
// defaults, or the operator's choice for one Resolve with agent run. null or
// '' = Auto (CoS chooses).
const githubAgentPinFields = {
provider: z.preprocess(emptyToNullString, z.string().trim().min(1).max(128).nullable()).optional(),
model: z.preprocess(emptyToNullString, z.string().trim().min(1).max(200).nullable()).optional(),
effort: z.preprocess(emptyToNullString, z.enum(EFFORT_LEVELS).nullable()).optional(),
};
export const githubAgentDefaultsSchema = z.object(githubAgentPinFields).strict();
export const githubNotificationAgentRunSchema = z.object(githubAgentPinFields).strict();
export const githubNotificationPullRequestActionSchema = z.object({
action: z.enum(['merge', 'do-review', 'untrusted-review']),
method: z.enum(['merge', 'squash', 'rebase']).optional(),
deleteBranch: z.boolean().optional(),
...githubAgentPinFields,
}).strict();
export const githubAccountCreateSchema = z.object({
label: z.string().trim().max(80).optional(),
host: z.string().trim().toLowerCase()
.transform((value) => value.replace(/^https?:\/\//, '').replace(/\/+$/, ''))
.pipe(z.string().min(1).max(253).regex(GITHUB_ACCOUNT_HOST_RE, 'Use a bare hostname such as github.example.com')),
login: z.string().trim().regex(GITHUB_ACCOUNT_LOGIN_RE, 'Not a valid GitHub login').nullable().optional(),
trust: z.enum(GITHUB_ACCOUNT_TRUST_LEVELS).optional(),
// null = the trust level's default (Private: local providers only).
allowedProviders: z.array(z.string().trim().min(1).max(128)).max(50).nullable().optional(),
mode: z.enum(GITHUB_ACCOUNT_MODES).optional(),
// Monthly subscription audit delivered as a PortOS notification (#12874).
auditReport: z.boolean().optional(),
// Private (Enterprise) accounts refuse every agent hand-off unless the operator
// opts in: the lanes run on PortOS's own providers, which the allow-list cannot bind.
allowAgents: z.boolean().optional(),
// Enterprise hosts only: every human on the instance counts as trusted (#13203).
trustInstanceUsers: z.boolean().optional(),
agentRules: githubAgentRulesSchema.optional(),
agentDefaults: githubAgentDefaultsSchema.nullable().optional(),
enabled: z.boolean().optional(),
}).strict();
export const githubAccountUpdateSchema = githubAccountCreateSchema.partial().strict();
// GitHub notifications inbox (#12870).
export const githubNotificationsQuerySchema = z.object({
accountId: z.string().trim().min(1).max(100).optional(),
view: z.enum(['needs-you', 'suspect', 'handled', 'all']).optional(),
}).strict();
export const githubNotificationsSyncSchema = z.object({
accountId: z.string().trim().min(1).max(100).optional(),
}).strict();
export const githubNotificationsClearSchema = z.object({
accountId: z.string().trim().min(1).max(100).optional(),
}).strict();
// Deployment approval from the inbox (#13198): operator only.
export const githubDeploymentReviewSchema = z.object({
state: z.enum(['approved', 'rejected']),
environmentIds: z.array(z.number().int().positive()).min(1).max(20),
comment: z.string().trim().max(1000).optional(),
}).strict();
export const githubNotificationActionSchema = z.object({
action: z.enum(['read', 'done', 'reopen', 'mute', 'unsubscribe', 'resubscribe']),
}).strict();
export const GITHUB_NOTIFICATION_THREAD_ID_RE = /^\d{1,20}$/;
// Automations tab (#12871): the one cadence it offers, or back to Run now only.
export const GITHUB_NOTIFICATION_CADENCES = Object.freeze({ 'weekdays-15m': '*/15 * * * 1-5', off: null });
export const githubAuditApplySchema = z.object({
suggestionId: z.string().trim().min(1).max(300),
}).strict();
export const githubNotificationCadenceSchema = z.object({
cadence: z.enum(Object.keys(GITHUB_NOTIFICATION_CADENCES)),
}).strict();
// =============================================================================
// INSIGHTS SCHEMAS
// =============================================================================
export const insightRefreshSchema = z.object({
providerId: providerRefSchema.optional(),
model: z.string().optional()
});
// Goal effectiveness scorecard (#2157).
export const scorecardComputeSchema = z.object({
weekStart: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional()
});
export const scorecardSettingsSchema = z.object({
enabled: z.boolean().optional(),
provider: providerRefSchema.nullable().optional(),
model: z.string().nullable().optional(),
feedBrainDigest: z.boolean().optional(),
weekStartsOn: z.number().int().min(1).max(7).optional()
});
// Per-goal mapping overrides: { [goalId]: { keywords?, personIds?, subcalendarIds?, enabled? } }.
const scorecardRuleOverrideSchema = z.object({
keywords: z.array(z.string()).optional(),
personIds: z.array(z.string()).optional(),
subcalendarIds: z.array(z.string()).optional(),
enabled: z.boolean().optional()
});
export const scorecardRulesSchema = z.record(z.string(), scorecardRuleOverrideSchema);
// =============================================================================
// SEARCH SCHEMAS
// =============================================================================
export const searchQuerySchema = z.object({
q: z.string().min(2).max(200).trim()
});
// =============================================================================
// MEDIA SKETCH / ANNOTATION SCHEMAS (issue #2036, phase 1)
// =============================================================================
// Vector strokes drawn over a generated image. Points are stored in the
// image's natural-pixel space so they restore exactly regardless of the
// display size (see AnnotationCanvas.jsx). The service (mediaSketches.js)
// re-sanitizes + clamps beyond this schema; the Zod layer rejects the
// obviously-malformed shapes early with a 400.
const sketchPointSchema = z.object({
x: z.number().finite(),
y: z.number().finite()
});
const sketchStrokeSchema = z.object({
mode: z.enum(['draw', 'erase']).optional(),
color: z.string().max(32).optional(),
size: z.number().positive().max(512).optional(),
points: z.array(sketchPointSchema).min(1).max(20000)
});
export const mediaSketchSaveSchema = z.object({
width: z.number().positive(),
height: z.number().positive(),
strokes: z.array(sketchStrokeSchema).max(5000),
// Flattened raster (image + strokes) as a PNG data URL. Optional so a caller
// can persist just the vector layer; the service decodes + stores the bytes.
png: z.string().startsWith('data:image/png;base64,').optional()
});
// =============================================================================
// BACKUP SCHEMAS
// =============================================================================
// Used by both the settings PUT route (.partial() for incremental updates) and
// any direct backup-config endpoint. destPath is nullable: the UI persists an
// empty string when the field is cleared, and the route handler treats empty/
// missing destPath as "not configured" rather than rejecting the save.
// The enabled/cron defaults here are the SAME interpretation `backupConfig.js`
// declares (omitted enabled = enabled, blank cron = midnight) and are sourced
// from it, so the boundary schema can never drift from the module the scheduler
// and the settings GET both resolve through (#6632).
export const backupConfigSchema = z.object({
destPath: z.string().nullable().optional(),
cronExpression: z.string().optional().default(DEFAULT_BACKUP_CRON),
enabled: z.boolean().optional().default(true),
// rsync filter patterns, bounded and kept inside the data root. `..` (any
// segment) and NUL are rejected rather than sanitized, so a hand-edited
// settings.json can't hand rsync a pattern that walks upward or smuggles a
// separator. Anchoring itself happens at READ time in
// `computeEffectiveExcludes` — the stored value stays what the user typed —
// but the length bound is measured on the ANCHORED form, so this accepts
// exactly what that normalizer will keep. The outer .max() is a cheap ceiling
// on a pathological payload; isSafeExcludePattern owns the real rule.
excludePaths: z.array(
z.string().trim().min(1).max(EXCLUDE_PATTERN_MAX_LENGTH + 1)
.refine(isSafeExcludePattern, { message: `Exclude pattern must be at most ${EXCLUDE_PATTERN_MAX_LENGTH} characters once anchored, and may not contain ".." or a NUL byte` })
).optional().default([]),
disabledDefaultExcludes: z.array(z.string()).optional().default([]),
// Per-source completed-snapshot retention. `null` (and an omitted field, via
// `resolveRetentionCount`) both mean unlimited — see backupConfig.js for why
// an existing install must never see this default itself. `.nullable()`
// rather than `emptyToUndefined`: the UI's explicit "Unlimited" choice IS a
// value worth persisting distinctly from "never touched this setting".
retentionCount: z.number().int().min(MIN_RETENTION_COUNT).max(MAX_RETENTION_COUNT).nullable().optional()
});
// Automatic PortOS self-update (Update tab). Stored under the top-level
// `autoUpdate` key and OFF by default — an install must never start restarting
// itself merely because it upgraded into this code. The accepted interpretation
// of a sparse slice (omitted channel, omitted interval) is `sharedSchemas.js`'s
// `resolveAutoUpdateConfig`, which the scheduler and the settings GET both read
// through, so this boundary schema cannot drift away from it.
export const autoUpdateSettingsSchema = z.object({
enabled: z.boolean().optional(),
channel: z.enum(AUTO_UPDATE_CHANNELS).optional(),
// Hours to wait after the last update before looking for an idle window.
minIntervalHours: z.number().min(AUTO_UPDATE_MIN_INTERVAL_HOURS_MIN).max(AUTO_UPDATE_MIN_INTERVAL_HOURS_MAX).optional(),
// Whether a checkout no script may safely repair queues a CoS agent.
resolveBlockersWithAgent: z.boolean().optional(),
}).strict();
// Scheduled Series Autopilot (#2174). Machine-local per-series cron schedules
// that fire `startSeriesAutopilot` unattended — the AI Provider Usage Policy's
// sanctioned "scheduled automation" exception. Stored under the top-level
// `seriesAutopilot` settings key (NOT on the federated series record — a
// schedule that synced to a peer would double-run the same series). Each entry
// is OFF by default (`enabled` defaults false); the run itself still passes
// through the cos-domain autonomy gate + daily budget inside startSeriesAutopilot.
// provider/model are OPTIONAL overrides — when absent the run uses the series'
// own `series.llm` (or the active provider); the scheduler maps them to the
// pipeline's providerOverride/modelOverride. A blank provider/model (UI sentinel
// for "use the series default") is coerced to undefined so it doesn't pin an
// empty string. Other autopilot run options are intentionally NOT accepted here:
// there's no UI producing them, so a scheduled run uses the series' persisted
// defaults for those (add a field only when a control exists to set it).
// Cron syntax/range validation lives in the pure leaf `cronValidation.js` so the
// scheduler, every save boundary, and the browser cron editor share ONE
// implementation (#6634). Re-exported here because callers already reach for
// `isValidCronExpression` through validation.js. Rejects a 5-token-but-out-of-
// range cron like `99 99 * * *` at the PUT boundary (a 400 the UI surfaces)
// instead of letting it be saved+enabled and then silently dropped by
// activeSchedules — which would leave the user with an "enabled" schedule that
// never fires (#2174).
export { isValidCronExpression, isCronShaped, findCronExpressionError } from './cronValidation.js';
export const seriesAutopilotScheduleSchema = z.object({
seriesId: z.string().min(1).max(64),
enabled: z.boolean().optional().default(false),
cron: z.string().min(1).max(120).refine(isValidCronExpression, 'invalid cron expression'),
timezone: z.string().min(1).max(64).optional(),
provider: z.preprocess((v) => (v === '' ? undefined : v), providerRefSchema.optional()),
model: z.preprocess((v) => (v === '' ? undefined : v), z.string().min(1).max(200).optional()),
// Optional per-schedule reasoning effort (#3641), mapped to the run's
// `effortOverride`. Validated against the union of accepted levels across
// effort-capable CLIs; the runner clamps a level the chosen provider doesn't
// offer and drops it for a provider with no effort control.
effort: z.preprocess((v) => (v === '' ? undefined : v), z.enum(EFFORT_LEVELS).optional()),
// Run every stage on the provider/model above, ignoring the per-stage pins
// from the Prompts page. Absent falls through to the persisted
// pipelineEditorialChecks setting, then off.
overrideStagePins: z.boolean().optional(),
}).strict();
export const seriesAutopilotSettingsSchema = z.object({
schedules: z.array(seriesAutopilotScheduleSchema).optional().default([]),
}).strict();
// Per-API external-access flags (issue: public API surface). Stored under the
// top-level `apiAccess` settings key (client-readable — NOT under `secrets`).
// Drives `server/lib/apiRegistry.js`: an entry that is `exposed && !requireAuth`
// re-opens its public mount even when the PortOS password is on. Both flags are
// optional so a partial PUT only patches what it carries; the registry fills
// absent flags from its per-API defaults (exposed:false, requireAuth:false).
export const apiAccessEntrySchema = z.object({
exposed: z.boolean().optional(),
requireAuth: z.boolean().optional(),
}).strict();
export const apiAccessSettingsSchema = z.object({
voice: apiAccessEntrySchema.optional(),
sdapi: apiAccessEntrySchema.optional(),
}).strict();
// Install-local feature participation flags. `instanceFeatureRegistry.js` owns
// the available feature ids and both schemas derive from it, so registering a
// feature there needs no edit here; the schemas keep generic settings saves from
// persisting an unknown or malformed feature state.
export const instanceFeatureSettingsSchema = z.object(
Object.fromEntries(INSTANCE_FEATURE_IDS.map((id) => [
id,
z.object({ enabled: z.boolean().optional() }).strict().optional(),
]))
).strict();
export const instanceFeatureIdSchema = z.enum([...INSTANCE_FEATURE_IDS]);
// `enabled: null` is the tri-state override going back to "inherit" — it clears
// the stored value rather than writing a third sentinel, so a grouped feature's
// resolution falls through to its group's `enabled` flag (see resolveOne in
// services/instanceFeatures.js). Every existing caller sends a real boolean;
// only the grouped-feature override control in Settings > Features sends null.
export const instanceFeatureUpdateSchema = z.object({
enabled: z.boolean().nullable(),
}).strict();
// Install-local feature GROUP participation flags. A group has no inherit
// state of its own — just an on/off default-true toggle — so unlike
// instanceFeatureUpdateSchema above this stays non-nullable.
export const instanceFeatureGroupSettingsSchema = z.object(
Object.fromEntries(INSTANCE_FEATURE_GROUP_IDS.map((id) => [
id,
z.object({ enabled: z.boolean().optional() }).strict().optional(),
]))
).strict();
export const instanceFeatureGroupIdSchema = z.enum([...INSTANCE_FEATURE_GROUP_IDS]);
export const instanceFeatureGroupUpdateSchema = z.object({
enabled: z.boolean(),
}).strict();
export const subdirFilterSchema = z.string()
.refine(isSafeSubdirFilter, 'subdirFilter must be a relative path with no wildcard, ".." , or leading "/" segments');
export const snapshotSourceSchema = z.string()
.refine(isSafeSnapshotSource, 'source must be "@legacy" or a single machine-name segment');
export const snapshotDownloadQuerySchema = z.object({
source: snapshotSourceSchema.optional(),
}).strict();
export const restoreRequestSchema = z.object({
snapshotId: z.string().min(1),
source: snapshotSourceSchema.optional(),
subdirFilter: subdirFilterSchema.optional().nullable(),
dryRun: z.boolean().optional().default(true),
// Install a snapshot's different federation identity over this machine's (#12596).
adoptIdentity: z.boolean().optional().default(false)
});
export const restoreDbRequestSchema = z.object({
snapshotId: z.string().min(1),
source: snapshotSourceSchema.optional(),
dryRun: z.boolean().optional().default(true)
});
// Resume a committed snapshot database restore awaiting recovery (#9725). The
// id must name the pending operation; recovery never replays the dump.
export const restoreDbRecoverRequestSchema = z.object({
id: z.string().uuid(),
}).strict();
// Per-feature AI provider assignment: which configured CLI provider/model a
// feature runs through (e.g. `settings.autofixer`, `settings.calendarSync`).
// Empty string (UI "unset" sentinel) is coerced to undefined so it round-trips
// as "use the default" rather than a bogus id. Both the autofixer (file edits
// + pm2) and Google Calendar MCP sync require an agentic CLI provider; the
// picker resolution layer (`pickCliProvider`) enforces type 'cli'.
// `emptyToUndefined` now lives in zodCompat.js (so per-domain schema files can
// use it without a cycle through this module) — re-exported for deep imports.
export { emptyToUndefined };
export const featureProviderConfigSchema = z.object({
providerId: z.preprocess(emptyToUndefined, providerRefSchema.optional()),
model: z.preprocess(emptyToUndefined, z.string().optional()),
});
// Autofixer settings extend the shared provider assignment with its isolation
// controls. `autoPromote` (default off) is the explicit promotion gate: when
// false the autonomous repair only STAGES a validated patch for review; when
// true a validated (and, if set, verified) diff is applied to the live checkout
// and the process restarted. `verifyCommand` runs in the isolated worktree
// before any change reaches live. See autofixer/sandbox.js.
export const autofixerSettingsSchema = featureProviderConfigSchema.extend({
autoPromote: z.boolean().optional(),
verifyCommand: z.preprocess(emptyToUndefined, z.string().max(500).optional()),
});
// Music settings slice (#2911). `chiptune` remembers the Track editor's last
// chiptune generation provider/model pin plus the publish preferences (target
// managed app + subdir inside its repo). `designer` (#4305) is the Generate
// tab's stepped music designer: its provider/model/effort pin plus optional
// meta-prompt overrides for the describe + lyrics steps (a blank override falls
// back to the shipped default server-side, in services/musicDesigner.js).
// Reuses the shared feature-provider shape so an empty-string picker value
// normalizes to unset. Every key stays optional so an older client PUTting only
// `{ chiptune }` — or only `{ designer }` — still validates.
export const musicSettingsSchema = z.object({
chiptune: featureProviderConfigSchema.extend({
publishAppId: z.preprocess(emptyToUndefined, z.string().max(120).optional()),
publishSubdir: z.preprocess(emptyToUndefined, z.string().max(200).optional()),
}).partial().optional(),
designer: featureProviderConfigSchema.extend({
effort: z.preprocess(emptyToUndefined, z.string().max(64).optional()),
describeTemplate: z.preprocess(emptyToUndefined, z.string().max(8000).optional()),
lyricsTemplate: z.preprocess(emptyToUndefined, z.string().max(8000).optional()),
}).partial().optional(),
});
// Federated media is an opt-in provider surface. The outer objects remain
// passthrough for mixed-version peers/settings UIs: a rolled-back install must
// preserve fields introduced by a newer build while still validating every
// field this build understands.
export const federatedMediaModelSchema = z.object({
engine: z.string().trim().min(1).max(80),
modelId: z.string().trim().min(1).max(256),
}).passthrough();
const federatedMediaModelListSchema = z.array(federatedMediaModelSchema).max(100).refine(
(models) => new Set(models.map((model) => `${model.engine}\u0000${model.modelId}`)).size === models.length,
{ message: 'models must not contain duplicate engine/model pairs' },
);
// Image/video federation shares this same model-pair shape (`{ engine,
// modelId }`) as audio for wire uniformity, but only `engine: 'local'`
// resolves to a live capability today — the provider only has readiness
// signals for this install's own local generator, not the cloud-CLI image/
// video backends (codex/grok/agy/external), which spend a *provider's own*
// account quota rather than sharing this machine's GPU. A peer that
// configures a non-local engine simply reports 'unknown-engine' and never
// admits a job, so this schema doesn't need to special-case it.
export const federatedMediaProviderSettingsSchema = z.object({
enabled: z.boolean().optional(),
maxQueuedJobs: z.number().int().min(1).max(20).optional(),
audioModels: federatedMediaModelListSchema.optional(),
imageModels: federatedMediaModelListSchema.optional(),
videoModels: federatedMediaModelListSchema.optional(),
}).passthrough();
// Consumer-side peer selection is independent from the provider's local queue
// limit. Unknown fields stay round-trip-safe across mixed-version Instances
// clients while known model pairs remain unique and bounded.
export const federatedMediaPeerSettingsSchema = z.object({
enabled: z.boolean().optional(),
audioModels: federatedMediaModelListSchema.optional(),
imageModels: federatedMediaModelListSchema.optional(),
videoModels: federatedMediaModelListSchema.optional(),
}).passthrough();
// Where UNATTENDED jobs (Creative Director / Creative Commission) of a given
// kind render. One peer + one model per kind, chosen by the local operator and
// stored server-side, so an LLM planner never names a peer. Nullable because
// clearing a kind is how routing is turned back off — an absent key means
// "unchanged", an explicit null means "render locally again".
export const federatedMediaRouteSchema = z.object({
peerId: z.string().trim().min(1).max(200),
engine: z.string().trim().min(1).max(80),
modelId: z.string().trim().min(1).max(256),
}).strict();
export const federatedMediaRoutingSchema = z.object({
image: federatedMediaRouteSchema.nullable().optional(),
video: federatedMediaRouteSchema.nullable().optional(),
}).passthrough();
export const federationSettingsSchema = z.object({
strictPullAuthorization: z.boolean().optional(),
mediaProvider: federatedMediaProviderSettingsSchema.optional(),
mediaRouting: federatedMediaRoutingSchema.optional(),
}).passthrough();
export const federatedMediaJobRoutingSchema = z.object({
engine: z.string().trim().min(1).max(80),
modelId: z.string().trim().min(1).max(256),
durationSec: z.number().finite().min(1).max(3600).optional(),
durationMode: z.enum(['auto', 'manual']).optional(),
}).strict();
// Provider submissions accept model selection, the canonical fixed-vocabulary
// instrumental prompt, and — since ADR
// docs/decisions/2026-08-22-federated-media-input-assets.md rule 2 — free-form
// lyrics. The asymmetry between the two text fields is deliberate rather than
// inconsistent: a style/mood/instrument profile renders `prompt` with no
// expressive loss, so the privacy-safe canonical form is required there; lyrics
// ARE the words, so no alphabet encodes them without discarding them, and they
// cross verbatim under the same submission-body rule image/video prompts do.
// The provider still refuses them for a model whose capability reports
// `lyrics: false`. URLs, paths, commands, provider credentials, and unknown
// fields are excluded by the strict object as before.
const federatedMediaAudioJobSubmissionSchema = federatedMediaJobRoutingSchema.extend({
kind: z.literal('audio'),
prompt: z.string().trim().min(1).max(8000),
lyrics: z.string().max(50_000).optional(),
}).strict().superRefine((value, ctx) => {
if (!isFederatedMediaAudioPrompt(value.prompt)) {
ctx.addIssue({
code: 'custom',
path: ['prompt'],
message: 'prompt must be rendered from a privacy-safe federated audio profile',
});
}
});
// Image/video prompts cross as submitted, with no fixed-vocabulary rendering
// like audio's: there is no closed taxonomy for arbitrary visual/motion content
// the way audio has a finite style/mood/instrument alphabet. Why that does not
// breach the "no PII on federation" rule — a submitted job body is not a status
// payload, and status/capability payloads stay absolutely prompt-free — is
// ADR docs/decisions/2026-08-20-federated-visual-prompts.md.
//
// Conditioning IMAGES ride the same rule (ADR
// docs/decisions/2026-08-22-federated-media-input-assets.md rule 1), by id
// rather than by value: the bytes went up through the authenticated,
// digest-verified asset endpoint first. What is still refused here — and refused
// by the routes, since neither has a field to name it — is a MODEL (LoRA
// weights, rule 3) and multi-step CHAIN STATE (a video to extend, chained
// chunks, IC-LoRA references, rule 4).
// Exported UN-REFINED as well, and the split is load-bearing rather than
// cosmetic. The cross-field rule below pairs `initImageStrength` with
// `initImage` — but a conditioning image reaches the body as an asset id
// resolved immediately BEFORE submission, so the persisted marker legitimately
// carries the strength with no image beside it yet. The marker and the request
// builder validate against the base; the provider route, which sees the fully
// assembled body, validates against the refined schema.
export const federatedMediaImageJobSubmissionBaseSchema = federatedMediaJobRoutingSchema.omit({
durationSec: true, durationMode: true,
}).extend({
kind: z.literal('image'),
prompt: z.string().trim().min(1).max(4000),
negativePrompt: z.string().trim().max(4000).optional(),
width: imageEdgeSchema,
height: imageEdgeSchema,
steps: z.number().int().min(1).max(150).optional(),
guidance: z.number().finite().min(0).max(30).optional(),
seed: z.number().int().min(0).optional(),
initImage: federatedMediaInputAssetRefSchema.optional(),
initImageStrength: z.number().finite().min(0).max(1).optional(),
referenceImages: z.array(federatedMediaInputAssetRefSchema)
.max(FEDERATED_MEDIA_ASSET_MAX_COUNT).optional(),
}).strict()
.refine(refineImagePixelCap, { message: PIXEL_CAP_MESSAGE, path: ['width'] });
export const federatedMediaImageJobSubmissionSchema = federatedMediaImageJobSubmissionBaseSchema
// A strength with nothing to apply it to is a caller bug, not a default to
// guess at: silently ignoring it renders at full denoise, which is the
// opposite of what a low strength asked for.
.refine((value) => value.initImageStrength === undefined || value.initImage !== undefined, {
message: 'initImageStrength requires an initImage',
path: ['initImageStrength'],
});
// Same boundary as the image schema above — see the ADRs named there.
//
// Exported UN-REFINED as well: `negotiateVideoConstraints` re-validates a
// partially-negotiated body against `.partial()`, and Zod refuses `.partial()`
// on a schema carrying refinements. Splitting the object from its cross-field
// rule keeps both callers honest instead of dropping the rule to keep the
// partial working.
export const federatedMediaVideoJobSubmissionBaseSchema = federatedMediaJobRoutingSchema.omit({
durationSec: true, durationMode: true,
}).extend({
kind: z.literal('video'),
prompt: z.string().trim().min(1).max(4000),
negativePrompt: z.string().trim().max(4000).optional(),
width: z.number().int().min(64).max(2048).optional(),
height: z.number().int().min(64).max(2048).optional(),
numFrames: z.number().int().min(1).max(FEDERATED_MEDIA_MAX_VIDEO_FRAMES).optional(),
fps: z.number().int().min(1).max(60).optional(),
steps: z.number().int().min(1).max(150).optional(),
guidance: z.number().finite().min(0).max(30).optional(),
seed: z.number().int().min(0).optional(),
sourceImage: federatedMediaInputAssetRefSchema.optional(),
lastImage: federatedMediaInputAssetRefSchema.optional(),
sourceAudio: federatedMediaInputAssetRefSchema.optional(),
audioConditioning: federatedSourceAudioSchema.optional(),
}).strict();
export const federatedMediaVideoJobSubmissionSchema = federatedMediaVideoJobSubmissionBaseSchema
.refine((v) => Boolean(v.sourceAudio) === Boolean(v.audioConditioning), {
message: 'sourceAudio and audioConditioning must be supplied together',
})
.refine((v) => !v.audioConditioning || (v.fps !== undefined && v.numFrames !== undefined), {
message: 'Source audio requires explicit fps and numFrames for its exact window',
})
.refine((v) => !v.sourceAudio || (!v.lastImage && v.sourceAudio.assetId.endsWith(v.audioConditioning?.clipSha256 || '!')), {
message: 'Source audio must match its clip digest and cannot combine with an end frame',
})
// First-last-frame needs both ends. A lone end frame would render a plain
// text-to-video clip and quietly discard the frame the caller supplied.
.refine((value) => value.lastImage === undefined || value.sourceImage !== undefined, {
message: 'lastImage requires a sourceImage (first-last-frame needs both ends)',
path: ['lastImage'],
});
// An already-shipped consumer's request body never carries `kind` — it only
// knows the pre-existing audio-only shape. Defaulting the missing field to
// 'audio' before the discriminated union runs keeps that body validating
// exactly as before; a new consumer names its kind explicitly.
export const federatedMediaJobSubmissionSchema = z.preprocess(
(value) => (isPlainObject(value) && value.kind === undefined ? { ...value, kind: 'audio' } : value),
z.discriminatedUnion('kind', [
federatedMediaAudioJobSubmissionSchema,
federatedMediaImageJobSubmissionSchema,
federatedMediaVideoJobSubmissionSchema,
]),
);
export const federatedMediaIdempotencyKeySchema = z.string().trim().min(1).max(200)
.regex(/^[A-Za-z0-9._:-]+$/, 'Idempotency-Key contains unsupported characters');
export const federatedMediaJobParamsSchema = z.object({
id: z.string().uuid(),
}).strict();
export const federatedMediaStatusQuerySchema = z.object({
kinds: z.string().trim().max(40).regex(/^[a-z]+(,[a-z]+)*$/).optional(),
}).passthrough();
// Creative Director settings slice. Each LLM-backed stage can pin its own
// provider/model instead of inheriting the system default. `evaluation` is a
// direct vision API call (blank = auto-pick a local vision model, else fall
// back to the coding agent); treatment and plan run as CoS agent tasks.
// Reuses the shared feature-provider shape so an empty-string picker value
// normalizes to unset.
export const creativeDirectorSettingsSchema = z.object({
treatment: featureProviderConfigSchema.partial().optional(),
plan: featureProviderConfigSchema.partial().optional(),
evaluation: featureProviderConfigSchema.partial().optional(),
});
/**
* Validate data against a schema
* Returns { success: true, data } or { success: false, errors }
*/
export function validate(schema, data) {
const result = schema.safeParse(data);
if (result.success) {
return { success: true, data: result.data };
}
return {
success: false,
errors: result.error.issues.map(e => ({
path: e.path.join('.'),
message: e.message
}))
};
}
// =============================================================================
// SCAFFOLD (app generator)
// =============================================================================
// Known scaffold templates — the single source of truth for the enum the
// scaffold route accepts. An unknown template MUST be rejected before any
// filesystem write or subprocess spawn (issue #2390), so the route can no
// longer create a target directory for a template it can't actually build.
export const SCAFFOLD_TEMPLATES = [
'portos-stack',
'vite-express',
'vite-react',
'express-api',
'ios-native',
'xcode-multiplatform'
];
// Ports may arrive absent (auto-allocated by the route) or as an explicit
// number. Tolerate the UI '' sentinel as "not provided"; anything else must be
// a valid TCP port so an out-of-range value is rejected deterministically.
const scaffoldPortSchema = z.preprocess(
emptyToUndefined,
z.number().int().min(1).max(65535).nullable().optional()
);
// GET /api/scaffold/directories. `includeFiles` is a query flag, so it arrives
// as the string 'true' rather than a boolean. The path is not trimmed: a
// directory name may legitimately begin or end with whitespace.
export const scaffoldDirectoriesQuerySchema = z.object({
path: z.string().min(1).max(4096).optional(),
includeFiles: z.enum(['true', 'false']).optional(),
});
// Full request schema for POST /api/scaffold. Validated before the route
// touches the filesystem — template enum, port range, and a name that yields a
// usable directory slug are all enforced up front.
export const scaffoldSchema = z.object({
name: z.string().trim().min(1).max(100)
// The route sanitizes name → [a-z0-9-]; a name with no alphanumerics
// slugifies to an all-dash/empty dirName. Reject it here rather than
// creating a garbage directory.
.refine(v => /[a-z0-9]/i.test(v), {
message: 'name must contain at least one letter or number'
}),
template: z.enum(SCAFFOLD_TEMPLATES),
parentDir: z.string().trim().min(1),
uiPort: scaffoldPortSchema,
apiPort: scaffoldPortSchema,
createGitHubRepo: z.boolean().optional().default(false),
githubOrg: z.preprocess(emptyToNull, z.string().min(1).nullable().optional())
});
// =============================================================================
// USAGE (devtools usage reports)
// =============================================================================
// Shape AND calendar validity — the regex alone accepts impossible dates like
// 2026-02-30, which would silently return an empty report instead of a 400.
const isoDay = z.string()
.regex(/^\d{4}-\d{2}-\d{2}$/, 'Expected YYYY-MM-DD')
.refine((s) => {
const d = new Date(`${s}T00:00:00Z`);
return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s;
}, { message: 'Not a valid calendar date' });
/**
* Query params for GET /api/usage — either a preset period or an explicit
* from/to date range (inclusive, YYYY-MM-DD). Explicit dates win over period.
*/
export const usageQuerySchema = z.object({
period: z.enum(['7d', '30d', '90d', 'all']).optional(),
from: isoDay.optional(),
to: isoDay.optional()
}).refine((q) => !(q.from && q.to) || q.from <= q.to, { message: 'from must be on or before to' });
/** Query for GET /api/usage/rolling-cost — the chart's span, independent of the report window. */
export const usageRollingCostQuerySchema = z.object({
range: z.enum(['1m', '3m', '6m', '1y', 'all']).optional()
});
/** Query for GET /api/usage/providers. `family` narrows the read to a single
* quota card (the per-card Refresh on the usage page) so one slow TUI scrape
* isn't paid for every provider at once. */
export const providerUsageQuerySchema = z.object({
refresh: z.enum(['0', '1', 'true', 'false']).optional(),
family: z.string().regex(/^[a-z0-9-]{1,32}$/, 'family must be a provider family id').optional(),
period: z.enum(['24h', '7d', '30d', 'week', 'month', 'reset']).optional(),
});
/** Body for POST /api/usage/messages — token counts persist forever, so
* reject non-integer/negative garbage instead of coercing it into counters. */
export const usageMessagesSchema = z.object({
providerId: z.string().min(1),
model: z.string().nullish(),
messageCount: z.number().int().nonnegative(),
tokenCount: z.number().int().nonnegative().optional().default(0),
inputTokenCount: z.number().int().nonnegative().optional().default(0)
});
/** Body for POST /api/usage/tokens — same guard as messages: no string or negative totals. */
export const usageTokensSchema = z.object({
inputTokens: z.number().int().nonnegative().optional().default(0),
outputTokens: z.number().int().nonnegative().optional().default(0)
});
/** Body for POST /api/usage/session — model/providerName become persisted keys/values. */
export const usageSessionSchema = z.object({
providerId: z.string().min(1),
providerName: z.string().max(200).optional(),
model: z.string().max(200).nullish()
});
/**
* What the user pays monthly for each provider family's quota plan, keyed by
* family id. Used by BOTH write paths — `PUT /api/usage/subscriptions` (wrapped
* below) and the `subscriptionCosts` slice of `PUT /api/settings` — so a price
* can't be written past validation through the generic settings endpoint.
*
* Keys are the real family ids, not a loose id pattern: this gates a PERSISTED
* write, and an arbitrary key would accumulate in settings.json with no editor
* row that could ever clear it. `null` is accepted and meaningful — it CLEARS a
* plan's price (the user cancelled it), which an omitted key must not do, since
* the editor submits only the rows it knows about. Prices are plain USD dollars
* (cents allowed), capped at `MAX_MONTHLY_COST` so a mistyped extra digit can't
* swamp every savings figure on the page.
*/
// `partialRecord`, not `record`: with an enum key schema Zod 4's `record` is
// EXHAUSTIVE — it would demand a price for every family on every save, which is
// the opposite of the patch semantics the editor relies on.
export const subscriptionCostsMapSchema = z.partialRecord(
z.enum(PROVIDER_FAMILY_IDS),
z.number().min(0).max(MAX_MONTHLY_COST).nullable()
);
/**
* Which TIER of each family's plan the user is on, keyed by family id. Same
* key rule and same patch semantics as the price map above — an omitted family
* keeps its stored tier, `null` (or an empty string, which normalizes to null)
* CLEARS it. Free text rather than an enum because these are vendor marketing
* names ("Max 20x", "Pro") that change on the vendor's schedule, not on the
* PortOS release cycle; the length cap is what keeps settings.json from
* collecting notes.
*
* Used by BOTH write paths — `PUT /api/usage/subscriptions` and the
* `subscriptionPlanTiers` slice of `PUT /api/settings`.
*/
export const subscriptionPlanTiersMapSchema = z.partialRecord(
z.enum(PROVIDER_FAMILY_IDS),
z.string().max(MAX_PLAN_TIER_LENGTH).nullable()
);
/**
* Body for PUT /api/usage/subscriptions. Both slices are OPTIONAL and
* independent: the price editor sends only `costs`, the plan editor only
* `tiers`, and neither save may disturb the other's stored map.
*/
export const subscriptionsUpdateSchema = z.object({
costs: subscriptionCostsMapSchema.optional(),
tiers: subscriptionPlanTiersMapSchema.optional(),
});
/**
* Body for PUT /api/usage/subscriptions/enabled — switch one subscription on or
* off. `family` is enumerated, not free text, because the handler fans the flag
* out across every provider record that family owns.
*/
export const subscriptionEnabledSchema = z.object({
family: z.enum(PROVIDER_FAMILY_IDS),
enabled: z.boolean(),
});
/**
* Instances that pay API rates rather than the viewer's subscriptions, so the
* Across Instances combined total can leave them out. Used by BOTH write
* paths — `PUT /api/usage/fleet-billing` (the per-row toggle) and the
* `usageApiBilledInstanceIds` slice of `PUT /api/settings` — so a restore
* dump can't write an unbounded or non-string list through the generic
* settings endpoint. Cap matches the stored peer-digest cap (64).
*/
export const usageApiBilledInstanceIdsSchema = z.array(z.string().min(1).max(200)).max(64);
/** Body for PUT /api/usage/fleet-billing. */
export const usageFleetBillingSchema = z.object({
instanceId: z.string().min(1).max(200),
usesSubscriptions: z.boolean(),
});
// =============================================================================
// PORTS
// =============================================================================
// POST /api/ports/check — probe a set of ports for availability.
export const portsCheckSchema = z.object({
ports: z.array(z.number().int().min(1).max(65535)).min(1)
});
// POST /api/ports/allocate — reserve N free ports. `count` accepts a number or
// a numeric string (the UI may send either) and defaults to 1 when absent,
// matching the prior `parseInt(count) || 1` behavior — but non-numeric garbage
// now 400s instead of silently collapsing to 1. The preprocess only forwards
// number|string so `z.coerce` can't quietly turn a boolean (`true → 1`) or an
// array (`[5] → 5`) into a valid count.
export const portsAllocateSchema = z.object({
count: z.preprocess(
(v) => {
if (v === undefined) return 1;
return (typeof v === 'number' || typeof v === 'string') ? v : NaN;
},
z.coerce.number().int().min(1).max(10)
)
});
// =============================================================================
// DATA MANAGER
// =============================================================================
// DELETE /api/data/:category — purge a category, or one entry inside it.
// `subPath` names a single top-level entry of the category directory; omitting
// it asks for the whole-directory wipe, which `purgeCategory` only honors for
// `purgeScope: 'category'` entries (#3327). `isTopLevelEntryName` in
// `fileUtils.js` is the authoritative gate — it runs in `purgeCategory`, which
// is the boundary a non-HTTP caller crosses too. The separator check is spelled
// out here rather than imported so this module keeps its narrow import surface
// (a partial mock of fileUtils in an unrelated suite would break schema
// construction at module load).
export const dataPurgeSchema = z.object({
subPath: z.string().min(1).max(255)
.refine(
(v) => !v.includes('/') && !v.includes('\\') && v !== '.' && v !== '..',
'subPath must name a single entry in the category'
)
.optional()
});
// =============================================================================
// DATABASE
// =============================================================================
const DB_BACKENDS = ['docker', 'native'];
// POST /api/database/switch — switch active backend, optionally migrating data.
export const databaseSwitchSchema = z.object({
target: z.enum(DB_BACKENDS),
migrate: z.boolean().optional()
});
// POST /api/database/maintenance/preflight — advisory only; never accepts a cutover.
export const databaseMaintenancePreflightSchema = z.object({
source: z.enum(DB_BACKENDS),
target: z.enum(DB_BACKENDS)
}).strict().refine(value => value.source !== value.target, { message: 'Source and target must differ' });
// POST /api/database/maintenance/cutover — accepts the offline cutover (202).
export const databaseMaintenanceCutoverSchema = databaseMaintenancePreflightSchema;
// POST /api/database/maintenance/recover — same-operation recovery only.
export const databaseMaintenanceRecoverSchema = z.object({ id: z.string().uuid() }).strict();
// POST /api/database/{start,stop,destroy} — operate on a named backend.
export const databaseBackendSchema = z.object({
backend: z.enum(DB_BACKENDS)
});
// POST /api/database/export — export from a specific backend, or (when omitted)
// the active backend.
export const databaseExportSchema = z.object({
backend: z.enum(DB_BACKENDS).optional()
});
// Dismissible system health warnings — see server/routes/systemHealth.js.
// Probe failures are intentionally excluded: a missing measurement cannot be dismissed.
export const SYSTEM_HEALTH_WARNING_TYPES = ['memory', 'cpu', 'disk', 'data-disk', 'process', 'restarts', 'apps', 'database', 'forge', 'code-review', 'health-settings'];
export const systemHealthWarningParamsSchema = z.object({ type: z.enum(SYSTEM_HEALTH_WARNING_TYPES) });
export const systemHealthWarningDismissSchema = z.object({ message: z.string().trim().min(1).max(500) });
export const appIconQuerySchema = z.object({
size: z.enum(['64', '128', '256']).default('128').transform(Number),
});
// Read-route query contracts: a malformed limit is a 400, never a silent
// negative slice or an ignored NaN.
export const listNotificationsQuerySchema = z.object({
type: z.enum(Object.values(NOTIFICATION_TYPES)).optional(),
unreadOnly: z.enum(['true', 'false']).optional(),
limit: z.coerce.number().int().min(1).max(1000).optional(),
});
export const agentToolsFeedQuerySchema = z.object({
accountId: z.string().min(1),
sort: z.enum(['hot', 'new', 'top', 'rising']).default('hot'),
limit: z.coerce.number().int().min(1).max(100).default(25),
});
export const agentToolsRelevantPostsQuerySchema = z.object({
agentId: z.string().min(1),
accountId: z.string().min(1),
maxResults: z.coerce.number().int().min(1).max(100).default(10),
});
/**
* Validate data against a Zod schema, throwing on failure.
* Returns parsed data on success, throws ServerError on failure.
*/
export function validateRequest(schema, data) {
const result = schema.safeParse(data);
if (result.success) return result.data;
const errors = result.error.issues.map(e => ({
path: e.path.join('.'),
message: e.message
}));
throw new ServerError('Validation failed', {
status: 400,
code: 'VALIDATION_ERROR',
context: { details: errors }
});
}
// Media cancellation bodies (#9932). An OMITTED jobId keeps the legacy
// "newest/running job" selection; a SUPPLIED jobId must be a usable id — a
// malformed one (array, object, null, blank) is a 400, never silently treated
// as absent, because absent selects a different live render to cancel.
export const mediaCancelJobIdSchema = z.string().trim().min(1).max(200);
export const imageCancelBodySchema = z.object({
jobId: mediaCancelJobIdSchema.optional(),
all: z.boolean().optional(),
});
export const videoCancelBodySchema = z.object({
jobId: mediaCancelJobIdSchema.optional(),
});
export const rapidReaderLibraryParamsSchema = z.object({ id: z.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/) });
export const rapidReaderLibraryCreateSchema = z.object({ title: z.string().trim().min(1).max(200), author: z.string().trim().max(200).optional(), text: z.string().trim().min(1).max(2 * 1024 * 1024) });
export const rapidReaderLibraryFetchSchema = z.object({ url: z.string().trim().url().max(2000).refine((value) => /^https?:\/\//i.test(value), 'url must be http(s)'), title: z.string().trim().min(1).max(200).optional() });
// =============================================================================
// SHELL
// =============================================================================
// POST /api/shell/sessions/:sessionId/image — hand a photo to whatever is running
// in a shell session. `data` is base64 image bytes; the real ceiling is enforced
// by `saveImageUpload` (MAX_SCREENSHOT_BYTES) against the DECODED buffer, so the
// cap here only refuses a payload too large to be worth decoding. The message cap
// matches the BTW route's — both end up bracket-pasted into the same TUI prompt.
export const shellImageDropSchema = z.object({
data: z.string().min(1, 'data is required (base64)').max(64 * 1024 * 1024),
filename: z.string().min(1, 'filename is required').max(255),
message: z.string().max(5000).optional()
});
// =============================================================================
// USER ACTION LEDGER
// =============================================================================
// GET /api/user-actions — read the machine-local operator-action ledger (#5594).
// Every value arrives as a query string, so numbers are coerced and `success` is
// the string form of the boolean. Range checking is deliberately loose here and
// the CLAMP lives in `userActions.normalizeListOptions`: a caller asking for 5000
// rows wants "as many as you will give me", not a 400.
const isParseableDate = (value) => !Number.isNaN(new Date(value).getTime());
const userActionDateFilter = z.string().trim().min(1).max(64)
.refine(isParseableDate, 'must be a parseable date');
const userActionType = z.enum([...USER_ACTION_TYPES]);
export const userActionsListQuerySchema = z.object({
type: userActionType.optional(),
// Repeated `?types=a&types=b` arrives as an array; a single one as a string.
types: z.union([userActionType, z.array(userActionType)]).optional(),
actor: z.enum([...USER_ACTION_ACTORS]).optional(),
target: z.string().trim().min(1).max(200).optional(),
success: z.enum(['true', 'false']).optional(),
from: userActionDateFilter.optional(),
to: userActionDateFilter.optional(),
limit: z.coerce.number().int().optional(),
offset: z.coerce.number().int().optional(),
});
// =============================================================================
// AGENT ACTIVITY LOG (server/routes/agentActivity.js)
// =============================================================================
// The activity log is a per-agent, per-day tree of JSON files under
// `data/agents/activity/<agentId>/<YYYY-MM-DD>.json`. Two things follow:
// `agentId` is interpolated into a filesystem path, so it is held to a bare
// filename segment (`isSafeRecordId` on top of the charset, so `..` can't turn
// a read into a traversal); and the read limits are CLAMPED here rather than in
// the service, because every handler slices an already-loaded array — an
// unbounded `limit` is a memory/response-size problem, not a query cost.
const AGENT_ACTIVITY_MAX_LIMIT = 500;
const agentActivityLimit = (defaultLimit) =>
z.coerce.number().int().min(1).max(AGENT_ACTIVITY_MAX_LIMIT).default(defaultLimit);
// A blank query value (`?action=` from an unset form field) reads as absent
// rather than as a 400 — it was `action || null` before this schema existed.
const agentActivityAction = z.preprocess(emptyToUndefined, z.string().trim().min(1).max(64).optional());
const agentActivityIds = csvIdsParam({ max: 50, maxIdLength: 128 });
// GET /api/agents/activity
export const agentActivityQuerySchema = z.object({
limit: agentActivityLimit(50),
agentIds: agentActivityIds,
action: agentActivityAction,
}).strict();
// GET /api/agents/activity/timeline — `before` is an infinite-scroll cursor the
// client echoes back from a row's `timestamp`, so it is a full ISO instant.
export const agentActivityTimelineQuerySchema = z.object({
limit: agentActivityLimit(50),
agentIds: agentActivityIds,
// One action or a comma-separated list (the Moltworld history asks for every mw_* kind).
action: csvIdsParam({ max: 10, maxIdLength: 64 }),
before: z.preprocess(emptyToUndefined, z.string().datetime().optional()),
}).strict();
export const agentActivityAgentParamsSchema = z.object({
agentId: z.string().trim().min(1).max(128)
.regex(/^[A-Za-z0-9._-]+$/, 'agentId must be alphanumeric with . _ -')
.refine(isSafeRecordId, 'agentId must be a bare filename segment'),
}).strict();
// GET /api/agents/activity/agent/:agentId — `date` stays a `YYYY-MM-DD` STRING
// all the way to `getActivityFilePath`, which takes that form directly. Parsing
// it to a Date first would re-derive the day in local time from a UTC midnight
// and read the neighbouring file for anyone west of UTC.
export const agentActivityAgentQuerySchema = z.object({
date: z.preprocess(emptyToUndefined, z.string().date().optional()),
limit: agentActivityLimit(100),
offset: z.coerce.number().int().min(0).default(0),
action: agentActivityAction,
}).strict();
// GET /api/agents/activity/agent/:agentId/stats — one file read per day, so the
// window is capped at a year rather than left open.
export const agentActivityStatsQuerySchema = z.object({
days: z.coerce.number().int().min(1).max(365).default(7),
}).strict();
// POST /api/agents/activity/cleanup — unlinks every activity file older than the
// window. The floor is 1 day, NOT 0: `daysToKeep: 0` puts the cutoff at now and
// deletes the whole archive, and a negative value reaches into future-dated
// files. "Delete everything" is not a retention window; if it is ever wanted it
// gets its own explicitly-named endpoint rather than riding this number.
export const agentActivityCleanupSchema = z.object({
daysToKeep: z.coerce.number().int().min(1).max(3650).default(30),
}).strict();
// GET /api/review/queue — pagination is opt-in so existing Review Hub clients
// keep receiving the legacy full-list envelope. Cursors are opaque and bounded
// before they reach the queue snapshot decoder.
export const reviewQueueQuerySchema = z.object({
limit: z.preprocess(emptyToUndefined, z.coerce.number().int().min(1).max(100).optional()),
cursor: z.preprocess(emptyToUndefined, z.string().trim().min(1).max(4096).optional()),
view: z.preprocess(emptyToUndefined, z.enum(['today', 'all', 'waiting', 'someday', 'history', 'snoozed']).optional()),
}).strict();
// =============================================================================
// CLIENT ERROR REPORT
// =============================================================================
// Browser-emitted error reports (window.onerror + unhandledrejection).
// The field caps here are outer bounds — anything bigger is a runaway producer
// and is refused before validation; the storage-size caps live in
// services/clientErrors.js and are intentionally lower (the Review Hub entry
// is a UI surface, not a forensic log).
export const CLIENT_ERROR_TYPES = ['error', 'unhandledrejection'];
export const clientErrorReportSchema = z.object({
type: z.enum(CLIENT_ERROR_TYPES),
message: z.string().min(1).max(2000),
stack: z.string().max(20000).optional(),
source: z.string().max(2000).optional(),
line: z.number().int().nonnegative().optional(),
column: z.number().int().nonnegative().optional(),
url: z.string().max(2000).optional(),
userAgent: z.string().max(1000).optional(),
});
// =============================================================================
// PAGINATION HELPERS
// =============================================================================
/**
* Parse a zero-based array index from an Express route parameter.
* @param {unknown} raw - Route parameter value
* @returns {number}
*/
export function parseIndexParam(raw) {
const index = Number(raw);
if (typeof raw !== 'string' || !/^\d+$/.test(raw) || !Number.isSafeInteger(index)) {
throw new ServerError('Invalid index', { status: 400, code: 'INVALID_INDEX' });
}
return index;
}
/**
* Parse limit/offset pagination from query params with defaults and clamping.
* @param {object} query - req.query object
* @param {object} options - { defaultLimit, maxLimit }
* @returns {{ limit: number, offset: number }}
*/
export function parsePagination(query, { defaultLimit = 50, maxLimit = 200 } = {}) {
const rawLimit = parseInt(query?.limit, 10);
const rawOffset = parseInt(query?.offset, 10);
const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, maxLimit) : defaultLimit;
const offset = Number.isFinite(rawOffset) && rawOffset >= 0 ? rawOffset : 0;
return { limit, offset };
}
// Express turns a repeated `?k=a&k=b` into an array; every field must be scalar
// before any cache read (#13150). Value leniency (bad/absent limit) stays in parsePagination.
export const messageInboxQuerySchema = z.object({
accountId: z.string().optional(),
search: z.string().optional(),
summary: z.string().optional(),
limit: z.string().optional(),
offset: z.string().optional()
});
/**
* Did the caller explicitly ask for pagination? True when either `limit` or
* `offset` is present in the query string. Lets a list endpoint stay
* backward-compatible (return the full array when neither is set) while opting
* into a bounded `{ items, total, limit, offset }` envelope the moment a client
* passes a pagination param.
* @param {object} query - req.query object
* @returns {boolean}
*/
export function isPaginationRequested(query) {
return query?.limit !== undefined || query?.offset !== undefined;
}
/**
* Slice an array into a bounded page using the same limit/offset parsing as
* `parsePagination`. Returns the page plus the metadata needed to render the
* envelope every paginated PortOS list endpoint shares.
* @param {Array} items - the full list (already filtered/sorted by the caller)
* @param {object} query - req.query object
* @param {object} options - { defaultLimit, maxLimit }
* @returns {{ items: Array, total: number, limit: number, offset: number }}
*/
export function paginateArray(items, query, options = {}) {
const list = Array.isArray(items) ? items : [];
const { limit, offset } = parsePagination(query, options);
return { items: list.slice(offset, offset + limit), total: list.length, limit, offset };
}
// =============================================================================
// SHARING (cross-network share buckets via cloud-synced folders)
// =============================================================================
export const bucketModeSchema = z.enum(['auto-merge', 'inbox']);
export const bucketCreateSchema = z.object({
name: z.string().trim().min(1).max(120),
path: z.string().trim().min(1).max(2000),
mode: bucketModeSchema.optional().default('inbox'),
displayNameOverride: z.string().trim().max(120).optional().nullable(),
bioOverride: z.string().trim().max(2000).optional().nullable(),
}).strict();
export const bucketUpdateSchema = z.object({
name: z.string().trim().min(1).max(120).optional(),
mode: bucketModeSchema.optional(),
displayNameOverride: z.string().trim().max(120).nullable().optional(),
bioOverride: z.string().trim().max(2000).nullable().optional(),
}).strict();
// Items shape for kind:'media'. Mirrors mediaCollections item key
// — { kind: 'image'|'video', ref: '<filename>' }.
const sharingMediaItemSchema = z.object({
kind: z.enum(['image', 'video']),
ref: z.string().min(1).max(500),
}).strict();
export const sharingExportSchema = z.object({
kind: z.enum(['series', 'universe', 'media']),
ids: z.array(z.string().min(1).max(120)).max(50).optional(),
items: z.array(sharingMediaItemSchema).max(200).optional(),
}).strict().refine(
(data) => {
if (data.kind === 'media') return Array.isArray(data.items) && data.items.length > 0;
return Array.isArray(data.ids) && data.ids.length > 0;
},
{ message: "Provide 'ids' for kind=series|universe, or 'items' for kind=media" },
);
// User-level sharing config — extends settings.json.
export const sharingSettingsPatchSchema = z.object({
sharingDisplayName: z.string().trim().max(120).optional(),
sharingBio: z.string().trim().max(2000).optional(),
}).strict();
// Geographic home location for location-aware features — the `weather_now`
// voice tool today, any future location-dependent surface tomorrow. Stored on
// `settings.location`. lat/lon are nullable so the user can clear a saved
// location and fall the consuming tool back to its default. The refine enforces
// both-or-neither so a half-set pair can't pin a nonsensical coordinate
// (e.g. a custom latitude with a default longitude).
export const locationSettingsSchema = z.object({
lat: z.number().min(-90).max(90).nullable().optional(),
lon: z.number().min(-180).max(180).nullable().optional(),
}).strict().refine(
(d) => (d.lat == null) === (d.lon == null),
{ message: 'Provide both lat and lon, or neither.' },
);
// Durable "don't show this again" for the dashboard first-run card (#5640).
// Top-level general-settings boolean — same record as timezone/location, never
// localStorage. Absent means show; only an explicit true suppresses.
export const networkSetupPreferenceSchema = z.enum(['tailscale', 'tailcat', 'none']);
export const hideFirstRunCardSchema = z.boolean();
// Grok Imagegen settings slice (`imageGen.grok`) — the Grok Build CLI backend
// (#2859). No model/effort knobs: grok's image tools run on xAI's fixed image
// backend, so only the enable gate, binary path, default aspect ratio, and
// per-mode cleaner flags are stored. `''` sentinels from the UI preprocess to
// undefined (same convention as other CLI provider slices); aspectRatio is
// constrained to the `N:M` shape the grok tool accepts so a hand-edited
// settings.json can't inject arbitrary prompt text.
export const imageGenGrokSettingsSchema = z.object({
enabled: z.boolean().optional(),
grokPath: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().max(500).optional()),
aspectRatio: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().regex(/^\d{1,2}:\d{1,2}$/, 'aspect ratio must look like 16:9').optional()),
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
});
const agyImageModelSchema = z.preprocess(
(v) => (v === '' ? undefined : v),
cloudModelIdString('model must be a valid Agy model id').optional(),
);
// Per-surface render defaults (`settings.renderDefaults`, #3231 Phase 2) —
// one optional entry per render target, each pinning a backend and/or a cloud
// model for that surface. `'auto'`, `''`, and null all mean "no pin — fall
// through to the install default" (renderTargetDefaults normalizes them).
// Deliberately TOLERANT of unknown keys at both levels (no `.strict()`): the
// Settings UI round-trips the WHOLE stored object on every save, so after a
// version rollback (or a newer client against an older server) a target/field
// this build doesn't know would otherwise 400 every Image Gen save until the
// user hand-edits settings.json — the same forward-compat call the settings
// route makes for catalogUserTypes. The route persists the raw body, so a
// newer build's pins survive the round-trip intact rather than being dropped.
// Known fields keep full enum/charset enforcement (that's what stops a bad
// model id reaching a CLI argv); the known-key alphabet is RENDER_TARGETS from
// lib/renderTargets.js, which the client re-exports rather than mirrors.
const renderTargetModelSchema = z.preprocess(
(v) => (v === '' ? null : v),
cloudModelIdString('model must be a valid model id').nullable().optional(),
);
// Shared by the per-target entries and `videoGenSettingsSchema.mode` below —
// one copy of the video-backend pin alphabet.
const videoModePinSchema = z.enum([RENDER_TARGET_BACKEND_AUTO, ...VIDEO_GEN_MODES]).nullable().optional();
const renderTargetEntrySchema = z.object({
imageMode: z.enum([RENDER_TARGET_BACKEND_AUTO, ...QUEUEABLE_IMAGE_MODES]).nullable().optional(),
imageModel: renderTargetModelSchema,
videoMode: videoModePinSchema,
videoModel: renderTargetModelSchema,
});
// A null entry is an explicit "no pin for this surface": the slice PATCH merges
// per target, so clearing one must be sent as a value, not an omitted key.
export const renderDefaultsSettingsSchema = z.object(
Object.fromEntries(RENDER_TARGETS.map((t) => [t, renderTargetEntrySchema.nullable().optional()])),
);
// Install-wide video render pin (`settings.videoGen`, #3231 Phase 4) — the
// third rung in resolveVideoMode's ladder (request → target pin → THIS →
// local). `'auto'`/`''`/null all mean "no pin — local". Tolerant of unknown
// keys for the same rollback/forward-compat reason as renderDefaults above.
// `defaultModelId` is the install-wide local video model choice used by the
// Video Gen form and pipeline video stages — typed here so a Settings save
// can't write junk to it.
export const videoGenSettingsSchema = z.object({
mode: videoModePinSchema,
defaultModelId: z.preprocess(emptyToNull, z.string().trim().max(64).nullable().optional()),
// Opt-in macOS GPU-watchdog mitigation for local MLX video renders (mlx
// #3267) — OFF by default, since a render is a short, attended action and
// sleeping the screen unasked reads as a crash. Set true to have PortOS
// sleep the display for the duration of a render; also settable per-render
// (see the `displaySleep` field on POST /api/video-gen).
displaySleep: z.boolean().optional(),
// Install-wide acknowledgement of restricted-model license gates, stored as
// the exact reviewed-license ids (`termsGate.id`). Written through
// POST /api/video-gen/model-terms; typed here so a Settings save can't put
// junk where the render gate reads authorization from.
acceptedModelTerms: z.array(z.string().trim().min(1).max(128)).max(50).optional(),
// fal.ai queue REST provider (#6213) — settings-stored key wins over the
// FAL_KEY env var (same precedence as loras.js's Civitai key).
fal: z.object({
apiKey: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().max(200).optional()),
}).optional(),
// reactor.inc fast-h3 provider (#6214) — same settings-wins-over-env
// precedence as `fal` above.
reactor: z.object({
apiKey: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().max(200).optional()),
}).optional(),
// Runway developer API — same settings-wins-over-env (RUNWAYML_API_SECRET) precedence.
runway: z.object({
apiKey: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().max(200).optional()),
}).optional(),
});
// POST /api/video-gen/model-terms — record (or withdraw) the acknowledgement of
// one restricted model's reviewed license. `termsId` is the exact versioned
// gate id; the route rejects ids no shipped model declares.
export const videoModelTermsSchema = z.object({
termsId: z.string().trim().min(1).max(128),
accepted: z.boolean(),
});
// Runway images share the private video credential; only render settings live here.
export const imageGenRunwaySettingsSchema = z.object({
enabled: z.boolean().optional(),
model: z.preprocess((v) => v === '' ? undefined : v, z.enum(RUNWAY_IMAGE_MODEL_IDS).optional()),
resolution: z.enum(RUNWAY_IMAGE_RESOLUTIONS).optional(),
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
});
// fal.ai Imagegen settings slice (`imageGen.fal`). The API key is NOT here —
// it is the fal.ai credential the video backend already owns (write-only via
// PUT /api/settings/credentials/fal). `model` must name a catalog endpoint
// (lib/falImageModels.js): each id is a different price, so free text is
// refused rather than persisted and discovered at render time.
export const imageGenFalSettingsSchema = z.object({
enabled: z.boolean().optional(),
model: z.preprocess((v) => (v === '' ? undefined : v), z.enum(FAL_IMAGE_MODEL_IDS).optional()),
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
});
export const imageGenAgySettingsSchema = z.object({
enabled: z.boolean().optional(),
agyPath: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().max(500).optional()),
model: agyImageModelSchema,
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
});
// Provider-agnostic embeddings settings. `provider: 'none'` is the default and
// makes embedText() a no-op — rows persist without an embedding and a future
// admin "Re-embed missing" action backfills. Model is optional so the user can
// pick provider first and choose a model from the live list in the UI.
export const settingsEmbeddingsSchema = z.object({
provider: z.enum(['ollama', 'lmstudio', 'none']),
model: z.string().trim().max(200).optional().nullable(),
}).strict();
// Local backend availability is machine-local configuration. Disabled means
// the user intentionally does not run that backend; it does not remove any
// installed models or prevent an explicit model-management action.
export const localLlmSettingsSchema = z.object({
ollama: z.object({ disabled: z.boolean().optional() }).strict().optional(),
lmstudio: z.object({ disabled: z.boolean().optional() }).strict().optional(),
// Idle windows for the two PM2-managed model servers, in minutes. `0` = never
// release the model, which is what every install did before this setting
// existed and stays the default. Capped at a day: a longer window is
// indistinguishable from "never" and is far likelier a units mix-up.
llama: z.object({
idleMinutes: z.number().int().min(0).max(1440).optional(),
keepLoaded: z.boolean().optional(),
pinned: z.boolean().optional(),
}).strict().optional(),
mtplx: z.object({
idleMinutes: z.number().int().min(0).max(1440).optional(),
keepLoaded: z.boolean().optional(),
pinned: z.boolean().optional(),
// The launch line a lazy start replays. MTPLX has no Start button any more —
// the first request that needs it brings it up — so the checkpoint and port
// the user chose have to outlive the process, or an on-demand start would
// fall back to "first verified checkpoint in the cache" and quietly serve
// something they didn't pick.
launch: z.object({
model: z.string().trim().max(300).nullable().optional(),
port: z.number().int().min(1).max(65535).optional(),
}).strict().optional(),
}).strict().optional(),
slotstream: z.object({
idleMinutes: z.number().int().min(0).max(1440).optional(),
keepLoaded: z.boolean().optional(),
pinned: z.boolean().optional(),
launch: z.object({
model: z.string().trim().max(300).nullable().optional(),
port: z.number().int().min(1).max(65535).optional(),
memoryGb: z.number().min(6).max(512).nullable().optional(),
}).strict().optional(),
}).strict().optional(),
}).strict();
// Only slices written by patchSettingsSlice callers belong on this mutation
// surface. Credentials/auth and executable-policy parents have dedicated APIs.
const renderFormNumberSchema = z.union([
z.number().finite(),
z.string().max(30).refine((value) => value === '' || Number.isFinite(Number(value)), 'Must be numeric or empty'),
]);
const renderFormSettingsSchema = z.object({
mode: z.enum(IMAGE_GEN_MODES).optional(),
modelId: z.string().max(300).nullable().optional(),
cloudModel: z.string().max(300).nullable().optional(),
width: z.number().int().positive().max(MAX_IMAGE_EDGE).optional(),
height: z.number().int().positive().max(MAX_IMAGE_EDGE).optional(),
steps: renderFormNumberSchema.optional(),
guidance: renderFormNumberSchema.optional(),
cfgScale: renderFormNumberSchema.optional(),
quantize: z.enum(['3', '4', '5', '6', '8']).optional(),
seed: renderFormNumberSchema.optional(),
negativePrompt: z.string().max(4000).optional(),
extraStyle: z.string().max(4000).optional(),
}).strict();
export const settingsSlicePartialSchemas = Object.freeze({
...Object.fromEntries(Object.entries(localLlmSettingsSchema.shape)
.map(([runtime, schema]) => [`localLlm.${runtime}`, schema.unwrap()])),
// The Media settings drawer (ImageGenTab) saves field-by-field through these
// so a sibling panel's later patch (VideoGen's LocalSetupPanel writing
// `imageGen.local.pythonPath`) survives a drawer save. Cleared strings travel
// as '' (every reader falls back on a blank); the two pins that readers
// coerce with `||` accept null so an un-pin needs no sentinel string.
imageGen: z.object({
mode: z.enum(IMAGE_GEN_MODES).optional(),
// Legacy flat field, kept populated beside `imageGen.external.sdapiUrl`.
sdapiUrl: z.string().max(500).optional(),
}).strict(),
'imageGen.external': z.object({
sdapiUrl: z.string().max(500).optional(),
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
}).strict(),
'imageGen.local': z.object({
pythonPath: z.string().max(500).nullable().optional(),
modelId: z.string().max(300).nullable().optional(),
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
}).strict(),
'imageGen.codex': z.object({
enabled: z.boolean().optional(),
codexPath: z.string().max(500).optional(),
model: z.string().max(300).optional(),
effort: z.string().max(40).optional(),
parallelLimit: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional(),
cleanC2PA: z.boolean().optional(),
denoise: z.boolean().optional(),
}).strict(),
'imageGen.grok': imageGenGrokSettingsSchema.strict(),
'imageGen.agy': imageGenAgySettingsSchema.strict(),
'imageGen.fal': imageGenFalSettingsSchema.strict(),
'imageGen.runway': imageGenRunwaySettingsSchema.strict(),
'imageGen.expose': z.object({ a1111: z.boolean().optional() }).strict(),
renderDefaults: renderDefaultsSettingsSchema,
videoGen: videoGenSettingsSchema.pick({ mode: true, defaultModelId: true, displaySleep: true }).strict(),
pipeline: z.object({ imageGen: renderFormSettingsSchema.nullable().optional() }).strict(),
writersRoom: z.object({ imageGen: renderFormSettingsSchema.nullable().optional() }).strict(),
seriesAutopilot: seriesAutopilotSettingsSchema.partial(),
pipelineEditorialChecks: pipelineEditorialChecksSettingsSchema.partial(),
autoUpdate: autoUpdateSettingsSchema,
// The Chiptune panel and the Music Designer each own one sub-slice, so a save
// from either cannot drop the other's prefs or a template saved elsewhere.
'music.chiptune': musicSettingsSchema.shape.chiptune.unwrap().strict(),
'music.designer': musicSettingsSchema.shape.designer.unwrap().strict(),
// The caption-model picker owns only these two keys; the rest of the slice
// (training defaults, segmentation, watchdog, display sleep) is hand-set.
loraTraining: loraTrainingConfigSchema.pick({ captionProviderId: true, captionModel: true }).strict(),
});
// Check raw JSON before Zod can strip a dangerous key. Arrays can contain
// nested objects too; none may smuggle prototype-related property names.
const hasPollutingKey = (value) => value !== null && typeof value === 'object'
&& Object.entries(value).some(([key, child]) => POLLUTING_KEYS.has(key) || hasPollutingKey(child));
export const settingsSlicePatchSchema = z.preprocess((value, ctx) => {
if (hasPollutingKey(value)) {
ctx.addIssue({ code: 'custom', message: 'Prototype-related keys are forbidden' });
}
return value;
}, z.object({
slicePath: z.enum(Object.keys(settingsSlicePartialSchemas)),
partial: z.record(z.unknown()),
}).strict().superRefine(({ slicePath, partial }, ctx) => {
const result = settingsSlicePartialSchemas[slicePath].safeParse(partial);
if (!result.success) {
for (const issue of result.error.issues) {
ctx.addIssue({ ...issue, path: ['partial', ...issue.path] });
}
}
}));
// =============================================================================
// LM STUDIO (server/routes/lmstudio.js)
// =============================================================================
// PUT /api/lmstudio/config — persisted straight into module-level state
// (lmStudioManager's `config`) that every other LM Studio call site reads via
// getBaseUrl(). A malformed baseUrl must be rejected up front rather than
// degrading local-LLM connectivity until the process restarts.
export const lmStudioConfigSchema = z.object({
baseUrl: z.string().trim().url().optional(),
timeout: z.number().int().positive().optional(),
defaultThinkingModel: z.string().trim().min(1).optional(),
});
// Shared by /download, /load, /unload — each acts on a single model id.
export const lmStudioModelIdSchema = z.object({
modelId: z.string().trim().min(1),
});
// POST /api/lmstudio/completion
export const lmStudioCompletionSchema = z.object({
prompt: z.string().min(1),
model: z.string().trim().min(1).optional(),
maxTokens: z.number().int().positive().optional(),
temperature: z.number().min(0).max(2).optional(),
systemPrompt: z.string().optional(),
});
// POST /api/lmstudio/analyze-task
export const lmStudioAnalyzeTaskSchema = z.object({
description: z.string().min(1),
id: z.string().optional(),
metadata: z.record(z.any()).optional(),
});
// POST /api/lmstudio/classify-memory
export const lmStudioClassifyMemorySchema = z.object({
content: z.string().min(1),
});
// POST /api/lmstudio/embeddings
export const lmStudioEmbeddingsSchema = z.object({
text: z.string().min(1),
model: z.string().trim().min(1).optional(),
});
// Subscription creation: persistent (bucket, record) tuple. Series + universe
// are the subscribable kinds (records that change over time and benefit from
// auto-re-export). Media is one-shot via /buckets/:id/export.
export const subscriptionCreateSchema = z.object({
bucketId: z.string().trim().min(1).max(120),
recordKind: z.enum(['series', 'universe']),
recordId: z.string().trim().min(1).max(120),
}).strict();
// Per-request LLM provider/model override. Shared by universe-builder expand
// routes and pipeline arc-planning routes. Optional so callers that omit the
// llm field fall back to the server's active provider.
export const llmSchema = z.object({
provider: providerRefSchema.nullable().optional(),
model: z.string().trim().max(200).nullable().optional(),
}).optional();
// =============================================================================
// DOCUMENT EDITING SCHEMAS (shared by apps.js and gsd.js document routes)
// =============================================================================
/**
* Body schema for PUT /api/apps/:id/documents/*docPath and
* PUT /api/cos/gsd/projects/:appId/documents/:docName.
* Both routes accept a content string plus an optional commit message.
*/
export const documentUpdateSchema = z.object({
content: z.string().max(500000),
commitMessage: z.string().max(200).optional()
});
// Legacy Export (issue #901) — portable identity bundle. `sections` optionally
// narrows the bundle to a subset of domains; omitted/empty means "all present
// sections". The enum is kept in sync with `legacyExport.js#getSectionKeys()`
// (asserted in legacyExport's tests) — validation.js must not import from
// services (cycle), so the keys are inlined here.
export const LEGACY_EXPORT_SECTIONS = ['identity', 'autobiography', 'brain', 'goals', 'decisions', 'health'];
export const legacyExportSchema = z.object({
sections: z.array(z.enum(LEGACY_EXPORT_SECTIONS)).optional(),
// Phase 2: render a `legacy-portrait.pdf` from the section Markdown. Default
// false — the Markdown/JSON bundle is the primary artifact.
includePdf: z.boolean().optional()
});
// Video downloader (#1946) — paste a YouTube/x.com URL, download the full
// video. The host allowlist is enforced in the service (assertSupportedVideoUrl)
// so the error names the supported hosts; the schema just guards the shape.
export const videoDownloadSchema = z.object({
url: z.string().url().max(2048)
});
// Git submodules. `repoPath` is the repo ROOT (omitted = the PortOS checkout,
// and it is separately checked against the workspace allowlist); `path` is the
// repo-relative submodule path, matching `git submodule status` output.
const optionalRepoPath = z.string().trim().min(1).max(4096).nullish();
export const submoduleStatusQuerySchema = z.object({
repoPath: optionalRepoPath
});
export const submoduleUpdateSchema = z.object({
path: z.string().trim().min(1).max(4096),
repoPath: optionalRepoPath,
commit: z.boolean().optional().default(false)
});
// =============================================================================
// TRANSITIONAL RE-EXPORTS (issue #1151 split)
// =============================================================================
// These domain schema groups moved to their own per-domain files (the
// brainValidation.js pattern); the re-exports keep every existing deep
// `import { x } from '../lib/validation.js'` working. New code should import
// from the domain file (or the barrel's namespace export) directly.
//
// Cycle note: the domain files must NOT import from this module — ESM hoists
// `export * from`, so they evaluate before this module's body runs and any
// value read back from here hits the TDZ. Shared zod primitives they need
// (e.g. `emptyToUndefined`) live in zodCompat.js.
export * from './peerSyncValidation.js';
export * from './creativeDirectorValidation.js';
export * from './creativeCommissionValidation.js';
export * from './musicVideoValidation.js';
export * from './storyBuilderValidation.js';
export * from './moodBoardValidation.js';
export * from './privacyValidation.js';
export * from './agentValidation.js';
export * from './cosValidation.js';
export * from './mediaValidation.js';
export * from './pipelineValidation.js';
import { stageConfigUpdateSchema } from './pipelineValidation.js';
export * from './quotaBurnValidation.js';
export * from './spriteValidation.js';
export * from './agentContextValidation.js';
export * from './eidoverseValidation.js';
// Reference prices and PortOS-run benchmark observations. A source is attached
// to each metric because prices, scores and runtime measurements differ.
const isAllowedComparisonSourceUrl = value => {
if (/^portos:\/\/model-comparison\/[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(value)) return true;
try {
const url = new URL(value);
return url.protocol === 'https:' && Boolean(url.hostname);
} catch {
return false;
}
};
const comparisonSourceSchema = z.object({
url: z.string().min(1).max(2000).refine(
isAllowedComparisonSourceUrl,
'Source must use HTTPS or identify a PortOS benchmark run',
),
retrievedAt: z.string().datetime().refine(value => Date.parse(value) <= Date.now(), 'Source date cannot be in the future'),
methodology: z.string().min(1).max(1000),
}).strict();
const comparisonMetricSchema = z.object({ value: z.number().finite().nonnegative(), source: comparisonSourceSchema }).strict();
export const modelComparisonObservationSchema = z.object({
id: z.string().min(1).max(200),
provider: z.string().min(1).max(160),
model: z.string().min(1).max(200),
effort: z.string().min(1).max(80),
configuration: z.string().min(1).max(500),
billing: z.enum(['api', 'subscription', 'local', 'free', 'unknown']),
benchmark: z.string().min(1).max(160),
quality: comparisonMetricSchema.nullable(),
costPerTask: comparisonMetricSchema.nullable(),
inputPerMillion: comparisonMetricSchema.nullable(),
outputPerMillion: comparisonMetricSchema.nullable(),
reasoningPerMillion: comparisonMetricSchema.nullable(),
responseSeconds: comparisonMetricSchema.nullable(),
tokensPerSecond: comparisonMetricSchema.nullable(),
tokensPerRun: comparisonMetricSchema.nullable().optional(),
inputTokens: comparisonMetricSchema.nullable().optional(),
outputTokens: comparisonMetricSchema.nullable().optional(),
apiEquivalentCost: comparisonMetricSchema.nullable().optional(),
tokenBasis: z.enum(['measured', 'estimated', 'mixed']).nullable().optional(),
completedTasks: z.number().int().nonnegative().max(1000).nullable().optional(),
totalTasks: z.number().int().positive().max(1000).nullable().optional(),
quota: z.object({ unitsPerTask: z.number().finite().nonnegative(), unit: z.string().min(1).max(80), source: comparisonSourceSchema }).strict().nullable(),
notes: z.string().max(2000),
}).strict().superRefine((row, ctx) => {
if (row.benchmark === 'PortOS Research Index v1 (AA v4.3.2 scale)' && row.quality) {
if (row.quality.value > 100) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['quality', 'value'], message: 'PortOS research index must be between 0 and 100' });
if (!row.quality.source.methodology.startsWith('PortOS estimate:')) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['quality', 'source', 'methodology'], message: 'Research estimates must disclose their derivation with PortOS estimate:' });
}
});
const modelComparisonCatalogBaseSchema = z.object({
schemaVersion: z.literal(1),
// Source imports can contain thousands of independently attributed rows and
// are applied as one atomic catalog merge.
observations: z.array(modelComparisonObservationSchema).max(12000),
}).strict().superRefine((value, ctx) => {
const ids = new Set();
value.observations.forEach((row, index) => {
if (ids.has(row.id)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['observations', index, 'id'], message: 'Duplicate observation id' });
ids.add(row.id);
if (!row.quality && !row.costPerTask && !row.inputPerMillion && !row.outputPerMillion && !row.reasoningPerMillion && !row.responseSeconds && !row.tokensPerSecond && !row.quota && !row.tokensPerRun && !row.inputTokens && !row.outputTokens && !row.apiEquivalentCost) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['observations', index], message: 'At least one sourced metric is required' });
}
});
});
// A migration may legitimately retire the last legacy observation. The stored
// catalog can then be empty, but client imports still need at least one row.
export const modelComparisonCatalogSchema = modelComparisonCatalogBaseSchema;
export const modelComparisonImportSchema = modelComparisonCatalogBaseSchema.refine(
value => value.observations.length > 0,
{ message: 'At least one observation is required', path: ['observations'] },
);
export const modelComparisonDiscoverySchema = z.object({ providerId: z.string().min(1).max(200) }).strict();
export const privateCredentialParamsSchema = z.object({ id: z.enum(CREDENTIALS.filter(entry => entry.privateStore).map(entry => entry.id)) });
export const privateCredentialInputSchema = z.object({ value: z.string().trim().max(2000) }).strict();
export const modelComparisonBenchmarkRunSchema = z.object({
providerId: z.string().min(1).max(200),
model: z.string().min(1).max(200),
effort: z.string().min(1).max(80).nullable().optional(),
}).strict();
// =============================================================================
// HARNESS ENABLEMENT + CREDENTIAL BOOTSTRAP APPS (#7564)
// =============================================================================
/**
* `settings.harnesses` — per-harness enablement: `{ [harnessId]: { enabled } }`.
* Keyed by a registry id only, so a typo cannot store a rule nothing reads. A
* harness with no entry is enabled when its binary is detected on PATH
* (`services/harnessEnablement.js`); `direct` is always enabled.
*/
// `partialRecord`: a Zod 4 `record` over an enum key is EXHAUSTIVE and would
// demand an entry for every harness.
export const harnessSettingsSchema = z.partialRecord(
z.enum(PROVIDER_HARNESS_IDS),
z.object({ enabled: z.boolean() }).strict(),
);
/**
* One credential-bootstrap APP (#7564): the wrapper CLI that mints a harness's
* credential at spawn (`<command> <args...> <harnessName> [<separator>] <harness args>`).
* Same field limits as the inline `credentialBootstrap` a record carries
* (`aiToolkit/validation.js`); `harnessNames` maps a harness id to the name the
* wrapper knows it by when that differs from the binary (`claude` → `claude-code`).
* `setupCommand` is advisory text — PortOS never runs it.
*/
export const credentialBootstrapSchema = z.object({
label: z.string().trim().min(1).max(100),
command: z.string().trim().min(1).max(200),
args: z.array(z.string().max(200)).max(20).optional(),
envCommand: z.array(z.string().min(1).max(500)).min(1).max(21).optional(),
argsSeparator: z.string().trim().max(20).optional(),
setupCommand: z.string().trim().max(500).optional(),
harnessNames: z.partialRecord(z.enum(PROVIDER_HARNESS_IDS), z.string().trim().min(1).max(100)).optional(),
}).strict();
/** `settings.credentialBootstraps` — apps keyed by the slug a composite id's `+<slug>` suffix names. */
export const credentialBootstrapsSettingsSchema = z.record(
z.string().regex(SERVICE_SLUG_RE, 'bootstrap slug must be lowercase alphanumeric with hyphens').max(64),
credentialBootstrapSchema,
);
/**
* `POST /api/providers/presets` (#7565) — "Save as preset": a composite id
* becomes a stored, derived preset. The composite's own grammar is checked
* here; whether it is RUNNABLE (harness enabled, service known, compatible) is
* the resolver's verdict, published as a 400 with its code. `effort` is
* validated against the harness's ladder in the service, not against a flat
* enum: which rungs exist is a per-harness (and per-model) fact.
*/
export const providerPresetCreateSchema = z.object({
compositeId: providerRefSchema.refine((value) => parseProviderRef(value)?.kind === 'composite', {
message: 'compositeId must be a composite <harness>.<cli|tui|api>@<service-slug>[+<bootstrap-slug>]',
}),
id: presetProviderIdSchema.optional(),
name: z.string().trim().min(1).max(100).optional(),
model: z.string().trim().min(1).max(512).nullable().optional(),
effort: z.string().trim().min(1).max(20).nullable().optional(),
}).strict();
/** `PUT /api/providers/harnesses/:id` — flip one harness's enablement. */
export const harnessEnablementUpdateSchema = z.object({ enabled: z.boolean() }).strict();
export const harnessIdParamSchema = z.enum(PROVIDER_HARNESS_IDS);
// =============================================================================
// PERSISTENT MIND BUNDLE (server/routes/cosMindRoutes.js)
// =============================================================================
/**
* `POST /api/cos/mind/bundle/export` (#7621) — seal the Mind into a downloadable,
* passphrase-encrypted bundle.
*
* The scope vocabulary and passphrase floor come from `mindBundleCrypto.js`, the
* module that owns the container contract, so the route, the sealer, and the UI
* cannot drift apart on what a bundle may declare. The passphrase is bounded but
* deliberately unconstrained in composition: it is a user-chosen secret, and a
* validation failure here must never echo it (`validateRequest` reports paths
* and messages, never values).
*/
export const mindBundleExportSchema = z.object({
scopes: z.array(z.enum(PERSISTENT_MIND_BUNDLE_SCOPES))
.min(1)
.max(PERSISTENT_MIND_BUNDLE_SCOPES.length)
.refine((scopes) => new Set(scopes).size === scopes.length, 'bundle scopes must be unique'),
passphrase: z.string()
.min(MIND_BUNDLE_PASSPHRASE_MIN_CHARS, `Passphrase must be at least ${MIND_BUNDLE_PASSPHRASE_MIN_CHARS} characters`)
.max(MIND_BUNDLE_PASSPHRASE_MAX_CHARS),
}).strict();
const mindBundlePassphrase = z.string()
.min(MIND_BUNDLE_PASSPHRASE_MIN_CHARS, `Passphrase must be at least ${MIND_BUNDLE_PASSPHRASE_MIN_CHARS} characters`)
.max(MIND_BUNDLE_PASSPHRASE_MAX_CHARS);
// The uploaded file, as text. Bounded here as well as in the container reader
// so an oversized upload is refused before a key derivation runs over it.
const mindBundleText = z.string().min(1).max(MIND_BUNDLE_MAX_CHARS);
/** Open a bundle and report what it carries. Read-only — no choices, no writes (#7622). */
export const mindBundlePreviewSchema = z.object({
bundle: mindBundleText,
passphrase: mindBundlePassphrase,
}).strict();
/**
* Apply a bundle under one whole-group choice per group. A group the caller
* omits keeps this install's value, so a partial payload can never overwrite a
* personality by accident; `.strict()` on the choice map means a group name
* this build does not know is a 400, not a silently ignored key.
*/
export const mindBundleApplySchema = z.object({
bundle: mindBundleText,
passphrase: mindBundlePassphrase,
choices: z.object(Object.fromEntries(
PERSISTENT_MIND_BUNDLE_GROUPS.map((group) => [group, z.enum(MIND_BUNDLE_GROUP_CHOICES).optional()]),
)).strict(),
}).strict();
export const appLaunchVideoPublishSchema = z.object({
format: z.enum(['mp4', 'gif']).default('gif'),
videoId: z.string().min(1).max(200).regex(/^[a-zA-Z0-9_-]+$/),
}).strict();
export const LAUNCH_VIDEO_MOTION_STYLES = Object.freeze(['walkthrough', 'showreel', 'ui-morph']);
// One launch timeline can render several frames (#8960). Each name maps to the
// exact size a composition declares in portosComposition.formats; the order is
// the canonical render/delivery order.
export const LAUNCH_VIDEO_FORMAT_SIZES = Object.freeze({ landscape: '1920x1080', vertical: '1080x1920', square: '1080x1080' });
export const LAUNCH_VIDEO_FORMATS = Object.freeze(Object.keys(LAUNCH_VIDEO_FORMAT_SIZES));
const launchVideoFormatSchema = z.enum(LAUNCH_VIDEO_FORMATS);
const launchVideoFormatListSchema = z.array(launchVideoFormatSchema).min(1).max(LAUNCH_VIDEO_FORMATS.length)
.refine(list => new Set(list).size === list.length, 'formats must not repeat');
// A style reference (#8961): a frame, a short clip, or a Media History image
// or video. `source` picks the bucket the filename is resolved against —
// `gallery` (Media History's own images/videos folders) or `upload` (the
// generic /api/uploads scratch dir) — so the route can contain the read to
// exactly one directory per kind, never a client-supplied path.
export const launchVideoStyleReferenceSchema = z.object({
kind: z.enum(['image', 'video']),
source: z.enum(['gallery', 'upload']),
filename: z.string().min(1).max(255).regex(/^[^/\\]+$/, 'filename must not contain a path separator'),
}).strict();
// Off / Light / Film shutter presets; the mapping lives in services/htmlComposition.
export const htmlCompositionMotionBlurChoiceSchema = z.enum(['off', 'light', 'film']);
export const appLaunchVideoRequestSchema = z.object({
sourceVideoId: z.string().min(1).max(200).regex(/^[a-zA-Z0-9_-]+$/).optional(),
feedback: z.string().trim().min(1).max(4000).optional(),
tone: z.enum(['default', 'polished', 'deadpan', 'cinematic', 'parody']).default('default'),
direction: z.string().trim().max(2000).default(''),
// `format` is the single-frame form older callers send; `formats` asks one
// run for several aspect ratios of the same film. The route normalizes both.
format: launchVideoFormatSchema.optional(),
formats: launchVideoFormatListSchema.optional(),
targetDurationSec: z.number().int().min(15).max(120).default(20),
generateMusic: z.boolean().default(false),
musicMethod: z.enum(['agent', 'service']).default('agent'),
// Legacy boolean for older callers; true means motionStyle "showreel".
motionGraphics: z.boolean().optional(),
motionStyle: z.enum(LAUNCH_VIDEO_MOTION_STYLES).optional(),
// Contact-sheet proof → critique → fix passes before the final render.
critiqueRounds: z.number().int().min(0).max(4).default(2),
// Render-time motion blur (#9080); omitted, the composition's own setting stands.
motionBlur: htmlCompositionMotionBlurChoiceSchema.optional(),
// Ask the agent to consult installed motion-design skills (npm run setup:motion).
motionSkills: z.boolean().default(false),
musicTrack: z.string().min(1).max(255).regex(/^[^/\\]+$/).optional(),
styleReference: launchVideoStyleReferenceSchema.optional(),
// Curated medium rulebook (#10254); only its motion/camera/sound/native-move parts reach the prompt.
styleGrammarId: knownFilmStyleIdSchema.optional(),
}).strict();
export const launchVideoOptionsSchema = z.object({
sourceVideoId: z.string().min(1).max(200).regex(/^[a-zA-Z0-9_-]+$/).optional(),
targetDurationSec: z.number().min(15).max(120),
appId: z.string().regex(/^[a-zA-Z0-9_-]+$/).max(128).optional(),
runId: z.string().regex(/^[a-zA-Z0-9_-]+$/).max(128).optional(),
}).strict().refine(value => Boolean(value.appId) === Boolean(value.runId), 'appId and runId must be supplied together');
export const launchVideoStoryboardSchema = z.object({
posterSec: z.number().nonnegative(),
scenes: z.array(z.object({
durationSec: z.number().positive(),
lines: z.array(z.object({
text: z.string().trim().min(1).max(10000),
wordCount: z.number().int().positive(),
holdSec: z.number().positive(),
}).strict()).max(100),
}).strict()).min(1).max(100),
}).strict();
// HTML composition inputs are local, editable assets, never provider prompts.
export const htmlCompositionRenderSchema = z.object({
launchVideo: launchVideoOptionsSchema.optional(),
synthesizeMusic: z.boolean().optional(),
// Master synthesized, library and uploaded audio to -14 LUFS / -1.5 dBTP; false keeps the bed as supplied.
masterLoudness: z.boolean().optional(),
// Overrides the page's own portosComposition.motionBlur when present (#9080).
motionBlur: htmlCompositionMotionBlurChoiceSchema.optional(),
directory: z.string().min(1).max(1024).refine(value => !value.startsWith('/') && !value.includes('\\') && !value.includes(':') && !value.split('/').some(part => part === '..' || part === '.' || !part), 'directory must be a relative path inside data'),
musicTrack: z.string().min(1).max(255).regex(/^[^/\\]+$/, 'musicTrack must be a Music-library filename').optional(),
audioUpload: z.string().min(1).max(255).regex(/^[^/\\\0]+$/, 'audioUpload must be an uploaded audio filename').refine(value => value !== '.' && value !== '..', 'audioUpload must be an uploaded audio filename').optional(),
// Several aspect ratios of one timeline, rendered in sequence on one page.
// Omitted, the job renders the composition's own width/height as before.
formats: launchVideoFormatListSchema.optional(),
// A proof renders a silent contact sheet for review instead of the video;
// `format` checks one declared framing, defaulting to the composition's own.
proof: z.object({ everySec: z.number().min(0.25).max(10).default(1), format: launchVideoFormatSchema.optional() }).strict().optional(),
}).refine(value => [value.synthesizeMusic, value.musicTrack, value.audioUpload].filter(Boolean).length <= 1, 'Choose synthesized music, a library track, or uploaded audio')
.refine(value => !(value.proof && (value.synthesizeMusic || value.musicTrack || value.audioUpload)), 'A proof is silent; omit synthesizeMusic, musicTrack and audioUpload')
.refine(value => !(value.proof && value.formats), 'A proof checks one framing; use proof.format instead of formats');
// GET /api/html-composition/beats — a Music-library filename, same shape as
// htmlCompositionRenderSchema's musicTrack but required (this endpoint exists
// only to measure one).
export const htmlCompositionBeatsQuerySchema = z.object({
musicTrack: z.string().min(1).max(255).regex(/^[^/\\]+$/, 'musicTrack must be a Music-library filename'),
}).strict();
// Public renders stay capped at 120s. A music-video owner passes a higher
// ceiling (the song length, hard-capped by the caller at 900s) and gets the
// same frame rules. superRefine lives on this factory because the exported
// schema is a ZodEffects and cannot be extended in place.
export function htmlCompositionContractSchemaFor(maxDurationSec = 120) {
return z.object({
durationSec: z.number().min(1).max(maxDurationSec),
fps: z.number().int().min(12).max(60),
width: z.number().int(),
height: z.number().int(),
// Subframes averaged per output frame to fake motion blur on fast moves.
// The integer form (1 default) keeps the existing tmix path byte for byte;
// the object form (#9077) samples a centred shutter in linear light, with a
// fixed count or 'auto' refinement that stops once the average converges.
motionBlur: z.union([
z.number().int().min(1).max(4),
z.object({
shutter: z.number().min(0.05).max(1).default(0.5),
samples: z.union([z.literal('auto'), z.number().int().min(4).max(64)]).default('auto'),
tolerance: z.number().min(1).max(8).default(2),
}).strict(),
]).default(1),
// Extra sizes this one timeline can render (#8960), reframed by the optional
// layout({ width, height }) hook before each format's first seek.
formats: z.array(z.enum(Object.values(LAUNCH_VIDEO_FORMAT_SIZES))).min(1).max(LAUNCH_VIDEO_FORMATS.length).optional(),
layout: z.boolean().default(false),
}).superRefine((value, ctx) => {
if (!['1920x1080', '1080x1920', '1080x1080', '1280x720'].includes(`${value.width}x${value.height}`)) {
ctx.addIssue({ code: 'custom', path: ['width'], message: 'width/height must be 1920x1080, 1080x1920, 1080x1080 or 1280x720' });
}
if (Math.abs(value.durationSec * value.fps - Math.round(value.durationSec * value.fps)) > 1e-8) {
ctx.addIssue({ code: 'custom', path: ['durationSec'], message: 'durationSec × fps must be a whole number of frames' });
}
});
}
export const htmlCompositionContractSchema = htmlCompositionContractSchemaFor(120);
// Jira issue key (ABC-123) or numeric id — the value is interpolated into upstream REST paths.
export const jiraTicketKeySchema = z.string().max(64).regex(/^([A-Za-z][A-Za-z0-9_]*-\d+|\d+)$/, 'Invalid Jira ticket id');
// Prompt stage names and variable keys become `stages/<name>.md` / a
// variables.json key, so they must be a single safe path segment (#9152).
export const promptStageNameSchema = z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, 'invalid stage name').max(80);
export const promptVariableKeySchema = z.string().regex(/^[A-Za-z0-9_-]+$/, 'invalid variable key').max(80);
// =============================================================================
// ROUTE BODY SCHEMAS (#9950) — handlers that used to read `req.body` by hand.
// `routeValidationConventions.test.js` fails any body-bearing POST/PUT/PATCH
// handler that skips `validateRequest`. A bodyless POST (a bare "run now"
// button) still parses an optional-field object: pass `req.body ?? {}`.
// =============================================================================
const nonEmptyString = z.string().min(1);
const optionalString = z.string().optional();
const nullishString = z.string().nullish();
// Project detection (routes/detect.js)
export const detectRepoBodySchema = z.object({ path: nonEmptyString });
export const detectPortBodySchema = z.object({ port: z.coerce.number().int().min(1).max(65535) });
export const detectPm2BodySchema = z.object({ name: nonEmptyString });
export const detectAiBodySchema = z.object({ path: nonEmptyString, providerId: nullishString });
// Messages (routes/messages.js)
export const MESSAGE_TOKEN_PROVIDERS = ['outlook', 'teams'];
export const messageSyncBodySchema = z.object({ mode: z.enum(['unread', 'full']).optional() });
export const messageFetchFullBodySchema = z.object({ force: z.boolean().default(false) });
export const messageActionBodySchema = z.object({ action: z.enum(['archive', 'delete']) });
export const messageTokenProviderBodySchema = z.object({ provider: z.enum(MESSAGE_TOKEN_PROVIDERS).optional() });
// CoS agents / tasks / schedule
export const cosAgentFeedbackBodySchema = z.object({
rating: z.enum(['positive', 'negative', 'neutral']),
comment: nullishString,
});
export const cosAgentBtwBodySchema = z.object({ message: z.string().trim().min(1).max(5000) });
export const cosTaskReorderBodySchema = z.object({ taskIds: z.array(nonEmptyString) });
export const cosScheduleTargetBodySchema = z.object({ taskType: nonEmptyString, appId: nullishString });
// A scoped release names the exact inventory row the operator saw (#12002).
export const heldCheckoutRetireBodySchema = z.object({
checkoutIdentity: z.string().regex(/^[a-f0-9]{64}$/).optional(),
observedAt: z.string().datetime({ offset: true }).optional(),
appId: nonEmptyString,
path: nonEmptyString,
head: z.string().regex(/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/),
branch: z.string().min(1).nullable(),
locked: z.boolean(),
lockReason: z.string().nullable(),
review: z.object({
prUrl: z.string().url(),
digest: z.string().regex(/^[a-f0-9]{64}$/),
acceptSuperseded: z.boolean(),
kind: z.literal('source-supersession').optional(),
}).optional(),
});
export const heldCheckoutReviewBodySchema = heldCheckoutRetireBodySchema.omit({ review: true }).extend({ prUrl: z.string().url(), kind: z.literal('source-supersession').optional() });
export const initializedCheckoutRetireBodySchema = heldCheckoutRetireBodySchema.extend({
review: heldCheckoutRetireBodySchema.shape.review.unwrap(),
}).strict();
export const initializedCheckoutTransactionSchema = z.object({ appId: nonEmptyString, transactionId: z.string().uuid() }).strict();
export const initializedCheckoutRestoreSchema = initializedCheckoutTransactionSchema.extend({
journalDigest: z.string().regex(/^[a-f0-9]{64}$/),
}).strict();
export const initializedCheckoutBranchRetireSchema = initializedCheckoutRestoreSchema.extend({
review: heldCheckoutRetireBodySchema.shape.review.unwrap(),
}).strict();
export const initializedCheckoutMetadataRestoreSchema = initializedCheckoutRestoreSchema.extend({
review: z.object({ digest: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),
}).strict();
export const initializedCheckoutFinalizationSchema = initializedCheckoutMetadataRestoreSchema;
export const initializedCheckoutQuarantineResumptionSchema = initializedCheckoutRestoreSchema.extend({
review: z.object({ digest: z.string().regex(/^[a-f0-9]{64}$/), acceptSuperseded: z.boolean().optional() }).strict(),
}).strict();
// Per-app task-type overrides (routes/apps/taskTypes.js)
export const appTaskTypeToggleBodySchema = z.object({ enabled: z.boolean() });
export const appTaskTypeOverrideBodySchema = z.object({
enabled: z.boolean().optional(),
interval: nullishString,
intervalMs: z.number().positive().finite().nullish(),
providerId: nullishString,
model: nullishString,
taskMetadata: z.record(z.string(), z.unknown()).nullish(),
}).refine((body) => Object.values(body).some((value) => value !== undefined), {
message: 'enabled (boolean), interval (string|null), intervalMs (number|null), providerId (string|null), model (string|null), or taskMetadata (object|null) required',
});
// Brain journal / inbox
export const brainInboxRetryBodySchema = z.object({ providerOverride: nullishString, modelOverride: nullishString });
export const brainJournalAppendBodySchema = z.object({
text: z.string().refine((text) => text.trim().length > 0, 'text is required'),
source: nullishString,
});
export const brainJournalReplaceBodySchema = z.object({ content: z.string(), ifMatchUpdatedAt: nullishString });
// Prompts (routes/prompts.js)
export const promptVariableUpdateBodySchema = z.object({ name: optionalString, category: optionalString, content: optionalString });
export const promptVariableCreateBodySchema = z.object({ key: promptVariableKeySchema, name: optionalString, category: optionalString, content: nonEmptyString });
export const promptStageCreateBodySchema = z.object({
stageName: promptStageNameSchema,
name: nonEmptyString,
description: optionalString,
model: z.string().default('default'),
returnsJson: z.boolean().default(false),
variables: z.array(z.string()).default([]),
template: z.string().default(''),
});
export const promptStageUpdateBodySchema = stageConfigUpdateSchema.extend({ template: z.string().optional() });
export const promptJobSkillBodySchema = z.object({ content: nonEmptyString });
export const promptPreviewBodySchema = z.object({ testData: z.record(z.string(), z.unknown()).default({}) });
// Smaller single-purpose bodies
// GET /api/calendar/review/:date — bounded page of the day's events. The
// defaults reproduce the legacy single-page response.
export const dailyReviewQuerySchema = z.object({
limit: z.coerce.number().int().min(1).max(200).default(200),
offset: z.coerce.number().int().min(0).default(0),
});
export const calendarAutoConfigureBodySchema = z.object({
email: optionalString,
requestId: z.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/).optional(),
});
// timeoutMs bounds an operator command run (#12021); absent means unbounded,
// the right default for an interactive run the operator is watching.
export const commandExecuteBodySchema = z.object({
command: nonEmptyString,
workspacePath: nullishString,
timeoutMs: z.number().int().positive().max(24 * 60 * 60 * 1000).optional(),
});
export const dataArchiveBodySchema = z.object({
daysToKeep: z.preprocess((value) => (value == null ? undefined : value), z.coerce.number().finite().min(0).optional()),
});
export const imageVisibilityBodySchema = z.object({ hidden: z.boolean().default(false) });
export const moltworldQueueFailBodySchema = z.object({ error: nullishString });
export const referenceRepoReviewedBodySchema = z.object({ sha: z.string().trim().default('') });
export const scaffoldTemplateCreateBodySchema = z.object({ templateId: nonEmptyString, name: nonEmptyString, targetPath: nonEmptyString });
export const screenshotUploadBodySchema = z.object({ data: nonEmptyString, filename: nullishString });
export const standardizeTargetBodySchema = z.object({ repoPath: nullishString, appId: nullishString, providerId: nullishString });
export const systemHealthThresholdsBodySchema = z.object({
memoryWarn: z.coerce.number().finite(),
memoryCritical: z.coerce.number().finite(),
diskWarn: z.coerce.number().finite(),
diskCritical: z.coerce.number().finite(),
});
export const voicePiperFetchBodySchema = z.object({ voice: nonEmptyString });
export const writersRoomSceneImageBodySchema = z.object({
sceneId: nullishString, filename: nullishString, jobId: nullishString, prompt: nullishString,
});
// One step of the global provider fallback list. `providerId` is a preset or
// composite reference; `model` / `effort` are optional pins for that step, so
// one preset may appear several times with different models or effort.
export const providerFallbackEntrySchema = z.object({
providerId: providerRefSchema,
model: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().min(1).max(200).optional()),
effort: z.preprocess((v) => (v === '' ? undefined : v), z.string().trim().min(1).max(40).optional()),
});
export const providerFallbackChainBodySchema = z.object({
entries: z.array(providerFallbackEntrySchema).max(50),
});
// Model-cache reads and explicit download streams share the same URL contract.
export const modelDownloadQuerySchema = z.object({
force: z.enum(['0', '1']).optional().transform(value => value === '1'),
});
export const modelDownloadParamsSchema = z.object({ modelId: z.string().min(1).max(256) });
export const icLoraDownloadParamsSchema = z.object({ mode: z.string().min(1).max(256) });
export const textEncoderDownloadParamsSchema = z.object({ id: z.string().min(1).max(256) });