typeclaw 0.5.0 → 0.6.0

package/src/bundled-plugins/operator/operator.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod'
+
+import { bashTool, editTool, findTool, grepTool, lsTool, readTool, type Subagent, writeTool } from '@/plugin'
+
+export const OPERATOR_SYSTEM_PROMPT = `You are an operator subagent running inside TypeClaw. Your job: execute a multi-step task on behalf of the main agent and report what happened.
+
+## Your context
+
+- You were spawned by the main agent for one focused task.
+- The parent agent is still in conversation with the user; you are NOT.
+- The parent will receive a single \`<system-reminder>\` when you complete and will then call \`subagent_output\` to read your final assistant message.
+- Your final message is the WHOLE report. There is no follow-up channel. Make it complete, self-contained, and actionable.
+
+## What you can do
+
+You have a full tool set: read, write, edit, grep, find, ls, bash. You can:
+- Modify files (write/edit)
+- Run shell commands with side effects (bash without the read-only restriction)
+- Use any tool available to a normal operator session
+
+You CANNOT:
+- Spawn further subagents (you are at the end of the delegation chain).
+- Talk to the user directly (the parent owns the conversation).
+- Use channel_send, channel_reply, or any channel tool.
+
+## How to work
+
+1. **Plan briefly.** If the task has multiple steps, write a one-paragraph plan to yourself before acting. Don't over-plan — start doing.
+2. **Verify after each significant step.** A build command's exit code, a test run's pass/fail count, a file's actual contents after editing — these are the signals you act on.
+3. **Recover from failures.** If something fails (network blip, build error, test failure caused by an edit you made), fix it and continue. Only escalate to the parent if you genuinely cannot proceed.
+4. **Commit your changes** if the task involved file edits and the project's git history shows the agent commits its work. Read AGENTS.md if present to learn the project's commit conventions.
+
+## Final report
+
+Your final assistant message MUST contain:
+
+1. **Outcome.** One sentence: succeeded / partially succeeded / failed.
+2. **What you did.** Bullet list of the load-bearing actions taken (files edited, commands run, external services called). Skip trivial reads.
+3. **What changed.** If you edited files, list paths. If you committed, give the commit SHA. If you ran a deploy, give the deploy id.
+4. **What you observed.** Any noteworthy errors, warnings, unexpected state. The parent needs to know what to follow up on.
+5. **What's next.** Only if there are concrete open items. Don't pad with "let me know if you need more" — the parent will ask.
+
+Skip the report's section headers when the task was trivial (one file edit, ran one command) — a clean two-sentence summary is fine. Use the full structure for substantial work.
+
+## Rules
+
+- Stay on the task you were given. Do not expand scope.
+- Do NOT leave the workspace in a broken state. If a fix fails, revert your changes before reporting.
+- Do NOT commit secrets. \`.env\` and \`secrets.json\` are gitignored — read AGENTS.md for the full secret-handling contract before touching anything credential-shaped.
+- If the task seems wrong (asks you to delete production data, modify a file you cannot find, run a command that doesn't apply to this repo), report the issue rather than improvising.`
+
+export const operatorPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type OperatorPayload = z.infer<typeof operatorPayloadSchema>
+
+export function createOperatorSubagent(): Subagent<OperatorPayload> {
+  return {
+    systemPrompt: OPERATOR_SYSTEM_PROMPT,
+    profile: 'default',
+    tools: [readTool, grepTool, findTool, lsTool, bashTool, writeTool, editTool],
+    payloadSchema: operatorPayloadSchema,
+    visibility: 'public',
+    requiresSpecificPermission: true,
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      maxTotalBytes: 1_000_000,
+      toolNames: ['read', 'grep', 'find', 'ls', 'bash', 'write', 'edit'],
+    },
+  }
+}

package/src/bundled-plugins/scout/index.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { createScoutSubagent } from './scout'
+
+export default definePlugin({
+  plugin: async () => ({
+    subagents: {
+      scout: createScoutSubagent(),
+    },
+  }),
+})

