typeclaw 0.51.0 → 0.52.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 (202) hide show
  1. package/dist/types/agent/bash-sandbox-env.d.ts +2 -0
  2. package/dist/types/agent/bash-sandbox.d.ts +4 -0
  3. package/dist/types/agent/index.d.ts +5 -0
  4. package/dist/types/agent/multimodal/look-at.d.ts +1 -1
  5. package/dist/types/agent/plugin-tools.d.ts +4 -0
  6. package/dist/types/agent/prompt-cache-key.d.ts +1 -0
  7. package/dist/types/agent/session-tail.d.ts +12 -0
  8. package/dist/types/agent/subagents.d.ts +5 -0
  9. package/dist/types/agent/system-prompt-composition.d.ts +1 -0
  10. package/dist/types/agent/system-prompt.d.ts +2 -0
  11. package/dist/types/agent/tools/channel-disengage.d.ts +1 -1
  12. package/dist/types/agent/tools/channel-edit.d.ts +1 -1
  13. package/dist/types/agent/tools/channel-fetch-attachment.d.ts +1 -1
  14. package/dist/types/agent/tools/channel-handoff.d.ts +1 -1
  15. package/dist/types/agent/tools/channel-history.d.ts +1 -1
  16. package/dist/types/agent/tools/channel-react.d.ts +1 -1
  17. package/dist/types/agent/tools/channel-read.d.ts +10 -2
  18. package/dist/types/agent/tools/channel-reply.d.ts +1 -1
  19. package/dist/types/agent/tools/channel-send.d.ts +1 -1
  20. package/dist/types/agent/tools/channel-session-search.d.ts +1 -1
  21. package/dist/types/agent/tools/grant-role.d.ts +1 -1
  22. package/dist/types/agent/tools/post-github-review.d.ts +1 -1
  23. package/dist/types/agent/tools/restart.d.ts +1 -1
  24. package/dist/types/agent/tools/skip-response.d.ts +1 -1
  25. package/dist/types/agent/tools/spawn-subagent.d.ts +2 -1
  26. package/dist/types/agent/tools/stream-snapshot.d.ts +1 -1
  27. package/dist/types/agent/tools/subagent-cancel.d.ts +1 -1
  28. package/dist/types/agent/tools/subagent-output.d.ts +1 -1
  29. package/dist/types/agent/tools/todo/index.d.ts +1 -1
  30. package/dist/types/agent/tools/webfetch/adaptive-html.d.ts +3 -3
  31. package/dist/types/agent/tools/webfetch/strategies/readability-process.d.ts +48 -0
  32. package/dist/types/agent/tools/webfetch/tool.d.ts +2 -2
  33. package/dist/types/agent/tools/websearch.d.ts +1 -1
  34. package/dist/types/channels/adapters/github/auth-app.d.ts +25 -0
  35. package/dist/types/channels/adapters/github/auth-pat.d.ts +17 -0
  36. package/dist/types/channels/adapters/github/auth.d.ts +24 -0
  37. package/dist/types/channels/github-token-bridge.d.ts +4 -0
  38. package/dist/types/channels/lost-background-context.d.ts +2 -0
  39. package/dist/types/channels/persistence.d.ts +1 -0
  40. package/dist/types/channels/router.d.ts +5 -1
  41. package/dist/types/channels/types.d.ts +1 -0
  42. package/dist/types/coding-agent/tool.d.ts +1 -1
  43. package/dist/types/config/config.d.ts +20 -11
  44. package/dist/types/config/providers.d.ts +47 -0
  45. package/dist/types/eval/sandbox.d.ts +2 -0
  46. package/dist/types/git/resolve-identity.d.ts +2 -0
  47. package/dist/types/init/dockerfile.d.ts +1 -0
  48. package/dist/types/init/gitignore.d.ts +1 -1
  49. package/dist/types/permissions/builtins.d.ts +1 -0
  50. package/dist/types/plugin/types.d.ts +3 -0
  51. package/dist/types/sandbox/canonical-secrets.d.ts +2 -2
  52. package/dist/types/sandbox/coding-agent.d.ts +1 -1
  53. package/dist/types/sandbox/dependency-bins.d.ts +1 -0
  54. package/dist/types/sandbox/dev-source.d.ts +2 -2
  55. package/dist/types/sandbox/hidden-paths.d.ts +1 -0
  56. package/dist/types/sandbox/index.d.ts +1 -1
  57. package/dist/types/sandbox/policy.d.ts +3 -0
  58. package/dist/types/typevault/cli-path.d.ts +2 -0
  59. package/dist/types/typevault/envelope-store.d.ts +11 -0
  60. package/dist/types/typevault/lifecycle.d.ts +13 -0
  61. package/dist/types/typevault/vault.d.ts +27 -0
  62. package/package.json +8 -7
  63. package/scripts/test.ts +252 -0
  64. package/src/agent/bash-sandbox-env.ts +33 -1
  65. package/src/agent/bash-sandbox.ts +20 -6
  66. package/src/agent/index.ts +120 -31
  67. package/src/agent/multimodal/look-at.ts +1 -1
  68. package/src/agent/plugin-tools.ts +35 -1
  69. package/src/agent/prompt-cache-key.ts +26 -3
  70. package/src/agent/session-origin.ts +39 -18
  71. package/src/agent/session-tail.ts +28 -0
  72. package/src/agent/subagents.ts +21 -2
  73. package/src/agent/system-prompt-composition.ts +18 -0
  74. package/src/agent/system-prompt.ts +39 -1
  75. package/src/agent/tool-error-remediation.ts +18 -3
  76. package/src/agent/tools/channel-disengage.ts +1 -1
  77. package/src/agent/tools/channel-edit.ts +1 -1
  78. package/src/agent/tools/channel-fetch-attachment.ts +1 -1
  79. package/src/agent/tools/channel-handoff.ts +3 -2
  80. package/src/agent/tools/channel-history.ts +2 -1
  81. package/src/agent/tools/channel-react.ts +1 -1
  82. package/src/agent/tools/channel-read.ts +36 -3
  83. package/src/agent/tools/channel-reply.ts +1 -1
  84. package/src/agent/tools/channel-send.ts +4 -3
  85. package/src/agent/tools/channel-session-search.ts +13 -4
  86. package/src/agent/tools/grant-role.ts +1 -1
  87. package/src/agent/tools/post-github-review.ts +1 -1
  88. package/src/agent/tools/restart.ts +1 -1
  89. package/src/agent/tools/skip-response.ts +1 -1
  90. package/src/agent/tools/spawn-subagent.ts +15 -1
  91. package/src/agent/tools/stream-snapshot.ts +1 -1
  92. package/src/agent/tools/subagent-cancel.ts +1 -1
  93. package/src/agent/tools/subagent-output.ts +1 -1
  94. package/src/agent/tools/todo/index.ts +1 -1
  95. package/src/agent/tools/webfetch/adaptive-html.ts +6 -4
  96. package/src/agent/tools/webfetch/strategies/readability-child.ts +25 -0
  97. package/src/agent/tools/webfetch/strategies/readability-process.ts +185 -0
  98. package/src/agent/tools/webfetch/tool.ts +6 -5
  99. package/src/agent/tools/websearch.ts +1 -1
  100. package/src/browser/dockerfile.ts +1 -1
  101. package/src/browser/fill-secret.ts +92 -35
  102. package/src/browser/registry.ts +6 -6
  103. package/src/bundled-plugins/agent-messenger-cli-auth/command.ts +211 -0
  104. package/src/bundled-plugins/agent-messenger-cli-auth/index.ts +186 -0
  105. package/src/bundled-plugins/backup/index.ts +17 -2
  106. package/src/bundled-plugins/backup/runner.ts +37 -2
  107. package/src/bundled-plugins/browser-agent/browser-agent.ts +51 -14
  108. package/src/bundled-plugins/browser-agent/index.ts +12 -5
  109. package/src/bundled-plugins/managed-browser/index.ts +25 -2
  110. package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +13 -5
  111. package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +56 -5
  112. package/src/bundled-plugins/memory/README.md +23 -2
  113. package/src/bundled-plugins/memory/append-fragment.ts +133 -0
  114. package/src/bundled-plugins/memory/append-tool.ts +80 -149
  115. package/src/bundled-plugins/memory/dreaming.ts +2 -0
  116. package/src/bundled-plugins/memory/index.ts +33 -6
  117. package/src/bundled-plugins/memory/memory-logger.ts +133 -11
  118. package/src/bundled-plugins/memory/references/store-reference-tool.ts +56 -32
  119. package/src/bundled-plugins/memory/remember-tool.ts +81 -0
  120. package/src/bundled-plugins/memory/search-tool-hybrid.ts +91 -0
  121. package/src/bundled-plugins/memory/search-tool.ts +58 -12
  122. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  123. package/src/bundled-plugins/memory/transcript-cursor.ts +30 -0
  124. package/src/bundled-plugins/memory/transcript-preload.ts +131 -26
  125. package/src/bundled-plugins/memory/transcript-view.ts +36 -0
  126. package/src/bundled-plugins/memory/watermark.ts +19 -10
  127. package/src/bundled-plugins/reviewer/reviewer.ts +20 -0
  128. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +3 -6
  129. package/src/bundled-plugins/security/policies/outbound-text.ts +20 -0
  130. package/src/bundled-plugins/security/policies/system-prompt-leak.ts +2 -7
  131. package/src/bundled-plugins/typevault/grants.ts +119 -0
  132. package/src/bundled-plugins/typevault/index.ts +152 -0
  133. package/src/bundled-plugins/typevault/request.ts +87 -0
  134. package/src/bundled-plugins/typevault/runtime.ts +45 -0
  135. package/src/bundled-plugins/typevault/skills/typevault/SKILL.md +65 -0
  136. package/src/channels/adapter-halt.ts +17 -0
  137. package/src/channels/adapters/github/history.ts +23 -2
  138. package/src/channels/adapters/github/inbound.ts +60 -1
  139. package/src/channels/adapters/github/index.ts +27 -5
  140. package/src/channels/adapters/github/reconcile-open-prs.ts +7 -1
  141. package/src/channels/adapters/kakaotalk-author-resolver.ts +7 -5
  142. package/src/channels/adapters/kakaotalk-channel-resolver.ts +45 -15
  143. package/src/channels/adapters/kakaotalk-classify.ts +7 -9
  144. package/src/channels/adapters/kakaotalk-list.ts +62 -0
  145. package/src/channels/adapters/kakaotalk-member-cache.ts +67 -0
  146. package/src/channels/adapters/kakaotalk-membership.ts +27 -10
  147. package/src/channels/adapters/kakaotalk-mention.ts +61 -0
  148. package/src/channels/adapters/kakaotalk.ts +159 -125
  149. package/src/channels/adapters/teams-classify.ts +18 -8
  150. package/src/channels/github-token-bridge.ts +13 -0
  151. package/src/channels/lost-background-context.ts +46 -0
  152. package/src/channels/manager.ts +52 -3
  153. package/src/channels/persistence.ts +5 -0
  154. package/src/channels/router.ts +120 -21
  155. package/src/channels/schema.ts +1 -1
  156. package/src/channels/types.ts +3 -0
  157. package/src/coding-agent/tool.ts +1 -1
  158. package/src/config/config.ts +20 -1
  159. package/src/config/providers.ts +65 -0
  160. package/src/container/start.ts +15 -2
  161. package/src/doctor/channel-checks.ts +33 -0
  162. package/src/doctor/checks.ts +12 -2
  163. package/src/eval/sandbox.ts +3 -0
  164. package/src/eval/tool.ts +1 -0
  165. package/src/git/resolve-identity.ts +67 -2
  166. package/src/git/system-commit.ts +7 -0
  167. package/src/init/dockerfile.ts +5 -1
  168. package/src/init/gitignore.ts +3 -3
  169. package/src/init/index.ts +1 -0
  170. package/src/init/models-dev.ts +2 -0
  171. package/src/init/validate-api-key.ts +5 -0
  172. package/src/migrations/secrets-v1-to-v2.ts +2 -0
  173. package/src/permissions/builtins.ts +8 -0
  174. package/src/plugin/types.ts +6 -0
  175. package/src/run/bundled-plugins.ts +12 -0
  176. package/src/run/channel-session-factory.ts +3 -0
  177. package/src/run/index.ts +13 -2
  178. package/src/sandbox/build.ts +1 -0
  179. package/src/sandbox/canonical-secrets.ts +6 -0
  180. package/src/sandbox/dependency-bins.ts +13 -1
  181. package/src/sandbox/dev-source.ts +21 -12
  182. package/src/sandbox/hidden-paths.ts +1 -1
  183. package/src/sandbox/index.ts +1 -0
  184. package/src/sandbox/policy.ts +5 -0
  185. package/src/secrets/hydrate.ts +4 -1
  186. package/src/secrets/storage.ts +10 -1
  187. package/src/server/command-runner.ts +4 -0
  188. package/src/server/index.ts +8 -1
  189. package/src/skills/typeclaw-config/SKILL.md +16 -0
  190. package/src/skills/typeclaw-memory/SKILL.md +3 -1
  191. package/src/skills/typeclaw-permissions/SKILL.md +8 -8
  192. package/src/skills/typeclaw-troubleshooting/SKILL.md +18 -1
  193. package/src/tunnels/active.ts +14 -0
  194. package/src/typevault/bash-cli.ts +18 -0
  195. package/src/typevault/cli-path.ts +11 -0
  196. package/src/typevault/envelope-helper.ts +17 -0
  197. package/src/typevault/envelope-store.ts +98 -0
  198. package/src/typevault/lifecycle.ts +132 -0
  199. package/src/typevault/prompt-tunnel.ts +33 -0
  200. package/src/typevault/redaction.ts +37 -0
  201. package/src/typevault/vault.ts +283 -0
  202. package/typeclaw.schema.json +40 -10
