@hienlh/ppm 0.23.24 → 0.23.26

package/src/services/schedule-script/ctx-ask.ts

@@ -0,0 +1,58 @@
+/**
+ * `ctx.ai.ask(prompt, opts)`: one question, one answer, through `completeOnce` — Claude's with
+ * PPM's account rotation, or the mock provider's free answer when the schedule runs on `mock`.
+ * A failed answer is a result with `ok: false`, never a throw: the script decides what then.
+ */
+import { providerRegistry } from "../../providers/registry.ts";
+import type { Schedule } from "../../types/scheduler.ts";
+
+export const ASK_DEFAULT_MODEL = "haiku";
+export const ASK_DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface AskOptions {
+  model?: string;
+  system?: string;
+  effort?: "low" | "medium" | "high";
+  jsonSchema?: Record<string, unknown>;
+  timeoutMs?: number;
+}
+
+export interface AskResult {
+  ok: boolean;
+  text: string;
+  json?: unknown;
+  costUsd?: number;
+  timedOut?: boolean;
+  error?: string;
+}
+
+type CompleteOnce = (input: {
+  prompt: string; model: string; systemPrompt?: string; effort?: AskOptions["effort"];
+  jsonSchema?: Record<string, unknown>; timeoutMs?: number;
+}) => Promise<{ text: string; json?: unknown; costUsd: number }>;
+
+export async function scheduleAsk(schedule: Pick<Schedule, "provider_id">, prompt: string, opts: AskOptions): Promise<AskResult> {
+  const providerId = schedule.provider_id === "mock" ? "mock" : "claude";
+  const provider = providerRegistry.get(providerId) as { completeOnce?: CompleteOnce } | undefined;
+  if (typeof provider?.completeOnce !== "function") {
+    return { ok: false, text: "", error: `The ${providerId} provider is not available` };
+  }
+  const timeoutMs = opts.timeoutMs ?? ASK_DEFAULT_TIMEOUT_MS;
+  const started = Date.now();
+  try {
+    const answer = await provider.completeOnce({
+      prompt,
+      model: opts.model ?? ASK_DEFAULT_MODEL,
+      ...(opts.system !== undefined && { systemPrompt: opts.system }),
+      ...(opts.effort && { effort: opts.effort }),
+      ...(opts.jsonSchema && { jsonSchema: opts.jsonSchema }),
+      timeoutMs,
+    });
+    return { ok: true, text: answer.text, ...(answer.json !== undefined && { json: answer.json }), costUsd: answer.costUsd };
+  } catch (e) {
+    return {
+      ok: false, text: "", error: (e as Error).message,
+      ...(Date.now() - started >= timeoutMs && { timedOut: true }),
+    };
+  }
+}

package/src/services/schedule-script/ctx-host.ts

