typeclaw 0.38.0 → 0.39.0

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 (63) hide show
  1. package/README.md +4 -0
  2. package/auth.schema.json +109 -0
  3. package/package.json +2 -2
  4. package/secrets.schema.json +109 -0
  5. package/src/agent/attention-escalation.ts +4 -3
  6. package/src/agent/auth.ts +2 -2
  7. package/src/agent/index.ts +25 -2
  8. package/src/agent/restart/index.ts +17 -8
  9. package/src/agent/session-origin.ts +15 -2
  10. package/src/agent/subagents.ts +29 -1
  11. package/src/agent/system-prompt.ts +18 -5
  12. package/src/agent/tools/restart.ts +0 -3
  13. package/src/agent/tools/spawn-subagent.ts +7 -0
  14. package/src/bundled-plugins/memory/README.md +12 -1
  15. package/src/bundled-plugins/memory/index.ts +63 -8
  16. package/src/bundled-plugins/memory/memory-logger.ts +14 -10
  17. package/src/bundled-plugins/operator/operator.ts +1 -0
  18. package/src/channels/adapters/kakaotalk.ts +1 -1
  19. package/src/channels/adapters/webex-bot-classify.ts +20 -14
  20. package/src/channels/adapters/webex-bot-reference.ts +8 -6
  21. package/src/channels/adapters/webex-bot.ts +106 -39
  22. package/src/channels/adapters/webex-channel-resolver.ts +29 -0
  23. package/src/channels/adapters/webex-classify.ts +104 -0
  24. package/src/channels/adapters/webex-format.ts +53 -0
  25. package/src/channels/adapters/webex-id-ref.ts +32 -0
  26. package/src/channels/adapters/webex-reference.ts +49 -0
  27. package/src/channels/adapters/webex.ts +493 -0
  28. package/src/channels/manager.ts +63 -7
  29. package/src/channels/persistence.ts +67 -5
  30. package/src/channels/router.ts +8 -0
  31. package/src/channels/schema.ts +2 -0
  32. package/src/cli/channel.ts +118 -7
  33. package/src/cli/init.ts +70 -1
  34. package/src/cli/model.ts +143 -3
  35. package/src/config/channels-mutation.ts +2 -1
  36. package/src/config/config.ts +94 -31
  37. package/src/config/index.ts +3 -0
  38. package/src/config/models-mutation.ts +105 -15
  39. package/src/config/providers-mutation.ts +4 -4
  40. package/src/config/providers.ts +6 -14
  41. package/src/container/shared.ts +21 -0
  42. package/src/container/start.ts +25 -7
  43. package/src/doctor/channel-checks.ts +43 -0
  44. package/src/hostd/daemon.ts +7 -5
  45. package/src/hostd/index.ts +1 -11
  46. package/src/hostd/paths.ts +0 -16
  47. package/src/hostd/protocol.ts +2 -2
  48. package/src/init/checkpoint.ts +1 -1
  49. package/src/init/index.ts +60 -3
  50. package/src/init/run-owner-claim.ts +1 -0
  51. package/src/init/webex-auth.ts +68 -0
  52. package/src/inspect/label.ts +13 -2
  53. package/src/inspect/render.ts +5 -3
  54. package/src/permissions/resolve.ts +38 -1
  55. package/src/role-claim/match-rule.ts +5 -1
  56. package/src/run/index.ts +4 -1
  57. package/src/secrets/codex-auth-json.ts +52 -17
  58. package/src/secrets/encryption.ts +5 -1
  59. package/src/secrets/export-codex-auth-file.ts +26 -3
  60. package/src/secrets/schema.ts +35 -0
  61. package/src/secrets/webex-store.ts +113 -0
  62. package/src/skills/typeclaw-config/SKILL.md +18 -16
  63. package/typeclaw.schema.json +326 -0
@@ -1,3 +1,4 @@
1
+ import { decodeWebexId } from '@/channels/adapters/webex-id-ref'
1
2
  import type { AdapterId } from '@/channels/schema'
