SKILL.md- the skill, written out in plain English

   curl -XPOST 127.0.0.1:3147/chat-schedule \
     -H "Content-Type: application/json" \
     -d '{"intent":"morning brief","fireAt":"2026-05-01T08:00:00Z"}'

AGENTS.md- what the AI loads when this skill comes up

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/chat-schedule.ts — create scheduled agents from the chat surface.
 *
 * Creates a new state/agents/<id>.json with separate display metadata
 * ({name, description}) and executable scheduling instructions ({intent, cron}).
 * Minted via snappy-chat POST /agent/create-scheduled.
 *
 * Schema: Agent from state/lib/agents.ts with optional schedule_cron.
 */

import { writeAgent, normalizeId, agentPath } from "./agents.ts";
import type { Agent } from "./agents.ts";
import { parseCron } from "./cron-match.ts";
import { randomBytes } from "crypto";
import { existsSync } from "fs";
import { join } from "path";

// A28: a scheduled agent backed by a deterministic sidecar must run that
// sidecar, not an LLM tick of its prompt - else it is born a zombie (ticks
// "ok", delivers nothing). When the loader_slug has a state/bin/<slug>/run.ts,
// bind tick_command at creation so the cron + manual-fire paths run real code.
function sidecarTickCommand(loaderSlug: string): string | undefined {
  if (!loaderSlug) return undefined;
  const root = process.env.SNAPPY_OS_ROOT ?? join(process.env.HOME ?? "/", "projects", "snappy-os");
  return existsSync(join(root, "state", "bin", loaderSlug, "run.ts"))
    ? `npx tsx state/bin/${loaderSlug}/run.ts`
    : undefined;
}

export interface ScheduleInput {
  name: string;           // display name, kebab-case normalized
  description?: string;   // short user-facing Scheduled card summary
  intent: string;         // the prompt/directive the scheduler will run
  cron: string;           // 5-field cron expression (e.g. "0 9 * * 1")
  loader_slug?: string;   // optional explicit loader; defaults to inferred
  // Typed contract fields (F399). script-builder sends these discrete
  // decomposition fields alongside the composed intent; persisted as the
  // agent's *_text fields so consumers need not re-parse the intent string.
  outcome?: string;                     // what a successful run produces
  inputs?: string;                      // what the run needs to start
  output_ownership?: string;            // who owns/receives the output
  // Script-builder fields (V2-R008). A script is reusable run logic, so it
  // carries its own model pin, retry policy, output check, project binding,
  // and a permissions note. All optional; the scheduled-task form omits them.
  model?: string;                       // pinned model for this script's runs
  project_id?: string;                  // workspace this script belongs to
  retry_max?: number;                   // max retries on transient failure
  retry_backoff?: "exp" | "fixed" | "none";
  expects_artifact?: string;            // deterministic output check (path)
  permissions_note?: string;            // what external effects this may cause
}

export interface ScheduleOutput {
  ok: boolean;
  id?: string;
  name?: string;
  description?: string;
  intent?: string;
  cron?: string;
  loader_slug?: string;
  error?: string;
}

/**
 * Validate a schedule value with the SAME parser the scheduler (cron-match.ts)
 * and the edit route (PUT /agent/:id) use. "manual" is the run-on-demand
 * sentinel. Returns null when valid, else a human-readable reason.
 *
 * Previously this only checked "5 space-separated fields", so a value like
 * "99 99 99 99 99" was created successfully but threw `out-of-range` on every
 * scheduler tick (cronMatch -> parseCron) and rendered "Manual only" on the
 * card (computeNextRun swallowed the throw -> next_run_ts: null). A task the
 * user explicitly scheduled silently never fired. Validation must agree with
 * the scheduler, not defer to it - the gate is the create boundary.
 */
