Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

21.8 KB
Raw Blame
import { z } from 'zod';
import { MAX_MODEL_ACCESS_PATTERNS, MAX_MODEL_ACCESS_PATTERN_LENGTH, MODEL_ACCESS_MODES } from './internal/modelAccess.js';
import { basename, extname } from 'path';
import { MAX_TIMEOUT, MIN_TIMEOUT } from './constants.js';
import { MAX_PROVIDER_REF_LENGTH, PRESET_ID_RE, PRESET_ONLY_MESSAGE, parseProviderRef } from './internal/providerRef.js';

/**
 * A run's provider selection: a preset record id or a composite reference the
 * host resolves through `resolveCompositeProvider` (#7564). Mirrors the host's
 * `providerRefSchema` (`server/lib/zodCompat.js`) over the vendored grammar.
 */
export const providerRefSchema = z.string().trim().min(1).max(MAX_PROVIDER_REF_LENGTH)
  .refine((value) => parseProviderRef(value) !== null, 'providerId must be a preset id or a composite <harness>.<cli|tui|api>@<service-slug>[+<bootstrap-slug>]');

// Image extensions a vision screenshot may carry. Mirrors the runner's
// getMimeType keys — anything else (or a no-extension path like `passwd`) is
// rejected.
const ALLOWED_SCREENSHOT_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);

// Reasoning-effort values accepted by the effort-capable CLI providers. Keep
// this local because the vendored toolkit must remain self-contained; the
// runtime mirror lives in server/lib/providerModels.js and the UI mirror lives
// in client/src/utils/providerModels.js.
const PROVIDER_EFFORT_LEVELS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];

const providerEffort = z.preprocess(
  (value) => (typeof value === 'string' && value.trim() === '' ? null : value),
  z.enum(PROVIDER_EFFORT_LEVELS).nullable().optional()
);

// Hardware metadata is declarative and machine-local. Keep the shape bounded
// so a provider record cannot turn into an unbounded arbitrary JSON payload.
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();

/**
 * Sanitize the untrusted `screenshots[]` array from POST /api/runs into safe,
 * screenshots-dir-relative basenames. `screenshots[]` is unauthenticated user
 * input passed to the vision loader, which base64-encodes each image and
 * forwards it to the configured external provider — so without this an entry
 * like `../../../../etc/passwd` or an absolute `/etc/passwd` would exfiltrate an
 * arbitrary readable file (issue #1870, the sibling of the #1820 vision-test
 * fix). `basename` collapses every directory component (neutralizing `../`
 * traversal AND absolute-path escapes, including the legitimate absolute paths
 * the RunnerPage uploads under data/screenshots) and the extension allow-list
 * rejects non-image references before any file is read. Lives here (not the
 * shared loadImageAsBase64) so trusted in-process callers that pass validated
 * absolute paths from other image roots — e.g. Universe Builder gallery images
 * under data/images — keep working; only the HTTP boundary is constrained.
 *
 * @param {unknown} screenshots
 * @returns {{ safe: string[], rejected: string[] }}
 */
export function sanitizeScreenshotRefs(screenshots) {
  const safe = [];
  const rejected = [];
  if (!Array.isArray(screenshots)) return { safe, rejected };
  for (const entry of screenshots) {
    if (typeof entry !== 'string' || !entry) {
      rejected.push(String(entry));
      continue;
    }
    const name = basename(entry);
    if (!name || name === '.' || name === '..' ||
        !ALLOWED_SCREENSHOT_EXTENSIONS.has(extname(name).toLowerCase())) {
      rejected.push(entry);
      continue;
    }
    safe.push(name);
  }
  return { safe, rejected };
}

/** A service or bootstrap slug on a preset (#7565): the same alphabet as a record id, clearable with `null`. */
const presetSlugField = z.string().regex(PRESET_ID_RE, 'must be a slug (lowercase alphanumeric with hyphens)').max(64).nullable().optional();

