paolodelia99 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -32,3 +32,7 @@ UPCOMING_CHANGELOG.md
 logs/
 *.bun-build
 tsconfig.tsbuildinfo
+
+# Local docs (agents + superpowers plans/specs)
+docs/agents/
+docs/superpowers/
diff --git a/packages/core/src/cron/duration.ts b/packages/core/src/cron/duration.ts
@@ -0,0 +1,27 @@
+export * as Duration from "./duration"
+
+import { Effect } from "effect"
+import { CronError } from "./port"
+
+const MIN_INTERVAL_MS = 60_000
+
+const RE = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/
+
+export const parseDuration = (input: string): Effect.Effect<number, CronError> =>
+  Effect.gen(function* () {
+    const match = RE.exec(input)
+    if (!match || (!match[1] && !match[2] && !match[3])) {
+      return yield* new CronError({ message: `Invalid duration: "${input}". Use format like 5m, 1h, 2h30m, 90s.` })
+    }
+    const hours = match[1] ? parseInt(match[1], 10) : 0
+    const minutes = match[2] ? parseInt(match[2], 10) : 0
+    const seconds = match[3] ? parseInt(match[3], 10) : 0
+    const ms = (hours * 3600 + minutes * 60 + seconds) * 1000
+    if (!Number.isFinite(ms)) {
+      return yield* new CronError({ message: `Interval too large: "${input}".` })
+    }
+    if (ms < MIN_INTERVAL_MS) {
+      return yield* new CronError({ message: `Interval must be at least 1 minute (60s). Got: ${ms / 1000}s` })
+    }
+    return ms
+  })
diff --git a/packages/core/src/cron/job.ts b/packages/core/src/cron/job.ts
@@ -0,0 +1,19 @@
+export * as Cron from "./job"
+
+import { Schema } from "effect"
+
+export const CronJob = Schema.Struct({
+  id: Schema.String,
+  sessionID: Schema.String,
+  prompt: Schema.String,
+  intervalMs: Schema.Number,
+  agent: Schema.optional(Schema.String),
+  model: Schema.optional(Schema.String),
+  createdAt: Schema.Number,
+  expiresAt: Schema.Number,
+  nextRunAt: Schema.Number,
+  lastRunAt: Schema.optional(Schema.Number),
+  runCount: Schema.Number,
+  context: Schema.optional(Schema.Unknown),
+})
+export type CronJob = Schema.Schema.Type<typeof CronJob>
diff --git a/packages/core/src/cron/port.ts b/packages/core/src/cron/port.ts
@@ -0,0 +1,22 @@
+export * as CronPort from "./port"
+
+import { Context, Effect, Schema } from "effect"
+
+export class CronDeliveryError extends Schema.TaggedErrorClass<CronDeliveryError>()("Cron.DeliveryError", {
+  message: Schema.String,
+}) {}
+
+export class CronError extends Schema.TaggedErrorClass<CronError>()("Cron.Error", {
+  message: Schema.String,
+}) {}
+
+interface Interface {
+  readonly deliver: (
+    sessionID: string,
+    prompt: string,
+    opts?: { readonly agent?: string; readonly model?: string; readonly context?: unknown },
+  ) => Effect.Effect<void, CronDeliveryError>
+  readonly exists: (sessionID: string) => Effect.Effect<boolean>
+}
+
+export class CronDeliveryPort extends Context.Service<CronDeliveryPort, Interface>()("@opencode/CronDeliveryPort") {}
diff --git a/packages/core/src/cron/service.ts b/packages/core/src/cron/service.ts
@@ -0,0 +1,189 @@
+import { Cause, Clock, Context, Effect, Fiber, Layer, Queue, Ref } from "effect"
+import { CronDeliveryPort, CronError } from "./port"
+import { CronJob } from "./job"
+
+interface Interface {
+  readonly add: (input: {
+    sessionID: string
+    prompt: string
+    intervalMs: number
+    agent?: string
+    model?: string
+    context?: unknown
+  }) => Effect.Effect<CronJob, CronError>
+  readonly list: (sessionID: string) => Effect.Effect<ReadonlyArray<CronJob>>
+  readonly remove: (sessionID: string, jobId: string) => Effect.Effect<number>
+}
+
+export class CronService extends Context.Service<CronService, Interface>()("@opencode/CronService") {}
+
+const sortByNextRun = (jobs: Array<CronJob>) => [...jobs].sort((a, b) => a.nextRunAt - b.nextRunAt)
+
+const make = Effect.gen(function* () {
+  const port = yield* CronDeliveryPort
+  const heap = yield* Ref.make<Array<CronJob>>([])
+  const wakeQueue = yield* Queue.unbounded<void>()
+  const PENDING_RESERVED = Symbol("pending-reserved")
+  type PendingValue = Fiber.Fiber<unknown, unknown> | typeof PENDING_RESERVED
+  const pending = yield* Ref.make<Map<string, PendingValue>>(new Map())
+
+  const insertJob = (job: CronJob) => Ref.update(heap, (jobs) => sortByNextRun([...jobs, job]))
+
+  const dequeueJob = () =>
+    Ref.modify(heap, (jobs) => {
+      if (jobs.length === 0) return [null as CronJob | null, jobs] as const
+      return [jobs[0], jobs.slice(1)] as const
+    })
+
+  const heapIsEmpty = () => Ref.get(heap).pipe(Effect.map((jobs) => jobs.length === 0))
+
+  const filterInPlace = (predicate: (job: CronJob) => boolean) =>
+    Ref.modify(heap, (jobs) => {
+      const kept = jobs.filter(predicate)
+      return [jobs.length - kept.length, sortByNextRun(kept)] as const
+    })
+
+  const loop = Effect.gen(function* () {
+    while (true) {
+      const empty = yield* heapIsEmpty()
+      if (empty) {
+        yield* Queue.take(wakeQueue)
+        continue
+      }
+
+      const top = yield* Ref.get(heap).pipe(Effect.map((jobs) => jobs[0]))
+      const now = yield* Clock.currentTimeMillis
+      const waitMs = Math.max(0, top.nextRunAt - now)
+
+      const result = yield* Effect.race(
+        Effect.sleep(waitMs).pipe(Effect.as("tick" as const)),
+        Queue.take(wakeQueue).pipe(Effect.as("wake" as const)),
+      )
+      if (result === "wake") continue
+
+      const job = yield* dequeueJob()
+      if (!job) continue
+
+      if (job.id !== top.id) {
+        // A sooner job was inserted during the sleep and won the heap head.
+        // Re-queue the job we just popped and re-iterate instead of firing early.
+        yield* insertJob(job)
+        continue
+      }
+
+      const current = yield* Clock.currentTimeMillis
+
+      if (current >= job.expiresAt) continue
+
+      // Reserve the pending slot atomically before forking so a fast delivery
+      // cannot complete and clear the slot before the fiber reference is stored.
+      const reserved = yield* Ref.modify(pending, (m) =>
+        m.has(job.id) ? ([false, m] as const) : ([true, m.set(job.id, PENDING_RESERVED)] as const),
+      )
+      if (!reserved) {
+        // Coalesced: a delivery is already pending for this job. Advance the
+        // schedule on cadence without forking another delivery.
+        yield* insertJob({ ...job, nextRunAt: job.nextRunAt + job.intervalMs })
+        continue
+      }
+
+      const fiber = yield* Effect.forkScoped(
+        port.deliver(job.sessionID, job.prompt, { agent: job.agent, model: job.model, context: job.context }).pipe(
+          Effect.catch((e) => Effect.logError("cron delivery failed", { sessionID: job.sessionID, error: String(e) })),
+          Effect.catchCause((cause) =>
+            Cause.hasInterrupts(cause)
+              ? Effect.failCause(cause)
+              : Effect.logError("cron delivery defect", { sessionID: job.sessionID, cause: Cause.pretty(cause) }),
+          ),
+          Effect.ensuring(
+            Ref.update(pending, (m) => {
+              if (m.get(job.id) === PENDING_RESERVED || m.get(job.id) === fiber) m.delete(job.id)
+              return m
+            }),
+          ),
+        ),
+      )
+      yield* Ref.update(pending, (m) => {
+        if (m.get(job.id) === PENDING_RESERVED) m.set(job.id, fiber)
+        return m
+      })
+
+      const updated: CronJob = {
+        ...job,
+        lastRunAt: current,
+        runCount: job.runCount + 1,
+        nextRunAt: job.nextRunAt + job.intervalMs,
+      }
+      yield* insertJob(updated)
+    }
+  })
+
+  yield* loop.pipe(Effect.forkScoped)
+
+  const add = (input: {
+    sessionID: string
+    prompt: string
+    intervalMs: number
+    agent?: string
+    model?: string
+    context?: unknown
+  }) =>
+    Effect.gen(function* () {
+      if (input.intervalMs < 60_000) {
+        return yield* new CronError({ message: "Interval must be at least 1 minute (60s)" })
+      }
+      const exists = yield* port.exists(input.sessionID)
+      if (!exists) {
+        return yield* new CronError({ message: `Session ${input.sessionID} not found` })
+      }
+      const now = yield* Clock.currentTimeMillis
+      const job: CronJob = {
+        id: crypto.randomUUID(),
+        sessionID: input.sessionID,
+        prompt: input.prompt,
+        intervalMs: input.intervalMs,
+        agent: input.agent,
+        model: input.model,
+        createdAt: now,
+        expiresAt: now + 7 * 24 * 60 * 60 * 1000,
+        nextRunAt: now,
+        runCount: 0,
+        context: input.context,
+      }
+      const inserted = yield* Ref.modify(heap, (jobs) => {
+        const count = jobs.filter((j) => j.sessionID === input.sessionID).length
+        if (count >= 50) return [false, jobs] as const
+        return [true, sortByNextRun([...jobs, job])] as const
+      })
+      if (!inserted) {
+        return yield* new CronError({ message: "Maximum 50 cron jobs per session" })
+      }
+      yield* Queue.offer(wakeQueue, undefined)
+      return job
+    })
+
+  const list = (sessionID: string) =>
+    Ref.get(heap).pipe(Effect.map((jobs) => jobs.filter((j) => j.sessionID === sessionID)))
+
+  const remove = (sessionID: string, jobId: string) =>
+    Effect.gen(function* () {
+      const before = yield* Ref.get(heap)
+      const removedIds = new Set(
+        before.filter((j) => j.sessionID === sessionID && (jobId === "all" || j.id === jobId)).map((j) => j.id),
+      )
+      const removed = yield* filterInPlace((j) => j.sessionID !== sessionID || (jobId !== "all" && j.id !== jobId))
+      yield* Ref.get(pending).pipe(
+        Effect.flatMap((m) =>
+          Effect.forEach([...m.entries()], ([id, fiber]) =>
+            removedIds.has(id) && fiber !== PENDING_RESERVED ? Fiber.interrupt(fiber).pipe(Effect.asVoid) : Effect.void,
+          ),
+        ),
+      )
+      yield* Queue.offer(wakeQueue, undefined)
+      return removed
+    })
+
+  return CronService.of({ add, list, remove })
+})
+
+export const layer = Layer.effect(CronService, make)
diff --git a/packages/core/src/plugin/skill.ts b/packages/core/src/plugin/skill.ts
@@ -7,8 +7,10 @@ import { Effect } from "effect"
 import { AbsolutePath } from "../schema"
 import { SkillV2 } from "../skill"
 import customizeOpencodeContent from "./skill/customize-opencode.md" with { type: "text" }
