cronfish 0.13.0 → 0.14.0

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">cronfish 🐟</h1>
 
-<p align="center"><strong>A file-based job scheduler for macOS. Drop a script in a folder; launchd runs it on a schedule.</strong></p>
+<p align="center"><strong>Write a cron job in Markdown — an LLM runs it on a schedule. Or drop a <code>.ts</code>/<code>.sh</code> script for the deterministic stuff. launchd fires all three.</strong></p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/cronfish"><img src="https://img.shields.io/npm/v/cronfish?logo=npm" alt="npm"></a>
@@ -14,9 +14,24 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
 </p>
 
-Cronfish is for personal automation — the small scheduled jobs you'd otherwise hand-roll as
-launchd plists or crontab lines. Drop a `.md` (Claude prompt), `.ts` (Bun program), or `.sh`
-(bash script) in `cron/`, run `cronfish sync`, and launchd takes it from there.
+The pitch in one file. This is a complete, scheduled cron job:
+
+```markdown
+---
+schedule: "every morning at 8"
+model: sonnet
+---
+
+Read my calendar for today, check the weather, and post a
+one-paragraph brief to the #daily Slack channel.
+```
+
+Drop it in `cron/`, run `cronfish sync`, and launchd runs it every morning — the body _is_ the job,
+handed to an LLM at fire time. No script to write, no glue code. **Markdown is a valid cron job.**
+
+When the work _is_ deterministic — a backup, a sync, a healthcheck — write it as `.ts` (Bun) or
+`.sh` (bash) instead. Same frontmatter, same `cronfish sync`, no LLM in the loop. One scheduler,
+three tiers; reach for the lightest that does the job.
 
 It makes the file the job: frontmatter is the schedule, the path is the slug — no hand-written
 plists, no registration step. You also get per-run logs, retries, concurrency guards, failure
@@ -31,20 +46,24 @@ every kind.
 
 ## Why cronfish?
 
-Claude's native scheduled agents are the obvious alternative, and for pure-LLM tasks they're great
-— zero setup, nothing to host. But everything runs on Anthropic's managed runtime: you pay their
-rates, and every job is a Claude job. Cronfish trades that convenience for control:
+Two kinds of scheduler exist today, and neither does both halves:
+
+- **cron / launchd** run scripts, never prose. A natural-language job isn't expressible.
+- **Claude's native scheduled agents** run prose, but _only_ prose — every job is an LLM job on
+  Anthropic's managed runtime, at their rates.
 
-- **Any job, not just LLM jobs.** Most scheduled work is plain bash or a TypeScript script — a
-  backup, a sync, a healthcheck. Cronfish runs those first-class, alongside `.md` Claude prompts.
-- **Any harness.** `.md` jobs shell out to a CLI you choose — Claude Code by default, or another
-  agent runner — so you're not locked to one model or one vendor.
-- **Local, so you control the bill.** Jobs run on your machine against whatever model you point
-  them at (hosted Claude, a local Ollama model, a LAN LiteLLM box). No managed-runtime markup, and
-  your data stays on your hardware.
+cronfish runs both from one folder:
+
+- **Markdown jobs are natural-language cron.** The body is the instruction; cronfish hands it to an
+  agent CLI (Claude Code by default) at fire time. No other scheduler runs a prose job.
+- **Script jobs stay deterministic.** `.ts` and `.sh` run code you wrote — the standard cron trust
+  model, first-class alongside `.md`.
+- **Any harness, any model, local or hosted.** `.md` jobs shell out to a CLI you choose — point them
+  at hosted Claude, a local Ollama model, or a LAN LiteLLM box. No managed-runtime markup; your data
+  stays on your hardware.
 
 Reach for Claude's scheduler when you want zero-ops and a single LLM task. Reach for cronfish when
-you have a mix of scripts and agents, care about cost, or want to choose the model.
+you want a mix of prose and scripts, care about cost, or want to choose the model.
 
 ## Quickstart
 