package/src/run/index.ts CHANGED
@@ -86,6 +86,8 @@ import { createSessionFactory, type SessionFactory } from '@/sessions'
86
86
  import { createStream, type Stream } from '@/stream'
87
87
  import { createTui as createTuiDefault, type TuiOptions } from '@/tui'
88
88
  import { createTunnelManager, type TunnelManager, type TunnelManagerOptions } from '@/tunnels'
89
+ import { setActiveTunnelManager } from '@/tunnels/active'
90
+ import { runtimeTunnels } from '@/typevault/prompt-tunnel'
89
91
 
90
92
  import { bootChannelRestartGreeting, bootBackgroundObligations } from './background-handoff-boot'
91
93
  import { BUNDLED_PLUGINS } from './bundled-plugins'
@@ -444,13 +446,14 @@ async function startAgentRuntime(
444
446
  })
445
447
 
446
448
  const tunnelManager: TunnelManager = createTunnelManagerFor({
447
- tunnels: getConfig().tunnels,
449
+ tunnels: runtimeTunnels(getConfig()),
448
450
  stream,
449
451
  resolveChannelUpstreamPort: (name) => {
450
452
  if (name === 'github') return getConfig().channels.github?.webhookPort ?? null
451
453
  return null
452
454
  },
453
455
  })