@@ -0,0 +1,113 @@
+/**
+ * PPM's side of a script's `ctx` (contract in the plan's ctx-api.md): answers the `call`s its
+ * process makes. A call made wrongly — no prompt, an option that does not exist — throws, so
+ * the script sees it at once; an AI that fails or runs out of time answers `ok: false`.
+ */
+import { isPlainObject } from "../../shared/schedule-definition.ts";
+import type { Schedule } from "../../types/scheduler.ts";
+import { projectService } from "../project.service.ts";
+import { scheduleChat, type ChatCallOptions } from "./chat-bridge.ts";
+import { scheduleAsk, type AskOptions } from "./ctx-ask.ts";
+import { saveState } from "./ctx-state.ts";
+import { collectFinishedTurns } from "./schedule-chat-db.ts";
+
+const ASK_MAX_TIMEOUT_MS = 600_000;
+const CHAT_MAX_TIMEOUT_MS = 2 * 60 * 60_000;
+const TITLE_MAX = 200;
+const NOTIFY_TITLE_MAX = 200;
+const NOTIFY_BODY_MAX = 4000;
+const SESSION_ID = /^[\w-]{1,128}$/;
+
+export type CtxCall = (method: string, params: unknown) => Promise<unknown>;
+
+export function ctxHost(schedule: Schedule): CtxCall {
+  return async (method, params) => {
+    const p = isPlainObject(params) ? params : {};
+    switch (method) {
+      case "save":
+        saveState(schedule.id, p.state);
+        return null;
+      case "notify":
+        await notify(schedule, p);
+        return null;
+      case "ai.ask": {
+        const prompt = text(p.prompt, "ctx.ai.ask", "prompt");
+        return scheduleAsk(schedule, prompt, askOptions(p.opts));
+      }
+      case "ai.chat": {
+        const key = text(p.key, "ctx.ai.chat", "key", TITLE_MAX);
+        const prompt = text(p.prompt, "ctx.ai.chat", "prompt");
+        return scheduleChat(schedule, key, prompt, chatOptions(p.opts));
+      }
+      case "ai.finished":
+        return collectFinishedTurns(schedule.id);
+      default:
+        throw new Error(`ctx has no ${method}`);
+    }
+  };
+}
+
+async function notify(schedule: Schedule, n: Record<string, unknown>): Promise<void> {
+  const title = text(n.title, "ctx.notify", "title", NOTIFY_TITLE_MAX);
+  if (typeof n.body !== "string") throw new Error("ctx.notify needs a body");
+  if (n.sessionId !== undefined && (typeof n.sessionId !== "string" || !SESSION_ID.test(n.sessionId))) {
+    throw new Error("ctx.notify: sessionId must be a chat's id");
+  }
+  let project = "";
+  try { project = projectService.resolve(schedule.project_path).name; } catch { /* not a registered project */ }
+  const { notificationService } = await import("../notification.service.ts");
+  // Not awaited: the dispatcher may hold it for the notification delay.
+  void notificationService.broadcast("schedule", {
+    title, body: n.body.slice(0, NOTIFY_BODY_MAX), project, sessionId: (n.sessionId as string | undefined) ?? "",
+  });
+}
+
+function askOptions(raw: unknown): AskOptions {
+  const o = options(raw, "ctx.ai.ask", ["model", "system", "effort", "jsonSchema", "timeoutMs"]);
+  if (o.model !== undefined) text(o.model, "ctx.ai.ask", "model");
+  if (o.system !== undefined && typeof o.system !== "string") throw new Error("ctx.ai.ask: system must be text");
+  if (o.effort !== undefined && !["low", "medium", "high"].includes(o.effort as string)) {
+    throw new Error('ctx.ai.ask: effort must be "low", "medium" or "high"');
+  }
+  if (o.jsonSchema !== undefined && !isPlainObject(o.jsonSchema)) throw new Error("ctx.ai.ask: jsonSchema must be an object");
+  timeout(o.timeoutMs, "ctx.ai.ask", ASK_MAX_TIMEOUT_MS);
+  return o as AskOptions;
+}
+
+function chatOptions(raw: unknown): ChatCallOptions {
+  const o = options(raw, "ctx.ai.chat", ["title", "projectPath", "sessionId", "wait", "timeoutMs"]);
+  if (o.title !== undefined) o.title = text(o.title, "ctx.ai.chat", "title", TITLE_MAX);
+  if (o.projectPath !== undefined) text(o.projectPath, "ctx.ai.chat", "projectPath");
+  if (o.sessionId !== undefined && (typeof o.sessionId !== "string" || !SESSION_ID.test(o.sessionId))) {
+    throw new Error("ctx.ai.chat: sessionId must be a chat's id");
+  }
+  if (o.wait !== undefined && typeof o.wait !== "boolean") throw new Error("ctx.ai.chat: wait must be true or false");
+  timeout(o.timeoutMs, "ctx.ai.chat", CHAT_MAX_TIMEOUT_MS);
+  return o as ChatCallOptions;
+}
+
+/** The options object, refusing a key the call does not have (a typo would otherwise be ignored). */
+function options(raw: unknown, call: string, allowed: string[]): Record<string, unknown> {
+  if (raw === undefined || raw === null) return {};
+  if (!isPlainObject(raw)) throw new Error(`${call}: options must be an object`);
+  const o = { ...raw };
+  for (const key of Object.keys(o)) {
+    if (o[key] === undefined) delete o[key];
+    else if (!allowed.includes(key)) throw new Error(`${call} has no option "${key}" (it takes ${allowed.join(", ")})`);
+  }
+  return o;
+}
+
+function text(value: unknown, call: string, name: string, max?: number): string {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${call} needs a ${name}`);
+  const trimmed = value.trim();
+  if (max !== undefined && trimmed.length > max) throw new Error(`${call}: ${name} is longer than ${max} characters`);
+  return name === "prompt" ? value : trimmed;
+}
+
+function timeout(value: unknown, call: string, max: number): void {
+  if (value === undefined) return;
+  if (!Number.isInteger(value) || (value as number) < 1000 || (value as number) > max) {
+    throw new Error(`${call}: timeoutMs must be a whole number of milliseconds from 1000 to ${max}`);
+  }
+}

package/src/services/schedule-script/ctx-state.ts

@@ -0,0 +1,37 @@
+/** `ctx.state`: one JSON value per schedule, read when its process starts and written by `save`. */
+import { utf8Length } from "../../shared/schedule-definition.ts";
+import type { Schedule } from "../../types/scheduler.ts";
+import { getDb } from "../db.service.ts";
+
+/** Ten times the largest state a bot keeps today (pr-review, ~141 KB). */
+export const STATE_MAX_BYTES = 2 * 1024 * 1024;
+
+export function loadState(schedule: Pick<Schedule, "state_json">): unknown {
+  if (!schedule.state_json) return {};
+  try {
+    return JSON.parse(schedule.state_json);
+  } catch {
+    return {};
+  }
+}
+
+/** Replaces the schedule's state with `json`, or throws and leaves the one it had. */
+export function saveState(scheduleId: number, json: unknown): void {
+  if (typeof json !== "string") throw new Error("ctx.state must be a JSON value");
+  const bytes = utf8Length(json);
+  if (bytes > STATE_MAX_BYTES) {
+    throw new Error(`ctx.state is ${(bytes / 1024 / 1024).toFixed(1)} MB; a schedule keeps at most 2 MB`);
+  }
+  try {
+    JSON.parse(json);
+  } catch {
+    throw new Error("ctx.state is not valid JSON");
+  }
+  // Not updateSchedule: a state written every tick is not an edit of the schedule (updated_at).
+  getDb().query("UPDATE schedules SET state_json = ? WHERE id = ?").run(json, scheduleId);
+}
+
+/** Forgets the state: the next process starts from `{}`. */
+export function clearState(scheduleId: number): void {
+  getDb().query("UPDATE schedules SET state_json = NULL WHERE id = ?").run(scheduleId);
+}

package/src/services/schedule-script/harness-source.ts

@@ -0,0 +1,168 @@
+/**
+ * The whole program of the child process a script schedule runs in, started as
+ * `[process.execPath, "--eval", HARNESS_SOURCE]` with `BUN_BE_BUN=1` — `bun` from source, the
+ * compiled `ppm` acting as bun in a release (the way `db-driver-install.ts` runs its bundler).
+ * It is a string because a compiled binary cannot spawn a file embedded in itself.
+ *
+ * It must leave no orphan behind, however PPM goes away (see this directory's CLAUDE.md):
+ *  - PPM holds the child's stdin open and never writes to it. The read below ends when PPM
+ *    dies, a SIGKILL included — Bun's IPC `disconnect` does not fire then.
+ *  - A script that blocks this thread's event loop never reads that EOF, so a Worker checks
+ *    every 250 ms that PPM is still the parent and SIGKILLs this process when it is not.
+ *    It reads the parent from /proc/self/stat: `process.ppid` inside a Worker kept the dead
+ *    parent's pid while the main thread was blocked. Elsewhere it asks whether that pid exists.
+ *
+ * Protocol (JSON over Bun IPC): child `ready` → PPM `init` → child `call`s answered by
+ * `result`s, `hb` every 10 s, then `done` with the final state. PPM answers `done` by closing
+ * stdin; `stop` aborts `ctx.signal`. Logging is plain stdout/stderr, which PPM reads by line.
+ * Written with String.raw and without `${`: every backslash below reaches the child as typed.
+ */
+export const HARNESS_SOURCE = String.raw`
+const PARENT = process.ppid;
+const STOP_GRACE_MS = 3000;
+const controller = new AbortController();
+const pending = new Map();
+let nextId = 1;
+let state = {};
+let finished = false;
+let exitCode = 0;
+
+function send(message) { try { process.send(message); } catch {} }
+function describe(e) { return e instanceof Error ? (e.stack || e.message) : String(e); }
+function abortError(reason) {
+  const e = new Error(reason);
+  e.name = "AbortError";
+  return e;
+}
+
+function parentGone() {
+  if (finished) process.exit(exitCode);
+  controller.abort(abortError("PPM stopped"));
+  setTimeout(() => process.exit(0), STOP_GRACE_MS);
+}
+(async () => {
+  try { for await (const _ of process.stdin) {} } catch {}
+  parentGone();
+})();
+
+function watchdogMain() {
+  const fs = require("node:fs");
+  self.onmessage = (event) => {
+    const parent = event.data;
+    const gone = () => {
+      try {
+        const stat = fs.readFileSync("/proc/self/stat", "utf8");
+        return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]) !== parent;
+      } catch {}
+      try { process.kill(parent, 0); return false; } catch (e) { return e.code === "ESRCH"; }
+    };
+    setInterval(() => { if (gone()) process.kill(process.pid, "SIGKILL"); }, 250);
+    self.postMessage("up");
+  };
+}
+async function startWatchdog() {
+  const source = "(" + watchdogMain.toString() + ")()";
+  const worker = new Worker(URL.createObjectURL(new Blob([source], { type: "application/javascript" })));
+  await new Promise((resolve) => {
+    const timer = setTimeout(resolve, 2000);
+    worker.onmessage = () => { clearTimeout(timer); resolve(); };
+    worker.onerror = (e) => { clearTimeout(timer); console.error("PPM watchdog failed to start: " + (e.message || e)); resolve(); };
+    worker.postMessage(PARENT);
+  });
+  worker.unref();
+}
+
+function call(method, params, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const id = nextId++;
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error("ctx." + method + " timed out"));
+    }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    send({ t: "call", id, method, params });
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve, reject) => {
+    const signal = controller.signal;
+    if (signal.aborted) return reject(signal.reason);
+    const onAbort = () => { clearTimeout(timer); reject(signal.reason); };
+    const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function serializeState() {
+  const json = JSON.stringify(state === undefined ? {} : state);
+  if (json === undefined) throw new Error("ctx.state must be a JSON value");
+  return json;
+}
+
+function makeCtx(init) {
+  state = init.state && typeof init.state === "object" ? init.state : {};
+  const opt = (o) => (o && typeof o === "object" ? o : {});
+  return {
+    schedule: init.schedule,
+    project: init.project,
+    inputs: Object.freeze(Object.assign({}, init.inputs)),
+    get state() { return state; },
+    set state(value) { state = value; },
+    save: async () => call("save", { state: serializeState() }, 30000),
+    log: (...args) => console.log(...args),
+    notify: (n) => call("notify", n, 30000),
+    signal: controller.signal,
+    sleep,
+    ai: {
+      ask: (prompt, o) => call("ai.ask", { prompt, opts: opt(o) }, (opt(o).timeoutMs || 120000) + 15000),
+      chat: (key, prompt, o) => call("ai.chat", { key, prompt, opts: opt(o) },
+        opt(o).wait === false ? 30000 : (opt(o).timeoutMs || 1800000) + 60000),
+      finished: () => call("ai.finished", {}, 30000),
+    },
+  };
+}
+
+function finish(error) {
+  if (finished) return;
+  finished = true;
+  let snapshot = null;
+  try { snapshot = serializeState(); } catch (e) { error = error || describe(e); }
+  exitCode = error ? 1 : 0;
+  send({ t: "done", state: snapshot, error });
+  setTimeout(() => process.exit(exitCode), 2000);
+}
+
+async function run(init) {
+  await startWatchdog();
+  setInterval(() => send({ t: "hb" }), init.heartbeatMs || 10000);
+  const ctx = makeCtx(init);
+  let error = null;
+  try {
+    const mod = await import(init.scriptPath);
+    if (typeof mod.default !== "function") {
+      throw new Error("A schedule script must export a default function: export default async function (ctx) { ... }");
+    }
+    await mod.default(ctx);
+  } catch (e) {
+    error = describe(e);
+  }
+  finish(error);
+}
+
+process.on("message", (m) => {
+  if (!m || typeof m !== "object") return;
+  if (m.t === "init") run(m).catch((e) => finish(describe(e)));
+  else if (m.t === "result") {
+    const p = pending.get(m.id);
+    if (!p) return;
+    pending.delete(m.id);
+    clearTimeout(p.timer);
+    if (m.ok) p.resolve(m.value);
+    else p.reject(new Error(m.error));
+  } else if (m.t === "stop") controller.abort(abortError(m.reason || "stopped"));
+});
+process.on("unhandledRejection", (e) => { console.error(describe(e)); finish(describe(e)); });
+process.on("uncaughtException", (e) => { console.error(describe(e)); finish(describe(e)); });
+send({ t: "ready" });
+`;

package/src/services/schedule-script/instance-guard.ts

@@ -0,0 +1,128 @@
+/**
+ * At most one child per script schedule, ever — the first rule of the bots these replace.
+ *
+ * In this process, a second start is refused while a child is alive. Across a server restart,
+ * each child is recorded with its pid and a random token it carries in its environment
+ * (`PPM_SCHEDULE_RUN`); before anything starts, `reconcileLeftovers()` looks at every recorded
+ * child still alive. Provably ours → killed, and waited for. Provably someone else's (after a
+ * reboot pids come round again) → forgotten. Unknowable and still alive after a wait → that
+ * schedule is blocked rather than started a second time: zero instances beats two.
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createLogger } from "../logger.ts";
+import { ScriptProcess, type SpawnScriptOptions } from "./script-process.ts";
+import { clearRuntimeChild, recordExit, recordSpawn, runtimeRowsWithChild } from "./script-runtime-db.ts";
+
+const log = createLogger("schedule-script");
+
+const live = new Map<number, ScriptProcess>();
+/** Schedules that must not start: the pid of a previous child that could not be stopped. */
+const blocked = new Map<number, number>();
+
+export const liveScript = (scheduleId: number): ScriptProcess | null => live.get(scheduleId) ?? null;
+export const blockedBy = (scheduleId: number): number | null => blocked.get(scheduleId) ?? null;
+export const liveScriptIds = (): number[] => [...live.keys()];
+
+/** Start the schedule's child, or return null when one is already running or the schedule is blocked. */
+export function startScript(scheduleId: number, opts: Omit<SpawnScriptOptions, "token">): ScriptProcess | null {
+  if (live.has(scheduleId) || blocked.has(scheduleId)) return null;
+  const token = randomUUID();
+  const child = new ScriptProcess({ ...opts, token });
+  live.set(scheduleId, child);
+  recordSpawn(scheduleId, child.pid, token);
+  void child.exited.then(() => {
+    if (live.get(scheduleId) === child) live.delete(scheduleId);
+    try { recordExit(scheduleId, token); } catch (e) { log.warn(`could not record the exit of schedule ${scheduleId}'s child:`, e); }
+  });
+  return child;
+}
+
+/** Abort every child's `ctx.signal`; for a shutdown, which cannot wait. Their stdin closes when PPM exits. */
+export function signalAllScripts(reason: string): void {
+  for (const child of live.values()) void child.stop(reason);
+}
+
+export type Ownership = "ours" | "not-ours" | "unknown";
+
+/** Whether the live process `pid` is a child PPM started with `token`. */
+export function ownership(pid: number, token: string): Ownership {
+  const marker = `PPM_SCHEDULE_RUN=${token}`;
+  if (process.platform === "linux") {
+    try {
+      return readFileSync(`/proc/${pid}/environ`, "utf8").split("\0").includes(marker) ? "ours" : "not-ours";
+    } catch (e) {
+      // EACCES: another user's process, which a child of ours never is. ENOENT: gone meanwhile.
+      const code = (e as NodeJS.ErrnoException).code;
+      return code === "EACCES" || code === "ENOENT" ? "not-ours" : "unknown";
+    }
+  }
+  if (process.platform === "darwin") {
+    const ps = Bun.spawnSync(["ps", "-E", "-p", String(pid), "-o", "command="]);
+    if (ps.exitCode !== 0) return "unknown";
+    return ps.stdout.toString().includes(marker) ? "ours" : "not-ours";
+  }
+  return "unknown";
+}
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+async function waitGone(pid: number, ms: number): Promise<boolean> {
+  const until = Date.now() + ms;
+  while (isAlive(pid)) {
+    if (Date.now() >= until) return false;
+    await Bun.sleep(50);
+  }
+  return true;
+}
+
+/** Decide about one recorded child; true when the schedule is free to start. */
+async function settleLeftover(
+  scheduleId: number, pid: number, token: string | null, waits: LeftoverWaits, owner: typeof ownership,
+): Promise<boolean> {
+  if (!isAlive(pid)) return true;
+  const verdict = token ? owner(pid, token) : "unknown";
+  if (verdict === "not-ours") return true;
+  if (verdict === "ours") {
+    log.warn(`Schedule ${scheduleId}: killing child ${pid}, left running by the previous server`);
+    try { process.kill(pid, "SIGKILL"); } catch { /* gone meanwhile */ }
+    return waitGone(pid, waits.killMs);
+  }
+  return waitGone(pid, waits.unknownMs);
+}
+
+export interface LeftoverWaits { killMs: number; unknownMs: number }
+
+/** Run before any schedule starts. Children of a previous server are stopped or block their schedule. */
+export async function reconcileLeftovers(
+  waits: LeftoverWaits = { killMs: 5_000, unknownMs: 10_000 },
+  owner: typeof ownership = ownership,
+): Promise<void> {
+  await Promise.all(runtimeRowsWithChild().map(async (row) => {
+    const pid = row.pid!;
+    if (await settleLeftover(row.schedule_id, pid, row.token, waits, owner)) {
+      clearRuntimeChild(row.schedule_id);
+      blocked.delete(row.schedule_id);
+    } else {
+      blocked.set(row.schedule_id, pid);
+      log.error(`Schedule ${row.schedule_id} will not start: its previous child ${pid} is still running and could not be stopped`);
+    }
+  }));
+}
+
+/** Look again at a blocked schedule (on an explicit start); true when it may start now. */
+export async function retryBlocked(scheduleId: number): Promise<boolean> {
+  const pid = blocked.get(scheduleId);
+  if (pid === undefined) return true;
+  if (isAlive(pid)) return false;
+  blocked.delete(scheduleId);
+  clearRuntimeChild(scheduleId);
+  return true;
+}

