typeclaw 0.3.1 → 0.5.0

package/src/cron/consumer.ts

@@ -1,10 +1,14 @@
 import type { AgentSession } from '@/agent'
-import { subscribeProviderErrors } from '@/agent/provider-error'
+import { promptWithFallback, resolveFallbackChain } from '@/agent/model-fallback'
 import type { SessionOrigin } from '@/agent/session-origin'
+import { getConfig } from '@/config'
+import type { KnownModelRef } from '@/config/providers'
 import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
 
-import type { CronJob, ExecJob, PromptJob } from './schema'
+import type { CronJob, ExecJob, HandlerJob, PromptJob } from './schema'
+
+export type CronHandlerInvoker = (job: HandlerJob) => Promise<void>
 
 // `hooks`, `sessionId`, `agentDir`, and `getTranscriptPath` are optional so
 // test fakes can stay one-liners. When present, the consumer fires
@@ -39,7 +43,19 @@ export type CronConsumerLogger = {
 export type CreateCronConsumerOptions = {
   stream: Stream
   cwd: string
-  createSessionForCron: (job: PromptJob) => Promise<CronSession>
+  // The optional `refOverride` argument is consumed by the fallback loop: the
+  // consumer calls this factory once per ref in the profile's chain, pinning
+  // each attempt to the specified model. Factories that don't honor the
+  // override silently lose fallback semantics, so production wiring threads
+  // it through to `createSession({ refOverride })`.
+  createSessionForCron: (job: PromptJob, refOverride?: KnownModelRef) => Promise<CronSession>
+  // Builds the `CronHandlerContext` for the job and awaits its `handler`.
+  // Wired by `src/run/index.ts` to reuse `runPromptForCommand` /
+  // `runExecForCommand` from the command runner so plugin cron handlers and
+  // container plugin commands share one implementation of `ctx.prompt` /
+  // `ctx.exec`. Optional so unit-test fakes that never schedule handler jobs
+  // stay one-liners.
+  invokeHandler?: CronHandlerInvoker
   logger?: CronConsumerLogger
 }
 
@@ -59,6 +75,7 @@ export function createCronConsumer({
   stream,
   cwd,
   createSessionForCron,
+  invokeHandler,
   logger = consoleLogger,
 }: CreateCronConsumerOptions): CronConsumer {
   const inFlight = new Set<string>()
@@ -81,8 +98,15 @@ export function createCronConsumer({
         try {
           if (job.kind === 'prompt') {
             await runPrompt(job, createSessionForCron, stream, logger)
-          } else {
+          } else if (job.kind === 'exec') {
             await runExec(job, cwd)
+          } else {
+            if (invokeHandler === undefined) {
+              throw new Error(
+                `handler job dispatched but no invokeHandler wired into the consumer (likely a misconfigured test or boot path)`,
+              )
+            }
+            await invokeHandler(job)
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err)
@@ -104,7 +128,7 @@ export function createCronConsumer({
 
 async function runPrompt(
   job: PromptJob,
-  createSessionForCron: (job: PromptJob) => Promise<CronSession>,
+  createSessionForCron: (job: PromptJob, refOverride?: KnownModelRef) => Promise<CronSession>,
   stream: Stream,
   logger: CronConsumerLogger,
 ): Promise<void> {
@@ -131,56 +155,157 @@ async function runPrompt(
     })
     return
   }
-  const session = await createSessionForCron(job)
-  const unsubProviderErrors =
-    session.session !== undefined
-      ? subscribeProviderErrors(session.session, (err) => {
-          logger.error(`[cron] ${job.id}: LLM call failed: ${err.message}`)
+  // Resolve the model fallback chain for the cron profile (cron jobs run
+  // under the `default` profile today). Single-ref configs produce a length-1
+  // chain; multi-ref configs (e.g. `"default": ["openai/...", "fireworks/..."]`)
+  // drive the retry-on-failure loop inside `runPromptOnce`.
+  const refs = resolveFallbackChain(getConfig().models, undefined)
+  await runPromptOnce(job, refs, createSessionForCron, logger)
+}
+
+async function runPromptOnce(
+  job: PromptJob,
+  refs: KnownModelRef[],
+  createSessionForCron: (job: PromptJob, refOverride?: KnownModelRef) => Promise<CronSession>,
+  logger: CronConsumerLogger,
+): Promise<void> {
+  // Per-attempt lifecycle: every session we create gets full
+  // turn-start → turn-end → session-end → dispose bracketing, regardless of
+  // whether the helper chose it as the final session or disposed it as a
+  // failed earlier attempt. Without per-attempt session.end, plugin state
+  // keyed by sessionId (security plugin's remote-taint map, memory plugin's
+  // debounce timer) would orphan for every failed attempt. We track the
+  // last session separately so we can fire session.idle exactly once on
+  // success (matching pre-fallback cron behavior — see the pre-fallback
+  // try/finally structure: idle inside the prompt try-block, end in the
+  // outer finally).
+  let lastSession: CronSession | null = null
+  const result = await promptWithFallback({
+    refs,
+    text: job.prompt,
+    createSessionForRef: async (ref) => {
+      const created = await createSessionForCron(job, ref)
+      lastSession = created
+      const turnEvent =
+        created.hooks && created.sessionId !== undefined && created.agentDir !== undefined
+          ? {
+              sessionId: created.sessionId,
+              agentDir: created.agentDir,
+              ...(created.origin !== undefined ? { origin: created.origin } : {}),
+            }
+          : undefined
+      if (created.hooks && turnEvent !== undefined) {
+        await created.hooks.runSessionTurnStart(turnEvent)
+      }
+      // Bridge the CronSession wrapper into the AgentSession surface the
+      // fallback helper expects:
+      //   prompt    → CronSession.prompt (wrapper that calls AgentSession.prompt
+      //               in production, or a hand-rolled test fake)
+      //   subscribe → CronSession.session.subscribe when an underlying agent
+      //               session is supplied, else a no-op (soft-error detection
+      //               degrades to "off" in that mode; only hard throws drive
+      //               fallback). Test fakes that omit `.session` lose
+      //               soft-error fallback — production code always provides it.
+      // .bind(created.session) is load-bearing: AgentSession.subscribe is a
+      // regular method that reads `this._eventListeners`. Destructuring drops
+      // the receiver.
+      const sessionForHelper: AgentSession = {
+        prompt: (text: string) => created.prompt(text),
+        subscribe: created.session?.subscribe.bind(created.session) ?? (() => () => {}),
+      } as unknown as AgentSession
+      return {
+        session: sessionForHelper,
+        // Per-attempt teardown. Fires turn.end and session.end for every
+        // session created (success or failure), then disposes the underlying
+        // resources. Hooks that throw are logged but don't prevent disposal.
+        dispose: async () => {
+          if (created.hooks && turnEvent !== undefined) {
+            try {
+              await created.hooks.runSessionTurnEnd(turnEvent)
+            } catch (e) {
+              logger.warn(`[cron] ${job.id}: turn-end hook threw: ${describe(e)}`)
+            }
+          }
+          if (created.hooks && created.sessionId !== undefined) {
+            try {
+              await created.hooks.runSessionEnd({
+                sessionId: created.sessionId,
+                ...(created.origin !== undefined ? { origin: created.origin } : {}),
+              })
+            } catch (e) {
+              logger.warn(`[cron] ${job.id}: session-end hook threw: ${describe(e)}`)
+            }
+          }
+          created.dispose?.()
+        },
+      }
+    },
+    onAttemptFailed: (attempt) => {
+      logger.warn(
+        `[cron] ${job.id}: ${attempt.outcome} failure on ${attempt.ref}: ${attempt.errorMessage ?? 'unknown'}; falling back`,
+      )
+    },
+  })
+
+  if (!result.success) {
+    logger.error(
+      `[cron] ${job.id}: all ${result.attempts.length} model(s) failed; last error: ${result.lastError?.message ?? 'unknown'}`,
+    )
+  }
+
+  // session.idle fires once, only on success, and only against the session
+  // that handled the turn. Then dispose the successful session (the helper
+  // returns the session+dispose so we can run post-prompt hooks against a
+  // live session before tearing it down). Failed-chain disposal is already
+  // handled by the helper's per-attempt dispose calls.
+  if (result.success && lastSession !== null) {
+    const finalSession: CronSession = lastSession
+    if (finalSession.hooks && finalSession.sessionId !== undefined) {
+      try {
+        await finalSession.hooks.runSessionIdle({
+          sessionId: finalSession.sessionId,
+          parentTranscriptPath: finalSession.getTranscriptPath?.(),
+          idleMs: 0,
+          ...(finalSession.origin !== undefined ? { origin: finalSession.origin } : {}),
         })
-      : null
-  const turnEvent =
-    session.hooks && session.sessionId !== undefined && session.agentDir !== undefined
-      ? {
-          sessionId: session.sessionId,
-          agentDir: session.agentDir,
-          ...(session.origin !== undefined ? { origin: session.origin } : {}),
-        }
-      : undefined
-  try {
-    if (session.hooks && turnEvent !== undefined) {
-      await session.hooks.runSessionTurnStart(turnEvent)
-    }
-    try {
-      await session.prompt(job.prompt)
-    } finally {
-      if (session.hooks && turnEvent !== undefined) {
-        await session.hooks.runSessionTurnEnd(turnEvent)
+      } catch (e) {
+        logger.warn(`[cron] ${job.id}: session-idle hook threw: ${describe(e)}`)
       }
     }
-    if (session.hooks && session.sessionId !== undefined) {
-      await session.hooks.runSessionIdle({
-        sessionId: session.sessionId,
-        parentTranscriptPath: session.getTranscriptPath?.(),
-        idleMs: 0,
-        ...(session.origin !== undefined ? { origin: session.origin } : {}),
-      })
-    }
-  } finally {
-    unsubProviderErrors?.()
-    if (session.hooks && session.sessionId !== undefined) {
-      await session.hooks.runSessionEnd({
-        sessionId: session.sessionId,
-        ...(session.origin !== undefined ? { origin: session.origin } : {}),
-      })
-    }
-    session.dispose?.()
+    await result.dispose()
   }
 }
 
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 async function runExec(job: ExecJob, cwd: string): Promise<void> {
   const [cmd, ...args] = job.command
   if (!cmd) throw new Error(`exec job ${job.id}: empty command`)
-  const proc = Bun.spawn({ cmd: [cmd, ...args], cwd, stdout: 'pipe', stderr: 'pipe' })
+  // Inject TYPECLAW_PARENT_ORIGIN_JSON so a child that proxies into the
+  // agent (typically a `typeclaw <container-cmd>` invocation through the
+  // host CLI's container-command-client) can stamp its session's
+  // spawnedByOrigin with the cron job's provenance. Without this the
+  // proxy would default to a synthetic owner origin and silently elevate
+  // a guest- or member-scheduled cron job to owner.
+  const parentOrigin = {
+    kind: 'cron',
+    jobId: job.id,
+    jobKind: 'exec',
+    ...(job.scheduledByRole !== undefined ? { scheduledByRole: job.scheduledByRole } : {}),
+    ...(job.scheduledByOrigin !== undefined ? { scheduledByOrigin: job.scheduledByOrigin } : {}),
+  }
+  const proc = Bun.spawn({
+    cmd: [cmd, ...args],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    env: {
+      ...process.env,
+      TYPECLAW_PARENT_ORIGIN_JSON: JSON.stringify(parentOrigin),
+    },
+  })
   const code = await proc.exited
   if (code !== 0) {
     const stderr = await new Response(proc.stderr).text()
@@ -190,7 +315,8 @@ async function runExec(job: ExecJob, cwd: string): Promise<void> {
 
 function isCronJob(value: unknown): value is CronJob {
   if (typeof value !== 'object' || value === null) return false
-  const v = value as { id?: unknown; kind?: unknown }
+  const v = value as { id?: unknown; kind?: unknown; handler?: unknown }
   if (typeof v.id !== 'string') return false
-  return v.kind === 'prompt' || v.kind === 'exec'
+  if (v.kind === 'prompt' || v.kind === 'exec') return true
+  return v.kind === 'handler' && typeof v.handler === 'function'
 }

package/src/cron/index.ts

@@ -21,7 +21,15 @@ export {
   type CronConsumerLogger,
   type CronSession,
 } from './consumer'
-export { createScheduler, type JobDiff, type Scheduler, type SchedulerLogger } from './scheduler'
+export {
+  type ComputeNextFireResult,
+  computeNextFire,
+  createScheduler,
+  type JobDiff,
+  type Scheduler,
+  type SchedulerLogger,
+} from './scheduler'
+export { aggregateCronList, type CronListEntry, type CronListSource } from './list'
 export {
   buildCronMigrationCommitMessage,
   cronFileSchema,
@@ -31,7 +39,9 @@ export {
   type CronMigrationResult,
   type CronMigrationStep,
   type ExecJob,
+  type HandlerJob,
   migrateLegacyCronShape,
+  type ParsedCronJob,
   type PromptJob,
 } from './schema'
 
@@ -41,6 +51,12 @@ export type LoadCronResult = { ok: true; file: CronFile | null } | { ok: false;
 
 export type LoadCronOptions = {
   subagents?: SubagentRegistry
+  // When true (the default), legacy-shape migrations are written back
+  // to cron.json on disk and committed by the system-commit helper.
+  // Read-only inspection callers must pass `false` so an unaware
+  // `typeclaw cron list` against a legacy file does not produce a
+  // commit on whatever branch the user happens to be on.
+  persistMigrations?: boolean
 }
 
 export async function loadCron(agentDir: string, options: LoadCronOptions = {}): Promise<LoadCronResult> {
@@ -62,7 +78,8 @@ export async function loadCron(agentDir: string, options: LoadCronOptions = {}):
   }
 
   const migrated = migrateLegacyCronShape(parsed)
-  if (migrated.changed) {
+  const persistMigrations = options.persistMigrations ?? true
+  if (migrated.changed && persistMigrations) {
     await persistMigratedCron(path, migrated.json, agentDir, migrated.applied)
   }
 

package/src/cron/list.ts

@@ -0,0 +1,105 @@
+import type { RegisteredCronJob } from '@/plugin'
+
+import { computeNextFire } from './scheduler'
+import type { CronJob } from './schema'
+
+// `plugin` carries `localId` (the original key on `definePlugin({ cronJobs })`)
+// so callers can render "memory.dreaming" rather than the synthetic
+// `__plugin_memory_dreaming` global id the scheduler uses internally.
+export type CronListSource = { kind: 'user' } | { kind: 'plugin'; pluginName: string; localId: string }
+
+// Display-oriented snapshot of a CronJob, separated from CronJob itself
+// so the WS wire shape stays stable as CronJob accretes runtime-only
+// fields (scheduledByOrigin, future description, etc.).
+export type CronListEntry = {
+  id: string
+  source: CronListSource
+  kind: 'prompt' | 'exec' | 'handler'
+  schedule: string
+  timezone: string | undefined
+  enabled: boolean
+  scheduledByRole: string | undefined
+  // null when cron-parser rejects `schedule` — keeps such rows visible
+  // in the list with the original error preserved in `scheduleError`,
+  // rather than dropping them silently as the scheduler would.
+  nextFireMs: number | null
+  scheduleError: string | undefined
+  prompt: string | undefined
+  subagent: string | undefined
+  command: readonly string[] | undefined
+}
+
+export type AggregateCronListOptions = {
+  userJobs: readonly CronJob[]
+  // Registered entries (not flat CronJob[]) so each row can be attributed
+  // to its plugin + localId without re-parsing the global id.
+  pluginJobs: readonly RegisteredCronJob[]
+  now: number
+}
+
+export function aggregateCronList(opts: AggregateCronListOptions): CronListEntry[] {
+  const entries: CronListEntry[] = []
+  for (const job of opts.userJobs) {
+    entries.push(toEntry(job, { kind: 'user' }, opts.now))
+  }
+  for (const reg of opts.pluginJobs) {
+    entries.push(toEntry(reg.job, { kind: 'plugin', pluginName: reg.pluginName, localId: reg.localId }, opts.now))
+  }
+  // Sort by next-fire time ascending so the soonest-firing job is at the
+  // top. Jobs with a null nextFireMs (parse errors) sort to the bottom
+  // so the human-readable list keeps the actionable rows first. Disabled
+  // jobs still get a nextFireMs computed — they appear in the list with
+  // an "(disabled)" badge but their position reflects when they WOULD
+  // have fired had they been enabled.
+  entries.sort(compareByNextFire)
+  return entries
+}
+
+function toEntry(job: CronJob, source: CronListSource, now: number): CronListEntry {
+  const fire = computeNextFire(job, now)
+  const base = {
+    id: job.id,
+    source,
+    schedule: job.schedule,
+    timezone: job.timezone,
+    enabled: job.enabled,
+    scheduledByRole: job.scheduledByRole,
+    nextFireMs: fire.ok ? fire.nextFire : null,
+    scheduleError: fire.ok ? undefined : fire.reason,
+  } as const
+  if (job.kind === 'prompt') {
+    return {
+      ...base,
+      kind: 'prompt',
+      prompt: job.prompt,
+      subagent: job.subagent,
+      command: undefined,
+    }
+  }
+  if (job.kind === 'exec') {
+    return {
+      ...base,
+      kind: 'exec',
+      prompt: undefined,
+      subagent: undefined,
+      command: job.command,
+    }
+  }
+  // Handler jobs carry a function reference, not a serializable payload.
+  // Surface the row so the list stays complete; leave action fields undefined.
+  return {
+    ...base,
+    kind: 'handler',
+    prompt: undefined,
+    subagent: undefined,
+    command: undefined,
+  }
+}
+
+function compareByNextFire(a: CronListEntry, b: CronListEntry): number {
+  if (a.nextFireMs === null && b.nextFireMs === null) return a.id.localeCompare(b.id)
+  if (a.nextFireMs === null) return 1
+  if (b.nextFireMs === null) return -1
+  if (a.nextFireMs !== b.nextFireMs) return a.nextFireMs - b.nextFireMs
+  return a.id.localeCompare(b.id)
+}

package/src/cron/scheduler.ts

@@ -177,12 +177,21 @@ function jobFingerprint(job: CronJob): string {
 
 function jobPayload(job: CronJob): unknown {
   if (job.kind === 'prompt') return { prompt: job.prompt, subagent: job.subagent ?? null, payload: job.payload ?? null }
-  return job.command
+  if (job.kind === 'exec') return job.command
+  // Use the handler's source as the discriminator. A constant placeholder
+  // would make every handler fingerprint identically, so a plugin reload
+  // that replaces the handler with a new implementation would be classified
+  // as `unchanged` by `diff()` — the old function reference would keep
+  // firing forever. `Function.prototype.toString()` returns the function's
+  // declared source (deterministic per declaration site, changes when the
+  // plugin module is re-imported with edits), which is the cheapest stable
+  // discriminator without keeping a separate identity Map. JSON-safe.
+  return { handler: String(job.handler) }
 }
 
-type ComputeNextFireResult = { ok: true; nextFire: number } | { ok: false; reason: string }
+export type ComputeNextFireResult = { ok: true; nextFire: number } | { ok: false; reason: string }
 
-function computeNextFire(job: CronJob, now: number): ComputeNextFireResult {
+export function computeNextFire(job: CronJob, now: number): ComputeNextFireResult {
   try {
     const expr = CronExpressionParser.parse(job.schedule, {
       currentDate: new Date(now),

package/src/cron/schema.ts

@@ -3,6 +3,7 @@ import { z } from 'zod'
 
 import type { SubagentRegistry } from '@/agent/subagents'
 import { validateSubagentPayload } from '@/agent/subagents'
+import type { CronHandlerContext } from '@/plugin/types'
 
 const idPattern = /^[a-zA-Z0-9_-]+$/
 
@@ -42,9 +43,16 @@ export const cronFileSchema = z.object({
   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 ParsedCronJob = z.infer<typeof cronJobSchema>
+export type PromptJob = Extract<ParsedCronJob, { kind: 'prompt' }>
+export type ExecJob = Extract<ParsedCronJob, { kind: 'exec' }>
+
+export type HandlerJob = z.infer<typeof baseJob> & {
+  kind: 'handler'
+  handler: (ctx: CronHandlerContext) => Promise<void>
+}
+
+export type CronJob = ParsedCronJob | HandlerJob
 export type CronFile = z.infer<typeof cronFileSchema>
 
 export type ParseCronResult = { ok: true; file: CronFile } | { ok: false; reason: string }

package/src/doctor/checks.ts

@@ -35,7 +35,6 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     agentFolderNodeModules(),
     agentFolderGitRepo(),
     configValid(),
-    configBundledProfiles(),
     hostdHomeWritable(),
     hostdReachable(),
     hostdRegistration(),
@@ -215,55 +214,6 @@ function configValid(): DoctorCheck {
   }
 }
 
-// Warns (not errors) when a model profile that a bundled subagent prefers is
-// absent from `models`. Bundled subagents fall back to `default` silently
-// today, but the operator likely declared a `fast`/`deep`/`vision` model in
-// the design discussion's tier scheme expecting the bundled subagents to
-// pick them up. This check surfaces the gap once at `typeclaw doctor` time
-// instead of leaving it buried in container logs (where the rate-limited
-// fallback warning lives).
-//
-// We deliberately limit this to known bundled profiles (memory-logger=fast,
-// dreaming=deep, multimodal-looker=vision). Plugin-contributed subagents
-// would require loading the plugin registry — a heavyweight async path
-// that doesn't belong in doctor's static check surface.
-const BUNDLED_PROFILES: ReadonlyArray<{ profile: string; subagent: string }> = [
-  { profile: 'fast', subagent: 'memory-logger' },
-  { profile: 'deep', subagent: 'dreaming' },
-  { profile: 'vision', subagent: 'multimodal-looker (via look_at tool)' },
-]
-
-function configBundledProfiles(): DoctorCheck {
-  return {
-    name: 'config.bundled-profiles',
-    category: 'config',
-    description: 'bundled subagent profiles (`fast`, `deep`, `vision`) declared in models',
-    applies: (ctx) => ctx.hasAgentFolder,
-    async run(ctx) {
-      const validation = validateConfig(ctx.cwd)
-      if (!validation.ok) {
-        return { status: 'ok', message: 'skipped (config.valid will report the underlying error)' }
-      }
-      const config = loadConfigSync(ctx.cwd)
-      const declared = new Set(Object.keys(config.models))
-      const missing = BUNDLED_PROFILES.filter((p) => !declared.has(p.profile))
-      if (missing.length === 0) {
-        return { status: 'ok', message: 'all bundled subagent profiles declared' }
-      }
-      return {
-        status: 'warning',
-        message: `${missing.length} bundled profile(s) missing; will fall back to \`default\``,
-        details: missing.map(
-          (m) => `${m.profile}: used by ${m.subagent}; declare \`models.${m.profile}\` in typeclaw.json to override`,
-        ),
-        fix: {
-          description: 'Add the missing profile(s) under `models` in typeclaw.json. See the typeclaw-config skill.',
-        },
-      }
-    },
-  }
-}
-
 function hostdHomeWritable(): DoctorCheck {
   return {
     name: 'hostd.home-writable',