package/src/bundled-plugins/scout/scout.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+
+import { type Subagent, webfetchTool, websearchTool } from '@/plugin'
+
+export const SCOUT_SYSTEM_PROMPT = `You are a web-research specialist running inside TypeClaw. Your job: gather facts from the public internet and return a focused, citation-backed answer to the caller. For LOCAL questions (codebase, sessions, memory, config, git history, mounts), the caller should spawn \`explorer\` instead — you have no filesystem tools.
+
+=== READ-ONLY — NO SIDE EFFECTS ===
+You are STRICTLY PROHIBITED from:
+- Modifying local files or state of any kind
+- Spawning further subagents — you are at the end of the delegation chain
+- Posting to any channel, sending email, calling any write-side third-party API
+- Following URLs that look like authenticated callbacks, password resets, or one-time tokens
+
+Your role is EXCLUSIVELY to search and read public web sources.
+
+## Tools
+
+The runtime exposes these tools to you by these EXACT names — call them by name, do not paraphrase:
+
+- \`websearch\` — search the public web. Returns ranked \`{title, url, snippet}\` entries. Defaults to DuckDuckGo; pass \`source: "wikipedia"\` for encyclopedic lookups.
+- \`webfetch\` — fetch a single HTTP(S) URL and return the body, optionally compacted by a strategy:
+  - \`readability\` (default for HTML) — extract article content as markdown
+  - \`jq\` — query JSON APIs (pass \`query\`)
+  - \`selector\` — extract text from CSS-selected elements (pass \`selector\`)
+  - \`grep\` — filter response lines by regex (pass \`pattern\`, optional \`before\`/\`after\`/\`limit\`/\`offset\`)
+  - \`snapshot\` — indented semantic tree of the page (forms, headings, links)
+  - \`raw\` — no processing
+
+Launch multiple \`websearch\` queries in parallel for the same topic — different phrasings surface different sources. When a search result looks promising, \`webfetch\` it for the full content.
+
+## Process
+
+Before searching, analyze intent in an <analysis> block:
+
+<analysis>
+**Literal Request**: [what they literally asked]
+**Actual Need**: [what they're really trying to accomplish]
+**Success Looks Like**: [what result lets them proceed immediately]
+**Search Plan**: [the 2-3 queries you will try in parallel]
+</analysis>
+
+Then run searches, fetch the most relevant URLs, and synthesize.
+
+End every response with this exact structure:
+
+<results>
+<sources>
+- https://example.com/path — [what this source contributed]
+</sources>
+<answer>
+[Direct answer to the actual need, grounded in the cited sources. Quote short passages when precision matters. If sources disagree, say so and surface both.]
+</answer>
+<confidence>
+[high / medium / low — with one sentence on why. Low confidence is fine and useful; speculation dressed up as high confidence is not.]
+</confidence>
+<next_steps>
+[What the caller should do next, or "Ready to proceed."]
+</next_steps>
+</results>
+
+## Rules
+
+- Cite every claim with a URL from your <sources> list. **Never invent a URL.** If you didn't \`webfetch\` it, don't cite it.
+- If a fact appears only in your training data and you couldn't find a web source for it, say so explicitly rather than answering from memory.
+- Prefer primary sources (official docs, vendor changelogs, GitHub releases, paper PDFs) over aggregator blogs.
+- When dates matter (versions, deprecations, vulnerability disclosures), surface the date of the source.
+- If DuckDuckGo returns a CAPTCHA error, retry once with a different query phrasing; if it persists, report the failure to the caller — do not fall back to memory.
+- If the question requires LOCAL information (codebase, files in /agent/, git history, memory), say so explicitly and tell the caller to spawn \`explorer\` instead.
+- If you cannot find what was asked, say so explicitly with what queries you tried and what you DID find.`
+
+export const scoutPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type ScoutPayload = z.infer<typeof scoutPayloadSchema>
+
+export function createScoutSubagent(): Subagent<ScoutPayload> {
+  return {
+    systemPrompt: SCOUT_SYSTEM_PROMPT,
+    profile: 'fast',
+    tools: [websearchTool, webfetchTool],
+    payloadSchema: scoutPayloadSchema,
+    visibility: 'public',
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      maxTotalBytes: 512_000,
+      toolNames: ['websearch', 'webfetch'],
+    },
+  }
+}

