typeclaw 0.1.1 → 0.1.3

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

@@ -0,0 +1,209 @@
+import { z } from 'zod'
+
+import { definePlugin, type Subagent } from '@/plugin'
+
+import { COMMIT_TIMEOUT_MS, makeDefaultGitSpawn, NETWORK_TIMEOUT_MS, runBackup, type BackupResult } from './runner'
+import {
+  cleanupMessageFile,
+  type CommitMessagePayload,
+  createCommitMessageSubagent,
+  createDiagnoseFailureSubagent,
+  type DiagnoseFailurePayload,
+  ensureMessageDir,
+  messageFilePath,
+  readMessageFile,
+} from './subagents'
+
+const DEFAULT_IDLE_MS = 30_000
+const MIN_IDLE_MS = 1_000
+
+const SUBAGENT_BACKUP_RUNNER = 'backup'
+const SUBAGENT_COMMIT_MESSAGE = 'backup-message'
+const SUBAGENT_DIAGNOSE = 'backup-diagnose'
+
+const SELF_INDUCED_SUBAGENT_NAMES = new Set<string>([
+  SUBAGENT_BACKUP_RUNNER,
+  SUBAGENT_COMMIT_MESSAGE,
+  SUBAGENT_DIAGNOSE,
+])
+
+const backupConfigSchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    idleMs: z.number().int().min(MIN_IDLE_MS).default(DEFAULT_IDLE_MS),
+    pushToOrigin: z.boolean().default(true),
+    commitTimeoutMs: z.number().int().min(1).default(COMMIT_TIMEOUT_MS),
+    networkTimeoutMs: z.number().int().min(1).default(NETWORK_TIMEOUT_MS),
+  })
+  .default({
+    enabled: true,
+    idleMs: DEFAULT_IDLE_MS,
+    pushToOrigin: true,
+    commitTimeoutMs: COMMIT_TIMEOUT_MS,
+    networkTimeoutMs: NETWORK_TIMEOUT_MS,
+  })
+
+const runnerPayloadSchema = z.object({
+  agentDir: z.string(),
+  pushToOrigin: z.boolean(),
+})
+
+type RunnerPayload = z.infer<typeof runnerPayloadSchema>
+
+export default definePlugin({
+  configSchema: backupConfigSchema,
+  plugin: async (ctx) => {
+    const enabled = ctx.config.enabled
+    const idleMs = ctx.config.idleMs
+    const pushToOrigin = ctx.config.pushToOrigin
+
+    const activeTurns = new Set<string>()
+    let idleTimer: ReturnType<typeof setTimeout> | null = null
+    let pendingFire = false
+    let inFlight = false
+
+    const cancelTimer = (): void => {
+      if (idleTimer !== null) {
+        clearTimeout(idleTimer)
+        idleTimer = null
+      }
+    }
+
+    const fireIfQuiet = async (): Promise<void> => {
+      if (!enabled) return
+      if (inFlight) {
+        pendingFire = true
+        return
+      }
+      if (activeTurns.size > 0) return
+      inFlight = true
+      try {
+        await ctx.spawnSubagent(SUBAGENT_BACKUP_RUNNER, {
+          agentDir: ctx.agentDir,
+          pushToOrigin,
+        } satisfies RunnerPayload)
+      } catch (err) {
+        ctx.logger.error(`backup runner spawn failed: ${err instanceof Error ? err.message : String(err)}`)
+      } finally {
+        inFlight = false
+        if (pendingFire) {
+          pendingFire = false
+          if (activeTurns.size === 0) {
+            queueMicrotask(() => {
+              void fireIfQuiet()
+            })
+          }
+        }
+      }
+    }
+
+    const isSelfInducedTurn = (origin: { kind: string; subagent?: string } | undefined): boolean => {
+      if (origin?.kind !== 'subagent') return false
+      const sub = origin.subagent
+      return sub !== undefined && SELF_INDUCED_SUBAGENT_NAMES.has(sub)
+    }
+
+    const runnerSubagent: Subagent<RunnerPayload> = {
+      systemPrompt: '(backup runner — no LLM)',
+      payloadSchema: runnerPayloadSchema,
+      inFlightKey: (payload) => payload.agentDir,
+      handler: async (sctx) => {
+        const result = await runBackupOnce(sctx.payload, ctx)
+        const summary = describeResult(result)
+        ctx.logger.info(`[backup] ${summary}`)
+      },
+    }
+
+    return {
+      subagents: {
+        [SUBAGENT_BACKUP_RUNNER]: runnerSubagent,
+        [SUBAGENT_COMMIT_MESSAGE]: createCommitMessageSubagent(),
+        [SUBAGENT_DIAGNOSE]: createDiagnoseFailureSubagent(),
+      },
+      hooks: {
+        'session.turn.start': (event) => {
+          if (isSelfInducedTurn(event.origin)) return
+          activeTurns.add(event.sessionId)
+          cancelTimer()
+        },
+        'session.turn.end': (event) => {
+          if (isSelfInducedTurn(event.origin)) return
+          activeTurns.delete(event.sessionId)
+        },
+        'session.end': (event) => {
+          activeTurns.delete(event.sessionId)
+        },
+        'session.idle': () => {
+          if (!enabled) return
+          if (activeTurns.size > 0) return
+          cancelTimer()
+          idleTimer = setTimeout(() => {
+            idleTimer = null
+            void fireIfQuiet()
+          }, idleMs)
+        },
+      },
+    }
+  },
+})
+
+async function runBackupOnce(
+  payload: RunnerPayload,
+  ctx: {
+    agentDir: string
+    logger: { info: (m: string) => void; warn: (m: string) => void }
+    spawnSubagent: (name: string, payload?: unknown) => Promise<void>
+  },
+): Promise<BackupResult> {
+  const messagePath = messageFilePath(payload.agentDir)
+  await ensureMessageDir(messagePath)
+  await cleanupMessageFile(messagePath)
+
+  const result = await runBackup(
+    { cwd: payload.agentDir, pushToOrigin: payload.pushToOrigin },
+    {
+      gitSpawn: makeDefaultGitSpawn(),
+      pickCommitMessage: async ({ status, diffstat }) => {
+        await cleanupMessageFile(messagePath)
+        const messagePayload: CommitMessagePayload = {
+          agentDir: payload.agentDir,
+          status,
+          diffstat,
+          outputPath: messagePath,
+        }
+        try {
+          await ctx.spawnSubagent(SUBAGENT_COMMIT_MESSAGE, messagePayload)
+        } catch (err) {
+          ctx.logger.warn(
+            `${SUBAGENT_COMMIT_MESSAGE} subagent failed, using fallback: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+        const written = await readMessageFile(messagePath)
+        await cleanupMessageFile(messagePath)
+        return written ?? 'chore: backup'
+      },
+      diagnoseFailure: async (input) => {
+        const diagPayload: DiagnoseFailurePayload = {
+          agentDir: input.cwd,
+          stage: input.stage,
+          exitCode: input.exitCode,
+          stderr: input.stderr,
+          stdout: input.stdout,
+        }
+        try {
+          await ctx.spawnSubagent(SUBAGENT_DIAGNOSE, diagPayload)
+        } catch (err) {
+          ctx.logger.warn(`${SUBAGENT_DIAGNOSE} subagent failed: ${err instanceof Error ? err.message : String(err)}`)
+        }
+      },
+    },
+  )
+
+  await cleanupMessageFile(messagePath)
+  return result
+}
+
+function describeResult(r: BackupResult): string {
+  if (r.ok) return r.kind
+  return `failed (${r.kind}): ${r.reason}`
+}

package/src/bundled-plugins/backup/runner.ts

@@ -0,0 +1,231 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const COMMIT_TIMEOUT_MS = 30_000
+export const NETWORK_TIMEOUT_MS = 60_000
+
+const RUNTIME_OWNED_PREFIXES = ['memory/'] as const
+const FORCE_ADD_PREFIXES = ['sessions/'] as const
+
+const NONINTERACTIVE_ENV = {
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_PAGER: 'cat',
+  PAGER: 'cat',
+  GCM_INTERACTIVE: 'never',
+} as const
+
+export type GitSpawnResult = {
+  exitCode: number
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+export type GitSpawn = (args: readonly string[], opts: { cwd: string; timeoutMs: number }) => Promise<GitSpawnResult>
+
+export type BackupRunnerDeps = {
+  gitSpawn: GitSpawn
+  pickCommitMessage: (input: { status: string; diffstat: string }) => Promise<string>
+  diagnoseFailure?: (input: BackupFailureInput) => Promise<void>
+  now?: () => number
+}
+
+export type BackupRunnerOptions = {
+  cwd: string
+  pushToOrigin: boolean
+}
+
+export type BackupFailureInput = {
+  cwd: string
+  stage: 'push' | 'rebase'
+  exitCode: number
+  stderr: string
+  stdout: string
+}
+
+export type BackupResult =
+  | { ok: true; kind: 'no-repo' | 'clean' | 'committed' | 'pushed' | 'rebased-and-pushed' }
+  | { ok: false; kind: 'commit-failed' | 'push-failed' | 'rebase-failed' | 'aborted'; reason: string }
+
+export async function runBackup(options: BackupRunnerOptions, deps: BackupRunnerDeps): Promise<BackupResult> {
+  const { cwd, pushToOrigin } = options
+
+  if (!existsSync(join(cwd, '.git'))) return { ok: true, kind: 'no-repo' }
+
+  const status = await deps.gitSpawn(['status', '--porcelain=v1', '--untracked-files=all'], {
+    cwd,
+    timeoutMs: COMMIT_TIMEOUT_MS,
+  })
+  if (status.exitCode !== 0) return { ok: false, kind: 'aborted', reason: `git status failed: ${shortErr(status)}` }
+  const dirty = filterAgentOwned(parsePorcelain(status.stdout))
+  const force = filterForceAdd(parsePorcelain(status.stdout))
+  if (dirty.length === 0 && force.length === 0) return { ok: true, kind: 'clean' }
+
+  if (dirty.length > 0) {
+    const add = await deps.gitSpawn(['add', '--', ...dirty], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+    if (add.exitCode !== 0) return { ok: false, kind: 'commit-failed', reason: `git add failed: ${shortErr(add)}` }
+  }
+  if (force.length > 0) {
+    const present = force.filter((p) => existsSync(join(cwd, p)))
+    if (present.length > 0) {
+      const addF = await deps.gitSpawn(['add', '-f', '--', ...present], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+      if (addF.exitCode !== 0) {
+        return { ok: false, kind: 'commit-failed', reason: `git add -f failed: ${shortErr(addF)}` }
+      }
+    }
+  }
+
+  const stagedCheck = await deps.gitSpawn(['diff', '--cached', '--quiet'], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+  if (stagedCheck.exitCode === 0) return { ok: true, kind: 'clean' }
+
+  const diffstat = await deps.gitSpawn(['diff', '--cached', '--stat'], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+  const message = await deps.pickCommitMessage({
+    status: status.stdout.slice(0, 4096),
+    diffstat: diffstat.stdout.slice(0, 4096),
+  })
+
+  const safeMessage = sanitizeCommitMessage(message)
+  const commit = await deps.gitSpawn(['commit', '-m', safeMessage], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+  if (commit.exitCode !== 0)
+    return { ok: false, kind: 'commit-failed', reason: `git commit failed: ${shortErr(commit)}` }
+
+  if (!pushToOrigin) return { ok: true, kind: 'committed' }
+
+  const upstream = await deps.gitSpawn(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], {
+    cwd,
+    timeoutMs: COMMIT_TIMEOUT_MS,
+  })
+  if (upstream.exitCode !== 0) return { ok: true, kind: 'committed' }
+
+  const upstreamRef = upstream.stdout.trim()
+  if (upstreamRef.length === 0) return { ok: true, kind: 'committed' }
+
+  const push = await deps.gitSpawn(['push'], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (push.exitCode === 0) return { ok: true, kind: 'pushed' }
+
+  if (!isNonFastForward(push)) {
+    await maybeDiagnose(deps, { cwd, stage: 'push', exitCode: push.exitCode, stderr: push.stderr, stdout: push.stdout })
+    return { ok: false, kind: 'push-failed', reason: shortErr(push) }
+  }
+
+  const fetch = await deps.gitSpawn(['fetch'], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (fetch.exitCode !== 0) {
+    await maybeDiagnose(deps, {
+      cwd,
+      stage: 'push',
+      exitCode: fetch.exitCode,
+      stderr: fetch.stderr,
+      stdout: fetch.stdout,
+    })
+    return { ok: false, kind: 'push-failed', reason: `git fetch failed: ${shortErr(fetch)}` }
+  }
+
+  const rebase = await deps.gitSpawn(['rebase', upstreamRef], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (rebase.exitCode !== 0) {
+    await deps.gitSpawn(['rebase', '--abort'], { cwd, timeoutMs: COMMIT_TIMEOUT_MS })
+    await maybeDiagnose(deps, {
+      cwd,
+      stage: 'rebase',
+      exitCode: rebase.exitCode,
+      stderr: rebase.stderr,
+      stdout: rebase.stdout,
+    })
+    return { ok: false, kind: 'rebase-failed', reason: `git rebase failed: ${shortErr(rebase)}` }
+  }
+
+  const push2 = await deps.gitSpawn(['push'], { cwd, timeoutMs: NETWORK_TIMEOUT_MS })
+  if (push2.exitCode !== 0) {
+    await maybeDiagnose(deps, {
+      cwd,
+      stage: 'push',
+      exitCode: push2.exitCode,
+      stderr: push2.stderr,
+      stdout: push2.stdout,
+    })
+    return { ok: false, kind: 'push-failed', reason: `git push (post-rebase) failed: ${shortErr(push2)}` }
+  }
+  return { ok: true, kind: 'rebased-and-pushed' }
+}
+
+async function maybeDiagnose(deps: BackupRunnerDeps, input: BackupFailureInput): Promise<void> {
+  if (!deps.diagnoseFailure) return
+  try {
+    await deps.diagnoseFailure(input)
+  } catch {
+    // Diagnosis is advisory; never let it mask the original failure.
+  }
+}
+
+function shortErr(r: GitSpawnResult): string {
+  if (r.timedOut) return `timed out (exit ${r.exitCode})`
+  const text = r.stderr.trim() || r.stdout.trim() || `exit ${r.exitCode}`
+  return text.length > 400 ? `${text.slice(0, 400)}…` : text
+}
+
+function isNonFastForward(r: GitSpawnResult): boolean {
+  const blob = `${r.stderr}\n${r.stdout}`.toLowerCase()
+  return blob.includes('non-fast-forward') || blob.includes('updates were rejected')
+}
+
+export function parsePorcelain(stdout: string): string[] {
+  const out: string[] = []
+  for (const raw of stdout.split('\n')) {
+    if (raw.length < 4) continue
+    const rest = raw.slice(3)
+    const arrowIdx = rest.indexOf(' -> ')
+    out.push(arrowIdx === -1 ? rest : rest.slice(arrowIdx + 4))
+  }
+  return out
+}
+
+function filterAgentOwned(paths: readonly string[]): string[] {
+  return paths.filter((p) => !RUNTIME_OWNED_PREFIXES.some((pre) => p.startsWith(pre)))
+}
+
+function filterForceAdd(paths: readonly string[]): string[] {
+  return paths.filter((p) => FORCE_ADD_PREFIXES.some((pre) => p.startsWith(pre)))
+}
+
+function sanitizeCommitMessage(raw: string): string {
+  const trimmed = raw.trim()
+  if (trimmed.length === 0) return 'Backup'
+  const subject = trimmed.split('\n')[0]?.slice(0, 200) ?? 'Backup'
+  const rest = trimmed.split('\n').slice(1).join('\n').trim()
+  return rest.length > 0 ? `${subject}\n\n${rest}` : subject
+}
+
+export function makeDefaultGitSpawn(): GitSpawn {
+  return async (args, { cwd, timeoutMs }) => {
+    const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+    if (!bun) {
+      return { exitCode: 127, stdout: '', stderr: 'Bun runtime not available', timedOut: false }
+    }
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      const proc = bun.spawn({
+        cmd: ['git', ...args],
+        cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: { ...process.env, ...NONINTERACTIVE_ENV },
+        signal: controller.signal,
+      })
+      const exitCode = await proc.exited
+      const stdout = await new Response(proc.stdout).text()
+      const stderr = await new Response(proc.stderr).text()
+      const timedOut = controller.signal.aborted
+      return { exitCode, stdout, stderr, timedOut }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return {
+        exitCode: 1,
+        stdout: '',
+        stderr: message,
+        timedOut: controller.signal.aborted,
+      }
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}

package/src/bundled-plugins/backup/subagents.ts

@@ -0,0 +1,200 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { z } from 'zod'
+
+import { bashTool, readTool, type Subagent, writeTool } from '@/plugin'
+
+const messagePayloadSchema = z.object({
+  agentDir: z.string(),
+  status: z.string(),
+  diffstat: z.string(),
+  outputPath: z.string(),
+})
+
+export type CommitMessagePayload = z.infer<typeof messagePayloadSchema>
+
+const diagnosePayloadSchema = z.object({
+  agentDir: z.string(),
+  stage: z.enum(['push', 'rebase']),
+  exitCode: z.number(),
+  stderr: z.string(),
+  stdout: z.string(),
+})
+
+export type DiagnoseFailurePayload = z.infer<typeof diagnosePayloadSchema>
+
+export const COMMIT_MESSAGE_SYSTEM_PROMPT = `You are typeclaw's backup commit-message subagent.
+
+A periodic backup is about to commit dirty files in the agent folder. Your only job is to produce a clear, conventional commit message describing those changes.
+
+# Input
+
+The user message gives you:
+- The output of \`git status --porcelain=v1 --untracked-files=all\` (truncated)
+- The output of \`git diff --cached --stat\` (truncated)
+- An absolute file path you must write the commit message to
+
+# What to write
+
+A single commit message in conventional-commit-ish style:
+- Subject line under 72 characters, imperative mood, lowercase first word, no trailing period.
+- Pick a sensible prefix when one fits: \`docs:\`, \`test:\`, \`refactor:\`, \`chore:\`, \`fix:\`, \`feat:\`. Default to \`chore: backup\` if nothing fits.
+- Optionally a blank line and a short body (1-3 lines) summarizing what changed and why if the diff makes the why obvious.
+
+Examples:
+- \`docs: update setup instructions\`
+- \`feat: add user search endpoint\`
+- \`chore: backup workspace state\`
+
+# Hard rules
+
+1. **Write exactly one file.** Use the \`write\` tool with the absolute path the user gave you. Do not write anywhere else. Do not read other files. Do not run commands.
+2. **Output is the file contents only.** No prose to the user, no explanation, no apologies. The runner ignores everything except the file you wrote.
+3. **Be honest about uncertainty.** If the diff looks like a mix of unrelated changes, write \`chore: backup\` rather than guessing a misleading subject.
+4. **Never include secrets, API keys, or paths that would identify the user's machine.** Stick to repo-relative descriptions.
+5. **Stop when the file is written.** Do not continue after the \`write\` succeeds.`
+
+export const DIAGNOSE_FAILURE_SYSTEM_PROMPT = `You are typeclaw's backup failure-diagnosis subagent.
+
+The deterministic backup runner just hit a git failure (push or rebase). The runner has already aborted any half-done state. Your job is to look at the git repo, figure out what went wrong, and either FIX IT or write a clear human-readable explanation.
+
+# Input
+
+The user message gives you:
+- The agent folder absolute path
+- The stage that failed (\`push\` or \`rebase\`)
+- The git exit code, stderr, and stdout
+
+# Tools
+
+You have \`bash\`, \`read\`, and \`write\`. Use \`bash\` to inspect git state (\`git status\`, \`git remote -v\`, \`git log -5 --oneline\`, \`git config --get remote.origin.url\`).
+
+# Allowed actions
+
+You MAY:
+- Inspect git state (read-only commands).
+- Set up a missing upstream branch via \`git push -u origin <branch>\` if it's clear that's the only issue.
+- Retry \`git push\` once after fixing a clear, narrow issue.
+
+You MUST NOT:
+- Force-push (\`--force\`, \`--force-with-lease\`).
+- Resolve merge conflicts by editing files. If a rebase had conflicts, the runner already aborted it. Leave the repo as-is and explain.
+- Mutate \`.git/config\` for credentials, signing keys, or remote URLs.
+- Touch any file outside \`.git/\` housekeeping.
+
+# Output
+
+Write a brief diagnosis (3-8 lines) describing:
+1. What the actual cause was (e.g. "no upstream tracking branch", "remote is ahead and rebase conflicted", "auth failed").
+2. What you did about it (or why you didn't).
+3. What the user should do next, if anything.
+
+Append your diagnosis to \`<agentDir>/sessions/backup-diagnostics.log\` with a timestamp prefix. Keep it short — this log is for the human, not the model.
+
+# When in doubt
+
+Do nothing destructive. Write the diagnosis and stop. The user can recover manually.`
+
+export type CreateCommitMessageSubagentOptions = {
+  fallbackMessage?: string
+}
+
+export function createCommitMessageSubagent(
+  options: CreateCommitMessageSubagentOptions = {},
+): Subagent<CommitMessagePayload> {
+  const fallback = options.fallbackMessage ?? 'chore: backup'
+  return {
+    systemPrompt: COMMIT_MESSAGE_SYSTEM_PROMPT,
+    tools: [writeTool],
+    payloadSchema: messagePayloadSchema,
+    inFlightKey: (payload) => payload.agentDir,
+    handler: async (ctx, runSession) => {
+      const userPrompt = buildCommitMessagePrompt(ctx.payload)
+      try {
+        await runSession({ userPrompt })
+      } catch {
+        await writeFile(ctx.payload.outputPath, fallback, 'utf8').catch(() => undefined)
+      }
+    },
+  }
+}
+
+export function createDiagnoseFailureSubagent(): Subagent<DiagnoseFailurePayload> {
+  return {
+    systemPrompt: DIAGNOSE_FAILURE_SYSTEM_PROMPT,
+    tools: [bashTool, readTool, writeTool],
+    payloadSchema: diagnosePayloadSchema,
+    inFlightKey: (payload) => payload.agentDir,
+    handler: async (ctx, runSession) => {
+      const userPrompt = buildDiagnosePrompt(ctx.payload)
+      try {
+        await runSession({ userPrompt })
+      } catch {
+        // Diagnosis is advisory; failures here must not propagate.
+      }
+    },
+  }
+}
+
+function buildCommitMessagePrompt(p: CommitMessagePayload): string {
+  return [
+    `Agent folder: ${p.agentDir}`,
+    `Write the commit message to: ${p.outputPath}`,
+    '',
+    '## git status --porcelain=v1 --untracked-files=all',
+    '```',
+    p.status.trim() || '(empty)',
+    '```',
+    '',
+    '## git diff --cached --stat',
+    '```',
+    p.diffstat.trim() || '(empty)',
+    '```',
+    '',
+    'Write the commit message and stop.',
+  ].join('\n')
+}
+
+function buildDiagnosePrompt(p: DiagnoseFailurePayload): string {
+  return [
+    `Agent folder: ${p.agentDir}`,
+    `Failed stage: ${p.stage}`,
+    `Exit code: ${p.exitCode}`,
+    '',
+    '## stderr',
+    '```',
+    p.stderr.trim() || '(empty)',
+    '```',
+    '',
+    '## stdout',
+    '```',
+    p.stdout.trim() || '(empty)',
+    '```',
+    '',
+    'Inspect the repo, do the smallest safe action if any, and write your diagnosis to the log file.',
+  ].join('\n')
+}
+
+export async function readMessageFile(path: string): Promise<string | null> {
+  try {
+    const raw = await readFile(path, 'utf8')
+    return raw.trim().length > 0 ? raw : null
+  } catch {
+    return null
+  }
+}
+
+export async function ensureMessageDir(outputPath: string): Promise<void> {
+  const dir = outputPath.slice(0, outputPath.lastIndexOf('/'))
+  if (dir.length === 0) return
+  await mkdir(dir, { recursive: true }).catch(() => undefined)
+}
+
+export async function cleanupMessageFile(path: string): Promise<void> {
+  await rm(path, { force: true }).catch(() => undefined)
+}
+
+export function messageFilePath(agentDir: string): string {
+  return join(agentDir, '.typeclaw', 'backup-message.tmp')
+}

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

@@ -1,4 +1,6 @@
-import { stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { access, constants as fsConstants, mkdir, stat, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 
 import { CronExpressionParser } from 'cron-parser'
 import { z } from 'zod'
@@ -212,6 +214,45 @@ export default definePlugin({
           bytesAtLastRun.delete(event.sessionId)
         },
       },
+      doctorChecks: {
+        'dir-writable': {
+          description: 'memory/ exists and is writable',
+          run: async (dctx) => {
+            const dir = join(dctx.agentDir, 'memory')
+            try {
+              await access(dir, fsConstants.W_OK)
+              return { status: 'ok', message: `${dir} writable` }
+            } catch {
+              return {
+                status: 'error',
+                message: `${dir} is missing or not writable`,
+                fix: { description: 'Create memory/ in the agent folder or fix its permissions on the host.' },
+              }
+            }
+          },
+        },
+        'daily-stream-current': {
+          description: "today's daily stream file exists",
+          run: async (dctx) => {
+            const today = new Date().toISOString().slice(0, 10)
+            const rel = `memory/${today}.md`
+            const abs = join(dctx.agentDir, rel)
+            if (existsSync(abs)) return { status: 'ok', message: `${rel} present` }
+            return {
+              status: 'warning',
+              message: `${rel} missing`,
+              fix: {
+                description: `Create empty ${rel} so memory-logger has a target.`,
+                apply: async () => {
+                  await mkdir(dirname(abs), { recursive: true })
+                  await writeFile(abs, '', 'utf8')
+                  return { summary: `created ${rel}`, changedPaths: [rel] }
+                },
+              },
+            }
+          },
+        },
+      },
     }
   },
 })