export const providerSchema = z.object({
  // Sample providers post a stable id (e.g. 'codex') so the server can adopt
  // them verbatim rather than slugifying the display name (which would turn
  // 'Codex CLI' into 'codex-cli' and break id-keyed CLI argument handling).
  id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, 'id must be lowercase alphanumeric with hyphens').max(80).optional(),
  name: z.string().min(1).max(100),
  type: z.enum(['cli', 'api', 'tui']),
  command: z.string().trim().optional(),
  args: z.array(z.string()).optional(),
  // CLI providers send `endpoint: ''` from the form; coerce empty/null to
  // undefined so the URL check only runs for actual values (API providers).
  endpoint: z.preprocess(
    (v) => (v === '' || v === null ? undefined : v),
    z.string().url().optional()
  ),
  apiKey: z.string().optional(),
  models: z.array(z.string()).optional(),
  // Optional hardware gates for local providers. The PortOS host decorates
  // responses with inferred runtime requirements as well, so old records do
  // not need a migration to participate in filtering.
  hardwareRequirements: providerHardwareRequirementsSchema.optional(),
  modelHardwareRequirements: z.record(providerHardwareRequirementsSchema).optional(),
  defaultModel: z.string().nullable().optional(),
  // Empty string is the UI's "use the provider/CLI default" sentinel.
  effort: providerEffort,
  lightModel: z.string().nullable().optional(),
  mediumModel: z.string().nullable().optional(),
  heavyModel: z.string().nullable().optional(),
  ultraModel: z.string().nullable().optional(),
  // PRESET-ONLY: the fallback chain reads `providers[fallbackProvider]` off the
  // stored map, where a composite never exists (#7564). `''` stays accepted: it is
  // the picker's "None (use system default)" sentinel, and ProviderForm spreads
  // the whole form into the body, so EVERY provider saved without a fallback
  // sends it. Refine rather than a union so the refusal keeps naming the rule.
  fallbackProvider: z.string().max(80).refine((value) => value === '' || PRESET_ID_RE.test(value), PRESET_ONLY_MESSAGE).nullable().optional(),
  // Model to run on the fallback provider. The UI sends '' when no model is
  // pinned (fall back to the fallback provider's own default), so allow empty.
  fallbackModel: z.string().nullable().optional(),
  // Per-request context window (Ollama num_ctx). Lifts the ~4K default so long
  // prompts (e.g. a whole manuscript) aren't silently truncated. Null = unset.
  numCtx: z.number().int().min(512).max(1048576).nullable().optional(),
  // Default generation controls for the local OpenAI-compatible backends
  // (Ollama, llama.cpp, MTPLX, vLLM) and the OpenCode wrappers in front of them.
  // Provider-level so the same local model keeps its defaults across API, CLI,
  // and TUI launchers; a run may still override them per task.
  // All three are nullable, and null is the UI's "unset" — a backend that is
  // never told a temperature / top_p / thinking mode keeps its own, which is not
  // the same as being pinned to a value. Without a clearable null the editor
  // could only ever add a pin, never remove one.
  temperature: z.number().min(0).max(2).nullable().optional(),
  topP: z.number().min(0).max(1).nullable().optional(),
  thinking: z.boolean().nullable().optional(),
  // Planning-time context window (tokens) the editorial budgeter may assume for
  // this provider — distinct from numCtx (what we *ask Ollama for*). For cloud
  // providers numCtx stays null and this reflects the model's real ceiling.
  contextWindow: z.number().int().min(512).max(2097152).nullable().optional(),
  // Per-model context windows READ FROM the provider's own `/models` catalog
  // (OpenRouter's `context_length`, vLLM's `max_model_len`, …), keyed by model
  // id. Written by model refresh, not typed by a human — it beats the hardcoded
  // model table and loses to the explicit `contextWindow` override above.
  // The ceiling is deliberately wider than `contextWindow`'s: that one bounds
  // what a person can type, this one has to accept whatever a vendor declares,
  // and rejecting a 10M-window model would 400 the whole provider write.
  modelContextWindows: z.record(z.number().int().min(512).max(33554432)).optional(),
  // Which of the provider's advertised catalog this install is entitled to
  // run — a plan/tier scope the upstream `/models` response does not declare
  // (internal/modelAccess.js). Applied on the way OUT to model pickers; the
  // stored `models` catalog is never narrowed by it. Nullable so the editor can
  // clear a policy back to "none" (absent means "unchanged" on a PATCH).
  modelAccess: z.object({
    mode: z.enum(MODEL_ACCESS_MODES),
    // An EMPTY list is valid and means "no constraint yet" — see the sentinel
    // note in internal/modelAccess.js. Rejecting it here would make the editor
    // unable to save the mode before the list is typed.
    patterns: z.array(z.string().trim().min(1).max(MAX_MODEL_ACCESS_PATTERN_LENGTH))
      .max(MAX_MODEL_ACCESS_PATTERNS).optional(),
  }).strict().nullable().optional(),
  timeout: z.number().int().min(MIN_TIMEOUT).max(MAX_TIMEOUT).optional(),
  enabled: z.boolean().optional(),
  // A CLI/TUI provider that can ALSO serve plain text through a non-HTTP
  // transport — today only `codex-app-server`, the ChatGPT-subscription
  // endpoint. A string rather than a boolean so a second transport is a new
  // value instead of a second flag that can contradict the first. Declaring it
  // only ADVERTISES the capability.
  textTransport: z.enum(['codex-app-server']).nullable().optional(),
  // The explicit opt-in that makes the advertised transport usable. Separate
  // from `enabled` (which governs the CLI harness) and defaulted off, so a
  // fresh install never bills a subscription for a background feature the user
  // has not knowingly pointed at it.
  textTransportEnabled: z.boolean().optional(),
  // The read-only sandbox blocks writes but not absolute-path reads. This
  // acknowledgement is separate from the enable flag so an API/client cannot
  // turn the transport on without recording the user's explicit consent.
  textTransportReadRiskAcknowledged: z.boolean().optional(),
  // Marks a `claude` CLI/TUI provider whose ANTHROPIC_BASE_URL points at a
  // local Ollama daemon — the "Claude Ollama" pattern. Drives model refresh to
  // pull tool-use-capable Ollama models instead of the static Anthropic list.
  ollamaBacked: z.boolean().optional(),
  // Marks a harness wrapper (OpenCode, and Codex via its native `--oss
  // --local-provider lmstudio`) whose backend is the LM Studio server on this
  // machine. Distinct from `ollamaBacked`: a different daemon, a different port,
  // and — unlike Ollama — a context window that is fixed when the model is
  // LOADED rather than settable per request, so PortOS prepares nothing before a
  // spawn (see `localRuntimeNamespace` in ../providerModels.js).
  lmstudioBacked: z.boolean().optional(),
  // Marks an OpenCode CLI/TUI wrapper for a separately started MTPLX native-MTP
  // server. This is intentionally distinct from `ollamaBacked`: model weights
  // and runtime protocol configuration are not interchangeable.
  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 serving Qwen3.8-27B with DFlash 2 drafting. Distinct from
  // `llamaBacked`: a different engine, a different port, and a different auth
  // story (vLLM is started behind an API key; llama-server is not).
  vllmBacked: z.boolean().optional(),
  // Marks an OpenCode CLI/TUI wrapper for a separately started local SGLang
  // container serving Qwen3.8-27B on a Hopper/Blackwell card. Distinct from
  // `vllmBacked`: a different engine, a different port, a different tool-call
  // parser, and an API key that is optional rather than required.
  sglangBacked: z.boolean().optional(),
  // Marks an OpenCode CLI/TUI wrapper for a hosted OpenAI-compatible gateway
  // ('orcarouter', 'openrouter', 'nvidia-nim' — see internal/gateways.js). Its API key is read
  // from the sibling API record of the SAME id at spawn/refresh time and is
  // never stored in this wrapper's config.
  gatewayBacked: z.string().optional(),
  // Legacy per-gateway marker, superseded by `gatewayBacked` and still read
  // forever — stored records are never rewritten (installs upgrade on their own
  // schedule, so an older peer/version must keep resolving its own data).
  orcarouterBacked: z.boolean().optional(),
  // Explicit opt-in to attach the provider's API key to an arbitrary
  // (non-local, non-allowlisted) endpoint. Guards against SSRF / key
  // exfiltration to a hostile or mistyped host — see
  // endpointGuard.js. Metadata endpoints stay blocked even when true.
  allowCustomEndpoint: z.boolean().optional(),
  // Pin a Codex CLI/TUI provider to PortOS's own account by appending
  // `--ignore-user-config` at spawn, so a bridge that re-pointed model routing
  // in the user's `~/.codex/config.toml` no longer decides where PortOS's runs
  // go. Default OFF: today's behavior (Codex reads the user's config) is the
  // one an existing install already relies on, and an override that silently
  // turned itself on would be its own surprise.
  ignoreUserConfig: z.boolean().optional(),
  // Codex authentication method pin (`forced_login_method`): 'chatgpt' = the
  // ChatGPT subscription, 'api' = API-key billing. Absent/null = Codex decides
  // from its own login state. Some models are available to only one method.
  codexAuthMode: z.enum(['chatgpt', 'api']).nullable().optional(),
  // A CLI/TUI provider whose harness auth is provisioned by an external CLI at
  // spawn time (e.g. a short-lived token for a proxy) rather than a static
  // `apiKey` PortOS stores. PortOS spawns `command`(+`args`) in front of the
  // harness invocation instead of the harness directly — the generic
  // `<bootstrap> run <harness> ...` shape. `setupCommand` is advisory only
  // (shown to the user as a one-time step, e.g. installing the bootstrap CLI's
  // package) — PortOS never executes it. Nullable so the editor can explicitly
  // clear a previously-set bootstrap back to "none" (absent means "unchanged"
  // on a PATCH, which is not the same as clearing it).
  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(),
    // What PortOS names the harness AS, when calling the bootstrap CLI — some
    // wrapper CLIs use their own identifier for a harness rather than its
    // binary name (e.g. `claude-code` where `command` is the binary `claude`).
    // Defaults to `command` when unset.
    harnessId: z.string().trim().min(1).max(100).optional(),
    // Inserted between the harness identifier and the harness's OWN args —
    // some wrapper CLIs need their own flags kept apart from the wrapped
    // program's (e.g. `<bootstrap> run <harness> -- <harness args>`).
    argsSeparator: z.string().trim().max(20).optional(),
  }).strict().nullable().optional(),
  envVars: z.record(z.string()).optional(),
  secretEnvVars: z.array(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(),
  // Claude Code's hidden `/low-priority` command is available only from its
  // interactive TUI after a session usage limit. It is an explicit opt-in
  // because continuation can draw on weekly usage.
  lowPriorityOnUsageLimit: z.boolean().optional(),
  // PRESET structure (#7565): a record carrying all three of `harnessId`,
  // `method` and `serviceId` is a DERIVED preset — its connection-owned values
  // are re-materialized from the named service instance on every save by the
  // host (`server/lib/providerPresets.js`). A record without them is a legacy
  // preset, executed exactly as before. Additive and nullable so an editor can
  // clear them; `method` must equal `type` (the host enforces it, since a
  // refinement here would not survive `.partial()` / `.extend()`). The ids are
  // slugs rather than enums because this directory stays self-contained.
  harnessId: z.string().regex(/^[a-z0-9-]+$/, 'harnessId must be a harness id').max(64).nullable().optional(),
  method: z.enum(['cli', 'tui', 'api']).nullable().optional(),
  serviceId: presetSlugField,
  // The subset of the service catalog this preset offers; `null` = the whole catalog.
  catalogNarrowing: z.array(z.string().trim().min(1).max(512)).max(1000).nullable().optional(),
  // The configured credential-bootstrap app (`settings.credentialBootstraps`
  // slug) a derived cli/tui preset spawns through; materialization writes the
  // inline `credentialBootstrap` object from it.
  credentialBootstrapId: presetSlugField,
});

