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
package/README.md CHANGED
@@ -5,6 +5,10 @@
5
5
  <h3 align="center">TypeClaw: The agent for perfectionists</h3>
6
6
  <p align="center">Crafted in every detail – it behaves in your team's chat and<br />gets sharper the longer it runs. Sandboxed and self-managing.</p>
7
7
 
8
+ <p align="center">
9
+ <a href="https://discord.gg/V4NQnbXpr"><img src="https://img.shields.io/badge/Discord-Chat%20with%20Typeey-5865F2?logo=discord&logoColor=white" alt="Chat with Typeey on Discord" /></a>
10
+ </p>
11
+
8
12
  <br />
9
13
  <br />
10
14
 
package/auth.schema.json CHANGED
@@ -498,6 +498,115 @@
498
498
  "currentAccount",
499
499
  "accounts"
500
500
  ]
501
+ },
502
+ "webex": {
503
+ "type": "object",
504
+ "properties": {
505
+ "currentAccount": {
506
+ "anyOf": [
507
+ {
508
+ "type": "string"
509
+ },
510
+ {
511
+ "type": "null"
512
+ }
513
+ ]
514
+ },
515
+ "accounts": {
516
+ "type": "object",
517
+ "propertyNames": {
518
+ "type": "string"
519
+ },
520
+ "additionalProperties": {
521
+ "type": "object",
522
+ "properties": {
523
+ "account_id": {
524
+ "type": "string"
525
+ },
526
+ "access_token": {
527
+ "type": "string"
528
+ },
529
+ "refresh_token": {
530
+ "type": "string"
531
+ },
532
+ "expires_at": {
533
+ "type": "number"
534
+ },
535
+ "device_url": {
536
+ "type": "string"
537
+ },
538
+ "user_id": {
539
+ "type": "string"
540
+ },
541
+ "client_id": {
542
+ "type": "string"
543
+ },
544
+ "client_secret": {
545
+ "type": "string"
546
+ },
547
+ "created_at": {
548
+ "type": "string"
549
+ },
550
+ "updated_at": {
551
+ "type": "string"
552
+ },
553
+ "email": {
554
+ "type": "string"
555
+ },
556
+ "encryptedPassword": {
557
+ "type": "object",
558
+ "properties": {
559
+ "v": {
560
+ "type": "number",
561
+ "const": 1
562
+ },
563
+ "alg": {
564
+ "type": "string",
565
+ "const": "AES-256-GCM"
566
+ },
567
+ "kid": {
568
+ "type": "string"
569
+ },
570
+ "iv": {
571
+ "type": "string"
572
+ },
573
+ "ciphertext": {
574
+ "type": "string"
575
+ },
576
+ "authTag": {
577
+ "type": "string"
578
+ },
579
+ "createdAt": {
580
+ "type": "string"
581
+ }
582
+ },
583
+ "required": [
584
+ "v",
585
+ "alg",
586
+ "kid",
587
+ "iv",
588
+ "ciphertext",
589
+ "authTag",
590
+ "createdAt"
591
+ ],
592
+ "additionalProperties": false
593
+ }
594
+ },
595
+ "required": [
596
+ "account_id",
597
+ "access_token",
598
+ "refresh_token",
599
+ "expires_at",
600
+ "created_at",
601
+ "updated_at"
602
+ ]
603
+ }
604
+ }
605
+ },
606
+ "required": [
607
+ "currentAccount",
608
+ "accounts"
609
+ ]
501
610
  }
502
611
  },
503
612
  "additionalProperties": {}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.38.0",
3
+ "version": "0.39.0",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -50,7 +50,7 @@
50
50
  "@mariozechner/pi-tui": "^0.67.3",
51
51
  "@modelcontextprotocol/sdk": "^1.29.0",
52
52
  "@mozilla/readability": "^0.6.0",
53
- "agent-messenger": "2.21.0",
53
+ "agent-messenger": "2.23.6",
54
54
  "cheerio": "^1.2.0",
55
55
  "citty": "^0.2.2",
56
56
  "cron-parser": "^5.5.0",
