typeclaw 0.38.1 → 0.39.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +5 -0
  2. package/package.json +2 -2
  3. package/src/agent/attention-escalation.ts +158 -7
  4. package/src/agent/auth.ts +2 -2
  5. package/src/agent/git-nudge.ts +7 -7
  6. package/src/agent/index.ts +25 -2
  7. package/src/agent/restart/index.ts +17 -8
  8. package/src/agent/session-origin.ts +21 -0
  9. package/src/agent/subagents.ts +29 -1
  10. package/src/agent/system-prompt.ts +18 -5
  11. package/src/agent/tools/restart.ts +0 -3
  12. package/src/agent/tools/spawn-subagent.ts +7 -0
  13. package/src/bundled-plugins/backup/index.ts +5 -2
  14. package/src/bundled-plugins/backup/runner.ts +55 -23
  15. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +7 -8
  16. package/src/bundled-plugins/memory/dreaming.ts +37 -24
  17. package/src/bundled-plugins/memory/index.ts +24 -6
  18. package/src/bundled-plugins/memory/memory-logger.ts +14 -10
  19. package/src/bundled-plugins/operator/operator.ts +1 -0
  20. package/src/channels/adapters/kakaotalk-membership.ts +67 -0
  21. package/src/channels/adapters/kakaotalk.ts +8 -0
  22. package/src/channels/adapters/line-token.ts +55 -0
  23. package/src/channels/adapters/line.ts +74 -0
  24. package/src/channels/adapters/webex-bot-classify.ts +14 -1
  25. package/src/channels/adapters/webex-bot.ts +24 -1
  26. package/src/channels/adapters/webex-classify.ts +16 -1
  27. package/src/channels/adapters/webex.ts +27 -1
  28. package/src/channels/router.ts +55 -2
  29. package/src/cli/hostd.ts +40 -0
  30. package/src/cli/model.ts +143 -3
  31. package/src/config/config.ts +101 -36
  32. package/src/config/index.ts +3 -0
  33. package/src/config/models-mutation.ts +105 -15
  34. package/src/config/providers-mutation.ts +4 -4
  35. package/src/config/providers.ts +6 -14
  36. package/src/container/shared.ts +136 -14
  37. package/src/container/shell.ts +12 -2
  38. package/src/container/start.ts +25 -7
  39. package/src/doctor/commit.ts +10 -10
  40. package/src/dreams/git.ts +20 -7
  41. package/src/dreams/index.ts +22 -7
  42. package/src/git/reconcile-ignored.ts +56 -27
  43. package/src/git/resolve-agent-git.ts +12 -0
  44. package/src/git/system-commit.ts +16 -10
  45. package/src/hostd/daemon.ts +16 -0
  46. package/src/hostd/index.ts +1 -11
  47. package/src/hostd/paths.ts +0 -16
  48. package/src/hostd/webex-renewal-manager.ts +216 -0
  49. package/src/init/dockerfile.ts +13 -4
  50. package/src/init/gitignore.ts +4 -2
  51. package/src/run/index.ts +4 -1
  52. package/src/secrets/schema.ts +1 -0
  53. package/src/secrets/webex-renewal.ts +215 -0
  54. package/src/server/index.ts +25 -3
  55. package/src/skills/typeclaw-config/SKILL.md +18 -16
  56. package/typeclaw.schema.json +172 -1
package/src/run/index.ts CHANGED
@@ -13,6 +13,7 @@ import {
13
13
  defaultCreateSessionForSubagent,
14
14
  invokeSubagent,
15
15
  isSubagentTimeoutError,
16
+ resolveSubagentProfile,
16
17
  type Subagent as InternalSubagent,
17
18
  type SubagentConsumer,
18
19
  type SubagentRegistry,
@@ -409,7 +410,9 @@ export async function startAgent({
409
410
  allowBackgroundFromSubagent,
410
411
  }
411
412
  : {}),
412
- ...(entry.pluginSubagent.profile !== undefined ? { profile: entry.pluginSubagent.profile } : {}),
413
+ ...(resolveSubagentProfile(entry.pluginSubagent, subagentOptions) !== undefined
414
+ ? { profile: resolveSubagentProfile(entry.pluginSubagent, subagentOptions) }
415
+ : {}),
413
416
  ...(entry.pluginSubagent.toolResultBudget !== undefined
414
417
  ? { toolResultBudget: entry.pluginSubagent.toolResultBudget }
415
418
  : {}),
@@ -193,6 +193,7 @@ export type PendingLoginRecord = z.infer<typeof kakaoPendingLoginRecordSchema>
193
193
  export type KakaoChannelBlock = z.infer<typeof kakaoChannelBlockSchema>
194
194
  export type WebexAccountRecord = z.infer<typeof webexAccountRecordSchema>
195
195
  export type WebexChannelBlock = z.infer<typeof webexChannelBlockSchema>
196
+ export type WebexEncryptedPassword = z.infer<typeof webexEncryptedPasswordSchema>
196
197
  export type SecretsFile = z.infer<typeof secretsFileSchema>
197
198
 
198
199
  export type ParseSecretsResult = { ok: true; file: SecretsFile } | { ok: false; reason: string }
@@ -0,0 +1,215 @@
1
+ import { join } from 'node:path'
2
+
3
+ import { loginWithPassword as upstreamLoginWithPassword } from 'agent-messenger/webex'
4
+
5
+ import { decrypt, EncryptionError } from './encryption'
6
+ import { type KeyStore, KeyStoreError } from './keys'
7
+ import { type WebexChannelBlock } from './schema'
8
+ import { SecretsBackend } from './storage'
9
+ import { SecretsWebexCredentialStore } from './webex-store'
10
+
11
+ // Webex password-login access tokens live ~27h. The daily renewal tick fires
12
+ // every 24h, so a token must be refreshed while it still has more than one
13
+ // tick-interval of life left — otherwise it expires in the gap between two
14
+ // ticks and every REST call (send, history, KMS key fetch) 401s while the
15
+ // Mercury listener stays connected on its already-authenticated socket. We
16
+ // renew when the token is within 8h of `expires_at`: that clears a full 24h
17
+ // tick plus headroom for host sleep / daemon respawn, and a fresh token
18
+ // minted on each tick keeps the window comfortably ahead of expiry.
19
+ export const RENEWAL_WINDOW_MS = 8 * 60 * 60 * 1000
20
+
21
+ export type WebexRenewalDecision =
22
+ | { kind: 'skip'; reason: 'no_account' | 'fresh_enough'; expiresInMs?: number }
23
+ | {
24
+ kind: 'reauth_required'
25
+ reason: 'no_password' | 'no_email' | 'key_missing' | 'decrypt_failed'
26
+ message: string
27
+ }
28
+ | { kind: 'should_renew'; account: WebexAccountSnapshot; password: string }
29
+
30
+ export type WebexAccountSnapshot = {
31
+ account_id: string
32
+ email: string
33
+ created_at: string
34
+ updated_at: string
35
+ }
36
+
37
+ export type WebexRenewalAttempt =
38
+ | { kind: 'ok'; account_id: string; previousExpiresAt: number; nextExpiresAt: number }
39
+ | { kind: 'reauth_required'; account_id: string; reason: string; message: string }
40
+ | { kind: 'transient_failure'; account_id: string; reason: string }
41
+
42
+ export type LoginWithPasswordFn = typeof upstreamLoginWithPassword
43
+
44
+ export type WebexRenewalContext = {
45
+ containerName: string
46
+ agentDir: string
47
+ keyStore: KeyStore
48
+ now?: () => number
49
+ loginWithPassword?: LoginWithPasswordFn
50
+ idbrokerHost?: string
51
+ }
52
+
53
+ export async function decideRenewal(block: WebexChannelBlock, ctx: WebexRenewalContext): Promise<WebexRenewalDecision> {
54
+ const accountId = block.currentAccount
55
+ if (!accountId) return { kind: 'skip', reason: 'no_account' }
56
+ const account = block.accounts[accountId]
57
+ if (!account) return { kind: 'skip', reason: 'no_account' }
58
+
59
+ const now = (ctx.now ?? Date.now)()
60
+ const expiresInMs = account.expires_at - now
61
+ if (Number.isFinite(expiresInMs) && expiresInMs > RENEWAL_WINDOW_MS) {
62
+ return { kind: 'skip', reason: 'fresh_enough', expiresInMs }
63
+ }
64
+
65
+ if (!account.email) {
66
+ return {
67
+ kind: 'reauth_required',
68
+ reason: 'no_email',
69
+ message: `Webex account ${accountId} has no stored email — run \`typeclaw channel reauth webex\`.`,
70
+ }
71
+ }
72
+ if (!account.encryptedPassword) {
73
+ return {
74
+ kind: 'reauth_required',
75
+ reason: 'no_password',
76
+ message: `Webex account ${accountId} has no stored password — run \`typeclaw channel reauth webex\`.`,
77
+ }
78
+ }
79
+
80
+ let plaintextPassword: string
81
+ try {
82
+ const key = await ctx.keyStore.read(ctx.containerName)
83
+ plaintextPassword = decrypt(account.encryptedPassword, key, {
84
+ containerName: ctx.containerName,
85
+ accountId: account.account_id,
86
+ })
87
+ } catch (err) {
88
+ return classifyDecryptFailure(err, accountId)
89
+ }
90
+
91
+ return {
92
+ kind: 'should_renew',
93
+ account: {
94
+ account_id: account.account_id,
95
+ email: account.email,
96
+ created_at: account.created_at,
97
+ updated_at: account.updated_at,
98
+ },
99
+ password: plaintextPassword,
100
+ }
101
+ }
102
+
103
+ export async function renewCurrentAccount(
104
+ ctx: WebexRenewalContext,
105
+ ): Promise<WebexRenewalAttempt | { kind: 'skipped'; reason: string; expiresInMs?: number }> {
106
+ const secretsPath = join(ctx.agentDir, 'secrets.json')
107
+ const backend = new SecretsBackend(secretsPath)
108
+ const block = backend.readChannelsSync()?.webex
109
+ const parsed = parseBlockOrEmpty(block)
110
+ const decision = await decideRenewal(parsed, ctx)
111
+
112
+ if (decision.kind === 'skip') {
113
+ return {
114
+ kind: 'skipped',
115
+ reason: decision.reason,
116
+ ...(decision.expiresInMs !== undefined ? { expiresInMs: decision.expiresInMs } : {}),
117
+ }
118
+ }
119
+ if (decision.kind === 'reauth_required') {
120
+ return {
121
+ kind: 'reauth_required',
122
+ account_id: parsed.currentAccount ?? '',
123
+ reason: decision.reason,
124
+ message: decision.message,
125
+ }
126
+ }
127
+
128
+ const loginWithPassword = ctx.loginWithPassword ?? upstreamLoginWithPassword
129
+ const loginOptions = ctx.idbrokerHost !== undefined ? { idbrokerHost: ctx.idbrokerHost } : undefined
130
+
131
+ let result: Awaited<ReturnType<LoginWithPasswordFn>>
132
+ try {
133
+ result = await loginWithPassword(decision.account.email, decision.password, loginOptions)
134
+ } catch (err) {
135
+ return classifyLoginFailure(err, decision.account.account_id)
136
+ }
137
+
138
+ // The renewed login resolves to the same Webex user, so reuse the stored
139
+ // account_id rather than `result.userId`: the store keys accounts by id and a
140
+ // drifted id would orphan the record (and its encryptedPassword) instead of
141
+ // updating it. `setAccount` merges and preserves email/encryptedPassword.
142
+ const store = new SecretsWebexCredentialStore({ mode: 'host', secretsPath })
143
+ const nowIso = new Date().toISOString()
144
+ const previousExpiresAt = parsed.accounts[decision.account.account_id]?.expires_at ?? 0
145
+ await store.setAccount({
146
+ account_id: decision.account.account_id,
147
+ access_token: result.accessToken,
148
+ refresh_token: result.refreshToken,
149
+ expires_at: result.expiresAt,
150
+ device_url: result.deviceUrl,
151
+ user_id: result.userId,
152
+ created_at: decision.account.created_at,
153
+ updated_at: nowIso,
154
+ email: decision.account.email,
155
+ })
156
+
157
+ return {
158
+ kind: 'ok',
159
+ account_id: decision.account.account_id,
160
+ previousExpiresAt,
161
+ nextExpiresAt: result.expiresAt,
162
+ }
163
+ }
164
+
165
+ function parseBlockOrEmpty(value: unknown): WebexChannelBlock {
166
+ if (value === undefined) return { currentAccount: null, accounts: {} }
167
+ return value as WebexChannelBlock
168
+ }
169
+
170
+ function classifyLoginFailure(err: unknown, accountId: string): WebexRenewalAttempt {
171
+ const message = err instanceof Error ? err.message : String(err)
172
+ // agent-messenger's loginWithPassword throws WebexError with a `code` for
173
+ // unrecoverable auth states (SSO/IdP or MFA accounts that headless password
174
+ // login can't satisfy). Those need human reauth; everything else (network,
175
+ // 5xx, transient idbroker hiccup) is retried on the next tick.
176
+ const code = (err as { code?: unknown })?.code
177
+ if (code === 'sso_required' || code === 'mfa_required') {
178
+ return {
179
+ kind: 'reauth_required',
180
+ account_id: accountId,
181
+ reason: String(code),
182
+ message: `${message} — run \`typeclaw channel reauth webex\`.`,
183
+ }
184
+ }
185
+ return { kind: 'transient_failure', account_id: accountId, reason: message }
186
+ }
187
+
188
+ function classifyDecryptFailure(err: unknown, accountId: string): WebexRenewalDecision {
189
+ if (err instanceof KeyStoreError) {
190
+ if (err.code === 'missing') {
191
+ return {
192
+ kind: 'reauth_required',
193
+ reason: 'key_missing',
194
+ message: `Encryption key missing for Webex account ${accountId} — run \`typeclaw channel reauth webex\` to mint a fresh one.`,
195
+ }
196
+ }
197
+ return {
198
+ kind: 'reauth_required',
199
+ reason: 'key_missing',
200
+ message: `Encryption key for Webex account ${accountId} is unusable (${err.code}: ${err.message}). Move it aside and run \`typeclaw channel reauth webex\` to mint a fresh one.`,
201
+ }
202
+ }
203
+ if (err instanceof EncryptionError) {
204
+ return {
205
+ kind: 'reauth_required',
206
+ reason: 'decrypt_failed',
207
+ message: `Could not decrypt stored Webex password (${err.code}) — run \`typeclaw channel reauth webex\`.`,
208
+ }
209
+ }
210
+ return {
211
+ kind: 'reauth_required',
212
+ reason: 'decrypt_failed',
213
+ message: `Could not decrypt stored Webex password (${err instanceof Error ? err.message : String(err)}).`,
214
+ }
215
+ }
@@ -8,7 +8,7 @@ import {
8
8
  type CreateSessionOptions,
9
9
  type CreateSessionResult,
10
10
  } from '@/agent'
11
- import { applyTurnThinkingLevel } from '@/agent/attention-escalation'
11
+ import { applyTurnThinkingLevel, getQuestionSignal, type QuestionSignal } from '@/agent/attention-escalation'
12
12
  import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
13
13
  import type { LiveSessionRegistry } from '@/agent/live-sessions'
14
14
  import type { LiveSubagentRegistry } from '@/agent/live-subagents'
@@ -165,6 +165,14 @@ type TunnelLogsWs = ServerWebSocket<TunnelLogsWsData>
165
165
  type InspectWs = ServerWebSocket<InspectWsData>
166
166
  type AnyOwnerWs = Ws | CommandWs
167
167
 
168
+ // A turn whose assistant leaf aborted or errored never produced a usable turn,
169
+ // so its question shape must not seed the next turn's cross-turn escalation.
170
+ function tuiTurnLeafFailed(session: AgentSession): boolean {
171
+ const leaf = session.sessionManager?.getLeafEntry()
172
+ if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return false
173
+ return leaf.message.stopReason === 'aborted' || leaf.message.stopReason === 'error'
174
+ }
175
+
168
176
  type QueuedPrompt = {
169
177
  streamMessageId: StreamMessageId
170
178
  text: string
@@ -180,6 +188,9 @@ type SessionState = {
180
188
  // loop, no-stream fallback) can use the live getter as the reset target — both
181
189
  // read this captured default instead.
182
190
  turnThinkingDefault: AgentSession['thinkingLevel']
191
+ // Prior real user turn's question shape, for cross-turn "Jeff Bezos" escalation.
192
+ // Null until the first user turn; carried turn-to-turn within this session only.
193
+ lastQuestionSignal: QuestionSignal | null
183
194
  sessionFileId: string
184
195
  origin: SessionOrigin
185
196
  sessionManager: { getSessionFile: () => string | undefined } | undefined
@@ -525,6 +536,7 @@ export function createServer({
525
536
  const state: SessionState = {
526
537
  session,
527
538
  turnThinkingDefault: session.thinkingLevel,
539
+ lastQuestionSignal: null,
528
540
  sessionFileId,
529
541
  origin,
530
542
  sessionManager,
@@ -789,8 +801,12 @@ export function createServer({
789
801
  retrievalContext.results.length > 0
790
802
  ? `${renderTurnTimeAnchor()}\n\n${msg.text}\n\n${retrievalContext.results}`
791
803
  : `${renderTurnTimeAnchor()}\n\n${msg.text}`
792
- applyTurnThinkingLevel(state.session, msg.text, state.turnThinkingDefault)
804
+ applyTurnThinkingLevel(state.session, msg.text, state.turnThinkingDefault, state.lastQuestionSignal)
793
805
  await state.session.prompt(turnText)
806
+ // A usable turn seeds the next turn's escalation; a failed leaf must
807
+ // CLEAR the prior signal (not just skip), else an older question
808
+ // leaks across the failed turn and wrongly escalates the next one.
809
+ state.lastQuestionSignal = tuiTurnLeafFailed(state.session) ? null : getQuestionSignal(msg.text)
794
810
  send(ws, doneMessage(state))
795
811
  } catch (err) {
796
812
  const message = err instanceof Error ? err.message : String(err)
@@ -1094,8 +1110,14 @@ async function drain(
1094
1110
  retrievalContext.results.length > 0
1095
1111
  ? `${renderTurnTimeAnchor()}\n\n${item.text}\n\n${retrievalContext.results}`
1096
1112
  : `${renderTurnTimeAnchor()}\n\n${item.text}`
1097
- applyTurnThinkingLevel(state.session, item.text, state.turnThinkingDefault)
1113
+ applyTurnThinkingLevel(state.session, item.text, state.turnThinkingDefault, state.lastQuestionSignal)
1098
1114
  await state.session.prompt(turnText)
1115
+ // Only real user turns move the signal: a usable turn seeds it, a failed
1116
+ // leaf CLEARS it (else an older question leaks across the failed turn).
1117
+ // Todo-continuation turns are not user turns, so they leave it untouched.
1118
+ if (item.source !== TODO_CONTINUATION_SOURCE) {
1119
+ state.lastQuestionSignal = tuiTurnLeafFailed(state.session) ? null : getQuestionSignal(item.text)
1120
+ }
1099
1121
  send(ws, doneMessage(state))
1100
1122
  } catch (err) {
1101
1123
  const message = err instanceof Error ? err.message : String(err)
@@ -15,6 +15,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
15
15
 
16
16
  - `port` — the TCP port the websocket server binds to inside the container. The TUI on the host stage connects to this. Default `8973`. **Restart-required.**
17
17
  - `model` — a fully-qualified `<provider>/<model-id>` string. The runtime resolves this against the built-in provider registry to decide which API to call for every turn. **Live-reloadable.**
18
+ - `thinkingLevel` (per-profile) — reasoning effort lives **inside `models`**, not as a top-level field. A profile value may be an object like `{ "model": "<ref>", "thinkingLevel": "high" }` (or `{ "models": ["<ref>", …], "thinkingLevel": … }` for a chain). A session resolves its effort as **the profile's own level → the `default` profile's level → the SDK default (`medium`)** — so the `default` profile's `thinkingLevel` is the de-facto global default, mirroring how `models.default` is the default model. Levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Clamped to each model's capabilities (`xhigh` is OpenAI-family-only). An attention-escalation cue in a turn still bumps that single turn to maximum effort regardless. Bare string/array profile values keep working; a profile becomes an object only when a level is attached. **Live-reloadable** (rides `models`).
18
19
  - `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
19
20
  - `plugins` — array of plugin module specifiers loaded at server boot: npm package names for published plugins, or relative paths for local plugins you are authoring. **Restart-required.**
20
21
  - `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
@@ -27,7 +28,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
27
28
 
28
29
  There is no file watcher, but there is a `reload` mechanism. When `typeclaw.json` changes:
29
30
 
30
- - **Live-reloadable fields** (`model`, `alias`, `channels`) take effect on the next `reload` — no container restart.
31
+ - **Live-reloadable fields** (`models` — including per-profile `thinkingLevel`, `alias`, `channels`) take effect on the next `reload` — no container restart.
31
32
  - **Restart-required fields** (`port`, `mounts`, `plugins`, `portForward`, `docker.file`, `git.ignore`) are reported as "reload landed but change won't apply until restart". The diff returns success; the runtime still has the old value in memory. Tell the user explicitly which one they're hitting. `docker.file` additionally requires an image rebuild — that happens automatically on the next `typeclaw start`, no extra flag needed. `git.ignore` refreshes the managed `.gitignore` and auto-commits it on the next `typeclaw start` if content changed.
32
33
  - **`$schema`** changes are ignored.
33
34
 
@@ -39,18 +40,19 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
39
40
 
40
41
  `typeclaw.json` is a single JSON object with these fields:
41
42
 
42
- | Field | Required | Type | Notes |
43
- | ------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
44
- | `$schema` | no | string | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it. |
45
- | `port` | no | integer | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.** |
46
- | `model` | no | string | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.** |
47
- | `mounts` | no | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.** |
48
- | `plugins` | no | array of strings | Plugin module specifiers loaded at server boot: use npm package names for published plugins (for example, `typeclaw-gws-multi-account`) and relative paths only for local plugins you are authoring (for example, `./packages/my-plugin`). Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**. |
49
- | `alias` | no | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Channels and Alias** below for schema/edit mechanics; the matching behavior lives in the `typeclaw-channels` skill. **Live-reloadable.** |
50
- | `channels` | no | object | Per-adapter engagement triggers and history-prefetch knobs for external messengers (plus the `github` webhook channel — see **GitHub channel** below). Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill; engagement behavior lives in `typeclaw-channels`. **Live-reloadable.** See **Channels and Alias** below. |
51
- | `portForward` | no | object | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below. |
52
- | `docker` | no | object | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, xvfb: true, claudeCode: false, codexCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
53
- | `git` | no | object | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below. |
43
+ | Field | Required | Type | Notes |
44
+ | -------------------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
45
+ | `$schema` | no | string | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it. |
46
+ | `port` | no | integer | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.** |
47
+ | `model` | no | string | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.** |
48
+ | `models.<profile>.thinkingLevel` | no | string | Per-profile reasoning effort (NOT a top-level field): `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh`. Lives in a profile object `{ "model": "<ref>", "thinkingLevel": … }`. Resolves as profile's own → `default` profile's → SDK default (`medium`). Set with `typeclaw model set <profile> <ref> --thinking <level>` or `typeclaw model thinking <level>` (for `default`). **Live-reloadable.** |
49
+ | `mounts` | no | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.** |
50
+ | `plugins` | no | array of strings | Plugin module specifiers loaded at server boot: use npm package names for published plugins (for example, `typeclaw-gws-multi-account`) and relative paths only for local plugins you are authoring (for example, `./packages/my-plugin`). Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**. |
51
+ | `alias` | no | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Channels and Alias** below for schema/edit mechanics; the matching behavior lives in the `typeclaw-channels` skill. **Live-reloadable.** |
52
+ | `channels` | no | object | Per-adapter engagement triggers and history-prefetch knobs for external messengers (plus the `github` webhook channel — see **GitHub channel** below). Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill; engagement behavior lives in `typeclaw-channels`. **Live-reloadable.** See **Channels and Alias** below. |
53
+ | `portForward` | no | object | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below. |
54
+ | `docker` | no | object | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, xvfb: true, claudeCode: false, codexCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
55
+ | `git` | no | object | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below. |
54
56
 
55
57
  > **Top-level keys not in this table are not "ignored unknowns" anymore** — they are reserved for **plugin config blocks**. The schema's `catchall(z.unknown())` preserves them, and the plugin loader hands each block to its owning plugin's `configSchema` for validation. The bundled memory plugin owns `memory` at the top level — see the `typeclaw-memory` skill for that block's semantics. Do not write a top-level key unless you know which plugin owns it.
56
58
 
@@ -93,7 +95,7 @@ Example with mounts:
93
95
  ```json
94
96
  {
95
97
  "$schema": "./node_modules/typeclaw/typeclaw.schema.json",
96
- "model": "openai/gpt-5.4-nano",
98
+ "model": "<provider>/<model-id>",
97
99
  "mounts": [
98
100
  { "name": "typeclaw", "path": "~/workspace/typeclaw", "description": "the typeclaw source repo" },
99
101
  { "name": "notes", "path": "~/notes", "readOnly": true, "description": "personal notes (read-only)" }
@@ -212,7 +214,7 @@ Default (no `portForward` field at all): forward every LISTEN.
212
214
  ```json
213
215
  {
214
216
  "$schema": "./node_modules/typeclaw/typeclaw.schema.json",
215
- "model": "openai/gpt-5.4-nano"
217
+ "model": "<provider>/<model-id>"
216
218
  }
217
219
  ```
218
220
 
@@ -532,7 +534,7 @@ Never echo, log, or commit values from `secrets.json` or `.env`. Both are gitign
532
534
 
533
535
  1. **Read `typeclaw.json`.** Don't guess from prior conversation — the user may have changed it since you last looked.
534
536
  2. Report the `model` field verbatim, plus the human-readable name from the **Allowed models** table.
535
- 3. If `model` is missing from the file, say so and report the default (`openai/gpt-5.4-nano` → GPT-5.4 nano).
537
+ 3. If `model` is missing from the file, say so and report the registry default — the entry marked **Default** in the **Allowed models** table.
536
538
 
537
539
  ## When the user says "switch to <model>"
538
540
 
@@ -116,6 +116,172 @@
116
116
  }
117
117
  ]
118
118
  }
119
+ },
120
+ {
121
+ "type": "object",
122
+ "properties": {
123
+ "model": {
124
+ "anyOf": [
125
+ {
126
+ "type": "string",
127
+ "enum": [
128
+ "openai/gpt-5.4-nano",
129
+ "openai/gpt-5.4-mini",
130
+ "openai/gpt-5.4",
131
+ "openai/gpt-5.5",
132
+ "openai-codex/gpt-5.4-mini",
133
+ "openai-codex/gpt-5.4",
134
+ "openai-codex/gpt-5.5",
135
+ "anthropic/claude-haiku-4-5",
136
+ "anthropic/claude-sonnet-4-6",
137
+ "anthropic/claude-opus-4-7",
138
+ "anthropic/claude-opus-4-8",
139
+ "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
140
+ "zai/glm-4.5-air",
141
+ "zai/glm-4.6",
142
+ "zai/glm-4.7",
143
+ "zai-coding/glm-4.5-air",
144
+ "zai-coding/glm-4.7",
145
+ "zai-coding/glm-5",
146
+ "zai-coding/glm-5-turbo",
147
+ "zai-coding/glm-5.1",
148
+ "xai/grok-4.3",
149
+ "xai/grok-4.20-0309-reasoning",
150
+ "xai/grok-4.20-0309-non-reasoning",
151
+ "xai/grok-build-0.1",
152
+ "minimax/MiniMax-M3",
153
+ "minimax/MiniMax-M2.7",
154
+ "minimax/MiniMax-M2.5",
155
+ "minimax/MiniMax-M2.1",
156
+ "minimax/MiniMax-M2",
157
+ "deepseek/deepseek-v4-flash",
158
+ "deepseek/deepseek-v4-pro",
159
+ "moonshot/kimi-k2.7-code",
160
+ "moonshot/kimi-k2.6",
161
+ "moonshot/kimi-k2.5",
162
+ "moonshot-coding/kimi-for-coding"
163
+ ]
164
+ },
165
+ {
166
+ "type": "string"
167
+ }
168
+ ]
169
+ },
170
+ "models": {
171
+ "anyOf": [
172
+ {
173
+ "anyOf": [
174
+ {
175
+ "type": "string",
176
+ "enum": [
177
+ "openai/gpt-5.4-nano",
178
+ "openai/gpt-5.4-mini",
179
+ "openai/gpt-5.4",
180
+ "openai/gpt-5.5",
181
+ "openai-codex/gpt-5.4-mini",
182
+ "openai-codex/gpt-5.4",
183
+ "openai-codex/gpt-5.5",
184
+ "anthropic/claude-haiku-4-5",
185
+ "anthropic/claude-sonnet-4-6",
186
+ "anthropic/claude-opus-4-7",
187
+ "anthropic/claude-opus-4-8",
188
+ "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
189
+ "zai/glm-4.5-air",
190
+ "zai/glm-4.6",
191
+ "zai/glm-4.7",
192
+ "zai-coding/glm-4.5-air",
193
+ "zai-coding/glm-4.7",
194
+ "zai-coding/glm-5",
195
+ "zai-coding/glm-5-turbo",
196
+ "zai-coding/glm-5.1",
197
+ "xai/grok-4.3",
198
+ "xai/grok-4.20-0309-reasoning",
199
+ "xai/grok-4.20-0309-non-reasoning",
200
+ "xai/grok-build-0.1",
201
+ "minimax/MiniMax-M3",
202
+ "minimax/MiniMax-M2.7",
203
+ "minimax/MiniMax-M2.5",
204
+ "minimax/MiniMax-M2.1",
205
+ "minimax/MiniMax-M2",
206
+ "deepseek/deepseek-v4-flash",
207
+ "deepseek/deepseek-v4-pro",
208
+ "moonshot/kimi-k2.7-code",
209
+ "moonshot/kimi-k2.6",
210
+ "moonshot/kimi-k2.5",
211
+ "moonshot-coding/kimi-for-coding"
212
+ ]
213
+ },
214
+ {
215
+ "type": "string"
216
+ }
217
+ ]
218
+ },
219
+ {
220
+ "minItems": 1,
221
+ "type": "array",
222
+ "items": {
223
+ "anyOf": [
224
+ {
225
+ "type": "string",
226
+ "enum": [
227
+ "openai/gpt-5.4-nano",
228
+ "openai/gpt-5.4-mini",
229
+ "openai/gpt-5.4",
230
+ "openai/gpt-5.5",
231
+ "openai-codex/gpt-5.4-mini",
232
+ "openai-codex/gpt-5.4",
233
+ "openai-codex/gpt-5.5",
234
+ "anthropic/claude-haiku-4-5",
235
+ "anthropic/claude-sonnet-4-6",
236
+ "anthropic/claude-opus-4-7",
237
+ "anthropic/claude-opus-4-8",
238
+ "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
239
+ "zai/glm-4.5-air",
240
+ "zai/glm-4.6",
241
+ "zai/glm-4.7",
242
+ "zai-coding/glm-4.5-air",
243
+ "zai-coding/glm-4.7",
244
+ "zai-coding/glm-5",
245
+ "zai-coding/glm-5-turbo",
246
+ "zai-coding/glm-5.1",
247
+ "xai/grok-4.3",
248
+ "xai/grok-4.20-0309-reasoning",
249
+ "xai/grok-4.20-0309-non-reasoning",
250
+ "xai/grok-build-0.1",
251
+ "minimax/MiniMax-M3",
252
+ "minimax/MiniMax-M2.7",
253
+ "minimax/MiniMax-M2.5",
254
+ "minimax/MiniMax-M2.1",
255
+ "minimax/MiniMax-M2",
256
+ "deepseek/deepseek-v4-flash",
257
+ "deepseek/deepseek-v4-pro",
258
+ "moonshot/kimi-k2.7-code",
259
+ "moonshot/kimi-k2.6",
260
+ "moonshot/kimi-k2.5",
261
+ "moonshot-coding/kimi-for-coding"
262
+ ]
263
+ },
264
+ {
265
+ "type": "string"
266
+ }
267
+ ]
268
+ }
269
+ }
270
+ ]
271
+ },
272
+ "thinkingLevel": {
273
+ "type": "string",
274
+ "enum": [
275
+ "off",
276
+ "minimal",
277
+ "low",
278
+ "medium",
279
+ "high",
280
+ "xhigh"
281
+ ]
282
+ }
283
+ },
284
+ "additionalProperties": false
119
285
  }
120
286
  ]
121
287
  }
@@ -288,13 +454,18 @@
288
454
  },
289
455
  "compose": {
290
456
  "default": {
291
- "exclude": false
457
+ "exclude": false,
458
+ "monorepo": false
292
459
  },
293
460
  "type": "object",
294
461
  "properties": {
295
462
  "exclude": {
296
463
  "default": false,
297
464
  "type": "boolean"
465
+ },
466
+ "monorepo": {
467
+ "default": false,
468
+ "type": "boolean"
298
469
  }
299
470
  }
300
471
  },