typeclaw 0.1.1 → 0.1.2

package/src/plugin/types.ts

@@ -97,6 +97,24 @@ export type SessionIdleEvent = {
   origin?: SessionOrigin
 }
 
+// Brackets every `session.prompt(...)` invocation. Distinct from
+// `session.start`/`session.end` (which bracket session lifetime) so that
+// long-lived TUI or channel sessions, which can sit idle between turns,
+// don't wedge a turn-counter forever. `origin` carries the session's origin
+// so observers can exclude their own induced turns when counting (e.g. the
+// backup plugin excludes `subagent: 'backup'` to avoid self-gating).
+export type SessionTurnStartEvent = {
+  sessionId: string
+  agentDir: string
+  origin?: SessionOrigin
+}
+
+export type SessionTurnEndEvent = {
+  sessionId: string
+  agentDir: string
+  origin?: SessionOrigin
+}
+
 // Provider prompt caching requires byte-identical prefixes. Mutations near the
 // end of `event.prompt` preserve cache hits across sessions; mutations near
 // the start invalidate the cache on every LLM call.
@@ -136,6 +154,8 @@ export type Hooks = {
   'session.end'?: (event: SessionEndEvent, ctx: HookContext) => Promise<void> | void
   'session.idle'?: (event: SessionIdleEvent, ctx: HookContext) => Promise<void> | void
   'session.prompt'?: (event: SessionPromptEvent, ctx: HookContext) => Promise<void> | void
+  'session.turn.start'?: (event: SessionTurnStartEvent, ctx: HookContext) => Promise<void> | void
+  'session.turn.end'?: (event: SessionTurnEndEvent, ctx: HookContext) => Promise<void> | void
   'tool.before'?: (event: ToolBeforeEvent, ctx: HookContext) => Promise<ToolBeforeResult> | ToolBeforeResult
   'tool.after'?: (event: ToolAfterEvent, ctx: HookContext) => Promise<void> | void
 }