@@ -498,6 +498,115 @@
498
498
  "currentAccount",
499
499
  "accounts"
500
500
  ]
501
+ },
502
+ "webex": {
503
+ "type": "object",
504
+ "properties": {
505
+ "currentAccount": {
506
+ "anyOf": [
507
+ {
508
+ "type": "string"
509
+ },
510
+ {
511
+ "type": "null"
512
+ }
513
+ ]
514
+ },
515
+ "accounts": {
516
+ "type": "object",
517
+ "propertyNames": {
518
+ "type": "string"
519
+ },
520
+ "additionalProperties": {
521
+ "type": "object",
522
+ "properties": {
523
+ "account_id": {
524
+ "type": "string"
525
+ },
526
+ "access_token": {
527
+ "type": "string"
528
+ },
529
+ "refresh_token": {
530
+ "type": "string"
531
+ },
532
+ "expires_at": {
533
+ "type": "number"
534
+ },
535
+ "device_url": {
536
+ "type": "string"
537
+ },
538
+ "user_id": {
539
+ "type": "string"
540
+ },
541
+ "client_id": {
542
+ "type": "string"
543
+ },
544
+ "client_secret": {
545
+ "type": "string"
546
+ },
547
+ "created_at": {
548
+ "type": "string"
549
+ },
550
+ "updated_at": {
551
+ "type": "string"
552
+ },
553
+ "email": {
554
+ "type": "string"
555
+ },
556
+ "encryptedPassword": {
557
+ "type": "object",
558
+ "properties": {
559
+ "v": {
560
+ "type": "number",
561
+ "const": 1
562
+ },
563
+ "alg": {
564
+ "type": "string",
565
+ "const": "AES-256-GCM"
566
+ },
567
+ "kid": {
568
+ "type": "string"
569
+ },
570
+ "iv": {
571
+ "type": "string"
572
+ },
573
+ "ciphertext": {
574
+ "type": "string"
575
+ },
576
+ "authTag": {
577
+ "type": "string"
578
+ },
579
+ "createdAt": {
580
+ "type": "string"
581
+ }
582
+ },
583
+ "required": [
584
+ "v",
585
+ "alg",
586
+ "kid",
587
+ "iv",
588
+ "ciphertext",
589
+ "authTag",
590
+ "createdAt"
591
+ ],
592
+ "additionalProperties": false
593
+ }
594
+ },
595
+ "required": [
596
+ "account_id",
597
+ "access_token",
598
+ "refresh_token",
599
+ "expires_at",
600
+ "created_at",
601
+ "updated_at"
602
+ ]
603
+ }
604
+ }
605
+ },
606
+ "required": [
607
+ "currentAccount",
608
+ "accounts"
609
+ ]
501
610
  }
502
611
  },
503
612
  "additionalProperties": {}
@@ -562,9 +562,10 @@ export function detectAttentionEscalation(text: string): boolean {
562
562
  return MORPHEME_PATTERNS.some((pattern) => pattern.test(normalized))
563
563
  }
564
564
 
565
- // Not `xhigh`: that level is OpenAI-family-only. `high` is universal and
566
- // `setThinkingLevel` clamps it down per-model, so it's safe to pass unconditionally.
567
- const ESCALATED_LEVEL: ThinkingLevel = 'high'
565
+ // `xhigh` is the strongest level. It's OpenAI-family-only, but `setThinkingLevel`
566
+ // clamps it per-model (down to `high` on non-OpenAI), so it's safe to pass
567
+ // unconditionally and gives OpenAI models maximum effort on escalation turns.
568
+ const ESCALATED_LEVEL: ThinkingLevel = 'xhigh'
568
569
 