/**
 * What ONE mode of a dual-mode create may set for itself.
 *
 * Every rule is taken from `providerSchema`'s own shape rather than restated,
 * so a bound the single-mode create enforces cannot quietly differ from the one
 * a pair create enforces. The set is deliberately small: anything NOT here is
 * shared by both records, which is what keeps the pair groupable
 * (`providerModeGroups` refuses siblings that disagree on command, endpoint,
 * credentials or env — the disjointness test in `validation.test.js` pins that
 * these keys stay clear of {@link MODE_GROUPED_KEYS}).
 */
const providerModeOverrideSchema = z.object({
  args: providerSchema.shape.args,
  headlessArgs: providerSchema.shape.headlessArgs,
  tuiPromptDelayMs: providerSchema.shape.tuiPromptDelayMs,
}).strict();

/** The keys {@link providerModeOverrideSchema} lets a mode vary. */
export const PROVIDER_MODE_OVERRIDE_KEYS = Object.freeze(Object.keys(providerModeOverrideSchema.shape));

/**
 * POST /api/providers — the create body, which may declare BOTH execution modes
 * of one harness instead of forcing the user to add the CLI and the TUI
 * separately and hope the two records happen to pair.
 *
 * Both keys are required: declaring a single mode is what `type` is for, so the
 * map's presence IS the "make me a pair" request. An empty `cli: {}` is the
 * normal case — the body's own `args` / `headlessArgs` already describe the CLI
 * record, and the key is there so the pair is declared rather than inferred.
 *
 * This `modes` is a per-mode MAP, where `POST /api/providers/bindings` takes a
 * plain array of mode names, because the two creates get their argv from
 * different places: a binding mints from the harness's shipped command recipe,
 * while a provider added here has no recipe at all — the user types each mode's
 * arguments, and they need somewhere to land.
 *
 * Create-only, and deliberately absent from `providerSchema` itself: pairing
 * describes two records being MINTED together, which a PATCH against one
 * existing record cannot mean, so the PATCH route's `providerSchema.partial()`
 * drops the key instead of half-acting on it.
 */