function cronError(cron: string): string | null {
  if (cron.trim().toLowerCase() === "manual") return null;
  try {
    parseCron(cron.trim());
    return null;
  } catch (e: unknown) {
    return (e instanceof Error ? e.message : "") || "invalid cron";
  }
}

/**
 * Create a scheduled agent from {name, description, intent, cron}.
 *
 * Returns {ok: true, id, name, description, intent, cron, loader_slug} on success.
 * Returns {ok: false, error: "..."} on failure.
 *
 * Idempotent: safe to call multiple times with same inputs (will re-write
 * the agent file but result is deterministic).
 */
export function createScheduledAgent(input: ScheduleInput): ScheduleOutput {
  // Validate inputs
  const name = (input.name || "").trim();
  if (!name || name.length === 0) {
    return { ok: false, error: "name required" };
  }
  if (name.length > 100) {
    return { ok: false, error: "name >100 chars" };
  }

  const intent = (input.intent || "").trim();
  if (!intent || intent.length === 0) {
    return { ok: false, error: "intent required" };
  }
  if (intent.length > 2000) {
    return { ok: false, error: "intent >2000 chars" };
  }

  const cron = (input.cron || "").trim();
  if (!cron || cron.length === 0) {
    return { ok: false, error: "cron required" };
  }
  const cronReason = cronError(cron);
  if (cronReason) {
    return { ok: false, error: `invalid cron: ${cronReason}` };
  }

  const loader_slug = (input.loader_slug || "").trim();
  const description = (input.description || "").trim();

  // Mint a collision-safe id: normalized name + short timestamp suffix.
  // The timestamp alone is NOT collision-safe: two creates in the same
  // millisecond (a double-clicked Save, or a scripted batch) produced an
  // identical id and writeAgent silently overwrote the first record (data
  // loss). Guard with a real existsSync check and append entropy on collision.
  const idBase = normalizeId(name).slice(0, 24) || "scheduled";
  const mintId = (suffix: string) => `${idBase}-${suffix}`.slice(0, 40);
  let id = mintId(Date.now().toString(36).slice(-6));
  for (let attempt = 0; existsSync(agentPath(id)) && attempt < 5; attempt++) {
    id = mintId(`${Date.now().toString(36).slice(-6)}${randomBytes(2).toString("hex")}`);
  }

  // Build the agent record. Lifecycle honesty (Robert CU audit): "running"
  // means the scheduler may tick this record (tick.sh gates on it). A manual
  // never-fired script is an idle definition, not a running process - only
  // cron-bound tasks are born schedule-enabled.
  // Script-builder fields (V2-R008). retry policy goes into pid_config; an
  // explicit output check, model pin, project binding, and permissions note
  // ride their typed fields. All omitted by the plain scheduled-task form.
  const model = (input.model || "").trim();
  const projectId = (input.project_id || "").trim();
  const expectsArtifact = (input.expects_artifact || "").trim();
  const permissionsNote = (input.permissions_note || "").trim();
  const pidConfig = (input.retry_max !== undefined || input.retry_backoff !== undefined)
    ? {
        ...(typeof input.retry_max === "number" && Number.isFinite(input.retry_max)
          ? { retry_max: Math.max(0, Math.floor(input.retry_max)) }
          : {}),
        ...(input.retry_backoff ? { retry_backoff: input.retry_backoff } : {}),
      }
    : undefined;

  const agent: Agent = {
    id,
    display_name: name,
    description: description || undefined,
    status: cron.toLowerCase() === "manual" ? "idle" : "running",
    prompt: intent,
    ticks: 0,
    max_ticks: 1000,
    started_at: new Date().toISOString(),
    last_tick_at: null,
    last_tick_status: null,
    last_tick_dur_secs: null,
    loader_slug: loader_slug || undefined,
    schedule_cron: cron,
    // A28: bind the deterministic sidecar at birth when one exists for this
    // loader, so the agent runs real code instead of an LLM-hope tick.
    tick_command: sidecarTickCommand(loader_slug),
    ...(model ? { model } : {}),
    ...(projectId ? { project_id: projectId } : {}),
    ...(expectsArtifact ? { expects_artifact: expectsArtifact } : {}),
    ...(permissionsNote ? { permissions_note: permissionsNote } : {}),
    ...(pidConfig && Object.keys(pidConfig).length > 0 ? { pid_config: pidConfig } : {}),
    // Typed contract fields (F399) — persist discrete decomposition fields when
    // the caller (script-builder) sends them, so consumers don't need to parse
    // the composed intent string to recover structured metadata.
    ...(typeof input.outcome        === "string" && input.outcome.trim()           ? { outcome_text: input.outcome.trim() }           : {}),
    ...(typeof input.inputs         === "string" && input.inputs.trim()            ? { inputs_text: input.inputs.trim() }            : {}),
    ...(typeof input.output_ownership === "string" && input.output_ownership.trim() ? { output_ownership_text: input.output_ownership.trim() } : {}),
  };

  try {
    writeAgent(agent);
    return {
      ok: true,
      id,
      name,
      description: description || undefined,
      intent,
      cron,
      loader_slug: loader_slug || undefined,
    };
  } catch (e: any) {
    return { ok: false, error: e?.message || "writeAgent failed" };
  }
}