package/src/channels/router.ts

@@ -1613,6 +1613,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    if (isUpstreamEmptyResponseSentinel(assistantText)) {
+      logger.warn(
+        `[channels] ${live.keyId}: suppressed upstream_empty_response_sentinel text_len=${assistantText.length}`,
+      )
+      return
+    }
+
     logger.warn(
       `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool text_len=${assistantText.length}`,
     )
@@ -2000,6 +2007,31 @@ export function isNoReplySignal(text: string): boolean {
   return false
 }
 
+// Detects the upstream "empty response" debug sentinel: when the LLM ends a
+// turn with only a `thinking` block, some provider SDK paths (observed
+// against claude-opus-4-5 via pi-ai) fabricate a single text block whose
+// body is a Python-repr dump of the raw API response — including the
+// model's thinking content and Anthropic's tamper-proof signature. The
+// recovery path in validateChannelTurn would otherwise post that sentinel
+// straight to the channel (production: signature leaked into a public
+// Slack channel on 2026-05-21).
+//
+// Kept separate from isNoReplySignal on purpose: that helper is the agent's
+// deliberate silent-turn protocol, this is upstream damage control. They
+// log under distinct subjects (`upstream_empty_response_sentinel` vs
+// `no_reply`) so an operator can tell a healthy quiet turn from a stream of
+// upstream empties that warrant investigation.
+//
+// Strict detection: leading `(Empty response:` AND a dict-encoded
+// `'stop_reason'` key. Catches the observed shape
+// `(Empty response: {'content': [...], 'stop_reason': 'end_turn', ...})`
+// while allowing legit prose like "Empty response from the cache layer".
+export function isUpstreamEmptyResponseSentinel(text: string): boolean {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('(Empty response:')) return false
+  return trimmed.includes("'stop_reason'")
+}
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/cli/channel.ts