+import schedulingContent from "./skill/scheduling.md" with { type: "text" }
 
 export const CustomizeOpencodeContent = customizeOpencodeContent
+export const SchedulingContent = schedulingContent
 
 export const Plugin = define({
   id: "skill",

diff --git a/packages/core/src/plugin/skill/scheduling.md b/packages/core/src/plugin/skill/scheduling.md
@@ -0,0 +1,26 @@
+---
+name: scheduling
+description: Schedule recurring prompts with cron_add, list with cron_list, cancel with cron_delete. Use when you need recurring reminders, checks, or automated actions.
+---
+
+## Adding a schedule
+
+Use `cron_add` to schedule a prompt:
+
+```
+cron_add(interval: "5m", prompt: "Check for new issues")
+```
+
+Interval format: `5m`, `1h`, `2h30m`, `90s`. Minimum 1m, max 7d lifespan, max 50 jobs/session.
+
+## Listing
+
+Use `cron_list` to see all scheduled jobs, in the following format:
+
+| ID            | Prompt                | Interval | Run | Next |
+| :------------ | :-------------------- | :------- | :-- | :--- |
+| `e15f1b62...` | Write "Hello, World!" | 1m       | 6   | ~1m  |
+
+## Cancelling
+
+`cron_delete(id: "id")` for one, `cron_delete(id: "all")` for all.
diff --git a/packages/core/test/cron/duration.test.ts b/packages/core/test/cron/duration.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "bun:test"
+import { Effect, Exit } from "effect"
+import { Duration } from "@opencode-ai/core/cron/duration"
+
+describe("parseDuration", () => {
+  const run = (input: string) => Effect.runSyncExit(Duration.parseDuration(input))
+
+  it("5m → 300000", () => {
+    expect(run("5m")).toEqual(Exit.succeed(300_000))
+  })
+
+  it("1h → 3600000", () => {
+    expect(run("1h")).toEqual(Exit.succeed(3_600_000))
+  })
+
+  it("2h30m → 9000000", () => {
+    expect(run("2h30m")).toEqual(Exit.succeed(9_000_000))
+  })
+
+  it("90s → 90000", () => {
+    expect(run("90s")).toEqual(Exit.succeed(90_000))
+  })
+
+  it("30s → reject (below floor)", () => {
+    const result = run("30s")
+    expect(Exit.isFailure(result)).toBe(true)
+    if (Exit.isFailure(result)) {
+      expect(result.cause).toBeDefined()
+    }
+  })
+
+  it("empty string → reject", () => {
+    const result = run("")
+    expect(Exit.isFailure(result)).toBe(true)
+  })
+
+  it("abc → reject", () => {
+    const result = run("abc")
+    expect(Exit.isFailure(result)).toBe(true)
+  })
+
+  it("5x → reject", () => {
+    const result = run("5x")
+    expect(Exit.isFailure(result)).toBe(true)
+  })
+
+  it("60s → 60000 (floor boundary accepted)", () => {
+    expect(run("60s")).toEqual(Exit.succeed(60_000))
+  })
+
+  it("1m → 60000", () => {
+    expect(run("1m")).toEqual(Exit.succeed(60_000))
+  })
+
+  it("1h0m0s → 3600000 (trailing zeros accepted)", () => {
+    expect(run("1h0m0s")).toEqual(Exit.succeed(3_600_000))
+  })
+
+  it("0h0m60s → 60000 (zero-prefixed forms accepted)", () => {
+    expect(run("0h0m60s")).toEqual(Exit.succeed(60_000))
+  })
+
+  it("0h0m0s → reject (all zero)", () => {
+    const result = run("0h0m0s")
+    expect(Exit.isFailure(result)).toBe(true)
+  })
+
+  it("0h0m59s → reject (below floor)", () => {
+    const result = run("0h0m59s")
+    expect(Exit.isFailure(result)).toBe(true)
+  })
+
+  it("huge magnitude → reject (overflow to Infinity)", () => {
+    const result = run(`${"9".repeat(400)}h`)
+    expect(Exit.isFailure(result)).toBe(true)
+  })
+})