@@ -79,7 +98,7 @@ you can document a folder of crons without the README getting parsed as a job.
 ```markdown
 ---
 schedule: "every 5 minutes" # see below for all accepted shapes
-model: haiku # claude alias | raw ID | local:<name>
+model: haiku # claude alias | raw ID | local:<name> | subconscious/<name>
 enabled: true # default true
 timeout: 300 # seconds; runner kills past this
 retries: 0 # retry count on non-zero exit
@@ -129,7 +148,7 @@ invokes the file as `/bin/bash <path>` with `cwd = consumer repo root`; stdout/s
 per-run log. **A `.sh` file with no frontmatter block fails at discovery** — cronfish prints the
 error in `list`/`sync` so you know to add one.
 
-## `model:` — claude alias, raw ID, or local
+## `model:` — claude alias, raw ID, local, or subconscious
 
 For Anthropic-hosted models, use the aliases `haiku` / `sonnet` / `opus` (resolve to the latest
 pinned IDs), or pass a raw ID like `claude-sonnet-4-6` verbatim.
@@ -153,6 +172,13 @@ will hallucinate tool calls. Use 14B+ for any agentic loop; 32B is the practical
 multi-step work. Local providers serve one request at a time — set `concurrency: queue` on
 overlapping jobs.
 
+For a **[Subconscious](https://subconscious.dev)-hosted model**, use the id verbatim with its
+`subconscious/` prefix — e.g. `subconscious/glm-5.2`. Same mechanics as `local:` (base URL +
+slot overrides injected at spawn), pointed at `https://api.subconscious.dev` and authenticated
+with `SUBCONSCIOUS_API_KEY` from the consumer `.env` (scope it into the job with
+`env: [SUBCONSCIOUS_API_KEY]`). Override the endpoint with `SUBCONSCIOUS_BASE_URL`. The job
+fails with a clear error if the key is unset.
+
 ## One-shot jobs — `cron/one-time/`
 
 Drop a `.md`, `.ts`, or `.sh` under `cron/one-time/` to schedule a job that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cronfish",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A file-based job scheduler for macOS. Drop a script in a folder; launchd runs it on a schedule.",
   "type": "module",
   "bin": {

package/src/models.ts

@@ -8,8 +8,12 @@
 // Messages natively; LiteLLM proxies it for everything else). The model
 // ID after the `local:` prefix is passed verbatim to `--model` and as
 // the three slot overrides so sub-agents route locally too.
+//
+// `subconscious/<id>` models route the same way to api.subconscious.dev
+// (a hosted Anthropic-compatible endpoint), authenticated with
+// SUBCONSCIOUS_API_KEY from the job env.
 
-export type Provider = "anthropic" | "local";
+export type Provider = "anthropic" | "local" | "subconscious";
 
 export interface Resolved {
   provider: Provider;
@@ -27,6 +31,11 @@ export function resolveModel(input: string | undefined): Resolved {
   if (raw.startsWith("local:")) {
     return { provider: "local", id: raw.slice("local:".length) };
   }
+  if (raw.startsWith("subconscious/")) {
+    // Subconscious's model namespace includes the prefix (e.g.
+    // subconscious/glm-5.2) — pass the id through verbatim.
+    return { provider: "subconscious", id: raw };
+  }
   if (ALIASES[raw]) return { provider: "anthropic", id: ALIASES[raw] };
   return { provider: "anthropic", id: raw };
 }
@@ -39,6 +48,38 @@ export function localClaudeEnv(modelId: string): Record<string, string> {
   const baseUrl =
     process.env.CRONFISH_LOCAL_BASE_URL ?? "http://localhost:11434";
   const authToken = process.env.CRONFISH_LOCAL_AUTH_TOKEN ?? "ollama";
+  return backendClaudeEnv(baseUrl, authToken, modelId);
+}
+
+// Env block for a `subconscious/*` model — api.subconscious.dev speaks the
+// Anthropic Messages API. Requires SUBCONSCIOUS_API_KEY in the job env
+// (consumer .env; scope with frontmatter `env: [SUBCONSCIOUS_API_KEY]`).
+export function subconsciousClaudeEnv(modelId: string): Record<string, string> {
+  const baseUrl = (
+    process.env.SUBCONSCIOUS_BASE_URL ?? "https://api.subconscious.dev"
+  ).replace(/\/$/, "");
+  const authToken = process.env.SUBCONSCIOUS_API_KEY;
+  if (!authToken) {
+    throw new Error(
+      "[models] SUBCONSCIOUS_API_KEY is not set — required for subconscious/* models",
+    );
+  }
+  return backendClaudeEnv(baseUrl, authToken, modelId);
+}
+
+// Env block for spawning `claude` against the given provider, or undefined
+// for api.anthropic.com models. Single dispatch point for the runner.
+export function claudeEnvFor(r: Resolved): Record<string, string> | undefined {
+  if (r.provider === "local") return localClaudeEnv(r.id);
+  if (r.provider === "subconscious") return subconsciousClaudeEnv(r.id);
+  return undefined;
+}
+
+function backendClaudeEnv(
+  baseUrl: string,
+  authToken: string,
+  modelId: string,
+): Record<string, string> {
   return {
     ANTHROPIC_BASE_URL: baseUrl,
     ANTHROPIC_AUTH_TOKEN: authToken,

package/src/runner.ts

@@ -35,7 +35,7 @@ import {
   type InvocationTrigger,
 } from "./db.ts";
 import { loadJob, slugFromPath, type JobMeta } from "./jobs.ts";
-import { resolveModel, localClaudeEnv } from "./models.ts";
+import { resolveModel, claudeEnvFor } from "./models.ts";
 import {
   DEFAULT_GRACE_SECONDS,
   archiveOneTime,
@@ -367,11 +367,11 @@ async function execMarkdown(
     appendLog(fd, `[runner] read-only: deny [${READ_ONLY_DENY.join(", ")}]`);
   }
   const cmd = buildClaudeArgs(CLAUDE_BIN, job, model.id, prompt);
-  const env = model.provider === "local" ? localClaudeEnv(model.id) : undefined;
+  const env = claudeEnvFor(model);
   if (env) {
     appendLog(
       fd,
-      `[runner] local base_url=${env.ANTHROPIC_BASE_URL} model=${model.id}`,
+      `[runner] ${model.provider} base_url=${env.ANTHROPIC_BASE_URL} model=${model.id}`,
     );
   }
   return runSpawn({ cmd, cwd: consumerRoot(), env }, fd, timeoutS);