2
3
 
3
4
  import type { MatchRule, Platform } from './match-rule'
@@ -7,6 +8,7 @@ const ADAPTER_TO_PLATFORM: Record<AdapterId, Platform> = {
7
8
  'discord-bot': 'discord',
8
9
  github: 'github',
9
10
  'telegram-bot': 'telegram',
11
+ webex: 'webex',
10
12
  'webex-bot': 'webex',
11
13
  line: 'line',
12
14
  kakaotalk: 'kakao',
@@ -53,10 +55,45 @@ function matchesChannel(rule: Extract<MatchRule, { kind: 'channel' }>, origin: M
53
55
  if (rule.chat !== undefined && rule.chat !== origin.chat) return false
54
56
  }
55
57
 
56
- if (rule.author !== undefined && rule.author !== origin.lastInboundAuthorId) return false
58
+ if (rule.author !== undefined && !matchesAuthor(rule.platform, rule.author, origin.lastInboundAuthorId)) return false
57
59
  return true
58
60
  }
59
61
 
62
+ // Webex person ids are base64(`ciscospark://<cluster>/PEOPLE/<uuid-or-email>`),
63
+ // so a hand-authored or claim-generated rule may carry the raw base64 id, its
64
+ // decoded ref (UUID for modern accounts, email for legacy Hydra accounts), and
65
+ // the inbound may arrive as either. We compare on the decoded PERSON ref when
66
+ // BOTH sides decode to a PEOPLE id, and otherwise fall back to raw equality —
67
+ // so `author:<uuid>`, `author:<legacy-email>`, and the legacy `author:<base64>`
68
+ // all match the same human. A value that decodes to a non-PERSON type (e.g. a
69
+ // room id pasted into `author:`) never normalizes, so it can only ever raw-
70
+ // match — a room uuid can never satisfy an author rule.
71
+ function matchesAuthor(platform: Platform, ruleAuthor: string, inboundAuthorId: string | undefined): boolean {
72
+ if (inboundAuthorId === undefined) return false
73
+ if (ruleAuthor === inboundAuthorId) return true
74
+ if (platform !== 'webex') return false
75
+ // Both sides must resolve to a real PERSON ref. `webexPersonRef` returns null
76
+ // for any non-PEOPLE id, and null === null would otherwise let two different
77
+ // room/message ids satisfy an `author:` rule — so require both non-null.
78
+ const ruleRef = webexPersonRef(ruleAuthor)
79
+ const inboundRef = webexPersonRef(inboundAuthorId)
80
+ return ruleRef !== null && inboundRef !== null && ruleRef === inboundRef
81
+ }
82
+
83
+ // Returns the comparable person identity for a Webex `author:` value: the
84
+ // decoded trailing ref when the value is a base64 PEOPLE id, or the value
85
+ // itself when it is already a ref (bare uuid/email). Returns null for anything
86
+ // that decodes to a non-PERSON Webex id, so two different resource types can
87
+ // never be coerced into matching. Emails are lower-cased so case variation in
88
+ // a legacy-account ref does not silently deny a grant. Keep this for backward
89
+ // compatibility with pre-migration rules that still carry blob-form ids.
90
+ function webexPersonRef(value: string): string | null {
91
+ const decoded = decodeWebexId(value)
92
+ if (decoded === null) return value.includes('@') ? value.toLowerCase() : value
93
+ if (decoded.type !== 'PEOPLE') return null
94
+ return decoded.uuid.includes('@') ? decoded.uuid.toLowerCase() : decoded.uuid
95
+ }
96
+
60
97
  // DM and group buckets are inferred from the workspace/chat shape of the
61
98
  // inbound origin. Different adapters mark DMs differently — Slack and Webex
62
99
  // use an `@dm` workspace marker, Discord uses a `dm` workspace marker, and
@@ -33,6 +33,7 @@ const ADAPTER_TO_PLATFORM: Record<
33
33
  'discord-bot': 'discord',
34
34
  github: 'github',
35
35
  'telegram-bot': 'telegram',