/**
 * HTTP-shape wrapper used by POST /agent/create-scheduled.
 *
 * Tolerant of arbitrary parsed bodies (any keys missing → empty
 * strings); validation lives in createScheduledAgent. Returns a
 * discriminated-union {status, ...payload} the route handler can
 * spread directly.
 */
export type CreateScheduledAgentRouteResult =
  | { status: 200; ok: true; id: string; name: string; description?: string; cron: string }
  | { status: 400; ok: false; error: string };

export function createScheduledAgentRoute(parsed: any): CreateScheduledAgentRouteResult {
  const retryMaxRaw = parsed?.retry_max;
  const retryBackoff = parsed?.retry_backoff;
  const result = createScheduledAgent({
    name: parsed?.name || "",
    description: parsed?.description || "",
    // Field tolerance: the create surface (scheduled-task-create.tsx) sends
    // `prompt`; this contract says `intent`. The mismatch made EVERY create
    // from the New-script page fail with "intent required" (Robert,
    // 2026-06-10: "this window doesnt even seem to work").
    intent: parsed?.intent || parsed?.prompt || "",
    cron: parsed?.cron || "",
    loader_slug: parsed?.loader_slug,
    // Typed contract fields (F399) passed by script-builder alongside intent.
    outcome:          typeof parsed?.outcome          === "string" ? parsed.outcome          : undefined,
    inputs:           typeof parsed?.inputs           === "string" ? parsed.inputs           : undefined,
    output_ownership: typeof parsed?.output_ownership === "string" ? parsed.output_ownership : undefined,
    // Script-builder fields (V2-R008). Ignored when the plain scheduled-task
    // form omits them.
    model: typeof parsed?.model === "string" ? parsed.model : undefined,
    project_id: typeof parsed?.project_id === "string" ? parsed.project_id : undefined,
    retry_max: typeof retryMaxRaw === "number" ? retryMaxRaw : undefined,
    retry_backoff: retryBackoff === "exp" || retryBackoff === "fixed" || retryBackoff === "none" ? retryBackoff : undefined,
    expects_artifact: typeof parsed?.expects_artifact === "string" ? parsed.expects_artifact : undefined,
    permissions_note: typeof parsed?.permissions_note === "string" ? parsed.permissions_note : undefined,
  });
  if (result.ok) {
    return { status: 200, ok: true, id: result.id!, name: result.name!, description: result.description, cron: result.cron! };
  }
  return { status: 400, ok: false, error: result.error || "create failed" };
}

scripts- helper scripts it can run

prose-only skill - no sidecar under state/bin/ yet. Steps, if any, are described in SKILL.md.

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet