typeclaw 0.1.4 → 0.1.6

package/src/container/require-running.ts

@@ -0,0 +1,33 @@
+import { containerNameFromCwd, inspectContainer, type ContainerState } from './shared'
+
+export type RequireContainerRunningResult = { ok: true; containerName: string } | { ok: false; reason: string }
+
+export type RequireContainerRunningOptions = {
+  cwd: string
+}
+
+type RequireContainerRunningDeps = {
+  inspect?: (name: string) => Promise<ContainerState>
+}
+
+// Pre-flight for CLI commands that need to talk to a live agent (tui, reload,
+// role claim). Without this, `resolveHostPort` silently falls back to the
+// configured port when the container is missing/stopped and the caller hits
+// an opaque websocket "Connection refused" or fetch error several frames deep.
+// We probe with `inspectContainer` — the same helper `shell` and `start` use —
+// and surface the canonical "Run `typeclaw start` first." prose that matches
+// `src/container/shell.ts`'s wording.
+export async function requireContainerRunning(
+  { cwd }: RequireContainerRunningOptions,
+  deps: RequireContainerRunningDeps = {},
+): Promise<RequireContainerRunningResult> {
+  const containerName = containerNameFromCwd(cwd)
+  const state = await (deps.inspect ?? inspectContainer)(containerName)
+  if (!state.exists) {
+    return { ok: false, reason: `Container ${containerName} not found. Run \`typeclaw start\` first.` }
+  }
+  if (!state.running) {
+    return { ok: false, reason: `Container ${containerName} is not running. Run \`typeclaw start\` first.` }
+  }
+  return { ok: true, containerName }
+}

package/src/container/start.ts

@@ -3,7 +3,8 @@ import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { isAbsolute, join, resolve } from 'node:path'
 
-import { configSchema, expandMountPath, type Config } from '@/config/config'
+import { expandMountPath, loadConfigSync, type Config } from '@/config'
+import { commitSystemFile as commitSystemFileShared } from '@/git/system-commit'
 import { send as sendToDaemon } from '@/hostd/client'
 import type { HttpInfoResult } from '@/hostd/protocol'
 import { ensureDaemon } from '@/hostd/spawn'
@@ -22,7 +23,7 @@ import { refreshPackageJson } from '@/init/packagejson'
 import { runBunUpdate, type UpdateRunner } from '@/init/run-bun-install'
 import { migrateKakaotalkCredentials } from '@/secrets'
 