36
+ webex: 'webex',
36
37
  'webex-bot': 'webex',
37
38
  line: 'line',
38
39
  kakaotalk: 'kakao',
@@ -40,5 +41,8 @@ const ADAPTER_TO_PLATFORM: Record<
40
41
 
41
42
  export function formatClaimMatchRule(origin: PartialChannelOrigin): string {
42
43
  const platform = ADAPTER_TO_PLATFORM[origin.adapter]
43
- return `${platform}:* author:${origin.authorId}`
44
+ // Webex authorIds are stored as decoded refs (UUID, or email for legacy
45
+ // accounts). The matcher still normalizes older blob-form rules/inbounds.
46
+ const author = origin.authorId
47
+ return `${platform}:* author:${author}`
44
48
  }
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
  : {}),
@@ -1,15 +1,21 @@
1
1
  import type { ProviderCredential } from './schema'
2
2
 
3
- // Emit the on-disk shape Codex CLI consumes at ~/.codex/auth.json. Mirrors
4
- // the modern (>= 0.93) shape: a single `tokens` object with access_token,
5
- // refresh_token, and optional account_id. Codex re-derives token expiry
6
- // from the JWT's `exp` claim on every load, so we deliberately omit a
7
- // top-level `expires` field even though typeclaw stores one.
3
+ // Emit the on-disk shape Codex CLI consumes at ~/.codex/auth.json: a `tokens`
4
+ // object with id_token, access_token, refresh_token, and optional account_id.
5
+ // No top-level `expires` — codex re-derives expiry from the JWT `exp` claim.
8
6
  //