@@ -164,6 +184,51 @@ export type PluginExports = {
   skills?: Record<string, PluginSkill>
   skillsDirs?: string[]
   hooks?: Hooks
+  doctorChecks?: Record<string, PluginDoctorCheck>
+}
+
+// `typeclaw doctor` plugin extension surface. Each check is read-only by
+// default; declaring `fix.apply` opts the check into `typeclaw doctor --fix`,
+// where the host serializes plugin fixes, validates their `changedPaths`
+// against the agent folder, and commits the union of all fixes in a single
+// commit.
+export type PluginDoctorCheck = {
+  description: string
+  category?: string
+  run: (ctx: PluginDoctorContext) => Promise<PluginCheckResult>
+}
+
+export type PluginDoctorContext = {
+  readonly pluginName: string
+  readonly agentDir: string
+  readonly config: unknown
+  readonly logger: PluginLogger
+}
+
+export type PluginCheckStatus = 'ok' | 'warning' | 'error'
+
+export type PluginCheckResult = {
+  status: PluginCheckStatus
+  message: string
+  details?: string[]
+  fix?: PluginFixSuggestion
+}
+
+export type PluginFixSuggestion = {
+  description: string
+  // When omitted, the fix is advisory-only. `typeclaw doctor --fix` only
+  // attempts to remediate checks whose suggestion includes an `apply`.
+  apply?: (ctx: PluginDoctorContext) => Promise<PluginFixResult>
+}
+
+export type PluginFixResult = {
+  // One-line description that appears in the commit body as a bullet.
+  summary: string
+  // POSIX paths relative to agentDir; the host validates each one stays
+  // inside agentDir before `git add`ing. Absolute paths and `..` segments
+  // are rejected to keep plugin fixes from staging files outside the agent
+  // folder. Empty array is valid (e.g. a fix that only logs).
+  changedPaths: string[]
 }
 
 export type DefinedPlugin<TConfig = never> = {

package/src/run/bundled-plugins.ts

@@ -1,4 +1,5 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
+import backupPlugin from '@/bundled-plugins/backup'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import securityPlugin from '@/bundled-plugins/security'
@@ -16,9 +17,16 @@ import type { ResolvedPlugin } from '@/plugin'
 // Letting `guard` run first would still work today since the two plugins
 // guard disjoint surfaces, but seeding the order now means future overlap
 // (e.g. a security policy on writes) blocks before guard's softer advice.
+//
+// `memory` is registered before `backup` so memory's dreaming commits always
+// land in the same git index window before backup's commit-and-push cycle.
+// They commit disjoint paths today (memory/ vs sessions/ + agent changes),
+// but if either ever holds .git/index.lock the deterministic order makes the
+// contention easier to reason about.
 export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
   { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
+  { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },
   { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },
 ]

package/src/run/index.ts

@@ -142,14 +142,15 @@ export async function startAgent({
     const entry = snap.pluginSubagentByShim.get(subagent)
     if (entry) {
       const sessionId = `subagent-${entry.pluginName}-${crypto.randomUUID()}`
+      const origin = {
+        kind: 'subagent' as const,
+        subagent: subagentOptions?.name ?? entry.subagentName,
+        parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
+      }
       const created = await createSessionWithDispose({
         systemPromptOverride: entry.pluginSubagent.systemPrompt,
         channelRouter: channelManager.router,
-        origin: {
-          kind: 'subagent',
-          subagent: subagentOptions?.name ?? entry.subagentName,
-          parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
-        },
+        origin,
         plugins: {
           registry: snap.registry,
           hooks: snap.hooks,
@@ -167,6 +168,8 @@ export async function startAgent({
         ...created,
         hooks: snap.hooks,
         sessionId,
+        agentDir: cwd,
+        origin,
       }
     }
     return defaultCreateSessionForSubagent(subagent, subagentOptions)
@@ -221,6 +224,8 @@ export async function startAgent({
         prompt: (text) => session.prompt(text),
         dispose: () => session.dispose(),
         sessionId,
+        agentDir: cwd,
+        origin: { kind: 'cron' as const, jobId: job.id, jobKind: 'prompt' as const },
         ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
         getTranscriptPath: () => sessionManager.getSessionFile(),
       }

package/src/server/index.ts

@@ -6,6 +6,7 @@ import {
   type CreateSessionOptions,
   type CreateSessionResult,
 } from '@/agent'
+import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { ChannelRouter } from '@/channels/router'
 import type { HookBus } from '@/plugin'
@@ -159,7 +160,7 @@ export function createServer({
 
           if (stream) {
             state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
-              enqueuePrompt(ws, state, msg),
+              enqueuePrompt(ws, state, msg, agentDir),
             )
 
             state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
@@ -190,6 +191,16 @@ export function createServer({
             return
           }
 
+          if (msg.type === 'doctor') {
+            await handleDoctor(ws, msg.requestId, pluginRuntime, agentDir)
+            return
+          }
+
+          if (msg.type === 'doctor_fix') {
+            await handleDoctorFix(ws, msg.requestId, msg.checkId, pluginRuntime, agentDir)
+            return
+          }
+
           if (msg.type === 'abort') {
             if (!state) return
             await state.session.abort()
@@ -215,13 +226,27 @@ export function createServer({
               return
             }
             send(ws, { type: 'prompt_started', messageId: `local-${crypto.randomUUID()}`, text: msg.text })
+            const fallbackHooks = state.runtimeSnapshot?.hooks
+            if (fallbackHooks !== undefined && agentDir !== undefined) {
+              await fallbackHooks.runSessionTurnStart({
+                sessionId: state.sessionFileId,
+                agentDir,
+                origin: state.origin,
+              })
+            }
             try {
               await state.session.prompt(msg.text)
               send(ws, { type: 'done' })
             } catch (err) {
               send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
             }
-            const fallbackHooks = state.runtimeSnapshot?.hooks
+            if (fallbackHooks !== undefined && agentDir !== undefined) {
+              await fallbackHooks.runSessionTurnEnd({
+                sessionId: state.sessionFileId,
+                agentDir,
+                origin: state.origin,
+              })
+            }
             if (fallbackHooks !== undefined) {
               await fallbackHooks.runSessionIdle({
                 sessionId: state.sessionFileId,
@@ -323,7 +348,7 @@ function forwardAssistantError(ws: Ws, message: unknown): void {
   send(ws, { type: 'error', message: text })
 }
 
-function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage): void {
+function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage, agentDir: string | undefined): void {
   const payload = msg.payload as { kind?: string; text?: string; delivery?: PromptDelivery }
   if (payload?.kind !== 'prompt' || typeof payload.text !== 'string') return
   const delivery: PromptDelivery = payload.delivery ?? 'queue'
@@ -339,7 +364,7 @@ function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage): void {
     ts: msg.ts,
   })
   pushQueueState(ws, state)
-  void drain(ws, state)
+  void drain(ws, state, agentDir)
 }
 
 // `session.idle` semantically means "the agent finished a prompt and is now
@@ -360,10 +385,26 @@ function makeIdleHookCaller(state: SessionState): () => Promise<void> {
   }
 }
 
-async function drain(ws: Ws, state: SessionState): Promise<void> {
+function makeTurnHookCallers(
+  state: SessionState,
+  agentDir: string | undefined,
+): { fireTurnStart: () => Promise<void>; fireTurnEnd: () => Promise<void> } {
+  const hooks: HookBus | undefined = state.runtimeSnapshot?.hooks
+  if (hooks === undefined || agentDir === undefined) {
+    return { fireTurnStart: async () => {}, fireTurnEnd: async () => {} }
+  }
+  const event = { sessionId: state.sessionFileId, agentDir, origin: state.origin }
+  return {
+    fireTurnStart: () => hooks.runSessionTurnStart(event),
+    fireTurnEnd: () => hooks.runSessionTurnEnd(event),
+  }
+}
+
+async function drain(ws: Ws, state: SessionState, agentDir: string | undefined): Promise<void> {
   if (state.draining) return
   state.draining = true
   const fireIdle = makeIdleHookCaller(state)
+  const { fireTurnStart, fireTurnEnd } = makeTurnHookCallers(state, agentDir)
   try {
     while (state.drainQueue.length > 0) {
       const item = state.drainQueue.shift()
@@ -371,12 +412,14 @@ async function drain(ws: Ws, state: SessionState): Promise<void> {
       pushQueueState(ws, state)
       send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
 
+      await fireTurnStart()
       try {
         await state.session.prompt(item.text)
         send(ws, { type: 'done' })
       } catch (err) {
         send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
       }
+      await fireTurnEnd()
       await fireIdle()
     }
   } finally {
@@ -393,6 +436,61 @@ function pushQueueState(ws: Ws, state: SessionState): void {
   send(ws, { type: 'queue_state', pending })
 }
 
+async function handleDoctor(
+  ws: Ws,
+  requestId: string,
+  pluginRuntime: PluginRuntime | undefined,
+  agentDir: string | undefined,
+): Promise<void> {
+  if (pluginRuntime === undefined || agentDir === undefined) {
+    send(ws, { type: 'doctor_result', requestId, checks: [] })
+    return
+  }
+  const snapshot = pluginRuntime.get()
+  if (snapshot === undefined) {
+    send(ws, { type: 'doctor_result', requestId, checks: [] })
+    return
+  }
+  try {
+    const checks = await runPluginDoctorChecks({ registry: snapshot.registry, agentDir })
+    send(ws, { type: 'doctor_result', requestId, checks })
+  } catch (err) {
+    send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
+  }
+}
+
+async function handleDoctorFix(
+  ws: Ws,
+  requestId: string,
+  checkId: string,
+  pluginRuntime: PluginRuntime | undefined,
+  agentDir: string | undefined,
+): Promise<void> {
+  if (pluginRuntime === undefined || agentDir === undefined) {
+    send(ws, {
+      type: 'doctor_fix_result',
+      requestId,
+      result: { ok: false, checkId, error: 'plugin runtime not configured' },
+    })
+    return
+  }
+  const snapshot = pluginRuntime.get()
+  if (snapshot === undefined) {
+    send(ws, {
+      type: 'doctor_fix_result',
+      requestId,
+      result: { ok: false, checkId, error: 'plugin runtime not configured' },
+    })
+    return
+  }
+  const outcome = await runPluginDoctorFix({ registry: snapshot.registry, agentDir, checkId })
+  const result =
+    outcome.ok === true
+      ? { ok: true as const, checkId, summary: outcome.summary, changedPaths: outcome.changedPaths }
+      : { ok: false as const, checkId, error: outcome.error }
+  send(ws, { type: 'doctor_fix_result', requestId, result })
+}
+
 async function handleReload(
   ws: Ws,
   reloadAll: ReloadAllFn | undefined,

package/src/shared/index.ts

@@ -1,5 +1,8 @@
 export {
   type ClientMessage,
+  type DoctorCheckPayload,
+  type DoctorFixPayload,
+  type DoctorRequestId,
   type PromptDelivery,
   type QueueStateItem,
   type ReloadResultPayload,

package/src/shared/protocol.ts

@@ -4,11 +4,31 @@ export type ReloadResultPayload =
 
 export type PromptDelivery = 'queue' | 'steer' | 'interrupt'
 
+export type DoctorRequestId = string
+
+export type DoctorCheckPayload = {
+  id: string
+  pluginName: string
+  checkName: string
+  description: string
+  category: string
+  status: 'ok' | 'warning' | 'error'
+  message: string
+  details?: string[]
+  fix?: { description: string; hasApply: boolean }
+}
+
+export type DoctorFixPayload =
+  | { ok: true; checkId: string; summary: string; changedPaths: string[] }
+  | { ok: false; checkId: string; error: string }
+
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }
   | { type: 'reload'; scope?: string }
   | { type: 'abort' }
   | { type: 'queue_cancel'; messageId: string }
+  | { type: 'doctor'; requestId: DoctorRequestId }
+  | { type: 'doctor_fix'; requestId: DoctorRequestId; checkId: string }
 
 export type QueueStateItem = { id: string; text: string; ts: number }
 
@@ -23,3 +43,5 @@ export type ServerMessage =
   | { type: 'notification'; payload: unknown; replyTo?: string; meta?: Record<string, string> }
   | { type: 'queue_state'; pending: QueueStateItem[] }
   | { type: 'prompt_started'; messageId: string; text: string }
+  | { type: 'doctor_result'; requestId: DoctorRequestId; checks: DoctorCheckPayload[] }
+  | { type: 'doctor_fix_result'; requestId: DoctorRequestId; result: DoctorFixPayload }

package/src/skills/typeclaw-config/SKILL.md

@@ -403,7 +403,7 @@ RUN apt-get install ... <baseline + enabled toggle packages>   ← toggles fan o
 ENV NODE_ENV=production
 # Custom lines from typeclaw.json#dockerfile.append.   ← only emitted when append is non-empty
 <your appended lines>
-ENTRYPOINT ["bun", "run", "typeclaw"]
+ENTRYPOINT ["/usr/local/bin/typeclaw-entrypoint"]
 CMD ["run"]
 ```
 

package/typeclaw.schema.json

@@ -706,6 +706,18 @@
         "allow"
       ]
     },
+    "network": {
+      "default": {
+        "blockInternal": false
+      },
+      "type": "object",
+      "properties": {
+        "blockInternal": {
+          "default": false,
+          "type": "boolean"
+        }
+      }
+    },
     "dockerfile": {
       "default": {
         "ffmpeg": false,
@@ -816,6 +828,44 @@
           }
         }
       }
+    },
+    "backup": {
+      "default": {
+        "enabled": true,
+        "idleMs": 30000,
+        "pushToOrigin": true,
+        "commitTimeoutMs": 30000,
+        "networkTimeoutMs": 60000
+      },
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "idleMs": {
+          "default": 30000,
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 9007199254740991
+        },
+        "pushToOrigin": {
+          "default": true,
+          "type": "boolean"
+        },
+        "commitTimeoutMs": {
+          "default": 30000,
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "networkTimeoutMs": {
+          "default": 60000,
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        }
+      }
     }
   },
   "additionalProperties": {}