@carbon-ni/pi-schedule 0.0.0-stage → 0.1.0

package/src/application/runtime.ts

@@ -0,0 +1,269 @@
+import {
+  emptyState,
+  createTask,
+  cancelTask,
+  dueTasks,
+  beginDispatch,
+  confirmDispatch,
+  type State,
+  type Task,
+  type Creator,
+  type CreateRequest,
+} from "../domain/scheduler.ts";
+
+export interface Store {
+  load(): State;
+  save(state: State): void;
+  close(): void;
+}
+
+interface Dependencies {
+  now(): number;
+  id(): string;
+  available(): boolean;
+  deliver(task: Task): void;
+  notify(message: string): void;
+}
+
+const GRACE_MS = 120_000;
+
+export class Runtime {
+  private state = emptyState();
+  private closed = false;
+  private lastTick: number;
+  private waiting = new Set<string>();
+  private parentId?: string;
+
+  private readonly store: Store;
+  readonly sessionId: string;
+  private readonly projectPath: string;
+  private readonly deps: Dependencies;
+
+  constructor(store: Store, sessionId: string, projectPath: string, deps: Dependencies) {
+    this.store = store;
+    this.sessionId = sessionId;
+    this.projectPath = projectPath;
+    this.deps = deps;
+    this.lastTick = deps.now();
+  }
+
+  start(): void {
+    this.state = this.store.load();
+    const now = this.deps.now();
+    const tasks = { ...this.state.tasks };
+    for (const task of Object.values(tasks)) {
+      if (task.status === "pending" && task.dueAt <= now) {
+        tasks[task.id] = { ...task, status: "overdue" };
+      }
+    }
+    this.commit({ ...this.state, tasks });
+    for (const task of this.list().filter((t) => ["overdue", "uncertain"].includes(t.status))) {
+      this.deps.notify(`${task.id} is ${task.status}. Inspect /schedule list before recovery.`);
+    }
+  }
+
+  get stopped(): boolean {
+    return this.closed;
+  }
+
+  private assertOpen(): void {
+    if (this.closed) throw new Error("Scheduler is closed. Reload Pi before scheduling.");
+  }
+
+  private commit(next: State): void {
+    this.assertOpen();
+    try {
+      this.store.save(next);
+    } catch (error) {
+      this.closed = true;
+      try {
+        this.store.close();
+      } catch {
+        /* Preserve the persistence failure; stale ownership fails closed. */
+      }
+      throw new Error(
+        `Scheduler stopped after persistence failure: ${String(error)}. Use /reload before retrying.`,
+        { cause: error },
+      );
+    }
+    this.state = next;
+  }
+
+  private task(id: string): Task {
+    const task = Object.hasOwn(this.state.tasks, id) ? this.state.tasks[id] : undefined;
+    if (!task || task.sessionId !== this.sessionId)
+      throw new Error("Unknown task. Use /schedule list.");
+    return task;
+  }
+
+  list(): Task[] {
+    return Object.values(this.state.tasks).map((t) => ({ ...t }));
+  }
+
+  inspect(id: string): { task: Task; chain: State["chains"][string] } {
+    const task = this.task(id);
+    return { task: { ...task }, chain: { ...this.state.chains[task.rootId] } };
+  }
+
+  newUserRequest(): void {
+    this.parentId = undefined;
+    this.commit({ ...this.state, activeRootId: undefined });
+  }
+
+  scheduledTurn(id: string): void {
+    const task = this.task(id);
+    if (task.status === "uncertain") this.commit(confirmDispatch(this.state, id, this.sessionId));
+    else if (task.status !== "dispatched")
+      throw new Error("No dispatch intent for this scheduled turn.");
+    this.parentId = id;
+    this.commit({ ...this.state, activeRootId: task.rootId });
+  }
+
+  create(request: Omit<CreateRequest, "projectPath" | "parentId">, creator: Creator): Task {
+    this.assertOpen();
+    if (Object.keys(this.state.tasks).length >= 1000) {
+      throw new Error("Session task history limit reached (1000). Start a new Pi session.");
+    }
+    let parentId: string | undefined;
+    if (creator === "agent" && this.state.activeRootId) {
+      const chain = this.state.chains[this.state.activeRootId];
+      if (chain.cancelled)
+        throw new Error("Follow-up chain is cancelled. Wait for a new user request.");
+      if (
+        this.list().some(
+          (t) =>
+            t.rootId === this.state.activeRootId &&
+            ["pending", "overdue", "uncertain"].includes(t.status),
+        )
+      ) {
+        throw new Error("Chain already has pending or uncertain work. Use /schedule list.");
+      }
+      parentId =
+        this.parentId ??
+        this.list()
+          .filter((t) => t.rootId === this.state.activeRootId && t.status === "dispatched")
+          .at(-1)?.id;
+      if (!parentId) throw new Error("No dispatched parent. Wait for the scheduled check.");
+    }
+    const id = this.deps.id();
+    const next = createTask(
+      this.state,
+      { ...request, projectPath: this.projectPath, parentId },
+      {
+        id,
+        sessionId: this.sessionId,
+        creator,
+        now: this.deps.now(),
+      },
+    );
+    if (creator === "agent") next.activeRootId = next.tasks[id].rootId;
+    this.commit(next);
+    return { ...this.state.tasks[id] };
+  }
+
+  cancel(id: string): void {
+    this.commit(cancelTask(this.state, id, this.sessionId));
+    this.waiting.delete(id);
+  }
+
+  dismiss(id: string): void {
+    const task = this.task(id);
+    if (task.status !== "uncertain")
+      throw new Error("Only uncertain dispatches need /schedule dismiss <id>.");
+    this.commit(
+      cancelTask(
+        { ...this.state, tasks: { ...this.state.tasks, [id]: { ...task, status: "pending" } } },
+        id,
+        this.sessionId,
+      ),
+    );
+  }
+
+  budget(id: string, runs: number, seconds: number): void {
+    const task = this.task(id);
+    if (
+      !Number.isSafeInteger(runs) ||
+      runs < 1 ||
+      runs > 20 ||
+      !Number.isSafeInteger(seconds) ||
+      seconds < 1 ||
+      seconds > 86400
+    ) {
+      throw new Error("Usage: /schedule budget <id> <1..20 runs> <duration up to 24h>.");
+    }
+    const chain = this.state.chains[task.rootId];
+    if (runs < chain.usedRuns) throw new Error("Budget cannot be lower than already used runs.");
+    this.commit({
+      ...this.state,
+      chains: {
+        ...this.state.chains,
+        [task.rootId]: { ...chain, maxRuns: runs, expiresAt: this.deps.now() + seconds * 1000 },
+      },
+    });
+  }
+
+  run(id: string): void {
+    const task = this.task(id);
+    if (task.status !== "overdue")
+      throw new Error(`Task is ${task.status}; only overdue work can be explicitly run.`);
+    if (!this.deps.available() || this.list().some((t) => t.status === "uncertain")) {
+      throw new Error("Wait until Pi is idle and resolve uncertain dispatches first.");
+    }
+    this.dispatch(task);
+  }
+
+  private dispatch(task: Task): void {
+    const pending = {
+      ...this.state,
+      tasks: { ...this.state.tasks, [task.id]: { ...task, status: "pending" as const } },
+    };
+    this.commit(beginDispatch(pending, task.id, this.sessionId, this.deps.now()));
+    // Only the actual Pi run-start event acknowledges delivery. A void API call cannot.
+    try {
+      this.deps.deliver(task);
+    } catch (error) {
+      this.deps.notify(
+        `${task.id} dispatch uncertain: ${String(error)}. Inspect before /schedule dismiss ${task.id}.`,
+      );
+    }
+  }
+
+  tick(): void {
+    if (this.closed) return;
+    const now = this.deps.now();
+    const gap = now - this.lastTick > GRACE_MS;
+    this.lastTick = now;
+    const available = this.deps.available();
+    const due = dueTasks(this.state, now, this.sessionId);
+    for (const task of due) {
+      const chain = this.state.chains[task.rootId];
+      const expired =
+        (task.creator === "agent" || task.parentId !== undefined) && now >= chain.expiresAt;
+      if (expired || gap || (now - task.dueAt > GRACE_MS && !this.waiting.has(task.id))) {
+        this.commit({
+          ...this.state,
+          tasks: { ...this.state.tasks, [task.id]: { ...task, status: "overdue" } },
+        });
+        this.waiting.delete(task.id);
+        this.deps.notify(
+          `${task.id} overdue${expired ? " (chain expired)" : ""}. Inspect /schedule list; use /schedule run ${task.id} when ready.`,
+        );
+        continue;
+      }
+      if (!available) {
+        this.waiting.add(task.id);
+        continue;
+      }
+      if (this.list().some((t) => t.status === "uncertain")) return;
+      this.dispatch(task);
+      this.waiting.delete(task.id);
+      return;
+    }
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.store.close();
+  }
+}