9
- // Pre-0.93 codex used a different layout (top-level OPENAI_API_KEY +
10
- // auth_mode discriminator + optional tokens). We don't emit that legacy
11
- // shape — every codex install old enough to require it has been replaced
12
- // by the version `docker.file.codexCli` installs in the container.
7
+ // id_token is load-bearing: codex's deserializer (token_data.rs) declares
8
+ // `id_token: IdTokenInfo` with no Option/#[serde(default)], so omitting it
9
+ // fails the whole auth.json load with `missing field id_token` before any
10
+ // model call. codex parses it via `parse_chatgpt_jwt_claims`, which accepts
11
+ // any decodable 3-part JWT and treats every claim as optional.
12
+ //
13
+ // We prefer a real captured id_token (`idToken`/`id_token` on the credential,
14
+ // e.g. from a future pi-ai that persists it) and fall back to `access`. The
15
+ // fallback is sound because this flow's access token is itself a ChatGPT-claims
16
+ // JWT (carries `https://api.openai.com/auth`), so codex reads the same
17
+ // plan/account fields from it — self-healing agents whose stored credential
18
+ // predates id_token capture, without a re-login.
13
19
  export function emitCodexAuthJson(credential: ProviderCredential): string {
14
20
  if (credential.type !== 'oauth') {
15
21
  throw new Error('emitCodexAuthJson only accepts oauth-typed credentials')
@@ -18,6 +24,8 @@ export function emitCodexAuthJson(credential: ProviderCredential): string {
18
24
  access?: unknown
19
25
  refresh?: unknown
20
26
  accountId?: unknown
27
+ idToken?: unknown
28
+ id_token?: unknown
21
29
  }
22
30
  const access = fields.access
23
31
  const refresh = fields.refresh
@@ -28,38 +36,65 @@ export function emitCodexAuthJson(credential: ProviderCredential): string {
28
36
  throw new Error('credential is missing a non-empty `refresh` field')
29
37
  }
30
38
 
31
- const tokens: Record<string, string> = { access_token: access, refresh_token: refresh }
39
+ const capturedIdToken = firstNonEmptyString(fields.idToken, fields.id_token)
40
+ const idToken = capturedIdToken ?? access
41
+
42
+ const tokens: Record<string, string> = {
43
+ id_token: idToken,
44
+ access_token: access,
45
+ refresh_token: refresh,
46
+ }
32
47
  if (typeof fields.accountId === 'string' && fields.accountId.length > 0) {
33
48
  tokens['account_id'] = fields.accountId
34
49
  }
35
50
  return `${JSON.stringify({ tokens }, null, 2)}\n`
36
51
  }
37
52
 
53
+ function firstNonEmptyString(...values: unknown[]): string | null {
54
+ for (const value of values) {
55
+ if (typeof value === 'string' && value.length > 0) return value
56
+ }
57
+ return null
58
+ }
59
+
38
60
  // Extracts the JWT `exp` claim (seconds since epoch) and converts to ms.
39
61
  // Used by the runtime exporter's newer-wins compare: ~/.codex/auth.json
40
62
  // carries no top-level expiry, but the JWT inside `tokens.access_token`
41
63
  // does. Returns null on any decode failure; the caller treats that as
42
64
  // "unknown freshness" and falls back to overwriting from typeclaw's copy.
43
65
  export function decodeCodexAccessTokenExpiryMs(accessToken: string): number | null {
44
- const parts = accessToken.split('.')
66
+ const payload = decodeJwtPayload(accessToken)
67
+ if (payload === null) return null
68
+ const exp = payload['exp']
69
+ if (typeof exp !== 'number' || !Number.isFinite(exp)) return null
70
+ return Math.floor(exp * 1000)
71
+ }
72
+
73
+ // True when the string decodes the way codex's `decode_jwt_payload` requires:
74
+ // three non-empty dot-separated parts with a base64url payload that is a JSON
75
+ // object. codex runs exactly this on `tokens.id_token` (via
76
+ // `parse_chatgpt_jwt_claims`) and rejects the whole auth.json if it fails, so
77
+ // the exporter uses this to decide whether an on-disk id_token is usable —
78
+ // not just non-empty.
79
+ export function isDecodableJwt(token: string): boolean {
80
+ return decodeJwtPayload(token) !== null
81
+ }
82
+
83
+ function decodeJwtPayload(jwt: string): Record<string, unknown> | null {
84
+ const parts = jwt.split('.')
45
85
  if (parts.length !== 3) return null
46
86
  const middle = parts[1] ?? ''
47
87
  if (middle === '') return null
48
88
  // base64url → base64, then pad to a multiple of 4 (atob is strict).
49
89
  const normalized = middle.replace(/-/g, '+').replace(/_/g, '/')
50
90
  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4)
51
- let payload: Record<string, unknown>
52
91
  try {
53
92
  const decoded = typeof atob === 'function' ? atob(padded) : Buffer.from(padded, 'base64').toString('utf8')
54
93
  const parsed: unknown = JSON.parse(decoded)
55
- if (!isPlainObject(parsed)) return null
56
- payload = parsed
94
+ return isPlainObject(parsed) ? parsed : null
57
95
  } catch {
58
96
  return null
59
97
  }
60
- const exp = payload['exp']
61
- if (typeof exp !== 'number' || !Number.isFinite(exp)) return null
62
- return Math.floor(exp * 1000)
63
98
  }
64
99
 