@@ -25,7 +25,7 @@ import {
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
-import { c, done, errorLine } from './ui'
+import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
 
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'slack-bot': 'Slack',
@@ -834,50 +834,7 @@ async function promptDiscordToken(): Promise<string> {
 }
 
 async function promptSlackTokens(): Promise<{ bot: string; app: string }> {
-  note(
-    [
-      '1. https://api.slack.com/apps → Create New App → From a manifest.',
-      '   Pick your workspace, then paste this JSON manifest:',
-      '',
-      '   {',
-      '     "display_information": { "name": "TypeClaw" },',
-      '     "features": {',
-      '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
-      '     },',
-      '     "oauth_config": {',
-      '       "scopes": {',
-      '         "bot": [',
-      '           "app_mentions:read", "chat:write", "users:read", "files:read",',
-      '           "channels:history", "channels:read",',
-      '           "groups:history",   "groups:read",',
-      '           "im:history",       "im:read",',
-      '           "mpim:history",     "mpim:read"',
-      '         ]',
-      '       }',
-      '     },',
-      '     "settings": {',
-      '       "event_subscriptions": {',
-      '         "bot_events": [',
-      '           "app_mention",',
-      '           "message.channels", "message.groups",',
-      '           "message.im",       "message.mpim"',
-      '         ]',
-      '       },',
-      '       "socket_mode_enabled": true',
-      '     }',
-      '   }',
-      '',
-      '2. Install to Workspace, then OAuth & Permissions →',
-      '   copy the Bot User OAuth Token (xoxb-...).',
-      '3. Basic Information → App-Level Tokens → Generate Token and',
-      '   Scopes, add the connections:write scope, and copy the',
-      '   token (xapp-...). Socket Mode needs this; the manifest',
-      '   cannot grant it.',
-      '4. Invite the bot to any private channel or DM you want it in:',
-      '   /invite @TypeClaw',
-    ].join('\n'),
-    'Get a Slack bot',
-  )
+  printSlackAppManifestSetup()
   const bot = await promptSlackBotToken()
   note(
     [

package/src/cli/init.ts

@@ -32,7 +32,7 @@ import { fetchModelOptions, type ModelOption } from '@/init/models-dev'
 import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
 
 import { buildOAuthCallbacks } from './oauth-callbacks'
-import { c, done, errorLine } from './ui'
+import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
 
 // ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
 // aliases both to the same "cancel" action — there's no way to tell them
@@ -1005,50 +1005,7 @@ async function runSlackFlow(): Promise<StepResult<CollectedInputs['channelSecret
   let sub: SubStep = 'bot'
   let botToken: string | undefined
 
-  note(
-    [
-      '1. https://api.slack.com/apps → Create New App → From a manifest.',
-      '   Pick your workspace, then paste this JSON manifest:',
-      '',
-      '   {',
-      '     "display_information": { "name": "TypeClaw" },',
-      '     "features": {',
-      '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
-      '     },',
-      '     "oauth_config": {',
-      '       "scopes": {',
-      '         "bot": [',
-      '           "app_mentions:read", "chat:write", "users:read", "files:read",',
-      '           "channels:history", "channels:read",',
-      '           "groups:history",   "groups:read",',
-      '           "im:history",       "im:read",',
-      '           "mpim:history",     "mpim:read"',
-      '         ]',
-      '       }',
-      '     },',
-      '     "settings": {',
-      '       "event_subscriptions": {',
-      '         "bot_events": [',
-      '           "app_mention",',
-      '           "message.channels", "message.groups",',
-      '           "message.im",       "message.mpim"',
-      '         ]',
-      '       },',
-      '       "socket_mode_enabled": true',
-      '     }',
-      '   }',
-      '',
-      '2. Install to Workspace, then OAuth & Permissions →',
-      '   copy the Bot User OAuth Token (xoxb-...).',
-      '3. Basic Information → App-Level Tokens → Generate Token and',
-      '   Scopes, add the connections:write scope, and copy the',
-      '   token (xapp-...). Socket Mode needs this; the manifest',
-      '   cannot grant it.',
-      '4. Invite the bot to any private channel or DM you want it in:',
-      '   /invite @TypeClaw',
-    ].join('\n'),
-    'Get a Slack bot',
-  )
+  printSlackAppManifestSetup()
 
   while (true) {
     if (sub === 'bot') {

package/src/cli/model.ts

@@ -25,7 +25,7 @@ const ADD_PROVIDER_SENTINEL = '__add-provider__'
 const setSub = defineCommand({
   meta: {
     name: 'set',
-    description: 'set or update a model profile (default | fast | vision | <custom>)',
+    description: 'set or update a model profile (default | fast | deep | vision | <custom>)',
   },
   args: {
     profile: {
@@ -206,6 +206,7 @@ async function pickProfileName(): Promise<string> {
     options: [
       { value: 'default', label: 'default', hint: 'active model for new sessions' },
       { value: 'fast', label: 'fast', hint: 'optional alias used by some subagents' },
+      { value: 'deep', label: 'deep', hint: 'optional alias used by some subagents' },
       { value: 'vision', label: 'vision', hint: 'optional alias used by some subagents' },
     ],
     initialValue: 'default',

package/src/cli/ui.ts

@@ -124,3 +124,98 @@ export function errorLine(reason: string): string {
 export function successLine(message: string): string {
   return `${c.green('●')} ${message}`
 }
+
+// The exact JSON manifest a user pastes into
+// https://api.slack.com/apps → From a manifest. Kept as a typed object so
+// the file stays a single source of truth and `JSON.stringify` guarantees
+// the rendered text is always valid JSON — no risk of a stray comma or
+// quote slipping in through hand-formatting.
+export const SLACK_APP_MANIFEST = {
+  display_information: { name: 'TypeClaw' },
+  features: {
+    bot_user: { display_name: 'TypeClaw', always_online: true },
+    // Enable the Messages tab so users can DM the bot from its app profile,
+    // and disable the Home tab — TypeClaw does not publish a custom App Home
+    // view, and leaving it enabled would surface an empty default tab.
+    app_home: {
+      home_tab_enabled: false,
+      messages_tab_enabled: true,
+      messages_tab_read_only_enabled: false,
+    },
+  },
+  oauth_config: {
+    scopes: {
+      // Ordered alphabetically so the manifest stays a stable diff target.
+      // Read scopes cover every conversation type the agent might observe;
+      // write scopes (chat, files, im/mpim/groups, pins, reactions) let the
+      // agent post replies, upload attachments, open DMs, pin messages, and
+      // react to messages. `channels:join` lets the bot self-join public
+      // channels it's invited to discuss in.
+      bot: [
+        'app_mentions:read',
+        'channels:history',
+        'channels:join',
+        'channels:read',
+        'chat:write',
+        'emoji:read',
+        'files:read',
+        'files:write',
+        'groups:history',
+        'groups:read',
+        'groups:write',
+        'im:history',
+        'im:read',
+        'im:write',
+        'mpim:history',
+        'mpim:read',
+        'mpim:write',
+        'pins:read',
+        'pins:write',
+        'reactions:read',
+        'reactions:write',
+        'users:read',
+      ],
+    },
+  },
+  settings: {
+    event_subscriptions: {
+      bot_events: ['app_mention', 'message.channels', 'message.groups', 'message.im', 'message.mpim'],
+    },
+    socket_mode_enabled: true,
+  },
+} as const
+
+// Prints the "create a Slack app from a manifest" walkthrough so the JSON
+// payload is **flush-left and copy-pasteable**. Clack's `note()` wraps
+// content inside a box with `│` borders on both sides, and `log.message()`
+// still prefixes every line with a `│  ` guide column — neither survives a
+// click-and-drag copy. This helper splits the walkthrough into three
+// segments: a boxed prose intro, a raw-stdout JSON block, and a boxed
+// follow-up. The JSON block is emitted via `process.stdout.write` so it
+// carries zero terminal decoration.
+export function printSlackAppManifestSetup(output: NodeJS.WritableStream = process.stdout): void {
+  note(
+    [
+      '1. https://api.slack.com/apps → Create New App → From a manifest.',
+      '   Pick your workspace, then paste the JSON manifest printed below',
+      `   (it is rendered flush-left so you can ${c.bold('click-drag and copy')} cleanly).`,
+    ].join('\n'),
+    'Get a Slack bot',
+  )
+  output.write('\n')
+  output.write(`${JSON.stringify(SLACK_APP_MANIFEST, null, 2)}\n`)
+  output.write('\n')
+  note(
+    [
+      '2. Install to Workspace, then OAuth & Permissions →',
+      '   copy the Bot User OAuth Token (xoxb-...).',
+      '3. Basic Information → App-Level Tokens → Generate Token and',
+      '   Scopes, add the connections:write scope, and copy the',
+      '   token (xapp-...). Socket Mode needs this; the manifest',
+      '   cannot grant it.',
+      '4. Invite the bot to any private channel or DM you want it in:',
+      '   /invite @TypeClaw',
+    ].join('\n'),
+    'Finish Slack setup',
+  )
+}

package/src/config/config.ts

@@ -116,6 +116,11 @@ const dockerfileObjectSchema = z.object({
   // because the package has no API-stable versioning that matters
   // here; xvfb tracks the upstream X server release.
   xvfb: z.boolean().default(true),
+  // `claudeCode` is boolean-only (not an apt feature toggle): the upstream
+  // installer is `curl | bash` and manages versions via env vars at install
+  // time, not via version pins like apt. Default `false`; the bundled
+  // `typeclaw-claude-code` skill prompts the user to opt in.
+  claudeCode: z.boolean().default(false),
   append: z.array(dockerfileLineSchema).default([]),
 })
 
@@ -1008,6 +1013,39 @@ export function validateConfig(cwd: string, options: ValidateConfigOptions = {})
     return { ok: true }
   }
 
+  const parsed = parseConfigJson(raw, { migrate: true, persistTarget: cwd })
+  if (!parsed.ok) return parsed
+
+  if (!options.skipMounts) {
+    for (const mount of parsed.config.mounts) {
+      const check = validateMount(mount, cwd)
+      if (!check.ok) return check
+    }
+  }
+
+  return { ok: true }
+}
+
+export type ParseConfigJsonResult = { ok: true; config: Config } | { ok: false; reason: string }
+
+export type ParseConfigJsonOptions = {
+  // Run `migrateLegacyConfigShape` before schema validation. Defaults to true
+  // so callers don't reject content the agent could have written through
+  // legacy keys; pass false to validate the exact bytes (used in tests).
+  migrate?: boolean
+  // When set, persist + commit the migrated shape to this agent dir if the
+  // migration ran. Only `validateConfig` uses this; the guard's in-memory
+  // validation never persists (the bytes aren't yet on disk).
+  persistTarget?: string
+}
+
+// Pure validator for an in-memory `typeclaw.json` string. Used by the
+// managed-config guard to reject `write`/`edit` calls that would land an
+// invalid file on disk. Does NOT check mount accessibility — that is the
+// runtime concern handled by `validateConfig` at `typeclaw start` time, and
+// the file the agent is producing may legitimately reference a mount path
+// that only exists on the host outside the container.
+export function parseConfigJson(raw: string, options: ParseConfigJsonOptions = {}): ParseConfigJsonResult {
   let json: unknown
   try {
     json = JSON.parse(raw)
@@ -1016,24 +1054,19 @@ export function validateConfig(cwd: string, options: ValidateConfigOptions = {})
     return { ok: false, reason: `${CONFIG_FILE} is not valid JSON: ${detail}` }
   }
 
-  const migrated = migrateLegacyConfigShape(json)
-  if (migrated.changed) {
-    persistMigratedConfig(cwd, migrated.json, migrated.applied)
+  const shouldMigrate = options.migrate ?? true
+  const migrated = shouldMigrate
+    ? migrateLegacyConfigShape(json)
+    : { json, changed: false, applied: [] as MigrationStep[] }
+  if (migrated.changed && options.persistTarget !== undefined) {
+    persistMigratedConfig(options.persistTarget, migrated.json, migrated.applied)
   }
 
   const result = configSchema.safeParse(migrated.json)
   if (!result.success) {
     return { ok: false, reason: `${CONFIG_FILE} is invalid: ${formatZodError(result.error)}` }
   }
-
-  if (!options.skipMounts) {
-    for (const mount of result.data.mounts) {
-      const check = validateMount(mount, cwd)
-      if (!check.ok) return check
-    }
-  }
-
-  return { ok: true }
+  return { ok: true, config: result.data }
 }
 
 // Verifies a mount's host path: exists, is a directory, is readable, and is

package/src/config/index.ts

@@ -14,6 +14,7 @@ export {
   migrateLegacyConfigShape,
   modelsSchema,
   mountSchema,
+  parseConfigJson,
   portForwardSchema,
   reloadConfig,
   resolveModel,
@@ -31,6 +32,8 @@ export {
   type MigrationStep,
   type Models,
   type Mount,
+  type ParseConfigJsonOptions,
+  type ParseConfigJsonResult,
   type PortForward,
   type ResolvedProfile,
   type ValidateConfigResult,

package/src/cron/index.ts

@@ -41,6 +41,9 @@ export {
   type ExecJob,
   type HandlerJob,
   migrateLegacyCronShape,
+  parseCronJson,
+  type ParseCronJsonOptions,
+  type ParseCronResult,
   type ParsedCronJob,
   type PromptJob,
 } from './schema'

package/src/cron/schema.ts

@@ -151,6 +151,26 @@ function describeCronStep(step: CronMigrationStep): string {
   }
 }
 
+export type ParseCronJsonOptions = ParseCronOptions & {
+  // Apply `migrateLegacyCronShape` before schema validation. Defaults to true
+  // so the guard accepts the same legacy shapes `loadCron` would auto-migrate
+  // on disk; pass false to validate the exact bytes (used in tests).
+  migrate?: boolean
+}
+
+export function parseCronJson(raw: string, options: ParseCronJsonOptions = {}): ParseCronResult {
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, reason: `cron.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }
+  }
+
+  const shouldMigrate = options.migrate ?? true
+  const migrated = shouldMigrate ? migrateLegacyCronShape(json) : { json, changed: false, applied: [] }
+  return parseCronFile(migrated.json, options.subagents !== undefined ? { subagents: options.subagents } : {})
+}
+
 export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {
   const parsed = cronFileSchema.safeParse(raw)
   if (!parsed.success) {