typeclaw 0.1.0

package/src/cron/scheduler.ts

@@ -0,0 +1,200 @@
+import { CronExpressionParser } from 'cron-parser'
+
+import type { CronJob } from './schema'
+
+export type SchedulerClock = {
+  now: () => number
+  setTimeout: (cb: () => void, ms: number) => number
+  clearTimeout: (handle: number) => void
+}
+
+export type SchedulerLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type CreateSchedulerOptions = {
+  jobs: CronJob[]
+  onFire: (job: CronJob) => void
+  clock?: SchedulerClock
+  logger?: SchedulerLogger
+}
+
+export type JobDiff = {
+  added: CronJob[]
+  removed: CronJob[]
+  updated: CronJob[]
+  unchanged: CronJob[]
+}
+
+export type Scheduler = {
+  start: () => void
+  stop: () => void
+  replaceJobs: (jobs: CronJob[]) => JobDiff
+}
+
+const realClock: SchedulerClock = {
+  now: () => Date.now(),
+  setTimeout: (cb, ms) => setTimeout(cb, ms) as unknown as number,
+  clearTimeout: (handle) => clearTimeout(handle as unknown as ReturnType<typeof setTimeout>),
+}
+
+const consoleLogger: SchedulerLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export function createScheduler({
+  jobs,
+  onFire,
+  clock = realClock,
+  logger = consoleLogger,
+}: CreateSchedulerOptions): Scheduler {
+  const registry = new Map<string, CronJob>()
+  for (const job of jobs) registry.set(job.id, job)
+
+  const handles = new Map<string, number>()
+  let started = false
+
+  function currentEnabled(id: string): CronJob | null {
+    const job = registry.get(id)
+    if (!job || !job.enabled) return null
+    return job
+  }
+
+  function scheduleNext(id: string): void {
+    if (!started) return
+    const job = currentEnabled(id)
+    if (!job) return
+
+    const result = computeNextFire(job, clock.now())
+    if (!result.ok) {
+      logger.warn(`[cron] ${id} not scheduled: invalid schedule "${job.schedule}"${tzSuffix(job)}: ${result.reason}`)
+      return
+    }
+
+    cancel(id)
+
+    const delay = Math.max(0, result.nextFire - clock.now())
+    const handle = clock.setTimeout(() => {
+      handles.delete(id)
+      if (!started) return
+      const live = currentEnabled(id)
+      if (!live) return
+      fire(live)
+      scheduleNext(id)
+    }, delay)
+    handles.set(id, handle)
+  }
+
+  function fire(job: CronJob): void {
+    logger.info(`[cron] firing ${job.kind} ${job.id}`)
+    try {
+      onFire(job)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      logger.error(`[cron] ${job.id} onFire threw synchronously: ${message}`)
+    }
+  }
+
+  function cancel(id: string): void {
+    const handle = handles.get(id)
+    if (handle === undefined) return
+    clock.clearTimeout(handle)
+    handles.delete(id)
+  }
+
+  function diff(next: CronJob[]): JobDiff {
+    const added: CronJob[] = []
+    const removed: CronJob[] = []
+    const updated: CronJob[] = []
+    const unchanged: CronJob[] = []
+
+    const nextById = new Map<string, CronJob>()
+    for (const job of next) nextById.set(job.id, job)
+
+    for (const [id, before] of registry) {
+      const after = nextById.get(id)
+      if (!after) {
+        removed.push(before)
+        continue
+      }
+      if (jobFingerprint(before) === jobFingerprint(after)) {
+        unchanged.push(after)
+      } else {
+        updated.push(after)
+      }
+    }
+    for (const [id, after] of nextById) {
+      if (!registry.has(id)) added.push(after)
+    }
+
+    return { added, removed, updated, unchanged }
+  }
+
+  return {
+    start() {
+      if (started) return
+      started = true
+      for (const id of registry.keys()) scheduleNext(id)
+    },
+    stop() {
+      started = false
+      for (const handle of handles.values()) clock.clearTimeout(handle)
+      handles.clear()
+    },
+    replaceJobs(next) {
+      const result = diff(next)
+
+      const newRegistry = new Map<string, CronJob>()
+      for (const job of next) newRegistry.set(job.id, job)
+      registry.clear()
+      for (const [id, job] of newRegistry) registry.set(id, job)
+
+      for (const job of result.removed) cancel(job.id)
+      for (const job of result.updated) {
+        cancel(job.id)
+        scheduleNext(job.id)
+      }
+      for (const job of result.added) scheduleNext(job.id)
+
+      return result
+    },
+  }
+}
+
+function jobFingerprint(job: CronJob): string {
+  return JSON.stringify({
+    schedule: job.schedule,
+    enabled: job.enabled,
+    timezone: job.timezone ?? null,
+    kind: job.kind,
+    payload: jobPayload(job),
+  })
+}
+
+function jobPayload(job: CronJob): unknown {
+  if (job.kind === 'prompt') return { prompt: job.prompt, subagent: job.subagent ?? null, payload: job.payload ?? null }
+  return job.command
+}
+
+type ComputeNextFireResult = { ok: true; nextFire: number } | { ok: false; reason: string }
+
+function computeNextFire(job: CronJob, now: number): ComputeNextFireResult {
+  try {
+    const expr = CronExpressionParser.parse(job.schedule, {
+      currentDate: new Date(now),
+      ...(job.timezone ? { tz: job.timezone } : {}),
+    })
+    return { ok: true, nextFire: expr.next().getTime() }
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    return { ok: false, reason }
+  }
+}
+
+function tzSuffix(job: CronJob): string {
+  return job.timezone ? ` (timezone "${job.timezone}")` : ''
+}