package/src/cli/commands.ts

@@ -0,0 +1,58 @@
+export const help = `Schedule one-off work in this open Pi session.
+Requires a writable private store and an awake computer. No background service.
+
+/schedule in 30m Check CI for owner/repo#123 and report failures
+/schedule at 2026-11-09T14:30:00+01:00 Check deployment status
+/schedule list
+/schedule show S-123                Inspect saved request and chain budget
+/schedule cancel S-123
+/schedule run S-123                 Explicitly run overdue work when idle
+/schedule dismiss S-123             Dismiss an uncertain dispatch after inspection
+/schedule budget S-123 5 3h         User-only: total chain runs and expiry from now
+
+Use a complete instruction with the exact PR/project. Natural language uses
+schedule_task; agent-created checks explain why and default to 3 runs / 2 hours.
+Current permissions still apply. Closing Pi stops execution. Reload/resume of
+missed work or a sleep/clock gap over 2 minutes marks it overdue; no auto catch-up.
+Dispatched means Pi started the turn, not that the requested check succeeded.
+Inspect uncertain work before dismissing; it is never automatically replayed.`;
+
+export type Command =
+  | { action: "help" | "list" }
+  | { action: "cancel" | "run" | "dismiss" | "show"; id: string }
+  | { action: "budget"; id: string; runs: number; seconds: number }
+  | { action: "create"; instruction: string; delaySeconds?: number; runAt?: string };
+
+function invalid(): never {
+  throw new Error("Invalid schedule command. Use /schedule help for examples.");
+}
+
+export function duration(text: string): number {
+  const match = /^(\d+)(s|m|h|d)$/.exec(text);
+  if (!match) return invalid();
+  const units: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+  const seconds = Number(match[1]) * units[match[2]];
+  if (!Number.isSafeInteger(seconds) || seconds < 1) return invalid();
+  return seconds;
+}
+
+export function parseCommand(text: string): Command {
+  const parts = text.trim().split(/\s+/);
+  const [action, arg, ...rest] = parts;
+  if ((!action || action === "help" || action === "list") && !arg)
+    return { action: action === "list" ? "list" : "help" };
+  if (["cancel", "run", "dismiss", "show"].includes(action) && arg && rest.length === 0) {
+    return { action: action as "cancel" | "run" | "dismiss" | "show", id: arg };
+  }
+  if (action === "budget" && arg && rest.length === 2 && /^\d+$/.test(rest[0])) {
+    return { action: "budget", id: arg, runs: Number(rest[0]), seconds: duration(rest[1]) };
+  }
+  if ((action === "in" || action === "at") && arg && rest.length > 0) {
+    return {
+      action: "create",
+      instruction: rest.join(" "),
+      ...(action === "in" ? { delaySeconds: duration(arg) } : { runAt: arg }),
+    };
+  }
+  return invalid();
+}