package/src/services/schedule-script/schedule-chat-db.ts

@@ -0,0 +1,99 @@
+/**
+ * The rows behind `ctx.ai.chat`: which chat each key of a schedule talks to (`schedule_chats`),
+ * and the turns a script started without waiting (`schedule_ai_turns`), which `ctx.ai.finished()`
+ * hands out once each. Both go with their schedule (ON DELETE CASCADE); the chats themselves stay.
+ */
+import { getDb } from "../db.service.ts";
+
+export interface ScheduleChat {
+  session_id: string;
+  /** The title the script last gave the chat, so a title the user set since is left alone. */
+  title: string | null;
+}
+
+export function getScheduleChat(scheduleId: number, key: string): ScheduleChat | null {
+  return getDb().query("SELECT session_id, title FROM schedule_chats WHERE schedule_id = ? AND key = ?")
+    .get(scheduleId, key) as ScheduleChat | null;
+}
+
+export function bindScheduleChat(scheduleId: number, key: string, sessionId: string, title: string | null): void {
+  getDb().query(
+    `INSERT INTO schedule_chats (schedule_id, key, session_id, title, last_used_at) VALUES (?, ?, ?, ?, datetime('now'))
+     ON CONFLICT(schedule_id, key) DO UPDATE SET session_id = excluded.session_id, title = excluded.title, last_used_at = excluded.last_used_at`,
+  ).run(scheduleId, key, sessionId, title);
+}
+
+export function unbindScheduleChat(scheduleId: number, key: string): void {
+  getDb().query("DELETE FROM schedule_chats WHERE schedule_id = ? AND key = ?").run(scheduleId, key);
+}
+
+export interface FinishedTurn {
+  key: string;
+  sessionId: string;
+  ok: boolean;
+  text: string;
+  costUsd?: number;
+  timedOut?: boolean;
+  error?: string;
+  startedAt: string;
+  finishedAt: string;
+}
+
+export function startAiTurn(scheduleId: number, key: string, sessionId: string): number {
+  const res = getDb().query("INSERT INTO schedule_ai_turns (schedule_id, key, session_id, status) VALUES (?, ?, ?, 'running')")
+    .run(scheduleId, key, sessionId);
+  return Number(res.lastInsertRowid);
+}
+
+export function finishAiTurn(id: number, out: { ok: boolean; text: string; sessionId: string; costUsd?: number; timedOut?: boolean; error?: string }): void {
+  getDb().query(
+    `UPDATE schedule_ai_turns SET status = ?, session_id = ?, text = ?, cost_usd = ?, error = ?, timed_out = ?, finished_at = datetime('now')
+     WHERE id = ? AND status = 'running'`,
+  ).run(out.ok ? "done" : "error", out.sessionId, out.text, out.costUsd ?? null, out.error ?? null, out.timedOut ? 1 : 0, id);
+}
+
+interface TurnRow {
+  id: number; key: string; session_id: string; status: string; text: string | null; cost_usd: number | null;
+  error: string | null; timed_out: number; started_at: string; finished_at: string | null;
+}
+
+/** The turns of `scheduleId` that ended since the last call, oldest first; each is returned once. */
+export function collectFinishedTurns(scheduleId: number): FinishedTurn[] {
+  const db = getDb();
+  return db.transaction(() => {
+    const rows = db.query(
+      "SELECT * FROM schedule_ai_turns WHERE schedule_id = ? AND collected = 0 AND status != 'running' ORDER BY id",
+    ).all(scheduleId) as TurnRow[];
+    if (rows.length) {
+      db.query(`UPDATE schedule_ai_turns SET collected = 1 WHERE id IN (${rows.map(() => "?").join(",")})`).run(...rows.map((r) => r.id));
+    }
+    return rows.map((r) => ({
+      key: r.key,
+      sessionId: r.session_id,
+      ok: r.status === "done",
+      text: r.text ?? "",
+      ...(r.cost_usd != null && { costUsd: r.cost_usd }),
+      ...(r.timed_out ? { timedOut: true } : {}),
+      ...(r.error != null && { error: r.error }),
+      startedAt: sqlTimeToIso(r.started_at),
+      finishedAt: sqlTimeToIso(r.finished_at ?? r.started_at),
+    }));
+  })();
+}
+
+/**
+ * Boot hygiene: a turn still `running` belonged to the server that just went away, so it ends
+ * as interrupted (the script hears of it through `finished()`); turns over 30 days old go.
+ */
+export function cleanupAiTurns(): void {
+  getDb().exec(`
+    UPDATE schedule_ai_turns SET status = 'error', error = 'interrupted: PPM restarted', finished_at = datetime('now')
+      WHERE status = 'running';
+    DELETE FROM schedule_ai_turns WHERE started_at < datetime('now', '-30 days');
+  `);
+}
+
+/** SQLite's `datetime('now')` is UTC without a zone: "2026-10-12 09:30:00". */
+function sqlTimeToIso(value: string): string {
+  return /^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d$/.test(value) ? `${value.replace(" ", "T")}.000Z` : value;
+}