export const providerCreateSchema = providerSchema.extend({
  modes: z.object({
    cli: providerModeOverrideSchema,
    tui: providerModeOverrideSchema,
  }).strict().optional(),
});


// PUT /api/providers/active — set the active provider by id. Constrain to the
// same slug shape createProvider assigns (`providerSchema.id`) so a reserved
// key like `__proto__` can't reach the `data.providers[id]` lookup in
// setActiveProvider (which walks the prototype chain and would otherwise treat
// `__proto__` as an existing provider and persist it as active).
export const providerActiveSchema = z.object({
  id: z.string().regex(PRESET_ID_RE, PRESET_ONLY_MESSAGE).max(80)
});

export const runSchema = z.object({
  // `type` defaults to 'ai' so the common case (AI run via /api/runs from
  // RunnerPage / AIProviders / etc.) doesn't have to send it explicitly.
  type: z.enum(['ai', 'command']).optional().default('ai'),
  providerId: providerRefSchema.optional(),
  model: z.string().optional(),
  workspacePath: z.string().optional(),
  workspaceName: z.string().optional(),
  command: z.string().optional(),
  prompt: z.string().optional(),
  screenshots: z.array(z.string()).optional(),
  timeout: z.number().int().min(MIN_TIMEOUT).max(MAX_TIMEOUT).optional()
});

// Prompt routes (routes/prompts.js). Free-form maps stay `z.record` because the
// stage config / variable / preview payloads are user-defined shapes; the point
// is that a wrong-typed top level (array, string, `config: "x"`) bounces as a
// 400 instead of reaching the file-writing service.
export const promptStageUpdateBodySchema = z.object({
  config: z.record(z.string(), z.unknown()).optional(),
  template: z.string().optional()
});
export const promptPreviewBodySchema = z.record(z.string(), z.unknown());
export const promptVariableCreateBodySchema = z.object({
  key: z.string().regex(/^[A-Za-z0-9_-]+$/, 'invalid variable key').max(80)
}).catchall(z.unknown());
export const promptVariableUpdateBodySchema = z.record(z.string(), z.unknown());

// POST /api/provider-status/:id/usage-limit — `waitTime` is a display string the
// status service regex-matches, so a non-string would throw a 500 there.
export const providerUsageLimitBodySchema = z.object({
  message: z.string().optional(),
  waitTime: z.string().optional()
});

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
    }))
  };
}