package/src/domain/scheduler.ts

@@ -0,0 +1,242 @@
+export type Creator = "user" | "agent";
+export type Status = "pending" | "uncertain" | "dispatched" | "cancelled" | "overdue";
+
+export interface Task {
+  id: string;
+  sessionId: string;
+  creator: Creator;
+  instruction: string;
+  projectPath: string;
+  target: string;
+  reason?: string;
+  parentId?: string;
+  rootId: string;
+  createdAt: number;
+  dueAt: number;
+  status: Status;
+}
+
+export interface Chain {
+  usedRuns: number;
+  maxRuns: number;
+  expiresAt: number;
+  cancelled: boolean;
+}
+
+export interface State {
+  version: 1;
+  tasks: Record<string, Task>;
+  chains: Record<string, Chain>;
+  activeRootId?: string;
+}
+
+export interface CreateRequest {
+  instruction: string;
+  projectPath: string;
+  target: string;
+  delaySeconds?: number;
+  runAt?: string;
+  reason?: string;
+  parentId?: string;
+}
+
+/** Attribution must be supplied by a trusted adapter, never by model arguments. */
+export interface CreateContext {
+  now: number;
+  id: string;
+  sessionId: string;
+  creator: Creator;
+}
+
+const MAX_PENDING = 20;
+const MAX_INSTRUCTION_BYTES = 8192;
+const MAX_AGENT_RUNS = 3;
+const CHAIN_LIFETIME_MS = 2 * 60 * 60 * 1000;
+
+export function emptyState(): State {
+  return { version: 1, tasks: {}, chains: {} };
+}
+
+function requireText(value: string, label: string): void {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${label} must not be blank.`);
+  }
+}
+
+function requireTime(value: number): void {
+  if (!Number.isSafeInteger(value) || Math.abs(value) > 8.64e15) {
+    throw new Error("Time must be a valid integer timestamp in milliseconds.");
+  }
+}
+
+function getOwn<T>(records: Record<string, T>, key: string): T | undefined {
+  return Object.hasOwn(records, key) ? records[key] : undefined;
+}
+
+function ownedTask(state: State, id: string, sessionId: string): Task {
+  const task = getOwn(state.tasks, id);
+  if (!task || task.sessionId !== sessionId) {
+    throw new Error("Task not found in this session. Use /schedule list.");
+  }
+  return task;
+}
+
+function deadline(request: CreateRequest, now: number): number {
+  if ((request.delaySeconds !== undefined) === (request.runAt !== undefined)) {
+    throw new Error("Choose exactly one of delaySeconds or runAt.");
+  }
+
+  let dueAt: number;
+  if (request.delaySeconds !== undefined) {
+    if (!Number.isSafeInteger(request.delaySeconds) || request.delaySeconds <= 0) {
+      throw new Error("delaySeconds must be a positive integer.");
+    }
+    dueAt = now + request.delaySeconds * 1000;
+  } else {
+    const match =
+      /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.exec(
+        request.runAt!,
+      );
+    if (!match) {
+      throw new Error("runAt needs an ISO-8601 timestamp with seconds and timezone offset.");
+    }
+    // Date.parse normalizes impossible dates such as February 30; reject them.
+    const calendar = new Date(`${match[1]}-${match[2]}-${match[3]}T00:00:00Z`);
+    if (!Number.isFinite(calendar.getTime()) || calendar.getUTCDate() !== Number(match[3])) {
+      throw new Error("runAt must contain a real calendar date.");
+    }
+    dueAt = Date.parse(request.runAt!);
+  }
+
+  requireTime(dueAt);
+  if (dueAt <= now) throw new Error("Due time must be in the future.");
+  return dueAt;
+}
+
+export function createTask(state: State, request: CreateRequest, ctx: CreateContext): State {
+  requireTime(ctx.now);
+  requireText(ctx.id, "Task ID");
+  requireText(ctx.sessionId, "Session ID");
+  requireText(request.instruction, "Instruction");
+  requireText(request.projectPath, "Project path");
+  requireText(request.target, "Target");
+  if (new TextEncoder().encode(request.instruction).length > MAX_INSTRUCTION_BYTES) {
+    throw new Error("Instruction must not exceed 8192 UTF-8 bytes.");
+  }
+  if (getOwn(state.tasks, ctx.id)) throw new Error("Task ID already exists.");
+  const pending = Object.values(state.tasks).filter(
+    (t) => t.sessionId === ctx.sessionId && (t.status === "pending" || t.status === "overdue"),
+  );
+  if (pending.length >= MAX_PENDING)
+    throw new Error("Limit of 20 pending tasks reached. Use /schedule list.");
+
+  const dueAt = deadline(request, ctx.now);
+  if (ctx.creator === "agent") requireText(request.reason!, "Agent scheduling reason");
+
+  const parent =
+    request.parentId === undefined ? undefined : ownedTask(state, request.parentId, ctx.sessionId);
+  if (parent && parent.status !== "dispatched") {
+    throw new Error("Follow-up parent must have been dispatched.");
+  }
+  if (parent && (parent.target !== request.target || parent.projectPath !== request.projectPath)) {
+    throw new Error("Follow-up scope must match the original project and target.");
+  }
+  const rootId = parent?.rootId ?? ctx.id;
+  const chain = parent
+    ? state.chains[rootId]
+    : {
+        usedRuns: 0,
+        maxRuns: MAX_AGENT_RUNS,
+        expiresAt: ctx.now + CHAIN_LIFETIME_MS,
+        cancelled: false,
+      };
+  if (chain.cancelled) throw new Error("Follow-up chain is cancelled.");
+  if (parent && pending.some((t) => t.rootId === rootId)) {
+    throw new Error("This chain already has a pending follow-up. Use /schedule list.");
+  }
+  const consumesBudget = ctx.creator === "agent" || parent !== undefined;
+  if (consumesBudget && chain.usedRuns >= chain.maxRuns) {
+    throw new Error("Follow-up run budget exhausted. Ask the user before scheduling more work.");
+  }
+  if (consumesBudget && dueAt >= chain.expiresAt) {
+    throw new Error("Follow-up deadline exceeds chain expiry. Report unresolved work to the user.");
+  }
+
+  const task: Task = {
+    id: ctx.id,
+    sessionId: ctx.sessionId,
+    creator: ctx.creator,
+    instruction: request.instruction,
+    projectPath: request.projectPath,
+    target: request.target,
+    reason: request.reason,
+    parentId: request.parentId,
+    rootId,
+    createdAt: ctx.now,
+    dueAt,
+    status: "pending",
+  };
+  return {
+    ...state,
+    tasks: { ...state.tasks, [task.id]: task },
+    chains: {
+      ...state.chains,
+      [rootId]: {
+        ...chain,
+        usedRuns: chain.usedRuns + Number(consumesBudget),
+      },
+    },
+  };
+}
+
+export function dueTasks(state: State, now: number, sessionId: string): Task[] {
+  requireTime(now);
+  return Object.values(state.tasks)
+    .filter((t) => t.sessionId === sessionId && t.status === "pending" && t.dueAt <= now)
+    .sort((a, b) => a.dueAt - b.dueAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((t) => ({ ...t }));
+}
+
+export function cancelTask(state: State, id: string, sessionId: string): State {
+  const task = ownedTask(state, id, sessionId);
+  if (task.status === "uncertain") {
+    throw new Error("Dispatch may already have started; inspect the conversation before recovery.");
+  }
+  const tasks = { ...state.tasks };
+  for (const candidate of Object.values(tasks)) {
+    if (
+      candidate.rootId === task.rootId &&
+      (candidate.status === "pending" || candidate.status === "overdue")
+    ) {
+      tasks[candidate.id] = { ...candidate, status: "cancelled" };
+    }
+  }
+  return {
+    ...state,
+    tasks,
+    chains: { ...state.chains, [task.rootId]: { ...state.chains[task.rootId], cancelled: true } },
+  };
+}
+
+/** Persist this returned intent before delivery; never automatically replay it. */
+export function beginDispatch(state: State, id: string, sessionId: string, now: number): State {
+  requireTime(now);
+  const task = ownedTask(state, id, sessionId);
+  if (task.status !== "pending" || task.dueAt > now) {
+    throw new Error("Task must be pending and due before dispatch.");
+  }
+  const chain = state.chains[task.rootId];
+  if (
+    chain.cancelled ||
+    ((task.creator === "agent" || task.parentId !== undefined) && now >= chain.expiresAt)
+  ) {
+    throw new Error("Follow-up chain is cancelled or expired. Report unresolved work to the user.");
+  }
+  return { ...state, tasks: { ...state.tasks, [id]: { ...task, status: "uncertain" } } };
+}
+
+export function confirmDispatch(state: State, id: string, sessionId: string): State {
+  const task = ownedTask(state, id, sessionId);
+  if (task.status !== "uncertain") throw new Error("No dispatch intent to acknowledge.");
+  return { ...state, tasks: { ...state.tasks, [id]: { ...task, status: "dispatched" } } };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { register } from "./infra/extension.ts";
+
+export default function schedule(pi: ExtensionAPI): void {
+  register(pi);
+}