-import { CONTAINER_PORT, findFreePort, isPortAllocatedError } from './port'
+import { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, isPortAllocatedError, resolveTuiToken } from './port'
 import {
   classifyRmStderr,
   cleanupRunCorpse,
@@ -30,7 +31,6 @@ import {
   defaultDockerExec,
   type DockerExec,
   type DockerExecResult,
-  getBun,
   imageTagFromCwd,
   isContainerNameConflict,
   sanitizeDockerStderr,
@@ -41,7 +41,6 @@ import { buildCrashReason, createVerifyRunning, type VerifyRunningFn } from './v
 const PACKAGE_FILE = 'package.json'
 const BUN_LOCK_FILE = 'bun.lock'
 const DEPENDENCY_FILES = [PACKAGE_FILE, BUN_LOCK_FILE] as const
-const CONFIG_FILE = 'typeclaw.json'
 const ENV_FILE = '.env'
 const COMPOSE_PROJECT = 'typeclaw'
 const CONTAINER_HOSTD_HOST = 'host.docker.internal'
@@ -57,6 +56,7 @@ export type StartPlan = {
   runArgs: string[]
   needsBuild: boolean
   hostPort: number
+  tuiToken: string | null
 }
 
 export type PlanStartOptions = {
@@ -65,6 +65,8 @@ export type PlanStartOptions = {
   imageExists: boolean
   forceBuild?: boolean
   hostdControl?: HostDaemonControl
+  publishHost?: string
+  tuiToken?: string | null
 }
 
 export type HostDaemonControl = {
@@ -127,6 +129,7 @@ export type StartResult =
       containerId: string
       built: boolean
       hostPort: number
+      tuiToken: string | null
       hostd: HostDaemonStatus
       // True when the container was already running and start() became a no-op.
       // Callers that want to distinguish "I just launched it" from "it was up
@@ -175,6 +178,14 @@ export async function start({
     // one-shot and idempotent — once `workspaces` is set, refreshPackageJson
     // is a no-op, so users who never edit their agent folder pay zero cost on
     // subsequent starts and users who customized `workspaces` are not clobbered.
+    //
+    // typeclaw.json migration is NOT triggered explicitly here — it follows
+    // the disk rewrite via persistMigratedConfig (src/config/config.ts), so
+    // every entry point that reads typeclaw.json (host CLI, hostd daemon,
+    // container runtime) also produces the commit. start() therefore only
+    // needs to orchestrate the .gitignore / package.json side; the
+    // refreshGitignore call below reads typeclaw.json and will incidentally
+    // trigger the migration commit if the file was legacy.
     await refreshGitignore(cwd)
     const pkgRefresh = await refreshPackageJson(cwd)
     await commitSystemFile(cwd, GITIGNORE_FILE, 'Update .gitignore')
@@ -233,7 +244,7 @@ export async function start({
     // line resolves against the agent's installed node_modules/typeclaw —
     // ensures the base image's CLI version matches the runtime the
     // container will actually load.
-    await refreshDockerfile(cwd)
+    const dockerfileRefresh = await refreshDockerfile(cwd)
     await migrateKakaotalkCredentials(cwd)
 
     if (state.exists) {
@@ -298,7 +309,17 @@ export async function start({
       : { state: 'disabled' as const }
     let hostdControl = hostd.state === 'registered' ? hostd.control : undefined
 
-    let plan = await planStart({ cwd, hostPort, imageExists: imageExisted, forceBuild, hostdControl })
+    const publishHost = await resolvePublishHost(exec)
+    const tuiToken = randomBytes(32).toString('base64url')
+    let plan = await planStart({
+      cwd,
+      hostPort,
+      imageExists: imageExisted,
+      forceBuild: forceBuild || dockerfileRefresh.changed,
+      hostdControl,
+      publishHost,
+      tuiToken,
+    })
 
     let built = false
     if (plan.needsBuild) {
@@ -347,7 +368,15 @@ export async function start({
         hostd = await registerWithDaemon({ cwd, containerName, cliEntry, hostPort, reuseCurrentHostDaemon })
         hostdControl = hostd.state === 'registered' ? hostd.control : undefined
       }
-      plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false, hostdControl })
+      plan = await planStart({
+        cwd,
+        hostPort,
+        imageExists: true,
+        forceBuild: false,
+        hostdControl,
+        publishHost,
+        tuiToken,
+      })
       run = await execRunWithConflictRetry(exec, plan.runArgs, cwd, containerName)
     }
 
@@ -370,6 +399,7 @@ export async function start({
       containerId,
       built,
       hostPort,
+      tuiToken,
       hostd: stripHostDaemonControl(hostd),
       alreadyRunning: false,
       autoUpgrade: upgrade,
@@ -403,6 +433,8 @@ export async function planStart({
   imageExists,
   forceBuild = false,
   hostdControl,
+  publishHost = '127.0.0.1',
+  tuiToken = null,
 }: PlanStartOptions): Promise<StartPlan> {
   const containerName = containerNameFromCwd(cwd)
   const imageTag = imageTagFromCwd(cwd)
@@ -416,7 +448,7 @@ export async function planStart({
   // the start() preflight force-removes any lingering corpse before the next
   // launch — so the only state Docker ever sees in `docker ps -a` is either
   // a running container or one the user has not started again yet.
-  const runArgs = ['run', '-d', '--name', containerName, '-p', `127.0.0.1:${hostPort}:${CONTAINER_PORT}`]
+  const runArgs = ['run', '-d', '--name', containerName, '-p', `${publishHost}:${hostPort}:${CONTAINER_PORT}`]
 
   // Network egress filter: when `typeclaw.json#network.blockInternal` is true,
   // grant the container CAP_NET_ADMIN at boot so the entrypoint shim can
@@ -443,6 +475,9 @@ export async function planStart({
   for (const [key, value] of Object.entries(composeLabels(cwd, containerName))) {
     runArgs.push('--label', `${key}=${value}`)
   }
+  if (tuiToken !== null) {
+    runArgs.push('--label', `${TUI_TOKEN_LABEL}=${tuiToken}`, '-e', `TYPECLAW_TUI_TOKEN=${tuiToken}`)
+  }
 
   if (existsSync(join(cwd, ENV_FILE))) {
     runArgs.push('--env-file', join(cwd, ENV_FILE))
@@ -493,59 +528,44 @@ export async function planStart({
     runArgs,
     needsBuild: forceBuild || !imageExists,
     hostPort,
+    tuiToken,
   }
 }
 
-export async function refreshDockerfile(cwd: string): Promise<void> {
+async function resolvePublishHost(exec: DockerExec): Promise<string> {
+  const result = await exec(['version', '--format', '{{.Server.Platform.Name}}'])
+  if (result.exitCode === 0 && result.stdout.toLowerCase().includes('docker desktop')) return '0.0.0.0'
+  return '127.0.0.1'
+}
+
+// The `changed` return drives auto-rebuild in start() so users don't need to
+// pass `--build` after a CLI upgrade or after editing `typeclaw.json#docker.*`.
+// Comparing rendered contents (rather than tracking a separate state file) is
+// the cheapest correct signal: the build context for `docker build` is the
+// Dockerfile itself, so equal contents definitionally produce an equivalent
+// image.
+export async function refreshDockerfile(cwd: string): Promise<{ changed: boolean }> {
   const cfg = await loadTypeclawConfig(cwd)
-  await writeFile(
-    join(cwd, DOCKERFILE),
-    buildDockerfile(cfg.dockerfile, { baseImageVersion: resolveBaseImageVersion(cwd) }),
-  )
+  const next = buildDockerfile(cfg.docker.file, { baseImageVersion: resolveBaseImageVersion(cwd) })
+  const path = join(cwd, DOCKERFILE)
+  const prev = await readFile(path, 'utf8').catch(() => null)
+  if (prev === next) return { changed: false }
+  await writeFile(path, next)
+  return { changed: true }
 }
 
 export async function refreshGitignore(cwd: string): Promise<void> {
   const cfg = await loadTypeclawConfig(cwd)
-  await writeFile(join(cwd, GITIGNORE_FILE), buildGitignore(cfg.gitignore))
+  await writeFile(join(cwd, GITIGNORE_FILE), buildGitignore(cfg.git.ignore))
 }
 
-// Commits TypeClaw-owned system file(s) if any are dirty in git. Skips silently
-// when the agent folder is not a git repo, when bun is unavailable, or when
-// every named file is clean (no changes since last commit). Uses the user's
-// global git config for authorship — TypeClaw does not impersonate the user
-// here. Accepts a single file or an array; the array form produces a single
-// atomic commit covering all listed paths, used for migrations that touch
-// multiple files together (e.g. enabling bun workspaces writes both
-// package.json and packages/.gitkeep in one commit).
-export async function commitSystemFile(cwd: string, file: string | readonly string[], message: string): Promise<void> {
-  const files = typeof file === 'string' ? [file] : file
-  if (files.length === 0) return
-
-  const bun = getBun()
-  if (!bun) return
-  if (!existsSync(join(cwd, '.git'))) return
-
-  const status = bun.spawn({
-    cmd: ['git', 'status', '--porcelain', '--', ...files],
-    cwd,
-    stdout: 'pipe',
-    stderr: 'pipe',
-  })
-  if ((await status.exited) !== 0) return
-  const dirty = (await new Response(status.stdout).text()).trim().length > 0
-  if (!dirty) return
-
-  const add = bun.spawn({ cmd: ['git', 'add', '--', ...files], cwd, stdout: 'pipe', stderr: 'pipe' })
-  if ((await add.exited) !== 0) return
-
-  const commit = bun.spawn({
-    cmd: ['git', 'commit', '-m', message, '--only', '--', ...files],
-    cwd,
-    stdout: 'pipe',
-    stderr: 'pipe',
-  })
-  await commit.exited
-}
+// Re-exported from src/git/system-commit.ts so existing call sites
+// (refreshGitignore wiring, doctor/commit.ts comment references, test
+// imports) keep working under the original name. New code should import
+// directly from @/git/system-commit instead. The sync sibling lives
+// alongside in that module and is used by persistMigratedConfig to pair
+// the migration write with a commit on every read path, not only here.
+export const commitSystemFile = commitSystemFileShared
 
 async function imageExists(exec: DockerExec, tag: string): Promise<boolean> {
   const result = await exec(['image', 'inspect', tag])
@@ -623,13 +643,15 @@ async function reportAlreadyRunning(exec: DockerExec, cwd: string, containerName
       reason: `Container ${containerName} is running but its published host port could not be resolved.`,
     }
   }
-  const plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false })
+  const tuiToken = await resolveTuiToken({ cwd, exec })
+  const plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false, tuiToken })
   return {
     ok: true,
     plan,
     containerId,
     built: false,
     hostPort,
+    tuiToken,
     hostd: { state: 'disabled' },
     alreadyRunning: true,
     autoUpgrade: { kind: 'skipped-already-running' },
@@ -693,7 +715,13 @@ async function detectDevSource(cwd: string): Promise<string | null> {
 // invalid mount entry — must surface so the user sees they configured a mount
 // that won't be applied.
 async function loadTypeclawConfig(cwd: string): Promise<Config> {
-  return configSchema.parse(await loadConfigJson(cwd))
+  // Goes through the shared loadConfigSync so the legacy-shape migration
+  // (and its paired git commit via persistMigratedConfig) follows every
+  // start() read path — refreshGitignore, the docker run argv builder, and
+  // the daemon-register payload all eventually land here. The function is
+  // declared async only to preserve the existing await sites; the work is
+  // synchronous under the hood.
+  return loadConfigSync(cwd)
 }
 
 async function registerWithDaemon({
@@ -740,16 +768,6 @@ async function useCurrentHostDaemon(): Promise<{ ok: true; httpPort: number } |
   return { ok: true, httpPort: result.port }
 }
 
-async function loadConfigJson(cwd: string): Promise<unknown> {
-  let raw: string
-  try {
-    raw = await readFile(join(cwd, CONFIG_FILE), 'utf8')
-  } catch {
-    return {}
-  }
-  return JSON.parse(raw)
-}
-
 type PreparedHostDaemonStatus =
   | { state: 'registered'; control: HostDaemonControl }
   | { state: 'unavailable'; reason: string }

package/src/cron/consumer.ts

@@ -100,8 +100,24 @@ async function runPrompt(
   stream: Stream,
 ): Promise<void> {
   if (job.subagent !== undefined) {
+    // Propagate the cron job's role and origin into the spawned subagent.
+    // Without this, every cron-triggered subagent (e.g. memory dreaming)
+    // resolves to `guest` because the new-session consumer reads provenance
+    // off the stream target rather than rebuilding it. Encode the parent
+    // origin as JSON since StreamTarget is a flat-string shape.
+    const parentOrigin: SessionOrigin = {
+      kind: 'cron',
+      jobId: job.id,
+      jobKind: 'prompt',
+      ...(job.scheduledByRole !== undefined ? { scheduledByRole: job.scheduledByRole } : {}),
+    }
     stream.publish({
-      target: { kind: 'new-session', subagent: job.subagent },
+      target: {
+        kind: 'new-session',
+        subagent: job.subagent,
+        ...(job.scheduledByRole !== undefined ? { spawnedByRole: job.scheduledByRole } : {}),
+        spawnedByOriginJson: JSON.stringify(parentOrigin),
+      },
       payload: job.payload,
     })
     return
@@ -131,11 +147,15 @@ async function runPrompt(
         sessionId: session.sessionId,
         parentTranscriptPath: session.getTranscriptPath?.(),
         idleMs: 0,
+        ...(session.origin !== undefined ? { origin: session.origin } : {}),
       })
     }
   } finally {
     if (session.hooks && session.sessionId !== undefined) {
-      await session.hooks.runSessionEnd({ sessionId: session.sessionId })
+      await session.hooks.runSessionEnd({
+        sessionId: session.sessionId,
+        ...(session.origin !== undefined ? { origin: session.origin } : {}),
+      })
     }
     session.dispose?.()
   }

package/src/cron/index.ts

@@ -1,10 +1,17 @@
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import type { SubagentRegistry } from '@/agent/subagents'
+import { commitSystemFile } from '@/git/system-commit'
 
-import { type CronFile, parseCronFile } from './schema'
+import {
+  buildCronMigrationCommitMessage,
+  type CronFile,
+  type CronMigrationStep,
+  migrateLegacyCronShape,
+  parseCronFile,
+} from './schema'
 
 export { createCronReloadable, type CreateCronReloadableOptions } from './reloadable'
 export {
@@ -15,7 +22,18 @@ export {
   type CronSession,
 } from './consumer'
 export { createScheduler, type JobDiff, type Scheduler, type SchedulerLogger } from './scheduler'
-export { cronFileSchema, cronJobSchema, type CronFile, type CronJob, type ExecJob, type PromptJob } from './schema'
+export {
+  buildCronMigrationCommitMessage,
+  cronFileSchema,
+  cronJobSchema,
+  type CronFile,
+  type CronJob,
+  type CronMigrationResult,
+  type CronMigrationStep,
+  type ExecJob,
+  migrateLegacyCronShape,
+  type PromptJob,
+} from './schema'
 
 const CRON_FILE = 'cron.json'
 
@@ -43,12 +61,35 @@ export async function loadCron(agentDir: string, options: LoadCronOptions = {}):
     return { ok: false, reason: `cron.json is not valid JSON: ${errorMessage(err)}` }
   }
 
-  const result = parseCronFile(parsed, options.subagents !== undefined ? { subagents: options.subagents } : {})
+  const migrated = migrateLegacyCronShape(parsed)
+  if (migrated.changed) {
+    await persistMigratedCron(path, migrated.json, agentDir, migrated.applied)
+  }
+
+  const result = parseCronFile(migrated.json, options.subagents !== undefined ? { subagents: options.subagents } : {})
   if (!result.ok) return { ok: false, reason: result.reason }
 
   return { ok: true, file: result.file }
 }
 
+async function persistMigratedCron(
+  path: string,
+  json: unknown,
+  agentDir: string,
+  applied: readonly CronMigrationStep[],
+): Promise<void> {
+  try {
+    await writeFile(path, `${JSON.stringify(json, null, 2)}\n`)
+  } catch {
+    return
+  }
+
+  const message = buildCronMigrationCommitMessage(applied)
+  if (message !== null) {
+    await commitSystemFile(agentDir, CRON_FILE, message)
+  }
+}
+
 function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/cron/schema.ts

@@ -11,6 +11,16 @@ const baseJob = z.object({
   schedule: z.string().min(1),
   enabled: z.boolean().default(true),
   timezone: z.string().optional(),
+  scheduledByRole: z.string().optional(),
+  // Audit snapshot of the SessionOrigin that scheduled this job. Persisted
+  // as opaque z.unknown() because SessionOrigin is recursive (a cron origin
+  // can contain a subagent origin can contain another cron origin, etc.)
+  // and we do not want to mirror that union in the cron schema. The cron
+  // consumer reads this back as-is and stamps it into the firing session's
+  // origin without further validation -- if it's malformed, role
+  // resolution falls back to `guest` via the same path that handles
+  // missing fields.
+  scheduledByOrigin: z.unknown().optional(),
 })
 
 const promptJob = baseJob.extend({
@@ -46,6 +56,93 @@ export type ParseCronOptions = {
   subagents?: SubagentRegistry
 }
 
+// One-shot rewrite for cron.json files that predate PR #171, when
+// `scheduledByRole` became mandatory on every job. The schema gate
+// (`parseCronFile`) rejects legacy entries with a precise remediation
+// message, but rejecting on every container boot is a stuck state for
+// the user — the agent crashes in a tight restart loop with no path
+// forward except hand-editing cron.json.
+//
+// The migration stamps `scheduledByRole: 'owner'` on every job that's
+// missing it. `owner` is the right default for two reasons:
+//   1. Before #171 there was no role concept; every cron job ran with
+//      the same (effectively-owner) privileges the agent had.
+//   2. The schema gate's own error message tells users to add
+//      `"scheduledByRole": "owner"` for manually-authored entries —
+//      we just do it for them.
+//
+// Mirrors `migrateLegacyConfigShape` in src/config/config.ts: pure
+// function, returns the rewritten JSON plus an `applied` array so
+// callers can build a meaningful commit message. Returns `changed:
+// false` on canonical input so the persist + commit path stays
+// untouched on the happy path.
+export type CronMigrationStep = { kind: 'stamp-scheduled-by-role-owner'; jobIds: string[] }
+
+export type CronMigrationResult = { json: unknown; changed: boolean; applied: CronMigrationStep[] }
+
+export function migrateLegacyCronShape(json: unknown): CronMigrationResult {
+  if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+    return { json, changed: false, applied: [] }
+  }
+
+  const obj = json as Record<string, unknown>
+  const jobs = obj.jobs
+  if (!Array.isArray(jobs)) {
+    return { json, changed: false, applied: [] }
+  }
+
+  const stampedIds: string[] = []
+  const nextJobs = jobs.map((job) => {
+    if (typeof job !== 'object' || job === null || Array.isArray(job)) return job
+    const record = job as Record<string, unknown>
+    if ('scheduledByRole' in record) return job
+    const id = typeof record.id === 'string' ? record.id : '<unknown>'
+    stampedIds.push(id)
+    return { ...record, scheduledByRole: 'owner' }
+  })
+
+  if (stampedIds.length === 0) {
+    return { json, changed: false, applied: [] }
+  }
+
+  return {
+    json: { ...obj, jobs: nextJobs },
+    changed: true,
+    applied: [{ kind: 'stamp-scheduled-by-role-owner', jobIds: stampedIds }],
+  }
+}
+
+// Builds a one-line git commit subject (plus enumerating body) for a
+// cron.json migration. Returns null when no steps were applied — callers
+// should not commit in that case. Mirrors `buildConfigMigrationCommitMessage`
+// in src/config/config.ts.
+export function buildCronMigrationCommitMessage(applied: readonly CronMigrationStep[]): string | null {
+  const first = applied[0]
+  if (first === undefined) return null
+
+  const subject =
+    applied.length === 1
+      ? `cron.json: ${shortCronStepLabel(first)}`
+      : `cron.json: migrate legacy shape (${applied.length} steps)`
+
+  const bodyLines: string[] = applied.map((step) => `- ${describeCronStep(step)}`)
+  return `${subject}\n\n${bodyLines.join('\n')}\n`
+}
+
+function shortCronStepLabel(step: CronMigrationStep): string {
+  switch (step.kind) {
+    case 'stamp-scheduled-by-role-owner':
+      return `stamp scheduledByRole: "owner" on ${step.jobIds.length} legacy job${step.jobIds.length === 1 ? '' : 's'}`
+  }
+}
+
+function describeCronStep(step: CronMigrationStep): string {
+  switch (step.kind) {
+    case 'stamp-scheduled-by-role-owner':
+      return `stamp scheduledByRole: "owner" on jobs without provenance (PR #171 backfill): ${step.jobIds.join(', ')}`
+  }
+}
+
 export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {
   const parsed = cronFileSchema.safeParse(raw)
   if (!parsed.success) {
@@ -73,6 +170,13 @@ export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): Par
       return { ok: false, reason: `job ${job.id}: invalid schedule "${job.schedule}": ${message}` }
     }
 
+    if (job.scheduledByRole === undefined) {
+      return {
+        ok: false,
+        reason: `job ${job.id}: missing 'scheduledByRole'. Add "scheduledByRole": "owner" if you authored this entry manually.`,
+      }
+    }
+
     if (job.kind === 'prompt' && job.subagent !== undefined && options.subagents !== undefined) {
       const subagent = options.subagents[job.subagent]
       if (!subagent) {