569
570
  export function resolveTurnThinkingLevel(
570
571
  text: string,
package/src/agent/auth.ts CHANGED
@@ -86,7 +86,7 @@ export function getAuthFor(providerId: KnownProviderId): Auth {
86
86
  // Uses the head of the fallback chain; auth for the rest of the chain is
87
87
  // resolved lazily when fallback actually fires.
88
88
  export function getAuth(): Auth {
89
- const defaultRef = getConfig().models.default[0]!
89
+ const defaultRef = getConfig().models.default.refs[0]!
90
90
  return getAuthFor(providerForModelRef(defaultRef))
91
91
  }
92
92
 
@@ -100,7 +100,7 @@ function hasAnyCredentialInEnv(apiKeyEnv: string | null): boolean {
100
100
 
101
101
  function missingCredentialMessage(providerId: KnownProviderId): string {
102
102
  const provider = KNOWN_PROVIDERS[providerId]
103
- const defaultRef = getConfig().models.default[0]!
103
+ const defaultRef = getConfig().models.default.refs[0]!
104
104
  const defaultProviderId = providerForModelRef(defaultRef)
105
105
  // For the `default` profile, name the model in the error message (matches
106
106
  // pre-multi-model behavior). For any other profile, the user is mixing
@@ -14,7 +14,14 @@ import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent
14
14
  import { loadMemory } from '@/bundled-plugins/memory/load-memory'
15
15
  import type { ChannelRouter } from '@/channels/router'
16
16
  import type { ReactionRef } from '@/channels/types'
17
- import { getConfig, resolveModel, resolveProfile } from '@/config'
17
+ import {
18
+ getConfig,
19
+ resolveModel,
20
+ resolveProfile,
21
+ type Models,
22
+ type ResolvedProfile,
23
+ type ThinkingLevel,
24
+ } from '@/config'
18
25
  import { defaultThinkingLevelForRef, isOpenAiFamilyRef, providerForModelRef, type ModelRef } from '@/config/providers'
19
26
  import { renderMcpCatalog } from '@/mcp/catalog'
20
27
  import type { McpManager } from '@/mcp/manager'
@@ -235,6 +242,20 @@ export type CreateSessionResult = {
235
242
  dispose: () => Promise<void>
236
243
  }
237
244
 
245
+ // A session's reasoning effort layers like the model does: the resolved
246
+ // profile's own `thinkingLevel` → the `default` profile's `thinkingLevel`
247
+ // (the de-facto global default, mirroring how `models.default` is the default
248
+ // model) → the per-provider/SDK default for the active ref. When the requested
249
+ // profile was unknown, `resolved` is already the `default` profile, so the
250
+ // first two terms coincide and the expression still does the right thing.
251
+ export function resolveSessionThinkingLevel(
252
+ models: Models,
253
+ resolved: Pick<ResolvedProfile, 'thinkingLevel'>,
254
+ activeRef: ModelRef,
255
+ ): ThinkingLevel | undefined {
256
+ return resolved.thinkingLevel ?? models.default.thinkingLevel ?? defaultThinkingLevelForRef(activeRef)
257
+ }
258
+
238
259
  export async function createSession(options: CreateSessionOptions = {}): Promise<AgentSession> {
239
260
  const { session } = await createSessionWithDispose(options)
240
261
  return session
@@ -439,7 +460,9 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
439
460
  : customToolsPreBudget
440
461
 
441
462
  const model = applyModelRuntimeOverrides(resolveModel(activeRef), activeRef)
442
- const thinkingLevel = defaultThinkingLevelForRef(activeRef)
463
+ // Read live so a reloaded `models` lands on the next session without a
464
+ // container restart.
465
+ const thinkingLevel = resolveSessionThinkingLevel(getConfig().models, resolved, activeRef)
443
466
  const { session } = await createAgentSession({
444
467
  model,
445
468
  sessionManager,
@@ -1,8 +1,7 @@
1
1
  import { basename } from 'node:path'
2
2
 
3
3
  import { type RestartHandoffOrigin, writeRestartHandoff } from '@/agent/restart-handoff'
4
- import { send, sendHttp } from '@/hostd/client'
5
- import { containerSocketPath } from '@/hostd/paths'
4
+ import { sendHttp } from '@/hostd/client'
6
5
  import type { Stream } from '@/stream'
7
6
 
8
7
  const ACK_TIMEOUT_MS = 5_000
@@ -16,7 +15,6 @@ export type ContainerRestartingBroadcast = {
16
15
  export type RequestContainerRestartOptions = {
17
16
  containerName: string
18
17
  build?: boolean
19
- socketPath?: string
20
18
  hostdUrl?: string
21
19
  hostdToken?: string
22
20
  ackTimeoutMs?: number
@@ -49,7 +47,6 @@ export type RequestContainerRestartResult =
49
47
  export async function requestContainerRestart({
50
48
  containerName,
51
49
  build,
52
- socketPath,
53
50
  hostdUrl,
54
51
  hostdToken,
55
52
  ackTimeoutMs,
@@ -65,10 +62,22 @@ export async function requestContainerRestart({
65
62
  const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
66
63
  const httpToken = hostdToken ?? process.env.TYPECLAW_HOSTD_TOKEN
67
64
  const ackBudget = ackTimeoutMs ?? ACK_TIMEOUT_MS
68
- const reply =
69
- httpUrl && httpToken
70
- ? await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
71
- : await send(request, { timeoutMs: ackBudget, socket: socketPath ?? containerSocketPath() })
65
+
66
+ // HTTP/TCP is the only container->hostd transport (TYPECLAW_HOSTD_URL/TOKEN,
67
+ // injected by start.ts via host.docker.internal). There is no Unix-socket
68
+ // fallback: the host run dir is never bind-mounted, so the old
69
+ // `/run/typeclaw-host/hostd.sock` dial always silently failed — and on native
70
+ // Windows the host transport is a named pipe, not a socket. Fail loud here
71
+ // when the control env is absent (hostd unregistered/disabled).
72
+ if (!httpUrl || !httpToken) {
73
+ return {
74
+ ok: false,
75
+ containerName,
76
+ reason:
77
+ 'host daemon control endpoint unavailable (TYPECLAW_HOSTD_URL/TYPECLAW_HOSTD_TOKEN not set); cannot request restart',
78
+ }
79
+ }
80
+ const reply = await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
72
81
 
73
82
  if (!reply.ok) return { ok: false, containerName, reason: reply.reason }
74
83
 
@@ -1,3 +1,4 @@
1
+ import { toRef } from '@/channels/adapters/webex-id-ref'
1
2
  import { MEMBERSHIP_FRESHNESS_MS, type MembershipCount } from '@/channels/membership'
2
3
  import type { AdapterId } from '@/channels/schema'
3
4
  import type { ChannelSelfIdentity, ReactionRef } from '@/channels/types'
@@ -156,6 +157,7 @@ const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
156
157
  supportsReactions: false,
157
158
  supportsAttachments: true,
158
159
  },
160
+ webex: { displayName: 'Webex', mentionMode: 'angle-id', supportsReactions: false, supportsAttachments: true },
159
161
  'webex-bot': { displayName: 'Webex', mentionMode: 'angle-id', supportsReactions: false, supportsAttachments: false },
160
162
  line: { displayName: 'LINE', mentionMode: 'alias', supportsReactions: false, supportsAttachments: false },
161
163
  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias', supportsReactions: false, supportsAttachments: true },
@@ -630,6 +632,12 @@ function renderSelfMention(platformInfo: PlatformInfo, self: ChannelSelfIdentity
630
632
  }
631
633
  }
632
634
 
635
+ const WEBEX_ADAPTERS = new Set<AdapterId>(['webex', 'webex-bot'])
636
+
637
+ function readableChannelId(adapter: AdapterId, id: string): string {
638
+ return WEBEX_ADAPTERS.has(adapter) ? toRef(id) : id
639
+ }
640
+
633
641
  function renderConversationLine(origin: {
634
642
  adapter: AdapterId
635
643
  workspace: string
@@ -642,8 +650,13 @@ function renderConversationLine(origin: {
642
650
  if (!hasChat && !hasWorkspace) return null
643
651
 
644
652
  const chatPrefix = origin.adapter === 'slack-bot' ? '#' : ''
645
- const chatLabel = hasChat ? `**${chatPrefix}${origin.chatName!}** (${origin.chat})` : `\`${origin.chat}\``
646
- const workspaceLabel = hasWorkspace ? `**${origin.workspaceName!}** (${origin.workspace})` : `\`${origin.workspace}\``
653
+ // The parenthetical/backtick id is a human-and-model disambiguator, NOT the
654
+ // send target — tools source the canonical room id from the JSON origin block,
655
+ // which stays raw. So decode webex base64 blobs to their readable ref here.
656
+ const chatId = readableChannelId(origin.adapter, origin.chat)
657
+ const workspaceId = readableChannelId(origin.adapter, origin.workspace)
658
+ const chatLabel = hasChat ? `**${chatPrefix}${origin.chatName!}** (${chatId})` : `\`${chatId}\``
659
+ const workspaceLabel = hasWorkspace ? `**${origin.workspaceName!}** (${workspaceId})` : `\`${workspaceId}\``
647
660
 
648
661
  return `Conversation: ${chatLabel} in ${workspaceLabel}.`
649
662
  }
@@ -130,6 +130,24 @@ function describePayload(payload: unknown): string {
130
130
  return typeof payload
131
131
  }
132
132
 
133
+ // Per-spawn override wins over the subagent's declared profile; absent override
134
+ // keeps the declared profile. Both may be undefined (no profile → createSession
135
+ // resolves `default`).
136
+ export function resolveSubagentProfile(
137
+ subagent: SubagentShared<any>,
138
+ options: CreateSessionForSubagentOptions | undefined,
139
+ ): string | undefined {
140
+ return options?.profileOverride ?? subagent.profile
141
+ }
142
+
143
+ function profileFromPayload(payload: unknown): string | undefined {
144
+ if (payload !== null && typeof payload === 'object') {
145
+ const value = (payload as { profile?: unknown }).profile
146
+ if (typeof value === 'string' && value !== '') return value
147
+ }
148
+ return undefined
149
+ }
150
+
133
151
  export type CreateSessionForSubagentResult = {
134
152
  session: AgentSession
135
153
  dispose?: () => Promise<void>
@@ -160,6 +178,12 @@ export type CreateSessionForSubagentOptions = {
160
178
  // wiring hooks without permissions would inject the GitHub token yet leave the
161
179
  // sandbox OFF — strictly weaker than the plugin-subagent branch this matches.
162
180
  permissions?: PermissionService
181
+ // Per-spawn model-profile override, resolved by `invokeSubagent` from the
182
+ // validated payload's `profile` field. Wins over the subagent's declared
183
+ // `profile`, letting a single spawn run a worker on a different model tier
184
+ // (e.g. operator on `deep`) without a second subagent. Unknown profile names
185
+ // fall back to `default` via resolveProfile, the same as a declared profile.
186
+ profileOverride?: string
163
187
  }
164
188
  export type CreateSessionForSubagent = (
165
189
  subagent: Subagent<any>,
@@ -180,7 +204,9 @@ export const defaultCreateSessionForSubagent: CreateSessionForSubagent = (subage
180
204
  customTools: subagent.customTools ?? [],
181
205
  ...(options?.plugins !== undefined ? { plugins: options.plugins } : {}),
182
206
  ...(options?.permissions !== undefined ? { permissions: options.permissions } : {}),
183
- ...(subagent.profile !== undefined ? { profile: subagent.profile } : {}),
207
+ ...(resolveSubagentProfile(subagent, options) !== undefined
208
+ ? { profile: resolveSubagentProfile(subagent, options) }
209
+ : {}),
184
210
  ...(subagent.toolResultBudget !== undefined ? { toolResultBudget: subagent.toolResultBudget } : {}),
185
211
  ...(subagent.bashPolicy !== undefined ? { bashPolicy: subagent.bashPolicy } : {}),
186
212
  })
@@ -255,11 +281,13 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
255
281
 
256
282
  const validatedPayload = validateSubagentPayload(name, subagent, options.payload)
257
283
  const createSessionForSubagent = options.createSessionForSubagent ?? defaultCreateSessionForSubagent
284
+ const profileOverride = profileFromPayload(validatedPayload)
258
285
  const sessionOptions: CreateSessionForSubagentOptions = {
259
286
  name,
260
287
  ...(options.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
261
288
  ...(options.spawnedByRole !== undefined ? { spawnedByRole: options.spawnedByRole } : {}),
262
289
  ...(options.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
290
+ ...(profileOverride !== undefined ? { profileOverride } : {}),
263
291
  }
264
292
 
265
293
  const runSession: RunSession = async (override) => {
@@ -48,9 +48,23 @@ If it describes how you sound, use SOUL.md; how you work, AGENTS.md. **Edit disc
48
48
  - **\`typeclaw.json\`** — runtime config. Read when needed.
49
49
  - **\`secrets.json\`** — canonical gitignored secrets store. \`.env\` is legacy/env override. Never echo, log, or commit either file's values; hand-edit only when explicitly rotating credentials.
50
50
 
51
- ## Execution bias
51
+ ## Understanding the request
52
52
 
53
- Start work in the same turn when the next action is clear; do not answer with only a plan. For multi-step work, give one short progress update, not narration.
53
+ When the next action is clear, start work in the same turn — don't answer with only a plan, and for multi-step work give one short progress update, not narration.
54
+
55
+ Read for the practical task behind the wording, not the literal speech act: a status question ("is the build red?") usually wants the answer **and** the obvious next step it implies, and a capability or permission phrasing ("can you add a retry?", "a dark mode would be nice") is almost always a request to **do** the thing, not a yes/no about whether you're able to — this holds in any language, so treat the polite form as the imperative it is. Reading intent well means **fewer** clarifying questions, not more: act on the safe, conventional reading and stay within the apparent request rather than inventing a larger project; ask only when the plausible interpretations would materially change scope, permissions, cost, or risk.
56
+
57
+ Recognizing the task also means recognizing **who** should do it. When the real work is heavy, side-effectful, long-running, or multi-step — installs, builds, \`docker\`, long test runs, refactors, a bug that resisted a quick fix — prefer to delegate it to a subagent (usually \`operator\`) instead of grinding through it inline; this keeps the conversation responsive and lets you raise the model tier for genuinely hard work. Keep quick, single-shot answers inline. See \`## Subagent orchestration\` for the mechanics.
58
+
59
+ ## Finishing the job
60
+
61
+ When the user asks you to build, run, fix, or verify something, the deliverable is a working artifact backed by real tool output — not a description of one. Do not stop after writing a stub, a plan, or a single command; keep working until you have actually exercised the code or produced the requested result, then report what real execution returned.
62
+
63
+ If a tool, install, or network call fails and blocks the real path, say so directly and try an alternative (different approach, different package, ask the user). Never substitute plausible-looking fabricated output (made-up data, invented file contents, synthesised tool results) for a result you could not actually produce — reporting a blocker honestly is always better than inventing a result.
64
+
65
+ ## Parallel tool calls
66
+
67
+ When you need several pieces of information that don't depend on each other, request them in a single response instead of one tool call per turn. Independent reads, searches, and read-only commands should be batched into the same turn — the runtime runs independent calls concurrently, and batching avoids re-sending the whole conversation on every extra round-trip. Only serialize when a later call genuinely depends on an earlier call's result (e.g. read a file before patching it).
54
68
 
55
69
  ## Tracking your work
56
70
 
@@ -96,7 +110,6 @@ Commits to your agent folder (your own state):
96
110
  - Match the user's register. If SOUL.md specifies a voice, use it; otherwise be concise and direct.
97
111
  - Read files/memory before guessing. Follow AGENTS.md under your IDENTITY.md role; suggest AGENTS.md additions for repeatable gaps.
98
112
  - Answer questions, do work, and avoid over-explaining unless asked.
99
- - Ask one clarifying question only when ambiguity would materially change the work; otherwise choose a reasonable default.
100
113
  - Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
101
114
 
102
115
  ## Subagent orchestration
@@ -107,9 +120,9 @@ Pick one of three modes:
107
120
 
108
121
  **Mode A — Research fan-out.** Broad search: spawn 2-5 \`explorer\`/\`scout\` workers in parallel with \`run_in_background: true\`, end your response, then collect each completion once via \`subagent_output\`. Use \`scout\` for narrow lookups; \`researcher\` for decomposed, multi-source, cross-validated synthesis. When the user *explicitly* says "research"/"investigate" (or equivalent), you MUST spawn \`researcher\` — answering from training memory or a single inline \`web_search\` does not satisfy the request, even if you think you know the answer. (Fanning out \`scout\`/\`explorer\` underneath is fine, but it does not replace \`researcher\`.)
109
122
 
110
- **Mode B — Delegate-and-converse.** For >~30s side-effectful/noisy work (installs, builds, \`docker\`, scrapes, long tests, multi-host loops, fetch-and-synthesize chains), spawn one background subagent and stay responsive: \`operator\` for side effects, \`scout\` quick lookup, \`researcher\` deep investigation, \`planner\` risk-aware sequencing. Keep single fast calls inline. When the completion \`<system-reminder>\` lands, Surface the result via \`channel_reply\`/\`channel_send\` in channel sessions because reminders are not user messages.
123
+ **Mode B — Delegate-and-converse.** For >~30s side-effectful/noisy work (installs, builds, \`docker\`, scrapes, long tests, multi-host loops, fetch-and-synthesize chains), spawn one background subagent and stay responsive: \`operator\` for side effects, \`scout\` quick lookup, \`researcher\` deep investigation, \`planner\` risk-aware sequencing. Keep single fast calls inline. For hard execution work that needs stronger reasoning than the default tier — gnarly bugs, non-obvious refactors, failures that resisted a quick fix — pass \`profile: "deep"\` to run that one spawn on a stronger model; leave it off for routine work. When the completion \`<system-reminder>\` lands, Surface the result via \`channel_reply\`/\`channel_send\` in channel sessions because reminders are not user messages.
111
124
 
112
- **Mode C — Troubleshooting.** After ~3 non-converging attempts at the same failure, stop and hand the loop to \`operator\` with \`run_in_background: true\`, symptom, attempts, and success condition. Read \`typeclaw-troubleshooting\` before spawning.
125
+ **Mode C — Troubleshooting.** After ~3 non-converging attempts at the same failure, stop and hand the loop to \`operator\` with \`run_in_background: true\` (and \`profile: "deep"\` when the failure is genuinely hard), symptom, attempts, and success condition. Read \`typeclaw-troubleshooting\` before spawning.
113
126
 
114
127
  **Status queries.** If the user asks "status?" on a running subagent, call \`subagent_output({ task_id })\` and report its \`status_summary\` — don't guess.
115
128
 
@@ -10,7 +10,6 @@ const EXIT_DELAY_MS = 500
10
10
  export type CreateRestartToolOptions = {
11
11
  containerName: string
12
12
  exit?: (code: number) => void
13
- socketPath?: string
14
13
  hostdUrl?: string
15
14
  hostdToken?: string
16
15
  // Optional so unit tests and ad-hoc tool construction keep working without
@@ -72,7 +71,6 @@ export type { ContainerRestartingBroadcast } from '@/agent/restart'
72
71
  export function createRestartTool({
73
72
  containerName,
74
73
  exit,
75
- socketPath,
76
74
  hostdUrl,
77
75
  hostdToken,
78
76
  stream,
@@ -121,7 +119,6 @@ export function createRestartTool({
121
119
  containerName,
122
120
  build,
123
121
  originatingSessionId,
124
- ...(socketPath !== undefined ? { socketPath } : {}),
125
122
  ...(hostdUrl !== undefined ? { hostdUrl } : {}),
126
123
  ...(hostdToken !== undefined ? { hostdToken } : {}),
127
124
  ...(ackTimeoutMs !== undefined ? { ackTimeoutMs } : {}),
@@ -88,6 +88,12 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
88
88
  'NOTE: background mode from subagents is only available when that subagent is explicitly enabled to drain child results; otherwise use sync spawns batched in one turn instead.',
89
89
  }),
90
90
  ),
91
+ profile: Type.Optional(
92
+ Type.String({
93
+ description:
94
+ 'Model profile to run this spawn on, overriding the subagent\'s default tier for this one task. Use "deep" for hard work that needs stronger reasoning (gnarly bugs, non-obvious refactors, failures that resisted a quick fix); omit (or "default") for routine work. Resolves against the configured model profiles; an unknown name falls back to default. Most useful on `operator` — leave it off unless the task clearly warrants a heavier model.',
95
+ }),
96
+ ),
91
97
  }),
92
98
 
93
99
  async execute(_toolCallId, params): Promise<ToolReturn> {
@@ -122,6 +128,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
122
128
  const background = params.run_in_background === true
123
129
  const payload: Record<string, unknown> = { requestId: taskId, prompt: params.prompt }
124
130
  if (params.description !== undefined) payload.description = params.description
131
+ if (params.profile !== undefined) payload.profile = params.profile
125
132
 
126
133
  const startedAt = now()
127
134
  const spawnedByRole = permissions?.resolveRole(origin)
@@ -42,7 +42,7 @@ All fields are **restart-required** — the plugin reads them once at boot. The
42
42
  | Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`. |
43
43
  | Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip. |
44
44
  | Hook | `session.end` | Spawns `memory-logger` immediately; also unlinks the retrieval-cache file for this session. |
45
- | Hook | `session.turn.start` | **Vector on:** renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including subagents. **Vector off:** when `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question. Fire-and-forget; failures route through the plugin logger. |
45
+ | Hook | `session.turn.start` | **Vector on:** renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). **Vector off:** when `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question. Fire-and-forget; failures route through the plugin logger. |
46
46
 
47
47
  ## Memory injection (two-tier, topic shards only)
48
48
 
@@ -61,6 +61,17 @@ Default budget is 16 KB. Direct mode when shard bytes sum ≤ budget: all shard
61
61
 
62
62
  The invariant `suppressSystemMemory === memory.vector.enabled` is load-bearing: a session must never carry memory in both the system prompt and the user turn.
63
63
 
64
+ ### Internal-infrastructure turns skip retrieval
65
+
66
+ The `session.turn.start` per-turn injection runs for user-delegated subagents (researcher, reviewer) but is skipped entirely for **TypeClaw-owned infrastructure turns**. Their `userPrompt` is a fixed instruction block (`buildInitialPrompt`), not a user message — feeding it into `hybridSearch` keyword-mines the subagent's own framing prose ("Read the transcript past the watermark…"), retrieves nothing useful, and embeds a ~560-token query that trips the 512-token bound warning on every spawn. None of these subagents consume injected long-term memory the way a conversational turn does, so retrieval there is pure waste.
67
+
68
+ The discriminator (`isInternalInfraTurn` in `index.ts`) matches two provenance shapes, because the infra subagents are spawned two different ways:
69
+
70
+ - **`system` provenance** — `memory-logger` and `backup` are spawned directly with a `system` parent origin, so either a `system` origin itself or a subagent whose `spawnedByOrigin.kind === 'system'` is skipped.
71
+ - **The dreaming cron job** — `dreaming` is spawned by the memory plugin's own cron job (`__plugin_memory_dreaming`), so its parent origin is `cron`, NOT `system` (the cron consumer stamps a `cron` parentOrigin so the subagent resolves to the right role). It is matched by that specific job id — `spawnedByOrigin.kind === 'cron' && jobId === __plugin_memory_dreaming` — derived via `buildPluginCronGlobalId` so it can't drift from the registration. A **user-scheduled** cron subagent has a different job id and is real delegated work, so it keeps memory.
72
+
73
+ This is the same "don't mine framing prose" class of bug PR #340 fixed for `memory-retrieval`, applied to the subagent turn-start path.
74
+
64
75
  ### Vector retrieval is parent-child, not a flat pool
65
76
 
66
77
  When `memory.vector.enabled` is true, `hybridSearch` does **not** rank topic vectors and stream-fragment vectors together in one flat cosine pool. It uses a parent-child collapse so the result set is always topic-level current truth: