typeclaw 0.39.7 → 0.40.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 (58) hide show
  1. package/package.json +1 -1
  2. package/scripts/dump-system-prompt.ts +4 -50
  3. package/src/agent/auth-reloadable.ts +24 -0
  4. package/src/agent/auth.ts +12 -0
  5. package/src/agent/index.ts +18 -58
  6. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +0 -2
  7. package/src/bundled-plugins/guard/policy.ts +0 -5
  8. package/src/bundled-plugins/memory/README.md +26 -37
  9. package/src/bundled-plugins/memory/index.ts +30 -144
  10. package/src/bundled-plugins/memory/load-memory.ts +7 -121
  11. package/src/bundled-plugins/memory/memory-logger.ts +8 -2
  12. package/src/bundled-plugins/memory/search-command.ts +2 -11
  13. package/src/bundled-plugins/memory/vector/doctor.ts +1 -1
  14. package/src/bundled-plugins/memory/vector/embedder.ts +4 -5
  15. package/src/bundled-plugins/memory/vector/hybrid.ts +47 -5
  16. package/src/bundled-plugins/memory/vector/relevance-gate.ts +11 -7
  17. package/src/bundled-plugins/memory/vector/script.ts +87 -0
  18. package/src/channels/adapters/describe-error.ts +40 -0
  19. package/src/channels/adapters/discord.ts +9 -12
  20. package/src/channels/adapters/kakaotalk.ts +14 -17
  21. package/src/channels/adapters/line.ts +11 -14
  22. package/src/channels/adapters/slack-bot.ts +15 -18
  23. package/src/channels/adapters/slack.ts +45 -21
  24. package/src/channels/adapters/telegram-bot.ts +15 -18
  25. package/src/channels/adapters/webex-bot.ts +13 -14
  26. package/src/channels/adapters/webex.ts +14 -15
  27. package/src/cli/compose.ts +20 -0
  28. package/src/cli/docker-preflight.ts +42 -0
  29. package/src/cli/hostd.ts +12 -3
  30. package/src/cli/init.ts +24 -22
  31. package/src/cli/logs.ts +7 -0
  32. package/src/cli/provider.ts +8 -1
  33. package/src/cli/reload.ts +6 -0
  34. package/src/cli/restart.ts +7 -0
  35. package/src/cli/shell.ts +7 -0
  36. package/src/cli/start.ts +7 -0
  37. package/src/cli/status.ts +9 -0
  38. package/src/cli/stop.ts +7 -0
  39. package/src/cli/tui.ts +6 -0
  40. package/src/config/config.ts +31 -8
  41. package/src/container/docker-app.ts +253 -0
  42. package/src/container/index.ts +11 -0
  43. package/src/container/start.ts +85 -41
  44. package/src/hostd/current-host-daemon.ts +21 -0
  45. package/src/hostd/daemon.ts +27 -3
  46. package/src/hostd/supervisor.ts +18 -3
  47. package/src/plugin/hooks.ts +3 -4
  48. package/src/plugin/types.ts +1 -1
  49. package/src/run/channel-session-factory.ts +3 -5
  50. package/src/run/index.ts +17 -16
  51. package/src/server/command-runner.ts +2 -11
  52. package/src/skills/typeclaw-memory/SKILL.md +2 -2
  53. package/src/skills/typeclaw-plugins/SKILL.md +1 -1
  54. package/typeclaw.schema.json +1 -23
  55. package/src/bundled-plugins/guard/policies/memory-retrieval-cache-write.ts +0 -43
  56. package/src/bundled-plugins/memory/memory-retrieval.ts +0 -111
  57. package/src/bundled-plugins/memory/vector/cache-write.ts +0 -19
  58. package/src/bundled-plugins/memory/vector/config.ts +0 -28
@@ -1197,7 +1197,7 @@ export function loadConfigBundleSync(cwd: string): { config: Config; pluginConfi
1197
1197
  // `changed` is the boolean equivalent of `applied.length > 0` and is preserved
1198
1198
  // for back-compat with the many call sites that only care whether ANY rewrite
1199
1199
  // happened.
1200
- export type MigrationStep = { kind: 'drop-github-seeded-event-allowlist' }
1200
+ export type MigrationStep = { kind: 'drop-github-seeded-event-allowlist' } | { kind: 'drop-memory-vector-config' }
1201
1201
 
1202
1202
  export type MigrationResult = { json: unknown; changed: boolean; applied: MigrationStep[] }
1203
1203
 
@@ -1207,18 +1207,20 @@ export function migrateLegacyConfigShape(json: unknown): MigrationResult {
1207
1207
  }
1208
1208
 
1209
1209
  const obj = json as Record<string, unknown>
1210
- const hasSeededGithubEventAllowlist = isSeededGithubEventAllowlist(obj)
1211
- if (!hasSeededGithubEventAllowlist) {
1212
- return { json, changed: false, applied: [] }
1213
- }
1214
-
1215
1210
  const applied: MigrationStep[] = []
1216
1211
  const next: Record<string, unknown> = { ...obj }
1217
- if (hasSeededGithubEventAllowlist) {
1212
+
1213
+ if (isSeededGithubEventAllowlist(obj)) {
1218
1214
  dropSeededGithubEventAllowlist(next)
1219
1215
  applied.push({ kind: 'drop-github-seeded-event-allowlist' })
1220
1216
  }
1221
- return { json: next, changed: true, applied }
1217
+
1218
+ if (hasLegacyMemoryVectorConfig(obj)) {
1219
+ dropMemoryVectorConfig(next)
1220
+ applied.push({ kind: 'drop-memory-vector-config' })
1221
+ }
1222
+
1223
+ return { json: applied.length > 0 ? next : json, changed: applied.length > 0, applied }
1222
1224
  }
1223
1225
 
1224
1226
  // True when channels.github.eventAllowlist deep-equals an allowlist that
@@ -1243,6 +1245,23 @@ function dropSeededGithubEventAllowlist(next: Record<string, unknown>): void {
1243
1245
  next.channels = { ...channels, github: rest }
1244
1246
  }
1245
1247
 
1248
+ function hasLegacyMemoryVectorConfig(obj: Record<string, unknown>): boolean {
1249
+ const memory = obj.memory
1250
+ return isPlainObject(memory) && Object.prototype.hasOwnProperty.call(memory, 'vector')
1251
+ }
1252
+
1253
+ function dropMemoryVectorConfig(next: Record<string, unknown>): void {
1254
+ const memory = next.memory
1255
+ if (!isPlainObject(memory)) return
1256
+ const clone = { ...memory }
1257
+ delete clone.vector
1258
+ if (Object.keys(clone).length === 0) {
1259
+ delete next.memory
1260
+ return
1261
+ }
1262
+ next.memory = clone
1263
+ }
1264
+
1246
1265
  function arraysEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
1247
1266
  if (a.length !== b.length) return false
1248
1267
  for (let i = 0; i < a.length; i++) {
@@ -1267,6 +1286,8 @@ function shortStepLabel(step: MigrationStep): string {
1267
1286
  switch (step.kind) {
1268
1287
  case 'drop-github-seeded-event-allowlist':
1269
1288
  return 'drop seeded channels.github.eventAllowlist'
1289
+ case 'drop-memory-vector-config':
1290
+ return 'drop memory.vector config'
1270
1291
  }
1271
1292
  }
1272
1293
 
@@ -1274,6 +1295,8 @@ function describeStep(step: MigrationStep): string {
1274
1295
  switch (step.kind) {
1275
1296
  case 'drop-github-seeded-event-allowlist':
1276
1297
  return 'drop seeded channels.github.eventAllowlist so it re-tracks the shipped default'
1298
+ case 'drop-memory-vector-config':
1299
+ return 'drop memory.vector config; vector memory is always on'
1277
1300
  }
1278
1301
  }
1279
1302
 
@@ -0,0 +1,253 @@
1
+ import { existsSync } from 'node:fs'
2
+
3
+ import { getBun } from './shared'
4
+ import type { DockerAvailability } from './shared'
5
+
6
+ // Detection + friendly guidance for "Docker is not reachable".
7
+ //
8
+ // `checkDockerAvailable` (in ./shared) already tells us WHETHER docker works and
9
+ // discriminates `binary-missing` (no `docker` on PATH) from `daemon-down` (CLI
10
+ // present, daemon refused the connection — the common "Docker Desktop / OrbStack
11
+ // installed but not started" case on macOS). What it does NOT do is tell the
12
+ // user WHICH runtime to nudge. This module fills that gap: it classifies the
13
+ // likely runtime and renders a short, copy-pasteable instruction instead of
14
+ // leaking the raw daemon error (which on OrbStack embeds a per-user socket path
15
+ // under the user's home dir — noise the user can't act on).
16
+ //
17
+ // Classification priority (most → least authoritative):
18
+ // 1. The configured socket: `DOCKER_HOST` or the socket path inside the raw
19
+ // daemon-down `detail`. An `orbstack` / `docker-desktop` / `colima` /
20
+ // `podman` marker in that path is a high-confidence signal of the runtime
21
+ // the CLI is actually configured to talk to — sharper than guessing from
22
+ // what's installed on disk.
23
+ // 2. Installed-app probes (filesystem / PATH). A fallback used only when the
24
+ // socket gives no hint.
25
+ // 3. Platform default (generic "start your Docker daemon").
26
+
27
+ export type DockerApp = 'docker-desktop' | 'orbstack' | 'colima' | 'podman'
28
+
29
+ export type DockerAppProbes = {
30
+ platform?: NodeJS.Platform
31
+ exists?: (path: string) => boolean
32
+ which?: (command: string) => string | null
33
+ env?: NodeJS.ProcessEnv
34
+ }
35
+
36
+ const APP_LABELS: Record<DockerApp, string> = {
37
+ 'docker-desktop': 'Docker Desktop',
38
+ orbstack: 'OrbStack',
39
+ colima: 'Colima',
40
+ podman: 'Podman',
41
+ }
42
+
43
+ export function dockerAppLabel(app: DockerApp): string {
44
+ return APP_LABELS[app]
45
+ }
46
+
47
+ function defaultWhich(command: string): string | null {
48
+ return getBun()?.which(command) ?? null
49
+ }
50
+
51
+ function resolveProbes(probes: DockerAppProbes): Required<DockerAppProbes> {
52
+ return {
53
+ platform: probes.platform ?? process.platform,
54
+ exists: probes.exists ?? existsSync,
55
+ which: probes.which ?? defaultWhich,
56
+ env: probes.env ?? process.env,
57
+ }
58
+ }
59
+
60
+ // Reads the socket the docker CLI is configured to use and classifies the
61
+ // runtime from its path. `DOCKER_HOST` wins (it overrides the default socket);
62
+ // otherwise we fall back to the socket path docker printed inside its own
63
+ // connection-refused error. Both are matched case-insensitively on the vendor's
64
+ // own directory/socket naming, which is ASCII by the tools' own conventions —
65
+ // these are protocol/path tokens, not human language, so English matching is
66
+ // correct here.
67
+ export function classifyConfiguredRuntime(env: NodeJS.ProcessEnv, detail: string | undefined): DockerApp | null {
68
+ // DOCKER_HOST is the runtime the CLI is actually configured to talk to, so it
69
+ // must win outright: classify it alone first and only consult the daemon error
70
+ // detail when DOCKER_HOST names no recognized runtime. Folding both into one
71
+ // haystack would let a stale marker in the error text override an explicit
72
+ // DOCKER_HOST (e.g. DOCKER_HOST=…/.colima/… but the error mentions orbstack).
73
+ return classifyRuntimeMarker(env.DOCKER_HOST) ?? classifyRuntimeMarker(detail)
74
+ }
75
+
76
+ function classifyRuntimeMarker(text: string | undefined): DockerApp | null {
77
+ if (!text) return null
78
+ const lower = text.toLowerCase()
79
+ if (lower.includes('orbstack')) return 'orbstack'
80
+ if (lower.includes('colima')) return 'colima'
81
+ if (lower.includes('podman')) return 'podman'
82
+ // Docker Desktop's user socket lives under `~/.docker/<context>/docker.sock`;
83
+ // the only stable runtime marker in that path is the `desktop`/`desktop-linux`
84
+ // context dir. Checked last so a colima/orbstack context that also sits under
85
+ // `~/.docker` is classified by its own sharper marker first.
86
+ if (lower.includes('desktop')) return 'docker-desktop'
87
+ return null
88
+ }
89
+
90
+ // Probes which Docker runtimes are installed on disk / PATH, most-canonical
91
+ // first. macOS app bundles for the GUI runtimes; PATH binaries for the CLI-first
92
+ // runtimes (Colima/Podman). The list is deliberately conservative — a false
93
+ // "installed" only downgrades the message from runtime-specific to generic, it
94
+ // never blocks anything.
95
+ export function detectInstalledDockerApps(probes: DockerAppProbes = {}): DockerApp[] {
96
+ const { platform, exists, which, env } = resolveProbes(probes)
97
+ const found: DockerApp[] = []
98
+
99
+ if (platform === 'darwin') {
100
+ if (exists('/Applications/Docker.app')) found.push('docker-desktop')
101
+ if (exists('/Applications/OrbStack.app')) found.push('orbstack')
102
+ }
103
+
104
+ if (platform === 'win32') {
105
+ if (windowsDockerDesktopInstalled(env, exists)) found.push('docker-desktop')
106
+ if (windowsPodmanInstalled(env, exists)) found.push('podman')
107
+ }
108
+
109
+ // Colima and OrbStack are macOS/Linux only, so probing them on win32 would be
110
+ // dead weight; Podman ships a `podman.exe` that also lands on PATH, caught by
111
+ // the install-path probe above. Off Windows, the PATH binaries are the
112
+ // canonical signal for the CLI-first runtimes.
113
+ if (platform !== 'win32') {
114
+ if (which('colima') !== null) found.push('colima')
115
+ if (which('podman') !== null) found.push('podman')
116
+ }
117
+
118
+ return found
119
+ }
120
+
121
+ // Docker Desktop's GUI launcher (`Docker Desktop.exe`) across the MSI, 32-bit,
122
+ // and per-user install layouts confirmed by the Docker Desktop installer and
123
+ // PowerShell's own probing scripts. Probing the exe (not just `docker` on PATH)
124
+ // is what lets us say "Docker Desktop is installed but not started" when the
125
+ // daemon is down — a stale PATH can hide the CLI even when Desktop is present.
126
+ function windowsDockerDesktopInstalled(env: NodeJS.ProcessEnv, exists: (path: string) => boolean): boolean {
127
+ const programFiles = env.ProgramW6432 ?? env.ProgramFiles ?? 'C:\\Program Files'
128
+ const programFilesX86 = env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)'
129
+ const candidates = [
130
+ `${programFiles}\\Docker\\Docker\\Docker Desktop.exe`,
131
+ `${programFilesX86}\\Docker\\Docker\\Docker Desktop.exe`,
132
+ ]
133
+ if (env.LOCALAPPDATA) {
134
+ candidates.push(`${env.LOCALAPPDATA}\\Programs\\Docker\\Docker\\Docker Desktop.exe`)
135
+ }
136
+ return candidates.some(exists)
137
+ }
138
+
139
+ // Podman's Windows install layouts: per-machine (current + legacy RedHat path)
140
+ // and per-user, from the official podman win-installer test script.
141
+ function windowsPodmanInstalled(env: NodeJS.ProcessEnv, exists: (path: string) => boolean): boolean {
142
+ const programFiles = env.ProgramW6432 ?? env.ProgramFiles ?? 'C:\\Program Files'
143
+ const candidates = [`${programFiles}\\Podman\\podman.exe`, `${programFiles}\\RedHat\\Podman\\podman.exe`]
144
+ if (env.LOCALAPPDATA) {
145
+ candidates.push(`${env.LOCALAPPDATA}\\Programs\\Podman\\podman.exe`)
146
+ }
147
+ return candidates.some(exists)
148
+ }
149
+
150
+ // The runtime we should nudge the user to start: configured-socket hint first,
151
+ // then the single installed app (if unambiguous), else null (caller emits the
152
+ // generic message). When multiple apps are installed and the socket gives no
153
+ // hint we deliberately return null rather than guess wrong — the
154
+ // "don't claim OrbStack just because the bundle exists" guardrail.
155
+ export function pickRuntimeToNudge(
156
+ env: NodeJS.ProcessEnv,
157
+ detail: string | undefined,
158
+ installed: DockerApp[],
159
+ ): DockerApp | null {
160
+ const configured = classifyConfiguredRuntime(env, detail)
161
+ if (configured !== null) return configured
162
+ if (installed.length === 1) return installed[0] ?? null
163
+ return null
164
+ }
165
+
166
+ function startInstructions(app: DockerApp, platform: NodeJS.Platform): string[] {
167
+ switch (app) {
168
+ case 'orbstack':
169
+ return platform === 'darwin'
170
+ ? ['Open OrbStack (from Applications or Spotlight), then retry.', 'Or from a terminal: `orb start`']
171
+ : ['Start OrbStack, then retry. (`orb start`)']
172
+ case 'docker-desktop':
173
+ if (platform === 'darwin') {
174
+ return [
175
+ 'Open Docker Desktop (from Applications or Spotlight), then retry.',
176
+ 'Or from a terminal: `open -a Docker`',
177
+ ]
178
+ }
179
+ if (platform === 'win32') {
180
+ return ['Start Docker Desktop from the Start menu, then retry.']
181
+ }
182
+ return ['Start Docker Desktop, then retry.']
183
+ case 'colima':
184
+ return ['Start Colima, then retry: `colima start`']
185
+ case 'podman':
186
+ return ['Start the Podman machine, then retry: `podman machine start`']
187
+ }
188
+ }
189
+
190
+ // Generic "start your daemon" guidance when we can't name the runtime. On Linux
191
+ // the daemon is usually systemd-managed; elsewhere it's a GUI app.
192
+ function genericStartInstructions(platform: NodeJS.Platform): string[] {
193
+ if (platform === 'linux') {
194
+ return ['Start the Docker daemon, then retry.', 'On most distros: `sudo systemctl start docker`']
195
+ }
196
+ if (platform === 'darwin') {
197
+ return ['Start your Docker runtime (Docker Desktop or OrbStack), then retry.']
198
+ }
199
+ return ['Start your Docker runtime, then retry.']
200
+ }
201
+
202
+ const INSTALL_LINES = [
203
+ 'TypeClaw runs every agent inside its own Docker container, so Docker is required.',
204
+ '',
205
+ 'Install one of:',
206
+ ' • Docker Desktop — https://docs.docker.com/get-docker/',
207
+ ' • OrbStack (macOS, lighter) — https://orbstack.dev',
208
+ ]
209
+
210
+ // Builds the friendly, multi-line guidance shown when Docker is unavailable.
211
+ // Pure (no I/O): callers pass the availability result plus pre-probed detection
212
+ // facts so this stays trivially testable and reusable by both the CLI preflight
213
+ // and `typeclaw init`. `retryHint` lets each caller append its own next step
214
+ // (e.g. "re-run `typeclaw init`" vs "retry `typeclaw start`").
215
+ export function renderDockerUnavailableGuidance(
216
+ availability: Extract<DockerAvailability, { ok: false }>,
217
+ options: {
218
+ platform: NodeJS.Platform
219
+ nudge: DockerApp | null
220
+ installed: DockerApp[]
221
+ retryHint?: string
222
+ },
223
+ ): { summary: string; lines: string[] } {
224
+ const { platform, nudge, installed, retryHint } = options
225
+
226
+ if (availability.reason === 'binary-missing') {
227
+ const lines = [...INSTALL_LINES]
228
+ if (retryHint) {
229
+ lines.push('', retryHint)
230
+ }
231
+ return { summary: 'Docker is not installed.', lines }
232
+ }
233
+
234
+ // daemon-down
235
+ const lines: string[] = []
236
+ let summary: string
237
+ if (nudge !== null) {
238
+ summary = `Docker is not running. ${dockerAppLabel(nudge)} is installed but not started.`
239
+ lines.push(...startInstructions(nudge, platform))
240
+ } else if (installed.length > 1) {
241
+ const names = installed.map(dockerAppLabel).join(', ')
242
+ summary = 'Docker is not running.'
243
+ lines.push(`Detected: ${names}. Start whichever one you use, then retry.`)
244
+ } else {
245
+ summary = 'Docker is installed but the daemon is not reachable.'
246
+ lines.push(...genericStartInstructions(platform))
247
+ }
248
+
249
+ if (retryHint) {
250
+ lines.push('', retryHint)
251
+ }
252
+ return { summary, lines }
253
+ }
@@ -1,3 +1,12 @@
1
+ export {
2
+ classifyConfiguredRuntime,
3
+ detectInstalledDockerApps,
4
+ dockerAppLabel,
5
+ pickRuntimeToNudge,
6
+ renderDockerUnavailableGuidance,
7
+ type DockerApp,
8
+ type DockerAppProbes,
9
+ } from './docker-app'
1
10
  export { buildDockerLogsCmd, logs, parseTailValue, planLogs, type LogsPlan, type LogsResult } from './logs'
2
11
  export { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, resolveHostPort, resolveTuiToken } from './port'
3
12
  export {
@@ -26,6 +35,8 @@ export {
26
35
  refreshDockerfile,
27
36
  refreshGitignore,
28
37
  start,
38
+ type CurrentHostDaemon,
39
+ type HostDaemonRegisterPayload,
29
40
  type HostDaemonStatus,
30
41
  type PlanStartOptions,
31
42
  type StartOptions,
@@ -4,12 +4,11 @@ import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
4
4
  import { tmpdir } from 'node:os'
5
5
  import { isAbsolute, join, relative, resolve } from 'node:path'
6
6
 
7
- import { agentUsesVector } from '@/bundled-plugins/memory/vector/config'
8
- import { expandMountPath, loadConfigSync, withDefaultPlugins, type Config } from '@/config'
7
+ import { expandMountPath, loadConfigSync, withDefaultPlugins, type Config, type PortForward } from '@/config'
9
8
  import { commitGitignoreWithUntracks, untrackTrulyIgnoredFiles } from '@/git/reconcile-ignored'
10
9
  import { commitSystemFile as commitSystemFileShared } from '@/git/system-commit'
11
10
  import { send as sendToDaemon } from '@/hostd/client'
12
- import { ensureModels } from '@/hostd/models'
11
+ import { ensureModels as ensureHostModels } from '@/hostd/models'
13
12
  import { homeRoot } from '@/hostd/paths'
14
13
  import type { HttpInfoResult } from '@/hostd/protocol'
15
14
  import { ensureDaemon, type EnsureDaemonResult } from '@/hostd/spawn'
@@ -94,6 +93,27 @@ export type HostDaemonControl = {
94
93
  brokerToken: string
95
94
  }
96
95
 
96
+ // Mirrors the `register` RPC's fields minus `kind`; shared by socket and
97
+ // in-process registration so both paths record the same registry entry.
98
+ export type HostDaemonRegisterPayload = {
99
+ containerName: string
100
+ cwd: string
101
+ restartToken: string
102
+ wsHostPort: number
103
+ portForward: PortForward
104
+ brokerToken: string
105
+ }
106
+
107
+ // Injected only on the daemon-owned restart path (reuseCurrentHostDaemon).
108
+ // The daemon registers the container in-process and reports its own HTTP port,
109
+ // so the restart skips the `http-info`/`register` self-RPCs — those round-trips
110
+ // can time out under IPC congestion and silently drop the TYPECLAW_HOSTD_* env
111
+ // triple, booting a container whose hostd-bridged adapters can't construct.
112
+ export type CurrentHostDaemon = {
113
+ httpPort: number
114
+ register: (payload: HostDaemonRegisterPayload) => Promise<{ ok: true } | { ok: false; reason: string }>
115
+ }
116
+
97
117
  export type StartOptions = {
98
118
  cwd: string
99
119
  preferredHostPort: number
@@ -106,7 +126,14 @@ export type StartOptions = {
106
126
  // Hostd's supervisor restart callback already runs inside the daemon process.
107
127
  // Reusing that daemon avoids a self-shutdown when disk source has drifted.
108
128
  reuseCurrentHostDaemon?: boolean
129
+ // Set by hostd's supervisor restart wrapper. When present, registration goes
130
+ // through the daemon in-process (no socket round-trips), so the env triple is
131
+ // injected from known-good values even under IPC congestion. See type docs.
132
+ currentHostDaemon?: CurrentHostDaemon
109
133
  ensureDeps?: (cwd: string, opts?: { force?: boolean }) => Promise<EnsureDepsResult>
134
+ // Test seam for host embedding model provisioning. Production callers use
135
+ // the file-locked host cache downloader.
136
+ ensureModels?: () => Promise<void>
110
137
  // Test seam for the typeclaw-version auto-upgrade. Production callers omit
111
138
  // this and get the real autoUpgradeTypeclawDep (which reads the CLI's own
112
139
  // package.json). Tests inject a stub to simulate `bun -g update typeclaw`
@@ -183,7 +210,9 @@ export async function start({
183
210
  allocatePort = findFreePort,
184
211
  cliEntry,
185
212
  reuseCurrentHostDaemon = false,
213
+ currentHostDaemon,
186
214
  ensureDeps = (dir, opts) => ensureDepsInstalled({ cwd: dir, ...opts }),
215
+ ensureModels = ensureHostModels,
187
216
  autoUpgrade = (dir) => autoUpgradeTypeclawDep({ cwd: dir, localSpec: resolveTypeclawSpec(dir) }),
188
217
  forceBunUpdate = runBunUpdate,
189
218
  readInstalledVersion = readInstalledTypeclawVersionFromAgent,
@@ -352,19 +381,14 @@ export async function start({
352
381
  // container will actually load.
353
382
  const dockerfileRefresh = await refreshDockerfile(cwd, { buildKit: hasBuildx })
354
383
 
355
- // Provision the embedding model only when THIS agent opts into vector. The
356
- // container embedder runs with local_files_only, so the model must already
357
- // be on the host's ~/.typeclaw/models cache before the container boots —
358
- // otherwise the startup vector index build fails. Kick the download off here
359
- // (idempotent + file-locked) so it overlaps the docker build, then await it
360
- // just before `docker run`. A vector-opted-out agent never reaches this, so
361
- // a host whose containers are all opted out never downloads the ~280 MB
362
- // model — including every agent under `typeclaw compose`, since each agent's
363
- // start() makes this decision independently. The `.catch` swallow only keeps
364
- // an early return between here and the await from logging an unhandled
365
- // rejection; the real error is surfaced when we await at the run site below.
366
- const modelsReady = agentUsesVector(cwd) ? ensureModels() : null
367
- modelsReady?.catch(() => {})
384
+ // The container embedder runs with local_files_only, so the model must
385
+ // already be on the host's ~/.typeclaw/models cache before the container
386
+ // boots. Kick the download off here (idempotent + file-locked) so it
387
+ // overlaps the docker build, then await it just before `docker run`. The
388
+ // `.catch` swallow only keeps an early return between here and the await
389
+ // from logging an unhandled rejection; the real error is surfaced below.
390
+ const modelsReady = ensureModels()
391
+ modelsReady.catch(() => {})
368
392
 
369
393
  if (state.exists) {
370
394
  // Container holds the name but is not running. Without `--rm`, this is
@@ -424,7 +448,7 @@ export async function start({
424
448
  // Register AFTER port allocation so the daemon's portbroker has the right
425
449
  // wsHostPort. Re-register on TOCTOU retry below if the port changes.
426
450
  let hostd: PreparedHostDaemonStatus = cliEntry
427
- ? await registerWithDaemon({ cwd, containerName, cliEntry, hostPort, reuseCurrentHostDaemon })
451
+ ? await registerWithDaemon({ cwd, containerName, cliEntry, hostPort, reuseCurrentHostDaemon, currentHostDaemon })
428
452
  : { state: 'disabled' as const }
429
453
  let hostdControl = hostd.state === 'registered' ? hostd.control : undefined
430
454
 
@@ -457,15 +481,13 @@ export async function start({
457
481
  built = true
458
482
  }
459
483
 
460
- if (modelsReady) {
461
- try {
462
- await modelsReady
463
- } catch (error) {
464
- await cleanupHostDaemonRegistration(containerName, hostd)
465
- return {
466
- ok: false,
467
- reason: `embedding model provisioning failed (memory.vector.enabled): ${error instanceof Error ? error.message : String(error)}`,
468
- }
484
+ try {
485
+ await modelsReady
486
+ } catch (error) {
487
+ await cleanupHostDaemonRegistration(containerName, hostd)
488
+ return {
489
+ ok: false,
490
+ reason: `embedding model unavailable; ensure network access on first start or a populated model cache: ${error instanceof Error ? error.message : String(error)}`,
469
491
  }
470
492
  }
471
493
 
@@ -503,7 +525,14 @@ export async function start({
503
525
  }
504
526
  hostPort = await allocatePort(0)
505
527
  if (cliEntry) {
506
- hostd = await registerWithDaemon({ cwd, containerName, cliEntry, hostPort, reuseCurrentHostDaemon })
528
+ hostd = await registerWithDaemon({
529
+ cwd,
530
+ containerName,
531
+ cliEntry,
532
+ hostPort,
533
+ reuseCurrentHostDaemon,
534
+ currentHostDaemon,
535
+ })
507
536
  hostdControl = hostd.state === 'registered' ? hostd.control : undefined
508
537
  }
509
538
  plan = await planStart({
@@ -726,15 +755,10 @@ export async function planStart({
726
755
  runArgs.push(...dockerBindMount({ src: hostPath, dst: target, readonly: mount.readOnly }))
727
756
  }
728
757
 
729
- // Shared model cache mount for embeddings. Gated on vector opt-in: a
730
- // vector-opted-out container has no embedder to feed, and the host never
731
- // populates ~/.typeclaw/models for it (see ensureModels gating in start()),
732
- // so mounting an empty cache would only invite a confusing local_files_only
733
- // miss if something inside the container reached for the model anyway.
734
- if (agentUsesVector(cwd)) {
735
- runArgs.push(...dockerBindMount({ src: join(homeRoot(), 'models'), dst: '/opt/models', readonly: true }))
736
- runArgs.push('-e', 'TYPECLAW_MODEL_CACHE=/opt/models')
737
- }
758
+ // Shared model cache mount for embeddings. Vector memory is always on, and
759
+ // the embedder runs with local_files_only inside the container.
760
+ runArgs.push(...dockerBindMount({ src: join(homeRoot(), 'models'), dst: '/opt/models', readonly: true }))
761
+ runArgs.push('-e', 'TYPECLAW_MODEL_CACHE=/opt/models')
738
762
 
739
763
  runArgs.push(imageTag)
740
764
 
@@ -1158,27 +1182,47 @@ async function registerWithDaemon({
1158
1182
  cliEntry,
1159
1183
  hostPort,
1160
1184
  reuseCurrentHostDaemon,
1185
+ currentHostDaemon,
1161
1186
  }: {
1162
1187
  cwd: string
1163
1188
  containerName: string
1164
1189
  cliEntry: string
1165
1190
  hostPort: number
1166
1191
  reuseCurrentHostDaemon: boolean
1192
+ currentHostDaemon: CurrentHostDaemon | undefined
1167
1193
  }): Promise<PreparedHostDaemonStatus> {
1168
- const prepared = reuseCurrentHostDaemon ? await useCurrentHostDaemon() : await ensureDaemonWithBridgeRetry(cliEntry)
1169
- if (!prepared.ok) return { state: 'unavailable', reason: prepared.reason }
1170
1194
  const token = randomBytes(32).toString('base64url')
1171
1195
  const brokerToken = randomBytes(32).toString('base64url')
1172
1196
  const cfg = await loadTypeclawConfig(cwd)
1173
- const reply = await sendToDaemon({
1174
- kind: 'register',
1197
+ const payload: HostDaemonRegisterPayload = {
1175
1198
  containerName,
1176
1199
  cwd,
1177
1200
  restartToken: token,
1178
1201
  wsHostPort: hostPort,
1179
1202
  portForward: cfg.portForward,
1180
1203
  brokerToken,
1181
- })
1204
+ }
1205
+
1206
+ if (currentHostDaemon) {
1207
+ // A thrown/rejected registrar must degrade to a still-booting container,
1208
+ // not abort start() — the daemon-owned restart already stopped the old
1209
+ // container, so ok:false here would leave the agent dead.
1210
+ let reply: { ok: true } | { ok: false; reason: string }
1211
+ try {
1212
+ reply = await currentHostDaemon.register(payload)
1213
+ } catch (error) {
1214
+ return { state: 'unavailable', reason: error instanceof Error ? error.message : String(error) }
1215
+ }
1216
+ if (!reply.ok) return { state: 'unavailable', reason: reply.reason }
1217
+ return {
1218
+ state: 'registered',
1219
+ control: { url: `http://${CONTAINER_HOSTD_HOST}:${currentHostDaemon.httpPort}`, token, brokerToken },
1220
+ }
1221
+ }
1222
+
1223
+ const prepared = reuseCurrentHostDaemon ? await useCurrentHostDaemon() : await ensureDaemonWithBridgeRetry(cliEntry)
1224
+ if (!prepared.ok) return { state: 'unavailable', reason: prepared.reason }
1225
+ const reply = await sendToDaemon({ kind: 'register', ...payload })
1182
1226
  if (!reply.ok) return { state: 'unavailable', reason: reply.reason }
1183
1227
  return {
1184
1228
  state: 'registered',
@@ -0,0 +1,21 @@
1
+ import type { CurrentHostDaemon } from '@/container'
2
+
3
+ // Shared between the daemon (which alone knows its HTTP port + in-process
4
+ // registrar, both available only after boot) and the renewal callbacks in
5
+ // cli/hostd.ts (constructed before the daemon). `ready()` lets a caller that
6
+ // fires before boot await population instead of racing to a null read.
7
+ export type CurrentHostDaemonHolder = {
8
+ set: (value: CurrentHostDaemon) => void
9
+ ready: () => Promise<CurrentHostDaemon>
10
+ }
11
+
12
+ export function createCurrentHostDaemonHolder(): CurrentHostDaemonHolder {
13
+ let resolveReady: (value: CurrentHostDaemon) => void
14
+ const readyPromise = new Promise<CurrentHostDaemon>((resolve) => {
15
+ resolveReady = resolve
16
+ })
17
+ return {
18
+ set: (value) => resolveReady(value),
19
+ ready: () => readyPromise,
20
+ }
21
+ }