65
100
  function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -33,6 +33,7 @@ export type EncryptedEnvelope = {
33
33
  export type EncryptionContext = {
34
34
  containerName: string
35
35
  accountId: string
36
+ purpose?: string
36
37
  }
37
38
 
38
39
  export class EncryptionError extends Error {
@@ -112,5 +113,8 @@ export function decrypt(envelope: EncryptedEnvelope, key: Buffer, context: Encry
112
113
  // Changing this format breaks decryption of every previously-stored ciphertext.
113
114
  // See the module-header threat-model comment for the binding rationale.
114
115
  function buildAad(context: EncryptionContext): Buffer {
115
- return Buffer.from(`typeclaw:kakaotalk-password:v1:${context.containerName}:${context.accountId}`, 'utf8')
116
+ return Buffer.from(
117
+ `typeclaw:${context.purpose ?? 'kakaotalk-password'}:v1:${context.containerName}:${context.accountId}`,
118
+ 'utf8',
119
+ )
116
120
  }
@@ -11,7 +11,7 @@ import {
11
11
  import { homedir } from 'node:os'
12
12
  import { dirname, isAbsolute, join, resolve } from 'node:path'
13
13
 
14
- import { decodeCodexAccessTokenExpiryMs, emitCodexAuthJson } from './codex-auth-json'
14
+ import { decodeCodexAccessTokenExpiryMs, emitCodexAuthJson, isDecodableJwt } from './codex-auth-json'
15
15
  import type { ProviderCredential, Providers } from './schema'
16
16
  import { SecretsBackend } from './storage'
17
17
 
@@ -86,6 +86,13 @@ export function exportCodexAuthFileIfApplicable(options: ExportCodexAuthFileOpti
86
86
  // missing JWT, undecodable exp), we return true. That's the "we have a
87
87
  // valid credential, the file is unusable, replace it" fallback case (B1
88
88
  // and B6 in the design doc).
89
+ //
90
+ // A file missing a usable `id_token` is unusable too, regardless of how
91
+ // fresh its access token is: codex rejects the whole auth.json with
92
+ // `missing field id_token` before any model call. This guard runs BEFORE
93
+ // the newer-wins expiry compare so a pre-fix TypeClaw-emitted file (valid,
94
+ // possibly fresher access token, but no id_token) is always rewritten —
95
+ // the path that self-heals already-broken agents on restart.
89
96
  function shouldOverwrite(
90
97
  targetPath: string,
91
98
  credential: ProviderCredential & { expires?: unknown; access?: unknown },
@@ -105,6 +112,8 @@ function shouldOverwrite(
105
112
  return true
106
113
  }
107
114
 
115
+ if (!onDiskHasUsableIdToken(parsed)) return true
116
+
108
117
  const onDiskAccess = readOnDiskAccessToken(parsed)
109
118
  if (onDiskAccess === null) return true
110
119
 
@@ -116,11 +125,25 @@ function shouldOverwrite(
116
125
  }
117
126
 
118
127
  function readOnDiskAccessToken(parsed: unknown): string | null {
128
+ return readOnDiskToken(parsed, 'access_token')
129
+ }
130
+
131
+ // codex parses `tokens.id_token` as a JWT, so a value that is absent, empty,
132
+ // or not a decodable JWT is unusable — codex rejects the whole auth.json on
133
+ // load. Validate decodability (not just presence) so a file with a non-empty
134
+ // but malformed id_token, even alongside a fresh access token, is treated as
135
+ // stale and rewritten rather than preserved by the newer-wins compare.
136
+ function onDiskHasUsableIdToken(parsed: unknown): boolean {
137
+ const idToken = readOnDiskToken(parsed, 'id_token')
138
+ return idToken !== null && isDecodableJwt(idToken)
139
+ }
140
+
141
+ function readOnDiskToken(parsed: unknown, field: 'access_token' | 'id_token'): string | null {
119
142
  if (typeof parsed !== 'object' || parsed === null) return null
120
143
  const tokens = (parsed as Record<string, unknown>)['tokens']
121
144
  if (typeof tokens !== 'object' || tokens === null) return null
122
- const access = (tokens as Record<string, unknown>)['access_token']
123
- return typeof access === 'string' && access.length > 0 ? access : null
145
+ const value = (tokens as Record<string, unknown>)[field]
146
+ return typeof value === 'string' && value.length > 0 ? value : null
124
147
  }
125
148
 
126
149
  // Resolution order for the credential's expiry:
@@ -93,6 +93,18 @@ const kakaoEncryptedPasswordSchema = z
93
93
  })
94
94
  .strict()
95
95
 
96
+ export const webexEncryptedPasswordSchema = z
97
+ .object({
98
+ v: z.literal(1),
99
+ alg: z.literal('AES-256-GCM'),
100
+ kid: z.string(),
101
+ iv: z.string(),
102
+ ciphertext: z.string(),
103
+ authTag: z.string(),
104
+ createdAt: z.string(),
105
+ })
106
+ .strict()
107
+
96
108
  export const kakaoAccountRecordSchema = z.object({
97
109
  account_id: z.string(),
98
110
  oauth_token: z.string(),
@@ -112,6 +124,26 @@ export const kakaoAccountRecordSchema = z.object({
112
124
 
113
125
  export type KakaoEncryptedPassword = z.infer<typeof kakaoEncryptedPasswordSchema>
114
126
 
127
+ export const webexAccountRecordSchema = z.object({
128
+ account_id: z.string(),
129
+ access_token: z.string(),
130
+ refresh_token: z.string(),
131
+ expires_at: z.number(),
132
+ device_url: z.string().optional(),
133
+ user_id: z.string().optional(),
134
+ client_id: z.string().optional(),
135
+ client_secret: z.string().optional(),
136
+ created_at: z.string(),
137
+ updated_at: z.string(),
138
+ email: z.string().optional(),
139
+ encryptedPassword: webexEncryptedPasswordSchema.optional(),
140
+ })
141
+
142
+ export const webexChannelBlockSchema = z.object({
143
+ currentAccount: z.string().nullable(),
144
+ accounts: z.record(z.string(), webexAccountRecordSchema),
145
+ })
146
+
115
147
  export const kakaoPendingLoginRecordSchema = z.object({
116
148
  device_uuid: z.string(),
117
149
  device_type: z.union([z.literal('pc'), z.literal('tablet')]),
@@ -133,6 +165,7 @@ export const channelsSchema = z
133
165
  'telegram-bot': telegramBotChannelSchema.optional(),
134
166
  line: lineChannelBlockSchema.optional(),
135
167
  kakaotalk: kakaoChannelBlockSchema.optional(),
168
+ webex: webexChannelBlockSchema.optional(),
136
169
  })
137
170
  .catchall(z.unknown())
138
171
 
@@ -158,6 +191,8 @@ export type LineChannelBlock = z.infer<typeof lineChannelBlockSchema>
158
191
  export type KakaoAccountRecord = z.infer<typeof kakaoAccountRecordSchema>
159
192
  export type PendingLoginRecord = z.infer<typeof kakaoPendingLoginRecordSchema>
160
193
  export type KakaoChannelBlock = z.infer<typeof kakaoChannelBlockSchema>
194
+ export type WebexAccountRecord = z.infer<typeof webexAccountRecordSchema>
195
+ export type WebexChannelBlock = z.infer<typeof webexChannelBlockSchema>
161
196
  export type SecretsFile = z.infer<typeof secretsFileSchema>
162
197
 
163
198
  export type ParseSecretsResult = { ok: true; file: SecretsFile } | { ok: false; reason: string }
@@ -0,0 +1,113 @@
1
+ import { sendHttp } from '@/hostd/client'
2
+
3
+ import { type WebexAccountRecord, type WebexChannelBlock, webexChannelBlockSchema } from './schema'
4
+ import { SecretsBackend } from './storage'
5
+
6
+ export type SetWebexAccountInput = WebexAccountRecord
7
+
8
+ export type SecretsWebexCredentialStoreOptions =
9
+ | { mode: 'host'; secretsPath: string }
10
+ | { mode: 'container'; secretsPath: string; hostdUrl: string; restartToken: string; containerName: string }
11
+
12
+ const EMPTY_BLOCK: WebexChannelBlock = { currentAccount: null, accounts: {} }
13
+
14
+ export class SecretsWebexCredentialStore {
15
+ private readonly backend: SecretsBackend
16
+ private writeChain: Promise<void> = Promise.resolve()
17
+
18
+ constructor(private readonly options: SecretsWebexCredentialStoreOptions) {
19
+ this.backend = new SecretsBackend(options.secretsPath)
20
+ }
21
+
22
+ async getAccount(id?: string): Promise<WebexAccountRecord | null> {
23
+ const block = this.readBlock()
24
+ const accountId = id ?? block.currentAccount
25
+ if (!accountId) return null
26
+ return block.accounts[accountId] ?? null
27
+ }
28
+
29
+ async getAccountWithRenewalFields(id?: string): Promise<WebexAccountRecord | null> {
30
+ return await this.getAccount(id)
31
+ }
32
+
33
+ async setAccount(account: SetWebexAccountInput): Promise<void> {
34
+ await this.writeBlock((block) => {
35
+ const merged = mergeAccountPreservingRenewalFields(account, block.accounts[account.account_id])
36
+ const accounts = { ...block.accounts, [account.account_id]: merged }
37
+ return { ...block, currentAccount: block.currentAccount ?? account.account_id, accounts }
38
+ })
39
+ }
40
+
41
+ async removeAccount(id: string): Promise<void> {
42
+ await this.writeBlock((block) => {
43
+ const accounts = { ...block.accounts }
44
+ delete accounts[id]
45
+ const currentAccount = block.currentAccount === id ? (Object.keys(accounts)[0] ?? null) : block.currentAccount
46
+ return { ...block, currentAccount, accounts }
47
+ })
48
+ }
49
+
50
+ async listAccounts(): Promise<Array<WebexAccountRecord & { is_current: boolean }>> {
51
+ const block = this.readBlock()
52
+ return Object.values(block.accounts).map((account) => ({
53
+ ...account,
54
+ is_current: account.account_id === block.currentAccount,
55
+ }))
56
+ }
57
+
58
+ async setCurrentAccount(id: string): Promise<void> {
59
+ await this.writeBlock((block) => ({ ...block, currentAccount: id }))
60
+ }
61
+
62
+ private readBlock(): WebexChannelBlock {
63
+ const channels =
64
+ this.options.mode === 'container' ? this.backend.tryReadChannelsSync() : this.backend.readChannelsSync()
65
+ return parseBlock(channels?.webex)
66
+ }
67
+
68
+ private async writeBlock(update: (current: WebexChannelBlock) => WebexChannelBlock): Promise<void> {
69
+ return this.enqueueWrite(async () => {
70
+ if (this.options.mode === 'container') {
71
+ const next = update(this.readBlock())
72
+ const response = await sendHttp(
73
+ {
74
+ kind: 'secrets-patch',
75
+ containerName: this.options.containerName,
76
+ patch: { channels: { webex: next } },
77
+ },
78
+ { url: this.options.hostdUrl, token: this.options.restartToken },
79
+ )
80
+ if (!response.ok) throw new Error(`secrets-patch failed: ${response.reason}`)
81
+ return
82
+ }
83
+
84
+ await this.backend.updateChannelsAsync(async (channels) => {
85
+ const next = { ...channels, webex: update(parseBlock(channels.webex)) }
86
+ return { result: undefined, next }
87
+ })
88
+ })
89
+ }
90
+
91
+ private enqueueWrite(op: () => Promise<void>): Promise<void> {
92
+ const next = this.writeChain.then(op, op)
93
+ this.writeChain = next.catch(() => {})
94
+ return next
95
+ }
96
+ }
97
+
98
+ function parseBlock(value: unknown): WebexChannelBlock {
99
+ if (value === undefined) return EMPTY_BLOCK
100
+ return webexChannelBlockSchema.parse(value)
101
+ }
102
+
103
+ function mergeAccountPreservingRenewalFields(
104
+ incoming: SetWebexAccountInput,
105
+ priorOnDisk: WebexChannelBlock['accounts'][string] | undefined,
106
+ ): WebexAccountRecord {
107
+ const merged: WebexAccountRecord = { ...incoming }
108
+ if (incoming.email !== undefined) merged.email = incoming.email
109
+ else if (priorOnDisk?.email !== undefined) merged.email = priorOnDisk.email
110
+ if (incoming.encryptedPassword !== undefined) merged.encryptedPassword = incoming.encryptedPassword
111
+ else if (priorOnDisk?.encryptedPassword !== undefined) merged.encryptedPassword = priorOnDisk.encryptedPassword
112
+ return merged
113
+ }
@@ -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