@hienlh/ppm 0.23.24 → 0.23.26

package/src/shared/schedule-definition.ts

@@ -0,0 +1,127 @@
+/**
+ * What makes a schedule definition valid: one set of rules for the routes, the CLI, the browser
+ * form and template import, so a template that imports is one the form would have accepted.
+ * Fields use the template's spelling (`cron`, `timeoutMs`…); the routes translate theirs.
+ */
+import { VALID_PERMISSION_MODES } from "../types/config.ts";
+import type { ScheduleInputDecl, ScheduleInputValue, ScheduleKind, ScheduleMode } from "../types/scheduler.ts";
+import { cronProblem } from "./schedule-cron.ts";
+
+export const SCHEDULE_LIMITS = {
+  name: 100,
+  description: 2000,
+  prompt: 100_000,
+  scriptBytes: 1_000_000,
+  inputs: 50,
+  inputLabel: 100,
+  inputDescription: 500,
+  minTimeoutMs: 10_000,
+  maxTimeoutMs: 6 * 60 * 60_000,
+} as const;
+
+export const DEFAULT_TIMEOUT_MS: Record<ScheduleKind, number> = { prompt: 1_800_000, script: 300_000 };
+
+export interface ScheduleDefinition {
+  kind: ScheduleKind;
+  mode: ScheduleMode;
+  cron?: string;
+  prompt?: string;
+  script?: string;
+  inputs?: ScheduleInputDecl[];
+  timeoutMs?: number;
+  maxTurns?: number;
+  permissionMode?: string;
+}
+
+const INPUT_KEY = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const INPUT_TYPES: readonly string[] = ["text", "number", "boolean", "secret"];
+const INPUT_FIELDS = new Set(["key", "label", "type", "required", "default", "description"]);
+
+export const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const utf8Length = (s: string): number => new TextEncoder().encode(s).length;
+
+/** Whether `value` has the type `decl` says (a secret is a string). */
+export function inputValueFits(decl: Pick<ScheduleInputDecl, "type">, value: unknown): value is ScheduleInputValue {
+  if (decl.type === "number") return typeof value === "number" && Number.isFinite(value);
+  if (decl.type === "boolean") return typeof value === "boolean";
+  return typeof value === "string";
+}
+
+/** Every problem with a list of input declarations, one sentence each. */
+export function inputDeclProblems(inputs: unknown): string[] {
+  if (!Array.isArray(inputs)) return ["inputs must be a list"];
+  const errors: string[] = [];
+  if (inputs.length > SCHEDULE_LIMITS.inputs) errors.push(`At most ${SCHEDULE_LIMITS.inputs} inputs`);
+  const seen = new Set<string>();
+  inputs.forEach((input, i) => {
+    const at = `inputs[${i}]`;
+    if (!isPlainObject(input)) { errors.push(`${at} must be an object`); return; }
+    for (const field of Object.keys(input)) if (!INPUT_FIELDS.has(field)) errors.push(`${at}: unknown field "${field}"`);
+    const { key, label, type, required, description } = input;
+    if (typeof key !== "string" || !INPUT_KEY.test(key)) errors.push(`${at}: key must be a letter or _ followed by letters, digits or _ (64 at most)`);
+    else if (seen.has(key)) errors.push(`${at}: key "${key}" is declared twice`);
+    else seen.add(key);
+    const name = typeof key === "string" ? `input "${key}"` : at;
+    if (typeof label !== "string" || !label.trim() || label.length > SCHEDULE_LIMITS.inputLabel) errors.push(`${name}: label must be 1-${SCHEDULE_LIMITS.inputLabel} characters`);
+    if (typeof type !== "string" || !INPUT_TYPES.includes(type)) errors.push(`${name}: type must be text, number, boolean or secret`);
+    if (required !== undefined && typeof required !== "boolean") errors.push(`${name}: required must be true or false`);
+    if (description !== undefined && (typeof description !== "string" || description.length > SCHEDULE_LIMITS.inputDescription)) {
+      errors.push(`${name}: description must be text of at most ${SCHEDULE_LIMITS.inputDescription} characters`);
+    }
+    if ("default" in input) {
+      if (type === "secret") errors.push(`${name}: a secret cannot have a default, or the file would be sharing it`);
+      else if (typeof type === "string" && INPUT_TYPES.includes(type) && !inputValueFits({ type: type as ScheduleInputDecl["type"] }, input.default)) {
+        errors.push(`${name}: default must be a ${type === "text" ? "string" : type}`);
+      }
+    }
+  });
+  return errors;
+}
+
+/** Every problem with `def`, one sentence each; empty when it is a valid schedule. */
+export function definitionProblems(def: Record<string, unknown>): string[] {
+  const { kind, mode, cron, prompt, script, inputs, timeoutMs, maxTurns, permissionMode } = def;
+  if (kind !== "prompt" && kind !== "script") return ['kind must be "prompt" or "script"'];
+  const errors: string[] = [];
+  if (mode !== "tick" && mode !== "always-on") errors.push('mode must be "tick" or "always-on"');
+  else if (kind === "prompt" && mode !== "tick") errors.push("A prompt schedule runs on a cron; it cannot be always on");
+
+  if (mode === "tick") {
+    if (typeof cron !== "string" || !cron.trim()) errors.push("A tick schedule needs a cron expression");
+    else {
+      const problem = cronProblem(cron, kind);
+      if (problem) errors.push(problem);
+    }
+  } else if (mode === "always-on" && cron !== undefined && cron !== "") {
+    errors.push("An always-on schedule has no cron expression");
+  }
+
+  if (kind === "prompt") {
+    if (typeof prompt !== "string" || !prompt.trim()) errors.push("A prompt schedule needs a prompt");
+    else if (prompt.length > SCHEDULE_LIMITS.prompt) errors.push(`The prompt is longer than ${SCHEDULE_LIMITS.prompt} characters`);
+    if (script !== undefined && script !== null && script !== "") errors.push("A prompt schedule has no script");
+    if (Array.isArray(inputs) ? inputs.length > 0 : inputs !== undefined) errors.push("Only a script schedule has inputs");
+  } else {
+    if (typeof script !== "string" || !script.trim()) errors.push("A script schedule needs a script");
+    else if (utf8Length(script) > SCHEDULE_LIMITS.scriptBytes) errors.push("The script is larger than 1 MB");
+    if (prompt !== undefined && prompt !== "") errors.push("A script schedule has no prompt");
+    if (inputs !== undefined) errors.push(...inputDeclProblems(inputs));
+  }
+
+  if (timeoutMs !== undefined) {
+    if (mode === "always-on") errors.push("An always-on schedule has no run timeout");
+    else if (!Number.isInteger(timeoutMs) || (timeoutMs as number) < SCHEDULE_LIMITS.minTimeoutMs || (timeoutMs as number) > SCHEDULE_LIMITS.maxTimeoutMs) {
+      errors.push("timeoutMs must be a whole number of milliseconds between 10 seconds and 6 hours");
+    }
+  }
+  // A script's ctx.ai.chat turn runs on the chat's own settings: its turn cap belongs to the
+  // chat's process, shared with whoever else writes there, so a schedule cannot set one.
+  if (maxTurns !== undefined && kind === "script") errors.push("Only a prompt schedule has maxTurns");
+  else if (maxTurns !== undefined && (!Number.isInteger(maxTurns) || (maxTurns as number) < 1)) errors.push("maxTurns must be a whole number of at least 1");
+  if (permissionMode !== undefined && !(VALID_PERMISSION_MODES as readonly unknown[]).includes(permissionMode)) {
+    errors.push(`permissionMode must be one of ${VALID_PERMISSION_MODES.join(", ")}`);
+  }
+  return errors;
+}