456
+ setActiveTunnelManager(tunnelManager)
454
457
 
455
458
  const legacyBackgroundHandoffs = new LegacyBackgroundHandoffReader(cwd, {
456
459
  onError: (error) => console.warn(`[run] legacy background upgrade failed: ${error}`),
@@ -495,6 +498,7 @@ async function startAgentRuntime(
495
498
  tunnelUrlForChannel: (name) => resolveTunnelUrlForChannel(name, tunnelManager),
496
499
  tunnelConfiguredForChannel: (name) => isTunnelConfiguredForChannel(name),
497
500
  createSessionForChannel: buildChannelSessionFactory({
501
+ getGithubSelf: githubTokenBridge.getSelf,
498
502
  cwd,
499
503
  sessionFactory,
500
504
  stream,
@@ -583,7 +587,8 @@ async function startAgentRuntime(
583
587
  const allowBackgroundFromSubagent =
584
588
  entry.pluginSubagent.canBackgroundSpawnSubagents === true && entry.pluginSubagent.canSpawnSubagents === true
585
589
  const created = await createSessionWithDispose({
586
- systemPromptOverride: entry.pluginSubagent.systemPrompt,
590
+ getGithubSelf: githubTokenBridge.getSelf,
591
+ systemPromptOverride: subagentOptions?.systemPromptOverride ?? entry.pluginSubagent.systemPrompt,
587
592
  sessionManager,
588
593
  channelRouter: channelManager.router,
589
594
  origin,
@@ -599,6 +604,7 @@ async function startAgentRuntime(
599
604
  ...(entry.pluginSubagent.tools ? { toolRefs: entry.pluginSubagent.tools } : {}),
600
605
  ...(entry.pluginSubagent.customTools ? { customTools: entry.pluginSubagent.customTools } : {}),
601
606
  toolNamePrefix: `__plugin_${entry.pluginName}_${entry.subagentName}`,
607
+ ...(entry.pluginSubagent.pluginTools ? { pluginToolNames: entry.pluginSubagent.pluginTools } : {}),
602
608
  },
603
609
  // Orchestration wiring is opt-in per subagent (canSpawnSubagents) so
604
610
  // only operator/reviewer can delegate; explorer/scout/etc. stay leaves.
@@ -662,6 +668,7 @@ async function startAgentRuntime(
662
668
  // attribution stay per-session).
663
669
  const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
664
670
  return defaultCreateSessionForSubagent(subagent, {
671
+ getGithubSelf: githubTokenBridge.getSelf,
665
672
  ...subagentOptions,
666
673
  plugins: {
667
674
  registry: snap.registry,
@@ -739,6 +746,7 @@ async function startAgentRuntime(
739
746
  origin,
740
747
  prompt: (text: string) =>
741
748
  runPromptForCommand({
749
+ getGithubSelf: githubTokenBridge.getSelf,
742
750
  text,
743
751
  origin,
744
752
  runtime: pluginRuntime,
@@ -783,6 +791,7 @@ async function startAgentRuntime(
783
791
  console.error(`[cron] ${job.id}: clear todos failed: ${err instanceof Error ? err.message : String(err)}`),
784
792
  )
785
793
  const session = await createSession({
794
+ getGithubSelf: githubTokenBridge.getSelf,
786
795
  reloadRegistry,
787
796
  sessionManager,
788
797
  stream,
@@ -1054,6 +1063,7 @@ async function startAgentRuntime(
1054
1063
 
1055
1064
  const commandRunnerFactory = (outbound: import('@/server/command-runner').CommandOutbound): CommandRunner =>
1056
1065
  createCommandRunner({
1066
+ getGithubSelf: githubTokenBridge.getSelf,
1057
1067
  pluginRuntime,
1058
1068
  permissions: pluginsLoaded.permissions,
1059
1069
  spawnSubagent: dispatchSpawnSubagent,
@@ -1067,6 +1077,7 @@ async function startAgentRuntime(
1067
1077
  })
1068
1078
 
1069
1079
  const serverFactory = createServer({
1080
+ getGithubSelf: githubTokenBridge.getSelf,
1070
1081
  port,
1071
1082
  reloadAll: reloadAllNonDestructive,
1072
1083
  reloadRegistry,
@@ -212,6 +212,7 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
212
212
  appendWritable(argv, policy)
213
213
  appendMasks(argv, policy)
214
214
  appendProtected(argv, policy)
215
+ for (const mount of policy.reveal ?? []) appendMount(argv, mount)
215
216
  appendSymlinks(argv, policy)
216
217
 
217
218
  if (policy.cwd !== undefined) {
@@ -16,6 +16,12 @@ export const RUNTIME_OWNED_SECRET_DIRS = [
16
16
  '.typeclaw/home',
17
17
  '.typeclaw/logs',
18
18
  BROWSER_PROFILE_RELATIVE_DIR,
19
+ // TypeVault (typevault.enabled): the agent's machine key and typevault's
20
+ // private state, and the vault itself, which holds the secrets.json envelope.
21
+ // Mirrors src/typevault/vault.ts; kept as literals so the sandbox does not
22
+ // load the typevault SDK.
23
+ '.typeclaw/typevault',
24
+ '.typevault',
19
25
  ] as const
20
26
 
21
27
  // SECURITY / classification: operator-provisioned CLI credential stores. TypeClaw
@@ -23,6 +23,10 @@ export async function reconcileDependencyBinWrappers(options: {
23
23
  agentDir: string
24
24
  sessionTmp: string
25
25
  baselineDirs?: readonly string[]
26
+ // Runtime-provided commands (bin name -> entrypoint), e.g. the TypeVault CLI
27
+ // TypeClaw itself ships. Never derived from the agent's package.json, and
28
+ // they own their name even when an agent dependency ships the same bin.
29
+ runtimeBins?: Readonly<Record<string, string>>
26
30
  }): Promise<DependencyBinReconciliation> {
27
31
  const dir = join(options.sessionTmp, DEPENDENCY_BIN_DIR_NAME)
28
32
  const previous = reconciliationLocks.get(dir) ?? Promise.resolve()
@@ -42,7 +46,12 @@ export async function reconcileDependencyBinWrappers(options: {
42
46
  }
43
47
 
44
48
  async function reconcileDependencyBinWrappersUnlocked(
45
- options: { agentDir: string; sessionTmp: string; baselineDirs?: readonly string[] },
49
+ options: {
50
+ agentDir: string
51
+ sessionTmp: string
52
+ baselineDirs?: readonly string[]
53
+ runtimeBins?: Readonly<Record<string, string>>
54
+ },
46
55
  dir: string,
47
56
  ): Promise<DependencyBinReconciliation> {
48
57
  const validation = await validateDependencyBins(options.agentDir, options.baselineDirs)
@@ -52,6 +61,9 @@ async function reconcileDependencyBinWrappersUnlocked(
52
61
  if (resolution.kind !== 'package' || wrappers.has(resolution.declaration.bin)) continue
53
62
  wrappers.set(resolution.declaration.bin, renderWrapper(resolution.containerEntrypoint))
54
63
  }
64
+ for (const [bin, entrypoint] of Object.entries(options.runtimeBins ?? {})) {
65
+ wrappers.set(bin, renderWrapper(entrypoint))
66
+ }
55
67
  for (const entry of await readdir(dir).catch(() => [])) {
56
68
  if (entry.startsWith('.')) continue
57
69
  if (!wrappers.has(entry)) await rm(join(dir, entry), { recursive: true, force: true })
@@ -1,5 +1,5 @@
1
- import { realpath } from 'node:fs/promises'
2
- import { dirname, isAbsolute, relative } from 'node:path'
1
+ import { realpath, stat } from 'node:fs/promises'
2
+ import { dirname, isAbsolute, join, relative } from 'node:path'
3
3
  import { fileURLToPath } from 'node:url'
4
4
 
5
5
  import type { SandboxMount } from './policy'
@@ -9,18 +9,27 @@ const RUNTIME_MODULE_FILE = fileURLToPath(import.meta.url)
9
9
  // Dev mode (`file:`/`link:` typeclaw dep): files under node_modules/typeclaw
10
10
  // are symlinks into a checkout outside the agent folder. `typeclaw start`
11
11
  // mirror-mounts that checkout read-only into the container, but bwrap only
12
- // binds the agent folder, so bundled SKILL.md symlinks dangle inside model
13
- // bash. Bind only the checkout's `src/` (where every bundled skill lives),
14
- // never the checkout root, so a developer's `.env` or `.git` stays out of the
15
- // sandbox. The path comes from the running module's own realpath, which the
16
- // model cannot redirect by rewriting node_modules. Registry installs resolve
17
- // inside the agent folder and get no mount.
18
- export async function resolveDevSourceMount(
12
+ // binds the agent folder, so anything typeclaw resolves inside the checkout
13
+ // dangles inside model bash. Bind the checkout's `src/` (bundled skills) and
14
+ // `node_modules/` (runtime-provided bins such as `typevault`, which resolve
15
+ // into typeclaw's own dependencies), never the checkout root, so a
16
+ // developer's `.env` or `.git` stays out of the sandbox. The path comes from
17
+ // the running module's own realpath, which the model cannot redirect by
18
+ // rewriting node_modules. Registry installs resolve inside the agent folder
19
+ // and get no mount.
20
+ export async function resolveDevSourceMounts(
19
21
  agentDir: string,
20
22
  moduleFile: string = RUNTIME_MODULE_FILE,
21
- ): Promise<Extract<SandboxMount, { type: 'ro-bind' }> | undefined> {
23
+ ): Promise<Extract<SandboxMount, { type: 'ro-bind' }>[]> {
22
24
  const srcDir = dirname(dirname(await realpath(moduleFile)))
23
25
  const rel = relative(await realpath(agentDir), srcDir)
24
- if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return undefined
25
- return { type: 'ro-bind', source: srcDir, dest: srcDir }
26
+ if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return []
27
+ const mounts: Extract<SandboxMount, { type: 'ro-bind' }>[] = [{ type: 'ro-bind', source: srcDir, dest: srcDir }]
28
+ const nodeModules = join(dirname(srcDir), 'node_modules')
29
+ // bwrap aborts on a missing bind source; a checkout that was never
30
+ // installed has nothing there to expose.
31
+ if ((await stat(nodeModules).catch(() => undefined))?.isDirectory()) {
32
+ mounts.push({ type: 'ro-bind', source: nodeModules, dest: nodeModules })
33
+ }
34
+ return mounts
26
35
  }
@@ -63,7 +63,7 @@ export function canWriteAgentRootInSandbox(permissions: PermissionService, origi
63
63
  return canSeePrivateSurface(permissions, origin) && seesSecrets
64
64
  }
65
65
 
66
- function canSeePrivateSurface(permissions: PermissionService, origin: SessionOrigin | undefined): boolean {
66
+ export function canSeePrivateSurface(permissions: PermissionService, origin: SessionOrigin | undefined): boolean {
67
67
  return (
68
68
  permissions.has(origin, CORE_PERMISSIONS.fsSeePrivate) ||
69
69
  permissions.has(origin, 'security.bypass.low') ||
@@ -24,6 +24,7 @@ export {
24
24
  _resetRealProcProbeCacheForTests,
25
25
  } from './availability'
26
26
  export {
27
+ canSeePrivateSurface,
27
28
  canWriteAgentRootInSandbox,
28
29
  ensureHiddenMaskTargets,
29
30
  resolveHiddenPaths,
@@ -132,6 +132,11 @@ export type SandboxPolicy = {
132
132
  masks?: SandboxMaskPolicy
133
133
  writable?: SandboxWritablePolicy
134
134
  protected?: SandboxProtectedPolicy
135
+ // Read-only binds rendered AFTER masks and protected zones, so they deliberately
136
+ // re-expose one path a mask covers. Only trusted runtime hooks set these (the
137
+ // TypeVault plugin re-exposes the ciphertext-only vault and its grant socket
138
+ // to a session holding vault.use); never derive one from model input.
139
+ reveal?: Extract<SandboxMount, { type: 'ro-bind' | 'tmpfs' }>[]
135
140
  symlinks?: SandboxSymlinkOp[]
136
141
  network?: SandboxNetwork
137
142
  env?: SandboxEnvPolicy
@@ -1,5 +1,7 @@
1
1
  import { readFileSync } from 'node:fs'
2
- import { join } from 'node:path'
2
+ import { dirname, join } from 'node:path'
3
+
4
+ import { isTypevaultMarker, readEnvelopeTextSync } from '@/typevault/envelope-store'
3
5
 
4
6
  import { channelFieldDefaultEnv } from './defaults'
5
7
  import { resolveSecret, secretFieldSchema, type Secret } from './resolve'
@@ -71,6 +73,7 @@ function readChannelSecrets(secretsPath: string): Record<string, Record<string,
71
73
  let raw: string
72
74
  try {
73
75
  raw = readFileSync(secretsPath, 'utf8')
76
+ if (isTypevaultMarker(raw)) raw = readEnvelopeTextSync(dirname(secretsPath))
74
77
  } catch {
75
78
  return {}
76
79
  }
@@ -5,6 +5,8 @@ import type { AuthOperationOptions, Credential, CredentialInfo, CredentialStore
5
5
  import { operationSignal, raceWithAbortSignal } from '@earendil-works/pi-ai/utils/abort'
6
6
  import lockfile from 'proper-lockfile'
7
7
 
8
+ import { isTypevaultMarker, readEnvelopeTextSync, writeEnvelopeTextSync } from '@/typevault/envelope-store'
9
+
8
10
  import { providerKeyDefaultEnv } from './defaults'
9
11
  import { resolveSecret } from './resolve'
10
12
  import {
@@ -511,7 +513,8 @@ export class SecretsBackend implements CredentialStore {
511
513
  }
512
514
 
513
515
  private readEnvelope(): SecretsFile {
514
- const raw = existsSync(this.secretsPath) ? readFileSync(this.secretsPath, 'utf8') : ''
516
+ const onDisk = existsSync(this.secretsPath) ? readFileSync(this.secretsPath, 'utf8') : ''
517
+ const raw = isTypevaultMarker(onDisk) ? readEnvelopeTextSync(dirname(this.secretsPath)) : onDisk
515
518
  if (!raw.trim()) return newEmptyEnvelope()
516
519
  let parsed: unknown
517
520
  try {
@@ -527,6 +530,12 @@ export class SecretsBackend implements CredentialStore {
527
530
  }
528
531
 
529
532
  private writeEnvelopeAtomic(envelope: SecretsFile): void {
533
+ // With typevault enabled, secrets.json is only the marker; the envelope
534
+ // itself is written into the vault and the marker is never rewritten.
535
+ if (existsSync(this.secretsPath) && isTypevaultMarker(readFileSync(this.secretsPath, 'utf8'))) {
536
+ writeEnvelopeTextSync(dirname(this.secretsPath), stringifyEnvelope(envelope))
537
+ return
538
+ }
530
539
  const tmp = `${this.secretsPath}.${process.pid}.${Date.now()}.${tempSequence++}.tmp`
531
540
  writeFileSync(tmp, stringifyEnvelope(envelope), { encoding: 'utf8', mode: FILE_MODE })
532
541
  try {
@@ -37,6 +37,7 @@ export type CommandOutbound = {
37
37
  }
38
38
 
39
39
  export type CommandRunnerOptions = {
40
+ readonly getGithubSelf?: CreateSessionOptions['getGithubSelf']
40
41
  pluginRuntime: PluginRuntime
41
42
  permissions: PermissionService
42
43
  spawnSubagent: CommandSpawnSubagent
@@ -190,6 +191,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
190
191
  origin,
191
192
  prompt: (text) =>
192
193
  runPromptForCommand({
194
+ getGithubSelf: opts.getGithubSelf,
193
195
  text,
194
196
  origin,
195
197
  runtime: opts.pluginRuntime,
@@ -413,6 +415,7 @@ function drainWrites(stream: WritableStream<Uint8Array>): Promise<void> {
413
415
  export type CreateSessionForCommand = (options: CreateSessionOptions) => Promise<CreateSessionResult>
414
416
 
415
417
  export async function runPromptForCommand(args: {
418
+ readonly getGithubSelf?: CreateSessionOptions['getGithubSelf']
416
419
  text: string
417
420
  origin: SessionOrigin
418
421
  runtime: PluginRuntime
@@ -446,6 +449,7 @@ export async function runPromptForCommand(args: {
446
449
  const sessionId = resolveSessionIdForOrigin(args.origin)
447
450
  const create = args._createSession ?? createSessionWithDispose
448
451
  const { session, dispose } = await create({
452
+ getGithubSelf: args.getGithubSelf,
449
453
  origin: args.origin,
450
454
  permissions: args.permissions,
451
455
  sessionManager: args.sessionFactory.createPersisted(),
@@ -74,6 +74,7 @@ export type ServerLogger = {
74
74
  }
75
75
 
76
76
  export type ServerOptions = {
77
+ readonly getGithubSelf?: CreateSessionOptions['getGithubSelf']
77
78
  port: number
78
79
  reloadAll?: ReloadAllFn
79
80
  reloadRegistry?: ReloadRegistry
@@ -197,7 +198,7 @@ type QueuedPrompt = {
197
198
  }
198
199
 
199
200
  type SessionState = {
200
- session: AgentSession
201
+ session: AgentSession & { resetLoopGuard?: () => void }
201
202
  activeModelRef: ReturnType<typeof resolveFallbackChain>[number]
202
203
  // The session's creation-time thinking level, captured once. An escalated turn
203
204
  // moves `session.thinkingLevel` to `high`, so neither turn-driving path (drain
@@ -286,6 +287,7 @@ function encodeBase64(bytes: Uint8Array): string {
286
287
  }
287
288
 
288
289
  export function createServer({
290
+ getGithubSelf,
289
291
  port,
290
292
  reloadAll,
291
293
  reloadRegistry,
@@ -548,6 +550,7 @@ export function createServer({
548
550
  // either side at exactly its current tool surface.
549
551
  const subagentRegistry = runtimeSnapshot?.subagents
550
552
  const result = await createSession({
553
+ getGithubSelf,
551
554
  reloadRegistry,
552
555
  sessionManager,
553
556
  origin,
@@ -836,6 +839,7 @@ export function createServer({
836
839
  return
837
840
  }
838
841
  send(ws, { type: 'prompt_started', messageId: `local-${crypto.randomUUID()}`, text: msg.text })
842
+ state.session.resetLoopGuard?.()
839
843
  const fallbackHooks = state.runtimeSnapshot?.hooks
840
844
  const retrievalContext: { results: string } = { results: '' }
841
845
  if (fallbackHooks !== undefined && agentDir !== undefined) {
@@ -1195,6 +1199,9 @@ async function drain(
1195
1199
  if (!item) break
1196
1200
  pushQueueState(ws, state)
1197
1201
  send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
1202
+ // Only a prompt typed in the TUI is a new request; continuations,
1203
+ // subagent completions, and restart handoffs keep the loop guard's history.
1204
+ if (item.source === 'tui') state.session.resetLoopGuard?.()
1198
1205
 
1199
1206
  if (agentDir !== undefined) {
1200
1207
  // recordTurnStart is a read-modify-write of the same state file; let
@@ -324,6 +324,22 @@ Off switch — the broker is constructed but never opens a WS, no LISTEN gets fo
324
324
 
325
325
  This is an ordinary operator config change, not a security request to push back on. Follow **Editing `typeclaw.json` safely**: set `eval.enabled` to `true`, and set `origins` to what they named (drop the key for "all origins"). Write, commit, and tell them: "Edited `eval` — restart-required. Run `typeclaw restart` (host stage)." If the installed TypeClaw predates `eval` (the field is missing from `typeclaw.schema.json`), say it needs a TypeClaw upgrade first instead of writing a field that would be dropped.
326
326
 
327
+ ## typevault (experimental)
328
+
329
+ ```json
330
+ "typevault": { "enabled": true, "promptPort": 8976 }
331
+ ```
332
+
333
+ `enabled` (default `false`) keeps the agent's `secrets.json` (provider keys, channel tokens, MCP logins) in the agent's own TypeVault vault instead of a plaintext file. **Restart-required**: the move happens in `typeclaw start`. Setting it back to `false` and restarting restores `secrets.json` from the vault; anything else stored in the vault stays there for the next time it is enabled. `.env` is never touched. While enabled, `secrets.json` only holds a marker; never edit it or `.typevault/` by hand.
334
+
335
+ ### When the user asks "turn on TypeVault" / "move my secrets into the vault"
336
+
337
+ Follow **Editing `typeclaw.json` safely**: set `typevault.enabled` to `true`, commit, and tell them: "Edited `typevault` — restart-required. Run `typeclaw restart` (host stage)." Mention that it is experimental. If the installed TypeClaw predates `typevault` (the field is missing from `typeclaw.schema.json`), say it needs an upgrade first.
338
+
339
+ ### The `vault_request` secret page
340
+
341
+ The one-time secret page is served on the container port in `typevault.promptPort` (default `8976`; **restart-required**), which must not match `channels.github.webhookPort` or any other listener. To move it, set the field, commit, and tell them to run `typeclaw restart`. With `typevault.enabled`, TypeClaw opens a free Cloudflare quick tunnel to it at boot and builds `cloudflared` into the image, so nothing needs configuring. An operator who wants a stable URL can add their own `manual` tunnel with `upstreamPort` set to that port, or a `cloudflare-named` one named `typevault` (its upstream is set in Cloudflare, so it has no `upstreamPort`); either replaces the implicit one. TypeClaw can't see or change a `cloudflare-named` tunnel's origin: whenever `typevault.promptPort` changes, the operator must also retarget the origin in Cloudflare, or the link opens but no page is served.
342
+
327
343
  ## Network and model HTTP internal destinations
328
344
 
329
345
  These are two independent gates:
@@ -15,7 +15,9 @@ Under budget you get shard bodies de-duplicated across turns; over budget you ge
15
15
 
16
16
  ## Writing
17
17
 
18
- You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards. Do not edit `memory/topics/`, `memory/skills/`, or the stream files yourself — the dreaming subagent and runtime own them. To capture something memorable, surface it in your reply and let the memory-logger append it to `memory/streams/`.
18
+ You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards. Do not edit `memory/topics/`, `memory/skills/`, or the stream files yourself — the dreaming subagent and runtime own them. Use `memory_remember({ topic, body, who?, verbatim? })` when asked to remember something, when correcting a fact, or when a durable decision or preference is established; skip routine chatter. Supply a short topic and self-contained body in the evidence language. `who` optionally names the attributed person; `verbatim: true` also saves the exact body as a linked reference.
19
+
20
+ `memory_remember` is available to every role alongside `memory_search`. The runtime stamps the session, transcript anchor, and channel provenance; the fragment and optional reference are indexed immediately. Deliberate fragments carry `kind: "explicit"` but still undergo normal dreaming consolidation. The tool never advances the memory-logger watermark, and memory-logger skips facts already saved by successful calls.
19
21
 
20
22
  `memory/skills/<name>/SKILL.md` is muscle memory the dreaming subagent distills from recurring procedures; the runtime auto-loads those as first-class skills on next boot. A durable task procedure you want to keep goes to its existing editable owner skill (or a support file that skill links) first — see `typeclaw-skills` for who owns which skill — not into `memory/skills/` or `AGENTS.md`.
21
23
 
@@ -25,12 +25,12 @@ You always have these four, even if `typeclaw.json` declares zero `roles`. User-
25
25
 
26
26
  Roles form a strict tower for **bypassable plugin guards**: each role bypasses guards at its tier and below. The canonical-secret invariant sits outside this tower.
27
27
 
28
- | Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]` |
29
- | --------- | ----------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
- | `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
31
- | `trusted` | none | `medium` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium` |
32
- | `member` | none | `low` | `channel.respond`, `session.control`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `fs.see.private`, `browser.shared`, `security.bypass.low` |
33
- | `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none |
28
+ | Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]` |
29
+ | --------- | ----------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `vault.use`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
31
+ | `trusted` | none | `medium` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `vault.use`, `security.bypass.low`, `security.bypass.medium` |
32
+ | `member` | none | `low` | `channel.respond`, `session.control`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `fs.see.private`, `browser.shared`, `vault.use`, `security.bypass.low` |
33
+ | `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none |
34
34
 
35
35
  A session that doesn't match anything resolves to `guest`. `guest` has no `channel.respond`, so the router silently drops inbound messages whose author resolves to `guest`. **This is the most common cause of "the agent stopped responding"**: the user added a channel but did not add a match rule, so every speaker in that channel is `guest` and every inbound is dropped before you ever see it. There is no message in your session log when this happens — only a host-side line `[channels] <key>: denied by permissions (channel.respond) author=<id>`.
36
36
 
@@ -58,7 +58,7 @@ For each user turn, the current speaker's effective role is delivered in the tur
58
58
 
59
59
  **The permission list (cron/subagent block) is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
60
60
 
61
- Memory recall is globally visible by default across all roles and origins. Provenance is additive searchable metadata, not an authorization boundary. The optional `workspace`, `chat`, and `thread` parameters on `memory_search` narrow results when a focused subset is needed; no memory-specific permission grant is required.
61
+ Memory recall is globally visible by default across all roles and origins. Provenance is additive searchable metadata, not an authorization boundary. The optional `workspace`, `chat`, and `thread` parameters on `memory_search` narrow results when a focused subset is needed; no memory-specific permission grant is required. `memory_remember` is likewise available to every role; it appends a runtime-stamped fragment to the daily stream for dreaming to consolidate.
62
62
 
63
63
  ## The match-rule DSL
64
64
 
@@ -92,7 +92,7 @@ Things the DSL rejects (the parser emits actionable errors at boot, but you shou
92
92
 
93
93
  Three sources contribute permission strings:
94
94
 
95
- 1. **Core** (always present): `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `browser.shared`.
95
+ 1. **Core** (always present): `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `browser.shared`, `vault.use` (with `typevault.enabled`, bash gets a TypeVault grant for the role's tier and the tiers below it).
96
96
  2. **Bundled security plugin** (always loaded): the eight per-guard strings (`security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`) AND three severity-tier strings (`security.bypass.low`, `security.bypass.medium`, `security.bypass.high`).
97
97
  3. **User-declared plugins** (variable): each plugin can contribute its own strings via `definePlugin({ permissions: [...] })`.
98
98
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-troubleshooting
3
- description: Use this skill when you are stuck in a fix-it loop — you've made roughly three attempts at the same failure and you're still cycling shell commands (kill the process, re-run, `sleep`, `capture-pane`, inspect, retry) without converging. Triggers include a hung or runaway process that won't die, a `C-c` that didn't stop the program, `<defunct>`/zombie processes piling up in `ps`, an interactive program that blocks `bash` waiting for input, a script that "ran" but produced no output and no file, repeated "not found"/timeout/same-error-again loops, and any moment you catch yourself thinking "let me wait a bit more and check again" for the third time. Also read it before you start a minutes-long or input-waiting program in your own session (dev server, REPL, watcher, `docker compose up`, interactive installer) — foreground `bash` blocks until exit, and this skill has the detached tmux start/observe/drive/stop pattern. Read it before you spawn `operator` to take over the debugging — it covers the operator hand-off prompt, the tmux session pattern, killing stuck/zombie processes properly, and the edge-triggered capture-pane polling loop that the inline retry-and-sleep approach gets wrong. Also read it when `gh` works but `git push`/`git fetch` to GitHub fails with 403, "Permission denied", or "Authentication failed", or when `gh` and git seem to act as different GitHub accounts.
3
+ description: Use this skill when you are stuck in a fix-it loop — you've made roughly three attempts at the same failure and you're still cycling shell commands (kill the process, re-run, `sleep`, `capture-pane`, inspect, retry) without converging. Triggers include a hung or runaway process that won't die, a `C-c` that didn't stop the program, `<defunct>`/zombie processes piling up in `ps`, an interactive program that blocks `bash` waiting for input, a script that "ran" but produced no output and no file, repeated "not found"/timeout/same-error-again loops, and any moment you catch yourself thinking "let me wait a bit more and check again" for the third time. Also read it before you start a minutes-long or input-waiting program in your own session (dev server, REPL, watcher, `docker compose up`, interactive installer) — foreground `bash` blocks until exit, and this skill has the detached tmux start/observe/drive/stop pattern. Read it before you spawn `operator` to take over the debugging — it covers the operator hand-off prompt, the tmux session pattern, killing stuck/zombie processes properly, and the edge-triggered capture-pane polling loop that the inline retry-and-sleep approach gets wrong. Also read it when `gh` works but `git push`/`git fetch` to GitHub fails with 403, "Permission denied", or "Authentication failed", or when `gh` and git seem to act as different GitHub accounts. Also read it when `vault_request` fails with `internal daemon error`.
4
4
  ---
5
5
 
6
6
  # typeclaw-troubleshooting
@@ -126,3 +126,20 @@ TypeClaw has two GitHub credential sources, and you cannot see either one (`secr
126
126
  These can belong to different GitHub accounts. A green `gh auth status` or a working `gh api` call proves nothing about the account `git push` uses. When a brokered git command fails on auth, TypeClaw appends a note to the result naming the credential source it used and that account's login. Read it before retrying.
127
127
 
128
128
  Do not try to fix this from inside the session. Don't rewrite the remote URL, embed a token, run `gh auth login`, or edit git credential config: the broker owns these credentials, and you can't read or change them. Report the mismatch to the operator, naming both accounts and the target repo, and tell them how to recover: correct or remove the mismatched push credential (`channels.github` in `secrets.json`, or the declared `GH_TOKEN` in `.env`), then run `typeclaw restart`.
129
+
130
+ ## TypeVault: `vault_request` fails with `internal daemon error`
131
+
132
+ The daemon returns this text for every unexpected failure and writes the real exception to its log. `.typeclaw/typevault/` is masked from your tools, so you can't read that log and shouldn't spawn `operator` to look for it. Tell the operator to run this on the host, in the agent folder:
133
+
134
+ ```sh
135
+ tail -n 40 .typeclaw/typevault/config/typevault/checkouts/*/run/daemon.log
136
+ ```
137
+
138
+ If the log says `Failed to start server. Is port <port> in use?` (`EADDRINUSE`), another process in the container holds the secret-page port (`typevault.promptPort`, default `8976`). The daemon binds that port on the first request, so `typevault whoami` still succeeds and nothing fails at boot.
139
+
140
+ - **Check first:** `channels.github.webhookPort` may match it. `typeclaw doctor` warns about this as `channel.github.webhook-port`.
141
+ - **Otherwise:** a service the agent or operator started is listening on that port.
142
+ - **Fix:** set `typevault.promptPort` in `typeclaw.json` to a free port, and don't stop the other listener. See the `typeclaw-config` skill for the edit.
143
+ - **Then restart:** after a failed bind the daemon keeps returning this error until it restarts, even once the port is free. The field is restart-required too. Tell the operator to run `typeclaw restart`, then retry `vault_request`.
144
+
145
+ Never ask the user to paste the secret into chat while this is broken.
@@ -0,0 +1,14 @@
1
+ import type { TunnelManager } from './manager'
2
+
3
+ // The container's running tunnel manager, for in-process runtime code that
4
+ // needs a tunnel's current public URL at call time (quick-tunnel URLs rotate
5
+ // on every restart, so a boot-time snapshot would go stale).
6
+ let active: Pick<TunnelManager, 'urlFor'> | undefined
7
+
8
+ export function setActiveTunnelManager(manager: Pick<TunnelManager, 'urlFor'> | undefined): void {
9
+ active = manager
10
+ }
11
+
12
+ export function activeTunnelUrl(tunnelName: string): string | null {
13
+ return active?.urlFor(tunnelName) ?? null
14
+ }
@@ -0,0 +1,18 @@
1
+ import { typevaultCliPath } from './cli-path'
2
+
3
+ // The `typevault` command in model bash. Its grant and vault reach bash under
4
+ // TypeClaw's own names, so a project's own typevault CLI (`bun typevault` in a
5
+ // checkout) never finds a TYPEVAULT_* variable steering it to the agent's
6
+ // vault. Only this command maps them back.
7
+ const env = process.env
8
+ if (env.TYPECLAW_VAULT_DIR) {
9
+ env.TYPEVAULT_DIR = env.TYPECLAW_VAULT_DIR
10
+ env.TYPEVAULT_GLOBAL = '1'
11
+ }
12
+ if (env.TYPECLAW_VAULT_GRANT) env.TYPEVAULT_GRANT = env.TYPECLAW_VAULT_GRANT
13
+ // typevault strips its own TYPEVAULT_* variables from a `run` child; these
14
+ // would otherwise hand the child the session's whole grant.
15
+ delete env.TYPECLAW_VAULT_DIR
16
+ delete env.TYPECLAW_VAULT_GRANT
17
+
18
+ await import(typevaultCliPath())
@@ -0,0 +1,11 @@
1
+ import { dirname, join } from 'node:path'
2
+
3
+ // Resolved without importing the SDK, so the bash sandbox can wrap the CLI
4
+ // without loading typevault on every agent.
5
+ export function typevaultCliPath(): string {
6
+ return join(dirname(Bun.resolveSync('typevault', import.meta.dir)), 'cli', 'index.ts')
7
+ }
8
+
9
+ export function typevaultBashCliPath(): string {
10
+ return join(import.meta.dir, 'bash-cli.ts')
11
+ }
@@ -0,0 +1,17 @@
1
+ import { requireSecretsEntry, writeSecretsEntry } from './vault'
2
+
3
+ const [op, agentDir] = process.argv.slice(2)
4
+
5
+ try {
6
+ if (agentDir === undefined) throw new Error('usage: envelope-helper.ts <read|write> <agentDir>')
7
+ if (op === 'read') {
8
+ process.stdout.write(await requireSecretsEntry(agentDir))
9
+ } else if (op === 'write') {
10
+ await writeSecretsEntry(agentDir, await Bun.stdin.text())
11
+ } else {
12
+ throw new Error(`unknown operation: ${op}`)
13
+ }
14
+ } catch (error) {
15
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
16
+ process.exit(1)
17
+ }