package/src/services/schedule-script/schedule-secrets.ts

@@ -0,0 +1,23 @@
+/**
+ * A script schedule's secret input values: one JSON object, encrypted with PPM's account key
+ * (`secrets_enc`). Only the process that runs the script ever sees them in the clear.
+ */
+import { decrypt, encrypt } from "../../lib/account-crypto.ts";
+import { isPlainObject } from "../../shared/schedule-definition.ts";
+import type { Schedule } from "../../types/scheduler.ts";
+
+export function readSecrets(schedule: Pick<Schedule, "secrets_enc">): Record<string, string> {
+  if (!schedule.secrets_enc) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decrypt(schedule.secrets_enc));
+  } catch {
+    throw new Error("This schedule's secrets cannot be read with this PPM's key; enter them again");
+  }
+  if (!isPlainObject(parsed)) return {};
+  return Object.fromEntries(Object.entries(parsed).filter((e): e is [string, string] => typeof e[1] === "string"));
+}
+
+export function encryptSecrets(secrets: Record<string, string>): string | null {
+  return Object.keys(secrets).length ? encrypt(JSON.stringify(secrets)) : null;
+}

package/src/services/schedule-script/script-files.ts

@@ -0,0 +1,37 @@
+/**
+ * Where a script schedule's files live: `<ppm dir>/schedule-runs/<db name>/<schedule id>/`.
+ * The database name is in the path because the dev server (`ppm.dev.db`) shares the PPM
+ * directory with production, and schedule ids of the two databases collide.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { getDbPath } from "../db.service.ts";
+import { getPpmDir } from "../ppm-dir.ts";
+
+const SCRIPT_FILE = /^script-[0-9a-f]{12}\.mjs$/;
+
+export function scheduleRunDir(scheduleId: number): string {
+  return join(getPpmDir(), "schedule-runs", basename(getDbPath()).replace(/\.db$/, ""), String(scheduleId));
+}
+
+/**
+ * The script as a module file the child imports, named by its content so a run never picks up
+ * an edit made while it starts. Older versions are removed; only one child runs per schedule,
+ * and it has imported its file before an edit can restart it.
+ */
+export function writeScriptFile(scheduleId: number, source: string): string {
+  const dir = scheduleRunDir(scheduleId);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const name = `script-${createHash("sha256").update(source).digest("hex").slice(0, 12)}.mjs`;
+  const file = join(dir, name);
+  if (!existsSync(file)) writeFileSync(file, source, { mode: 0o600 });
+  for (const old of readdirSync(dir)) {
+    if (old !== name && SCRIPT_FILE.test(old)) rmSync(join(dir, old), { force: true });
+  }
+  return file;
+}
+
+export function removeRunDir(scheduleId: number): void {
+  rmSync(scheduleRunDir(scheduleId), { recursive: true, force: true });
+}