package/src/shared/schedule-inputs.ts

@@ -0,0 +1,85 @@
+/**
+ * Input values of a script schedule. A value is kept apart from its declaration: the
+ * non-secret ones in plain JSON, the secret ones encrypted on the server. These helpers are
+ * the rules both halves share; none of them ever echoes a secret's value back.
+ */
+import type { ScheduleInputDecl, ScheduleInputValue } from "../types/scheduler.ts";
+import { inputValueFits } from "./schedule-definition.ts";
+
+/** A value to set, or null to clear it (back to the default; a cleared secret is unset). */
+export type InputValuePatch = Record<string, ScheduleInputValue | null>;
+
+const typeName = (decl: ScheduleInputDecl): string => (decl.type === "text" || decl.type === "secret" ? "text" : decl.type);
+
+/** Problems with values a caller supplies: `values` for ordinary inputs, `secrets` for secret ones. */
+export function inputValueProblems(decls: ScheduleInputDecl[], values: InputValuePatch, secrets: InputValuePatch = {}): string[] {
+  const byKey = new Map(decls.map((d) => [d.key, d]));
+  const errors: string[] = [];
+  for (const [key, value] of Object.entries(values)) {
+    const decl = byKey.get(key);
+    if (!decl) errors.push(`No input named "${key}"`);
+    else if (decl.type === "secret") errors.push(`"${key}" is a secret; set it as a secret`);
+    else if (value !== null && !inputValueFits(decl, value)) errors.push(`"${key}" must be ${typeName(decl)}`);
+  }
+  for (const [key, value] of Object.entries(secrets)) {
+    const decl = byKey.get(key);
+    if (!decl) errors.push(`No input named "${key}"`);
+    else if (decl.type !== "secret") errors.push(`"${key}" is not a secret`);
+    else if (value !== null && (typeof value !== "string" || value === "")) errors.push(`The secret "${key}" must be non-empty text`);
+  }
+  return errors;
+}
+
+/** Text from a command line, as the type `decl` declares; an Error when it does not read as one. */
+export function coerceInputValue(decl: ScheduleInputDecl, raw: string): ScheduleInputValue | Error {
+  if (decl.type === "number") {
+    const n = Number(raw);
+    return raw.trim() !== "" && Number.isFinite(n) ? n : new Error(`"${decl.key}" must be a number`);
+  }
+  if (decl.type === "boolean") {
+    const v = raw.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(v)) return true;
+    if (["false", "0", "no", "off"].includes(v)) return false;
+    return new Error(`"${decl.key}" must be true or false`);
+  }
+  return raw;
+}
+
+/** Required inputs with nothing to run on: no value, no default, and for a secret, nothing saved. */
+export function missingRequiredInputs(
+  decls: ScheduleInputDecl[],
+  values: Record<string, ScheduleInputValue>,
+  secretsSet: readonly string[],
+): string[] {
+  return decls
+    .filter((d) => d.required)
+    .filter((d) => (d.type === "secret" ? !secretsSet.includes(d.key) : values[d.key] === undefined && d.default === undefined))
+    .map((d) => d.key);
+}
+
+/**
+ * Declarations in one spelling: fields in a fixed order, `required` only when true. Saved that
+ * way, a form that sends back what it was given saves the same text, and an always-on process
+ * is not restarted by a save that changed nothing.
+ */
+export function normalizeInputs(decls: ScheduleInputDecl[]): ScheduleInputDecl[] {
+  return decls.map((d) => ({
+    key: d.key,
+    label: d.label,
+    type: d.type,
+    ...(d.required && { required: true }),
+    ...(d.default !== undefined && { default: d.default }),
+    ...(d.description && { description: d.description }),
+  }));
+}
+
+/** What a script sees as `ctx.inputs`: the value, else the default, else undefined. */
+export function resolveInputValues(
+  decls: ScheduleInputDecl[],
+  values: Record<string, ScheduleInputValue>,
+  secrets: Record<string, string>,
+): Record<string, ScheduleInputValue | undefined> {
+  const out: Record<string, ScheduleInputValue | undefined> = {};
+  for (const d of decls) out[d.key] = d.type === "secret" ? secrets[d.key] : (values[d.key] ?? d.default);
+  return out;
+}