package/src/cron/schema.ts

@@ -0,0 +1,96 @@
+import { CronExpressionParser } from 'cron-parser'
+import { z } from 'zod'
+
+import type { SubagentRegistry } from '@/agent/subagents'
+import { validateSubagentPayload } from '@/agent/subagents'
+
+const idPattern = /^[a-zA-Z0-9_-]+$/
+
+const baseJob = z.object({
+  id: z.string().min(1).regex(idPattern, 'id must contain only letters, digits, hyphens, or underscores'),
+  schedule: z.string().min(1),
+  enabled: z.boolean().default(true),
+  timezone: z.string().optional(),
+})
+
+const promptJob = baseJob.extend({
+  kind: z.literal('prompt'),
+  prompt: z.string().min(1),
+  subagent: z.string().min(1).optional(),
+  payload: z.unknown().optional(),
+})
+
+const execJob = baseJob.extend({
+  kind: z.literal('exec'),
+  command: z.array(z.string().min(1)).min(1),
+})
+
+export const cronJobSchema = z.discriminatedUnion('kind', [promptJob, execJob])
+
+export const cronFileSchema = z.object({
+  $schema: z.string().optional(),
+  jobs: z.array(cronJobSchema).default([]),
+})
+
+export type CronJob = z.infer<typeof cronJobSchema>
+export type PromptJob = Extract<CronJob, { kind: 'prompt' }>
+export type ExecJob = Extract<CronJob, { kind: 'exec' }>
+export type CronFile = z.infer<typeof cronFileSchema>
+
+export type ParseCronResult = { ok: true; file: CronFile } | { ok: false; reason: string }
+
+export type ParseCronOptions = {
+  // When provided, prompt jobs with a `subagent` field are validated against
+  // the registry: the name must exist, and the optional `payload` must match
+  // the registered subagent's payloadSchema (or be absent if no schema).
+  subagents?: SubagentRegistry
+}
+
+export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {
+  const parsed = cronFileSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, reason: parsed.error.issues.map(formatIssue).join('; ') }
+  }
+
+  const file = parsed.data
+  const seen = new Set<string>()
+  for (const job of file.jobs) {
+    if (seen.has(job.id)) {
+      return { ok: false, reason: `duplicate job id: ${job.id}` }
+    }
+    seen.add(job.id)
+
+    try {
+      const expr = CronExpressionParser.parse(job.schedule, job.timezone ? { tz: job.timezone } : undefined)
+      // cron-parser validates the timezone lazily on first next() call, not at
+      // parse time, so we must force evaluation here to catch bogus zones.
+      expr.next()
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      if (job.timezone && /invalid|unhandled timestamp|unrecognized/i.test(message)) {
+        return { ok: false, reason: `job ${job.id}: invalid timezone "${job.timezone}": ${message}` }
+      }
+      return { ok: false, reason: `job ${job.id}: invalid schedule "${job.schedule}": ${message}` }
+    }
+
+    if (job.kind === 'prompt' && job.subagent !== undefined && options.subagents !== undefined) {
+      const subagent = options.subagents[job.subagent]
+      if (!subagent) {
+        return { ok: false, reason: `job ${job.id}: unknown subagent "${job.subagent}"` }
+      }
+      try {
+        validateSubagentPayload(job.subagent, subagent, job.payload)
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        return { ok: false, reason: `job ${job.id}: ${message}` }
+      }
+    }
+  }
+
+  return { ok: true, file }
+}
+
+function formatIssue(issue: { path: PropertyKey[]; message: string }): string {
+  const path = issue.path.length > 0 ? issue.path.map(String).join('.') : '<root>'
+  return `${path}: ${issue.message}`
+}

