@rtrentjones/greenlight 0.2.29 → 0.3.0

package/assets/skills/provider-gemini/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: provider-gemini
+description: How the `agent` lane works in Greenlight — an autonomous cron-triggered Cloudflare Worker backed by Google Gemini (free tier). Covers the GEMINI_API_KEY (Google AI Studio, no billing), the gemini-2.5-flash generateContent call, the wrangler deploy (cron + KV + secret + custom_domain), the /, /status, /run surface, api-mode verify, and the free-tier safety envelope. Use when building, deploying, or verifying an agent tool.
+---
+
+# provider-gemini
+
+The `agent` lane is an **autonomous tool**: a Cloudflare Worker that wakes on a **cron trigger**,
+calls **Gemini** (Google's LLM, free tier), does low-stakes work, stores the result in KV, and
+exposes a tiny HTTP surface. It's the keepalive Worker pattern promoted to a user tool — free,
+always-available, immune to repo-inactivity, no OCI box, no new paid account.
+
+`agent` → target **workers**, data **none | kv** (kv holds the last output + run metadata).
+
+## Token — `GEMINI_API_KEY`
+
+Create it at **Google AI Studio** (https://aistudio.google.com/apikey) — **free tier, no billing,
+no card**. `greenlight add` verifies it against `…/v1beta/models?key=…` (HTTP 200). One key serves
+every agent (shared, not per-tool). It is a **Cloudflare Worker secret** (`wrangler secret put
+GEMINI_API_KEY`) — never in the repo.
+
+## The model + call
+
+`gemini-2.5-flash` (fast; generous free limits — ~15 RPM / 1500 req/day, so a daily cron is ~1/day).
+
+```
+POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${GEMINI_API_KEY}
+{ "contents": [{ "parts": [{ "text": "<prompt>" }] }] }
+→ candidates[0].content.parts[0].text
+```
+
+## Deploy — wrangler (workers target)
+
+Like the astro blog: cron + KV + secret + `custom_domain` in `wrangler.toml`; no Terraform.
+
+```toml
+[triggers]
+crons = ["0 13 * * *"]            # daily; stays far under the free-tier quota
+[[kv_namespaces]]
+binding = "STATE"
+[[routes]]
+pattern = "<name>.<domain>"
+custom_domain = true
+```
+
+## Surface
+
+| route | purpose |
+|---|---|
+| `scheduled()` | the cron: prompt Gemini → `STATE.put(today, text + metadata)` |
+| `GET /` | the latest output (public, read-only) |
+| `GET /status` | `{ ok, lastRun, model, preview }` — the **api-mode verify** target |
+| `POST /run` | force a run — **bearer-gated** (a `RUN_TOKEN` secret) so randoms can't burn the Gemini quota; lets deploy/verify seed the first output |
+
+## Verify — `api` mode on `/status`
+
+`verify.config.ts` hits `/status` and asserts `ok: true` + a recent run. (Output *quality* is a
+future `eval` mode — LLM-judged.) Because the first cron may not have fired at deploy time, the
+deploy step `POST /run`s once to seed, then verifies.
+
+## Safety envelope
+
+- **Low-stakes / read-only** first agents (generate → store → serve; no destructive external actions).
+- **Bearer on `/run`**; the cron frequency stays far under the free-tier daily limit.
+- Key is **secret-only** (a Worker secret), never committed or echoed.
+
+## No keepalive
+
+An agent needs no keepalive — the cron *is* its heartbeat and the Worker is always-available
+(Cloudflare's edge, not a reclaimable box). Don't add it to `module.keepalive.targets_json`.

package/dist/bin.js

@@ -6,7 +6,7 @@ import {
   resolveUrl,
   scanSqlFiles,
   verifyAll
-} from "./chunk-HMU7D7R2.js";
+} from "./chunk-P6FRYOOV.js";
 import "./chunk-HX7VA25D.js";
 import "./chunk-N3IKUCSF.js";
 import "./chunk-KP3Y6WRU.js";
@@ -351,6 +351,29 @@ var PACKS = [
     skill: "provider-neon",
     tfModules: ["neon"]
   },
+  {
+    id: "gemini",
+    name: "Google Gemini (free tier)",
+    // The LLM behind the `agent` lane. (A future `llm` axis would generalize this beyond agents.)
+    appliesTo: (t) => t.lane === "agent",
+    guide: "docs/provider-tokens.md \u2014 GEMINI_API_KEY (Google AI Studio, free tier, no billing)",
+    setupUrl: "https://aistudio.google.com/apikey",
+    tokens: [
+      {
+        // The agent Worker's LLM credential. Free tier (no billing / no card); set as a Cloudflare
+        // Worker secret, never in the repo. One key serves every agent (shared, not per-tool).
+        envVar: "GEMINI_API_KEY",
+        label: "Google AI Studio API key (Gemini free tier)",
+        verify: async (t) => {
+          const r = await fetch(`https://generativelanguage.googleapis.com/v1beta/models?key=${t}`);
+          return { ok: okStatus(r), detail: `HTTP ${r.status}` };
+        }
+      }
+    ],
+    skill: "provider-gemini"
+    // No tfModules: the agent Worker (cron + KV + secret + custom_domain) deploys via wrangler,
+    // like the astro blog — KV/DNS are wrangler-managed for the workers target.
+  },
   {
     id: "hcp",
     name: "HCP Terraform (remote state)",
@@ -478,7 +501,7 @@ function tokensForTool(tool) {
 }
 
 // src/version.ts
-var MODULE_REF = "v0.2.29";
+var MODULE_REF = "v0.3.0";
 var MODULE_SOURCE_BASE = "git::https://github.com/RTrentJones/greenlight.git//infra/modules";
 function moduleSource(module, ref = MODULE_REF) {
   return `${MODULE_SOURCE_BASE}/${module}?ref=${ref}`;
@@ -488,6 +511,14 @@ function moduleSource(module, ref = MODULE_REF) {
 var hcl = (s) => s.replace(/\n{3,}/g, "\n\n").trimEnd();
 function emitToolTf(opts) {
   const { name, domain, lane, target, data, envs, ref = MODULE_REF } = opts;
+  if (lane === "agent") {
+    const suffix = data && data !== "none" ? `/${data}` : "";
+    return `# ${name} \u2014 agent/${target}${suffix}, emitted by \`greenlight add\`.
+# Wrangler-managed: the Worker (cron + KV + custom_domain route + GEMINI_API_KEY/RUN_TOKEN
+# secrets) deploys via \`wrangler deploy\` from tools/${name}/. No Terraform here \u2014 see that
+# wrangler.toml + the provider-gemini skill + docs/agents-plan.md.
+`;
+  }
   const port = opts.port ?? 8e3;
   const slug = opts.slug ?? `OWNER/${name}`;
   const useSupabase = data === "supabase";
@@ -875,10 +906,10 @@ async function agentCommand(args) {
     const { config } = await loadManifest();
     const entry = resolveEntry(config, name);
     const dir = resolve3(process.cwd(), entry.dir ?? ".");
-    materializeAgentKit(dir, { target: entry.target, data: entry.data });
+    materializeAgentKit(dir, { lane: entry.lane, target: entry.target, data: entry.data });
     console.log(
       `
-Synced the kit for "${name}" \u2192 ${entry.dir ?? "."} (target=${entry.target}, data=${entry.data}).`
+Synced the kit for "${name}" \u2192 ${entry.dir ?? "."} (lane=${entry.lane}, target=${entry.target}, data=${entry.data}).`
     );
     return;
   }
@@ -1035,7 +1066,7 @@ function setGitHubSecret(repo, env, key, value) {
 async function gatherSecrets(name, repo, env, prefill) {
   const { config } = await loadManifest();
   const entry = resolveEntry(config, name);
-  const packs = packsForTool({ target: entry.target, data: entry.data });
+  const packs = packsForTool({ lane: entry.lane, target: entry.target, data: entry.data });
   const dest = env ? `env "${env}" of ${repo}` : repo;
   const existing = listGitHubSecrets(repo, env);
   console.log(`Gathering secrets for "${name}" \u2192 GitHub ${dest}`);
@@ -1194,7 +1225,7 @@ async function addCommand(args) {
   const entry = next.tools.find((t) => t.name === name);
   const data = entry?.data ?? "none";
   const envs = entry?.envs ?? ["beta", "prod"];
-  const toolInfo = { target, data };
+  const toolInfo = { lane, target, data };
   const dest = resolve5(process.cwd(), "tools", name);
   if (existsSync5(dest)) throw new Error(`tools/${name} already exists`);
   const src = templateDir(lane, target);
@@ -1209,6 +1240,11 @@ async function addCommand(args) {
     }
     const shippedGitignore = join(dest, "gitignore");
     if (existsSync5(shippedGitignore)) renameSync(shippedGitignore, join(dest, ".gitignore"));
+    const wranglerPath = join(dest, "wrangler.toml");
+    if (existsSync5(wranglerPath)) {
+      const wt = readFileSync3(wranglerPath, "utf8").replaceAll("agent-tool", name).replaceAll("example.dev", config.domain);
+      writeFileSync2(wranglerPath, wt);
+    }
     console.log(`\u2714 copied ${src} \u2192 tools/${name}`);
     if (existsSync5(pkgPath)) registerWorkspaceMember(process.cwd(), `tools/${name}`);
   } else {
@@ -1838,11 +1874,11 @@ async function adoptWrapper(ctx) {
       `verify/${name}.config.ts`
     );
   }
-  const providers = providersForTool({ target, data });
+  const providers = providersForTool({ lane, target, data });
   if (existsSync6(join2(cwd, "infra/main.tf")) && providers.some((p) => p !== "cloudflare" && p !== "github")) {
     console.log(`\xB7 ensure infra/main.tf declares provider(s): ${providers.join(", ")}`);
   }
-  materializeAgentKit(dest, { target, data });
+  materializeAgentKit(dest, { lane, target, data });
   addGreenlightScript(dest);
   if (target === "oci") {
     const wrapperSlug = parseRepo(safeGit(cwd, ["remote", "get-url", "origin"])) ?? "OWNER/REPO";
@@ -1940,7 +1976,7 @@ async function adoptStandalone(ctx) {
     ".github/workflows/greenlight-promote.yml"
   );
   writeIfAbsent(join2(repo, "verify.config.ts"), starterVerifyConfig(lane), "verify.config.ts");
-  materializeAgentKit(repo, { target, data });
+  materializeAgentKit(repo, { lane, target, data });
   writeIfAbsent(join2(repo, "mise.toml"), MISE_TOML, "mise.toml");
   writeIfAbsent(join2(repo, ".node-version"), "24\n", ".node-version");
   const nextReg = addTool(reg, {
@@ -2674,6 +2710,13 @@ function defaultSpec(lane) {
       return { mode: "api", checks: [{ path: "/", status: 200 }] };
     case "mcp":
       return { mode: "mcp", expectTools: [] };
+    case "agent":
+      return {
+        mode: "api",
+        checks: [{ path: "/status", status: 200 }],
+        settleRetries: 6,
+        settleMs: 5e3
+      };
   }
 }
 function printReport(report) {

package/dist/{chunk-HMU7D7R2.js → chunk-P6FRYOOV.js}

@@ -13,7 +13,7 @@ import { createJiti } from "jiti";
 
 // ../packages/shared/src/schema.ts
 import { z } from "zod";
-var LaneEnum = z.enum(["astro", "next", "mcp"]);
+var LaneEnum = z.enum(["astro", "next", "mcp", "agent"]);
 var TargetEnum = z.enum(["workers", "vercel", "oci"]);
 var DataEnum = z.enum(["none", "d1", "kv", "supabase", "neon"]);
 var AuthEnum = z.enum(["none", "bearer", "oauth"]);
@@ -22,7 +22,8 @@ var EnvEnum = z.enum(["preview", "beta", "prod"]);
 var MATRIX = {
   astro: { targets: ["workers"], data: ["none", "d1", "kv"] },
   next: { targets: ["vercel"], data: ["none", "supabase", "neon"] },
-  mcp: { targets: ["workers", "oci"], data: ["none"] }
+  mcp: { targets: ["workers", "oci"], data: ["none"] },
+  agent: { targets: ["workers"], data: ["none", "kv"] }
 };
 var ToolSchema = z.object({
   name: z.string().regex(/^[a-z][a-z0-9-]*$/, "tool name must be kebab-case starting with a letter"),

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   defineConfig,
   defineVerify,
   loadConfig
-} from "./chunk-HMU7D7R2.js";
+} from "./chunk-P6FRYOOV.js";
 import "./chunk-HX7VA25D.js";
 import "./chunk-N3IKUCSF.js";
 import "./chunk-KP3Y6WRU.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtrentjones/greenlight",
-  "version": "0.2.29",
+  "version": "0.3.0",
   "description": "Greenlight CLI — setup and lifecycle for the harness.",
   "license": "MIT",
   "repository": {
@@ -31,10 +31,10 @@
     "@anthropic-ai/sdk": "^0.69.0"
   },
   "devDependencies": {
-    "@rtrentjones/greenlight-adapters": "0.2.29",
-    "@rtrentjones/greenlight-loop": "0.2.29",
-    "@rtrentjones/greenlight-verify": "0.2.29",
-    "@rtrentjones/greenlight-shared": "0.2.29"
+    "@rtrentjones/greenlight-adapters": "0.3.0",
+    "@rtrentjones/greenlight-loop": "0.3.0",
+    "@rtrentjones/greenlight-verify": "0.3.0",
+    "@rtrentjones/greenlight-shared": "0.3.0"
   },
   "scripts": {
     "build": "node scripts/copy-assets.mjs && tsup",

package/templates/_template-agent/README.md

@@ -0,0 +1,33 @@
+# agent — autonomous Gemini-backed Worker
+
+A cron-triggered Cloudflare Worker that calls **Gemini** (free tier), stores the result in **KV**,
+and serves it. Scaffolded by `greenlight add <name> --lane agent --target workers --data kv`.
+
+## What it does
+
+- `scheduled` (cron, daily) → prompt Gemini → store the text + metadata in KV.
+- `GET /` — the latest output (plain text).
+- `GET /status` — `{ ok, lastRun, model, preview }` (the verify target).
+- `POST /run` — force a run; **bearer-gated** (`Authorization: Bearer $RUN_TOKEN`).
+
+## Setup (once)
+
+`greenlight add` already rewrote the worker `name` + route domain in `wrangler.toml`. Then:
+
+1. **KV namespace** — `pnpm exec wrangler kv namespace create STATE`, and paste the id into the
+   three `id = "REPLACE_WITH_KV_NAMESPACE_ID"` slots in `wrangler.toml`.
+2. **Secrets** (per env — the key never goes in the repo):
+   - `pnpm exec wrangler secret put GEMINI_API_KEY --env prod` — your Google AI Studio key (free,
+     `aistudio.google.com/apikey`).
+   - `pnpm exec wrangler secret put RUN_TOKEN --env prod` — any random string.
+3. **Deploy → seed → verify**:
+   - `pnpm greenlight deploy <name>` (or `pnpm exec wrangler deploy --env prod`).
+   - `curl -XPOST https://<name>.<domain>/run -H "Authorization: Bearer $RUN_TOKEN"` (seed the first run).
+   - `pnpm greenlight verify <name> --env prod`.
+
+## Free-tier safety
+
+The daily cron is ~1 Gemini call/day (the free tier allows ~1500/day). `/run` is bearer-gated so it
+can't be used to burn the quota. The key lives **only** as a Worker secret.
+
+See the `provider-gemini` skill + [docs/agents-plan.md](../../docs/agents-plan.md).

package/templates/_template-agent/gitignore

@@ -0,0 +1,5 @@
+# Shipped as `gitignore` (no dot) so it survives the npm tarball; `greenlight add` renames it to
+# `.gitignore` on scaffold.
+node_modules/
+.wrangler/
+dist/

package/templates/_template-agent/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "_template-agent",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250601.0",
+    "typescript": "^5.6.0",
+    "wrangler": "^3.90.0"
+  }
+}

package/templates/_template-agent/src/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent Worker — autonomous, cron-triggered, Gemini-backed.
+ *
+ * On the cron (`scheduled`) it asks Gemini for content and stores it in KV. The `fetch` handler
+ * serves the latest output (`GET /`), reports last-run metadata (`GET /status` — the verify
+ * target), and force-runs (`POST /run`, bearer-gated so it can't be used to burn the free-tier
+ * quota; the deploy step uses it to seed the first output before verify).
+ *
+ * GEMINI_API_KEY + RUN_TOKEN are Worker secrets (`wrangler secret put …`), never in wrangler.toml.
+ */
+
+export interface Env {
+  STATE: KVNamespace;
+  GEMINI_API_KEY: string;
+  RUN_TOKEN?: string;
+  MODEL: string;
+  GREENLIGHT_ENV: string;
+}
+
+interface AgentRecord {
+  ok: true;
+  text: string;
+  lastRun: string;
+  model: string;
+}
+
+const PROMPT =
+  'In one or two sentences, share a single concrete, non-obvious tip about deploying software ' +
+  'safely. Vary the topic each time. Plain text, no preamble, no markdown.';
+
+async function callGemini(env: Env): Promise<string> {
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${env.MODEL}:generateContent?key=${env.GEMINI_API_KEY}`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ contents: [{ parts: [{ text: PROMPT }] }] }),
+  });
+  if (!res.ok) throw new Error(`Gemini HTTP ${res.status}`);
+  const data = (await res.json()) as {
+    candidates?: { content?: { parts?: { text?: string }[] } }[];
+  };
+  const text = data.candidates?.[0]?.content?.parts?.[0]?.text?.trim();
+  if (!text) throw new Error('Gemini returned no text');
+  return text;
+}
+
+function key(env: Env): string {
+  return `${env.GREENLIGHT_ENV}:latest`;
+}
+
+async function runOnce(env: Env): Promise<AgentRecord> {
+  const rec: AgentRecord = {
+    ok: true,
+    text: await callGemini(env),
+    lastRun: new Date().toISOString(),
+    model: env.MODEL,
+  };
+  await env.STATE.put(key(env), JSON.stringify(rec));
+  return rec;
+}
+
+async function latest(env: Env): Promise<AgentRecord | null> {
+  const raw = await env.STATE.get(key(env));
+  return raw ? (JSON.parse(raw) as AgentRecord) : null;
+}
+
+export default {
+  async scheduled(_event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
+    ctx.waitUntil(runOnce(env));
+  },
+
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const { pathname } = new URL(req.url);
+
+    if (req.method === 'POST' && pathname === '/run') {
+      const auth = req.headers.get('authorization');
+      if (!env.RUN_TOKEN || auth !== `Bearer ${env.RUN_TOKEN}`) {
+        return new Response('unauthorized', { status: 401 });
+      }
+      return Response.json(await runOnce(env));
+    }
+
+    if (pathname === '/status') {
+      const rec = await latest(env);
+      return Response.json({
+        ok: Boolean(rec),
+        lastRun: rec?.lastRun ?? null,
+        model: env.MODEL,
+        preview: rec ? rec.text.slice(0, 80) : null,
+      });
+    }
+
+    const rec = await latest(env);
+    if (!rec) return new Response('No run yet — POST /run to seed.\n', { status: 200 });
+    return new Response(`${rec.text}\n`, {
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    });
+  },
+};

package/templates/_template-agent/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "lib": ["es2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/_template-agent/verify.config.ts

@@ -0,0 +1,8 @@
+// The agent exposes GET /status with last-run metadata. The deploy step seeds a run (POST /run)
+// before verify, so /status reports ok:true — assert that. settle absorbs Cloudflare propagation.
+export default {
+  mode: 'api',
+  checks: [{ path: '/status', status: 200, contains: '"ok":true' }],
+  settleRetries: 6,
+  settleMs: 5000,
+};

package/templates/_template-agent/wrangler.toml

@@ -0,0 +1,47 @@
+# Agent Worker. `greenlight add` rewrites `name` (agent-tool → your tool) + the route domain
+# (example.dev → your domain). You still set the KV namespace id (create it once with
+# `wrangler kv namespace create STATE`) and the secrets:
+#   wrangler secret put GEMINI_API_KEY --env prod   (Google AI Studio key — free tier)
+#   wrangler secret put RUN_TOKEN --env prod         (any random string; bearer for POST /run)
+name = "agent-tool"
+main = "src/index.ts"
+compatibility_date = "2025-06-01"
+
+# Daily 13:00 UTC — far under the Gemini free-tier quota (~1500 req/day). Edit to taste.
+[triggers]
+crons = ["0 13 * * *"]
+
+[vars]
+MODEL = "gemini-2.5-flash"
+GREENLIGHT_ENV = "prod"
+
+# Output store. `wrangler kv namespace create STATE` → paste the id here (and per-env below).
+[[kv_namespaces]]
+binding = "STATE"
+id = "REPLACE_WITH_KV_NAMESPACE_ID"
+
+# Named environments (the deploy uses `wrangler deploy --env prod|beta`). Wrangler envs do NOT
+# inherit top-level config, so vars + kv + routes are repeated per env.
+[env.prod]
+name = "agent-tool"
+routes = [{ pattern = "agent-tool.example.dev", custom_domain = true }]
+
+[env.prod.vars]
+MODEL = "gemini-2.5-flash"
+GREENLIGHT_ENV = "prod"
+
+[[env.prod.kv_namespaces]]
+binding = "STATE"
+id = "REPLACE_WITH_KV_NAMESPACE_ID"
+
+[env.beta]
+name = "agent-tool-beta"
+routes = [{ pattern = "beta.agent-tool.example.dev", custom_domain = true }]
+
+[env.beta.vars]
+MODEL = "gemini-2.5-flash"
+GREENLIGHT_ENV = "beta"
+
+[[env.beta.kv_namespaces]]
+binding = "STATE"
+id = "REPLACE_WITH_KV_NAMESPACE_ID"