typeclaw 0.1.1 → 0.1.3

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"]
 ```
 
@@ -539,17 +539,56 @@ Do **not** edit `typeclaw.json` to a model the registry doesn't know, even if th
 
 `typeclaw.json` does **not** hold API keys or OAuth tokens. Credentials live in two gitignored files:
 
-- **`./.env`** (API key providers): the env var depends on which provider's model you've selected.
-  - `OPENAI_API_KEY` — required for any `openai/...` model.
-  - `FIREWORKS_API_KEY` — required for any `fireworks/...` model.
-- **`./secrets.json`** (OAuth providers): structured JSON file managed by `pi-coding-agent`'s `AuthStorage`, wrapped by `SecretsBackend`. Contains refresh + access tokens. The container refreshes tokens on its own with file locking; the host writes once at `typeclaw init` time when the user picks "OAuth (browser login)". (Pre-rename agent folders may carry the file as `auth.json`; it is migrated to `secrets.json` on the next agent boot.)
-  - `openai-codex/...` models — credentials persisted under the `llm` slice as `{ "llm": { "openai-codex": { "type": "oauth", ... } } }`.
+- **`./.env`** (any environment variable, including API keys): plain `KEY=value` lines, loaded by Docker via `--env-file` at container start. The canonical env-var names per provider:
+  - `OPENAI_API_KEY` — for any `openai/...` model.
+  - `FIREWORKS_API_KEY` — for any `fireworks/...` model.
+- **`./secrets.json`** (structured store): a `v2` envelope managed by `SecretsBackend` (wraps `pi-coding-agent`'s `AuthStorage`). Two top-level slices:
+  - `providers.*` — per-provider credentials. API-key providers store `{ type: 'api_key', key: <Secret> }`. OAuth providers store the `pi-coding-agent` token blob `{ type: 'oauth', access_token, refresh_token, expires_at, ... }`. The container auto-refreshes OAuth tokens with file locking; api-key writes only happen on explicit user-driven rotation.
+  - `channels.*` — per-adapter credentials, with named fields per adapter:
+    - `discord-bot: { token: <Secret> }`
+    - `slack-bot: { botToken: <Secret>, appToken: <Secret> }`
+    - `telegram-bot: { token: <Secret> }`
 
-If a user wants to switch from API key to OAuth (or vice versa) for a provider that supports both, the easiest path is to delete the relevant entry from `.env` / `secrets.json` and re-run `typeclaw init` from inside the agent folder — it'll prompt for the auth method again.
+  (Pre-v2 agent folders carry the older `llm` slice and channel-env-var-keyed shape; they are upgraded transparently on first read. Pre-rename folders may even carry the file as `auth.json`; it is renamed to `secrets.json` on the next boot.)
 
-If the user wants to rotate or change the key, edit `.env`, not `typeclaw.json`. After editing `.env`, the same restart rule applies: `typeclaw restart` on the host stage.
+### The `Secret` shape and env-wins resolution
 
-Never echo, log, or commit values from `.env`. `.env` is gitignored by default — keep it that way.
+Every secret-bearing field in `secrets.json` is a **`Secret`**: either a plain string or an object `{ value?, env? }`.
+
+```json
+{
+  "version": 2,
+  "providers": {
+    "fireworks": { "type": "api_key", "key": "fw_xxx" },
+    "openai-codex": { "type": "oauth", "access_token": "...", "refresh_token": "...", "expires_at": 99 }
+  },
+  "channels": {
+    "slack-bot": {
+      "botToken": "xoxb-...",
+      "appToken": { "value": "xapp-...", "env": "MY_CUSTOM_SLACK_APP_TOKEN" }
+    }
+  }
+}
+```
+
+**Resolution at boot, in order:**
+
+1. `process.env[secret.env]` — explicit binding wins (the `env` field on the object form).
+2. `process.env[<canonical env name>]` — canonical-env fallback (`SLACK_BOT_TOKEN`, `FIREWORKS_API_KEY`, etc.).
+3. `secret.value` — the on-disk value.
+4. Otherwise the field is treated as missing.
+
+**Env wins, the file is never auto-mutated.** When the env var is set, that value is used in-memory via `setRuntimeApiKey` (api-keys) or `process.env` injection (channels) — `secrets.json` is **not** rewritten to capture the env value. The user's file stays user-owned.
+
+**Custom env-var binding** — the optional `env` field on the object form lets the user route a credential through an env var of their choosing (e.g., a CI system that exposes `MY_PROD_SLACK_TOKEN` instead of `SLACK_BOT_TOKEN`).
+
+### Switching credentials
+
+If a user wants to switch from API key to OAuth (or vice versa) for a provider that supports both, the easiest path is to delete the relevant entry from `.env` / `secrets.json#providers` and re-run `typeclaw init` from inside the agent folder — it'll prompt for the auth method again.
+
+If the user wants to rotate an api-key, edit either `.env` (env-wins picks it up immediately) or `secrets.json#providers.<provider>.key` (rewrite the `value` field, or remove the entry if the env var should take over). After either, `typeclaw restart` on the host stage.
+
+Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitignored by default — keep them that way.
 
 ## Editing `typeclaw.json` safely
 

package/typeclaw.schema.json

@@ -706,6 +706,18 @@
         "allow"
       ]
     },
+    "network": {
+      "default": {
+        "blockInternal": true
+      },
+      "type": "object",
+      "properties": {
+        "blockInternal": {
+          "default": true,
+          "type": "boolean"
+        }
+      }
+    },
     "dockerfile": {
       "default": {
         "ffmpeg": false,
@@ -780,6 +792,40 @@
         }
       }
     },
+    "tool-result-cap": {
+      "default": {
+        "enabled": true,
+        "imageMaxBytes": 262144,
+        "textMaxBytes": 65536,
+        "exemptTools": []
+      },
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "imageMaxBytes": {
+          "default": 262144,
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 9007199254740991
+        },
+        "textMaxBytes": {
+          "default": 65536,
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 9007199254740991
+        },
+        "exemptTools": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "memory": {
       "default": {
         "idleMs": 10000,
@@ -816,6 +862,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": {}

package/src/secrets/env.ts

@@ -1,43 +0,0 @@
-import { readFileSync, writeFileSync } from 'node:fs'
-
-// No-op when the file is missing or the key is absent: the caller has
-// already persisted to `secrets.json` and just wants `.env` to stop being a
-// second source of truth. Parsing matches `parseEnvKeys` in
-// `src/init/index.ts` — line-based, trim, skip blanks/comments, split on the
-// first `=`. Duplicate assignments to the same key are all removed because
-// dotenv resolves "last wins" so every duplicate carries the value we just
-// promoted.
-export function stripEnvKey(path: string, key: string): void {
-  let original: string
-  try {
-    original = readFileSync(path, 'utf8')
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
-    throw error
-  }
-
-  const next = removeKeyFromEnvText(original, key)
-  if (next === original) return
-  writeFileSync(path, next)
-}
-
-export function removeKeyFromEnvText(content: string, key: string): string {
-  const lines = content.split('\n')
-  const kept: string[] = []
-  for (const line of lines) {
-    const trimmed = line.trim()
-    if (trimmed === '' || trimmed.startsWith('#')) {
-      kept.push(line)
-      continue
-    }
-    const eq = trimmed.indexOf('=')
-    if (eq <= 0) {
-      kept.push(line)
-      continue
-    }
-    const lineKey = trimmed.slice(0, eq).trim()
-    if (lineKey === key) continue
-    kept.push(line)
-  }
-  return kept.join('\n')
-}