package/src/hostd/client.ts

@@ -0,0 +1,113 @@
+import { existsSync } from 'node:fs'
+
+import type { Socket } from 'bun'
+
+import { socketPath } from './paths'
+import type { Request, Response } from './protocol'
+
+const DEFAULT_TIMEOUT_MS = 3_000
+
+export async function isDaemonReachable(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<boolean> {
+  if (!existsSync(socketPath())) return false
+  try {
+    const reply = await send({ kind: 'list' }, { timeoutMs })
+    return reply.ok
+  } catch {
+    return false
+  }
+}
+
+export type SendOptions = {
+  timeoutMs?: number
+  socket?: string
+}
+
+export type SendHttpOptions = {
+  timeoutMs?: number
+  url: string
+  token: string
+}
+
+export async function sendHttp(req: Request, opts: SendHttpOptions): Promise<Response> {
+  const controller = new AbortController()
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetch(new URL('/rpc', opts.url), {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${opts.token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(req),
+      signal: controller.signal,
+    })
+    const parsed = (await res.json()) as Response
+    return parsed
+  } catch (error) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+      return { ok: false, reason: `daemon ack timeout after ${timeoutMs}ms` }
+    }
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export async function send(req: Request, opts: SendOptions = {}): Promise<Response> {
+  const path = opts.socket ?? socketPath()
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  type State = { buf: string; resolve: (r: Response) => void }
+  const state: State = {
+    buf: '',
+    resolve: () => {},
+  }
+
+  const replyPromise = new Promise<Response>((resolve) => {
+    state.resolve = resolve
+  })
+
+  let sock: Socket<State>
+  try {
+    sock = await Bun.connect<State>({
+      unix: path,
+      socket: {
+        data: (s, chunk) => {
+          s.data.buf += chunk.toString('utf8')
+          const newline = s.data.buf.indexOf('\n')
+          if (newline < 0) return
+          const line = s.data.buf.slice(0, newline)
+          try {
+            const parsed = JSON.parse(line) as Response
+            s.data.resolve(parsed)
+          } catch {
+            s.data.resolve({ ok: false, reason: 'invalid response from daemon' })
+          }
+          s.end()
+        },
+        close: () => {},
+        error: () => {
+          state.resolve({ ok: false, reason: 'socket error' })
+        },
+      },
+    })
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+  sock.data = state
+  sock.write(`${JSON.stringify(req)}\n`)
+
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const timeoutPromise = new Promise<Response>((resolve) => {
+    timer = setTimeout(() => resolve({ ok: false, reason: `daemon ack timeout after ${timeoutMs}ms` }), timeoutMs)
+  })
+  try {
+    return await Promise.race([replyPromise, timeoutPromise])
+  } finally {
+    if (timer) clearTimeout(timer)
+    try {
+      sock.end()
+    } catch {}
+  }
+}