package/src/shared/schedule-template.ts

@@ -0,0 +1,164 @@
+/**
+ * A schedule as one shareable file, `<name>.ppm-schedule.json`.
+ *
+ * What a template never carries: a secret's value, ids, the chat session, the script's state,
+ * run history, the project or provider it ran on, or a path on the machine it came from. A
+ * secret input is declared with no default, and a file that gives one a default is refused, so
+ * nobody shares a token by exporting a schedule. Parsing is strict: an unknown field or format
+ * version refuses the whole file rather than dropping what it does not understand.
+ */
+import type { ScheduleInputDecl, ScheduleInputValue, ScheduleKind, ScheduleMode } from "../types/scheduler.ts";
+import { definitionProblems, isPlainObject, SCHEDULE_LIMITS, type ScheduleDefinition } from "./schedule-definition.ts";
+
+export const SCHEDULE_TEMPLATE_VERSION = 1;
+export const SCHEDULE_TEMPLATE_SUFFIX = ".ppm-schedule.json";
+
+export interface ScheduleTemplate extends ScheduleDefinition {
+  ppmScheduleTemplate: typeof SCHEDULE_TEMPLATE_VERSION;
+  name: string;
+  description?: string;
+}
+
+export type TemplateParse = { ok: true; template: ScheduleTemplate } | { ok: false; errors: string[] };
+
+/** Field order of a written template; also the only fields a template may have. */
+const FIELDS = [
+  "ppmScheduleTemplate", "name", "description", "kind", "mode", "cron", "prompt", "script",
+  "inputs", "timeoutMs", "maxTurns", "permissionMode",
+] as const;
+
+const INPUT_ORDER = ["key", "label", "type", "required", "default", "description"] as const;
+
+/** A path that only means something on the machine it was written on. */
+const ABSOLUTE_PATH = /^(?:\/|~(?:[/\\]|$)|[A-Za-z]:[\\/]|\\\\)/;
+
+export function parseScheduleTemplate(input: unknown): TemplateParse {
+  let data = input;
+  if (typeof input === "string") {
+    try {
+      data = JSON.parse(input);
+    } catch {
+      // Not the parser's message: it quotes the text it stopped at, and a file picked by
+      // mistake can be a token (`Unexpected identifier "ghp_…"`).
+      return { ok: false, errors: ["This file is not JSON"] };
+    }
+  }
+  if (!isPlainObject(data) || !("ppmScheduleTemplate" in data)) {
+    return { ok: false, errors: ["This is not a PPM schedule template (it has no ppmScheduleTemplate field)"] };
+  }
+  const version = data.ppmScheduleTemplate;
+  if (version !== SCHEDULE_TEMPLATE_VERSION) {
+    return {
+      ok: false,
+      errors: [typeof version === "number" && version > SCHEDULE_TEMPLATE_VERSION
+        ? `This template was made by a newer PPM (format ${version}); update PPM to import it`
+        : `Unknown template format: ${JSON.stringify(version)}`],
+    };
+  }
+  const errors: string[] = [];
+  for (const field of Object.keys(data)) {
+    if (!(FIELDS as readonly string[]).includes(field)) errors.push(`Unknown field "${field}"`);
+  }
+  const { name, description } = data;
+  if (typeof name !== "string" || !name.trim() || name.length > SCHEDULE_LIMITS.name) {
+    errors.push(`name must be 1-${SCHEDULE_LIMITS.name} characters`);
+  }
+  if (description !== undefined && (typeof description !== "string" || description.length > SCHEDULE_LIMITS.description)) {
+    errors.push(`description must be text of at most ${SCHEDULE_LIMITS.description} characters`);
+  }
+  errors.push(...definitionProblems(data));
+  if (errors.length) return { ok: false, errors };
+  return { ok: true, template: ordered(data) as unknown as ScheduleTemplate };
+}
+
+/** The schedule fields an export reads, as the server holds them. */
+export interface TemplateSource {
+  name: string;
+  description: string;
+  kind: ScheduleKind;
+  mode: ScheduleMode;
+  cron_expr: string;
+  prompt: string;
+  script: string | null;
+  inputs: ScheduleInputDecl[];
+  inputValues: Record<string, ScheduleInputValue>;
+  timeout_ms: number;
+  max_turns: number | null;
+  permission_mode: string;
+}
+
+/**
+ * A template of `s`. A non-secret input's current value becomes its default, unless it looks
+ * like an absolute path (which is warned about). `machinePaths` (the home directory, the project folder) are looked for
+ * in the script or prompt: each line that names one comes back as a warning, not a refusal —
+ * the code is the author's to fix.
+ */
+export function templateFromSchedule(s: TemplateSource, machinePaths: string[] = []): { template: ScheduleTemplate; warnings: string[] } {
+  const warnings: string[] = [];
+  const inputs = s.inputs.map((decl) => {
+    const { default: declared, ...rest } = decl;
+    const current = s.inputValues[decl.key];
+    if (decl.type === "secret") return rest;
+    const isPath = typeof current === "string" && ABSOLUTE_PATH.test(current);
+    if (isPath) warnings.push(`The value of "${decl.key}" is a path on this machine, so it was left out`);
+    const keepDeclared = current === undefined || isPath;
+    const value = keepDeclared ? declared : current;
+    return value === undefined ? rest : { ...rest, default: value };
+  });
+  const raw: Record<string, unknown> = {
+    ppmScheduleTemplate: SCHEDULE_TEMPLATE_VERSION,
+    name: s.name,
+    ...(s.description && { description: s.description }),
+    kind: s.kind,
+    mode: s.mode,
+    ...(s.mode === "tick" && { cron: s.cron_expr }),
+    ...(s.kind === "prompt" ? { prompt: s.prompt } : { script: s.script ?? "", inputs }),
+    ...(s.mode === "tick" && { timeoutMs: s.timeout_ms }),
+    ...(s.max_turns != null && { maxTurns: s.max_turns }),
+    permissionMode: s.permission_mode,
+  };
+  const body = s.kind === "prompt" ? s.prompt : (s.script ?? "");
+  warnings.push(...machinePathWarnings(body, machinePaths));
+  return { template: ordered(raw) as unknown as ScheduleTemplate, warnings };
+}
+
+export function serializeScheduleTemplate(template: ScheduleTemplate): string {
+  return `${JSON.stringify(ordered(template as unknown as Record<string, unknown>), null, 2)}\n`;
+}
+
+export function scheduleTemplateFileName(name: string): string {
+  const slug = name
+    .replace(/đ/g, "d").replace(/Đ/g, "D")
+    .normalize("NFKD").replace(/[̀-ͯ]/g, "")
+    .toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")
+    .slice(0, 60) || "schedule";
+  return `${slug}${SCHEDULE_TEMPLATE_SUFFIX}`;
+}
+
+function machinePathWarnings(body: string, machinePaths: string[]): string[] {
+  const paths = machinePaths.filter((p) => p.length > 1);
+  const warnings: string[] = [];
+  body.split("\n").forEach((line, i) => {
+    const hit = paths.find((p) => line.includes(p));
+    if (hit && warnings.length < 20) warnings.push(`Line ${i + 1} mentions ${hit}, which only exists on this machine`);
+  });
+  return warnings;
+}
+
+/** The known fields of `data` in the written order, inputs included; absent fields stay absent. */
+function ordered(data: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const field of FIELDS) {
+    if (data[field] === undefined) continue;
+    out[field] = field === "inputs" && Array.isArray(data.inputs)
+      ? data.inputs.map((input) => pick(input as Record<string, unknown>, INPUT_ORDER))
+      : data[field];
+  }
+  return out;
+}
+
+function pick(obj: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const k of keys) if (obj[k] !== undefined) out[k] = obj[k];
+  return out;
+}

package/src/types/config.ts

@@ -2,6 +2,7 @@ import { CLAUDE_MODEL_IDS } from "./claude-models.ts";
 import { DEFAULT_NOTIFICATION_SETTINGS, type NotificationSettings } from "../shared/notification-settings.ts";
 import { DEFAULT_LOG_LEVEL, type LogLevel } from "../shared/log-levels.ts";
 import type { PpmToolSwitches } from "../shared/ppm-tools.ts";
+import { isValidLeftoverIdleMinutes } from "../shared/leftover-processes.ts";
 
 export interface TelegramConfig {
   bot_token: string;
@@ -67,6 +68,7 @@ export interface PpmConfig {
   query_audit: QueryAuditConfig;
   session_trace: SessionTraceConfig;
   tunnel: TunnelConfig;
+  share_host: ShareHostConfig;
   android?: AndroidConfig;
   /** Lowest level written to ppm.log. `PPM_LOG_LEVEL` overrides it; see `services/logger.ts`. */
   log_level?: LogLevel;
@@ -96,6 +98,25 @@ export interface TunnelConfig {
   dismissed?: boolean;
 }
 
+/**
+ * The share host: a public address for design review links that reaches the review pages and
+ * nothing else of PPM (`src/services/share-host/`). `token` (named mode only) is secret, like
+ * `tunnel.namedTunnelToken`. The fields are kept when `mode` changes, so going back is one click.
+ */
+export interface ShareHostConfig {
+  /** Off until turned on: nothing is published for review links without it. */
+  enabled: boolean;
+  /** `quick`: its own temporary address; `named`: its own tunnel on a domain; `shared`: a hostname on PPM's tunnel. */
+  mode: "quick" | "named" | "shared";
+  hostname?: string;
+  /** The share host's own tunnel (`named`), kept after switching mode: this installation created it. */
+  tunnelName?: string;
+  /** Run token of that tunnel. Secret, like `namedTunnelToken`. */
+  token?: string;
+  zoneID?: string;
+  accountID?: string;
+}
+
 export interface QueryAuditConfig {
   /** Entries older than this are pruned. */
   retention_days: number;
@@ -138,6 +159,13 @@ export interface AIConfig {
   tab_tools?: boolean;
   /** PPM's own AI tools, on or off one by one (`src/shared/ppm-tools.ts` has the defaults). */
   ppm_tools?: PpmToolSwitches;
+  /**
+   * Idle minutes after which PPM stops what a chat left running — servers, emulators and daemons
+   * its commands started. Unset or 0 never stops them, and the server log names what 30 idle
+   * minutes would have stopped. Linux with systemd only
+   * (`src/services/chat-session-processes/`).
+   */
+  leftover_processes_idle_minutes?: number;
   providers: Record<string, AIProviderConfig>;
 }
 
@@ -157,6 +185,7 @@ export interface AIProviderConfig {
   api_key?: string;
   base_url?: string;
   effort?: "low" | "medium" | "high" | "xhigh" | "max";
+  // Steps one message may take, at most 1000; 0 = no limit.
   max_turns?: number;
   max_budget_usd?: number;
   thinking_budget_tokens?: number;
@@ -241,6 +270,10 @@ export const DEFAULT_CONFIG: PpmConfig = {
     enabled: true,
     mode: "quick",
   },
+  share_host: {
+    enabled: false,
+    mode: "quick",
+  },
   log_level: DEFAULT_LOG_LEVEL,
 };
 
@@ -303,8 +336,8 @@ export function validateAIProviderConfig(config: Partial<AIProviderConfig>): str
   if (config.effort && !VALID_EFFORTS.includes(config.effort as any)) {
     errors.push(`effort must be one of: ${VALID_EFFORTS.join(", ")}`);
   }
-  if (config.max_turns != null && (!Number.isInteger(config.max_turns) || config.max_turns < 1 || config.max_turns > 500)) {
-    errors.push("max_turns must be integer 1-500");
+  if (config.max_turns != null && (!Number.isInteger(config.max_turns) || config.max_turns < 0 || config.max_turns > 1000)) {
+    errors.push("max_turns must be a whole number from 0 to 1000, 0 for no limit");
   }
   if (config.max_budget_usd != null && (config.max_budget_usd < 0.01 || config.max_budget_usd > 50)) {
     errors.push("max_budget_usd must be 0.01-50.00");
@@ -374,6 +407,11 @@ export function sanitizeConfig(config: PpmConfig): boolean {
     dirty = true;
   }
 
+  if ("leftover_processes_idle_minutes" in config.ai && !isValidLeftoverIdleMinutes(config.ai.leftover_processes_idle_minutes)) {
+    delete config.ai.leftover_processes_idle_minutes;
+    dirty = true;
+  }
+
   // Migrate/repair theme (legacy string → {style, mode})
   const migrated = migrateThemeValue(config.theme);
   if (migrated) {
@@ -419,5 +457,13 @@ export function sanitizeConfig(config: PpmConfig): boolean {
     dirty = true;
   }
 
+  // Same rule as `tunnel`: repair only a malformed row; incomplete identities are the resolver's call.
+  const shareHost = config.share_host as ShareHostConfig | null | undefined;
+  if (typeof shareHost !== "object" || shareHost === null || typeof shareHost.enabled !== "boolean" ||
+      (shareHost.mode !== "quick" && shareHost.mode !== "named" && shareHost.mode !== "shared")) {
+    config.share_host = structuredClone(DEFAULT_CONFIG.share_host);
+    dirty = true;
+  }
+
   return dirty;
 }

package/src/types/scheduler.ts

@@ -2,6 +2,24 @@
 
 export type RunStatus = "running" | "done" | "error" | "skipped";
 
+/** `prompt`: a message sent to the schedule's own chat. `script`: JavaScript run in a child process. */
+export type ScheduleKind = "prompt" | "script";
+/** `tick`: one short run per cron fire. `always-on`: a daemon PPM keeps alive. A prompt is always `tick`. */
+export type ScheduleMode = "tick" | "always-on";
+export type ScheduleInputType = "text" | "number" | "boolean" | "secret";
+export type ScheduleInputValue = string | number | boolean;
+
+/** An input a script schedule declares. Its value is stored apart from the declaration. */
+export interface ScheduleInputDecl {
+  key: string;
+  label: string;
+  type: ScheduleInputType;
+  required?: boolean;
+  /** Never on a secret: a template carrying one would be sharing it. */
+  default?: ScheduleInputValue;
+  description?: string;
+}
+
 export interface Schedule {
   id: number;
   name: string;
@@ -18,6 +36,47 @@ export interface Schedule {
   next_fire_at: string | null;
   created_at: string;
   updated_at: string;
+  kind: ScheduleKind;
+  mode: ScheduleMode;
+  description: string;
+  /** Script source; null for a prompt schedule. */
+  script: string | null;
+  /** JSON array of {@link ScheduleInputDecl}. */
+  inputs_json: string;
+  /** JSON object of the non-secret input values. */
+  input_values_json: string;
+  /** The secret input values, encrypted. Never leaves the server. */
+  secrets_enc: string | null;
+  /** The script's `ctx.state`, as JSON. */
+  state_json: string | null;
+}
+
+/**
+ * What a script schedule's process is doing. `starting`: on, and not started yet (the server is
+ * still settling what the previous one left). `blocked`: a previous process could not be stopped,
+ * so this one is not started at all.
+ */
+export type ScheduleRunState = "idle" | "running" | "starting" | "stopping" | "restarting" | "failed" | "blocked" | "stopped";
+
+export interface ScheduleStatusView {
+  state: ScheduleRunState;
+  pid: number | null;
+  /** When the running process started. */
+  since: string | null;
+  /** When a crashed always-on process starts again. */
+  restartAt: string | null;
+  restarts: number;
+  lastError: string | null;
+}
+
+/** A schedule as the API answers it: never the secrets, not even encrypted, and not the state. */
+export interface ScheduleView extends Omit<Schedule, "secrets_enc" | "state_json" | "inputs_json" | "input_values_json"> {
+  inputs: ScheduleInputDecl[];
+  /** The non-secret input values. */
+  inputValues: Record<string, ScheduleInputValue>;
+  /** Which secret inputs have a value saved. */
+  secretsSet: string[];
+  status: ScheduleStatusView;
 }
 
 export interface ScheduleRun {
@@ -45,6 +104,13 @@ export interface NewSchedule {
   timeout_ms?: number;
   enabled?: boolean;
   next_fire_at?: string | null;
+  kind?: ScheduleKind;
+  mode?: ScheduleMode;
+  description?: string;
+  script?: string | null;
+  inputs_json?: string;
+  input_values_json?: string;
+  secrets_enc?: string | null;
 }
 
 /** Result of one schedule execution (returned by scheduler-runner). */
@@ -56,3 +122,21 @@ export interface RunResult {
   error?: string;
   rotatedToSessionId?: string;
 }
+
+/** What the scheduler runs schedules with; constructor-injected (`scheduler.service.ts`). */
+export interface SchedulerRunner {
+  ensureScheduleSession(schedule: Schedule): Promise<string>;
+  runScheduleOnce(schedule: Schedule, sessionId: string): Promise<RunResult>;
+  /** One tick of a script schedule, to the end of its process. */
+  runScriptTick(schedule: Schedule): Promise<void>;
+}
+
+/** The processes of always-on script schedules (`schedule-script/always-on-supervisor.ts`). */
+export interface AlwaysOnScripts {
+  /** Settles what a previous server left behind; no script starts before it is done. */
+  prepare(): Promise<void>;
+  sync(): void;
+  restart(id: number): Promise<void>;
+  isRunning(id: number): boolean;
+  stopAll(reason: string): void;
+}