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
@@ -0,0 +1,98 @@
1
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
2
+ import { join } from 'node:path'
3
+
4
+ import { typevaultDir } from './vault'
5
+
6
+ // secrets.json while the envelope lives in the vault. Its `version` is not 2,
7
+ // so a TypeClaw build without vault support refuses the file loudly instead of
8
+ // booting with an empty credential store.
9
+ export const TYPEVAULT_SECRETS_MARKER = {
10
+ $comment:
11
+ 'TypeClaw keeps this agent\'s secrets in its TypeVault vault (.typevault/). Set typevault.enabled to false in typeclaw.json and run "typeclaw restart" to restore this file.',
12
+ version: 'typevault',
13
+ } as const
14
+
15
+ export function typevaultMarkerText(): string {
16
+ return `${JSON.stringify(TYPEVAULT_SECRETS_MARKER, null, 2)}\n`
17
+ }
18
+
19
+ export function isTypevaultMarker(raw: string): boolean {
20
+ try {
21
+ const parsed: unknown = JSON.parse(raw)
22
+ return (
23
+ typeof parsed === 'object' &&
24
+ parsed !== null &&
25
+ (parsed as { version?: unknown }).version === TYPEVAULT_SECRETS_MARKER.version
26
+ )
27
+ } catch {
28
+ return false
29
+ }
30
+ }
31
+
32
+ export function isTypevaultMarkerFile(secretsPath: string): boolean {
33
+ return existsSync(secretsPath) && isTypevaultMarker(readFileSync(secretsPath, 'utf8'))
34
+ }
35
+
36
+ type CachedEnvelope = { text: string; stamp: string }
37
+
38
+ const cache = new Map<string, CachedEnvelope>()
39
+
40
+ // SecretsBackend's contract is synchronous, while typevault's SDK is async, so
41
+ // reads and writes cross into a short-lived helper process. Reads are cached
42
+ // per agent and refetched only when the vault's entries changed, which also
43
+ // picks up writes made by another process. Reads are lock-free, so a snapshot
44
+ // is cached only when no write landed while it was being fetched; otherwise an
45
+ // old envelope could be labelled with a newer write's stamp and later
46
+ // overwrite that write.
47
+ export function readEnvelopeTextSync(
48
+ agentDir: string,
49
+ fetch: (agentDir: string) => string = (dir) => runHelperSync(dir, 'read'),
50
+ ): string {
51
+ const before = entriesStamp(agentDir)
52
+ const cached = cache.get(agentDir)
53
+ if (cached !== undefined && cached.stamp === before) return cached.text
54
+ const text = fetch(agentDir)
55
+ if (entriesStamp(agentDir) === before) cache.set(agentDir, { text, stamp: before })
56
+ else cache.delete(agentDir)
57
+ return text
58
+ }
59
+
60
+ export function writeEnvelopeTextSync(agentDir: string, text: string): void {
61
+ cache.delete(agentDir)
62
+ runHelperSync(agentDir, 'write', text)
63
+ cache.set(agentDir, { text, stamp: entriesStamp(agentDir) })
64
+ }
65
+
66
+ // Every entry file's name, size and mtime, not just the directory's mtime, so
67
+ // a rewrite within one coarse directory timestamp still changes the stamp.
68
+ export function entriesStamp(agentDir: string): string {
69
+ const entries = join(typevaultDir(agentDir), 'entries')
70
+ if (!existsSync(entries)) return 'absent'
71
+ return readdirSync(entries)
72
+ .sort()
73
+ .map((name) => {
74
+ const stat = statSync(join(entries, name), { throwIfNoEntry: false })
75
+ return stat === undefined ? `${name}:gone` : `${name}:${stat.size}:${stat.mtimeMs}:${stat.ino}`
76
+ })
77
+ .join('|')
78
+ }
79
+
80
+ // A synchronous spawn cannot be interrupted from JavaScript, so a helper that
81
+ // never exits would block the caller's thread for good.
82
+ const HELPER_TIMEOUT_MS = 30_000
83
+
84
+ export function runHelperSync(agentDir: string, op: 'read' | 'write', input?: string): string {
85
+ const result = Bun.spawnSync([process.execPath, join(import.meta.dir, 'envelope-helper.ts'), op, agentDir], {
86
+ stdin: input === undefined ? 'ignore' : Buffer.from(input, 'utf8'),
87
+ stdout: 'pipe',
88
+ stderr: 'pipe',
89
+ timeout: HELPER_TIMEOUT_MS,
90
+ })
91
+ if (result.exitCode !== 0) {
92
+ const reason = result.exitedDueToTimeout
93
+ ? `timed out after ${HELPER_TIMEOUT_MS}ms`
94
+ : result.stderr.toString().trim() || `exit code ${result.exitCode}`
95
+ throw new Error(`TypeVault ${op} of the secrets envelope failed: ${reason}`)
96
+ }
97
+ return result.stdout.toString()
98
+ }
@@ -0,0 +1,132 @@
1
+ import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
2
+ import { join } from 'node:path'
3
+
4
+ import lockfile from 'proper-lockfile'
5
+
6
+ import { parseSecretsFile } from '@/secrets/schema'
7
+ import { ASYNC_LOCK_OPTIONS } from '@/secrets/storage'
8
+
9
+ import { isTypevaultMarker, typevaultMarkerText } from './envelope-store'
10
+ import {
11
+ clearLegacyDaemonClaims,
12
+ provisionVault,
13
+ readSecretsEntry,
14
+ requireSecretsEntry,
15
+ vaultExists,
16
+ writeSecretsEntry,
17
+ } from './vault'
18
+
19
+ export type TypevaultReconcileResult =
20
+ | { action: 'unchanged' }
21
+ | { action: 'enabled' }
22
+ | { action: 'resumed' }
23
+ | { action: 'restored' }
24
+ | { action: 'skipped'; warning: string }
25
+
26
+ // Runs host-side in `typeclaw start` while the container is down, so it is
27
+ // the only writer. Whichever side was live before the toggle wins: enabling
28
+ // moves secrets.json into the vault (overwriting a dormant vault's stale copy),
29
+ // disabling writes the vault's copy back. A dormant vault is resumed, never
30
+ // re-initialized, so entries stored through the vault survive the round trip.
31
+ export async function reconcileTypevault(agentDir: string, enabled: boolean): Promise<TypevaultReconcileResult> {
32
+ const secretsPath = join(agentDir, 'secrets.json')
33
+ // The common case (never enabled) must not even take the lock: start runs
34
+ // this on every launch, including agent folders it cannot write to.
35
+ if (!enabled && !isMarkerFile(secretsPath)) return { action: 'unchanged' }
36
+ const release = await lockfile.lock(secretsPath, ASYNC_LOCK_OPTIONS)
37
+ try {
38
+ clearLegacyDaemonClaims(agentDir)
39
+ return enabled ? await enable(agentDir, secretsPath) : await disable(agentDir, secretsPath)
40
+ } finally {
41
+ await release()
42
+ }
43
+ }
44
+
45
+ async function enable(agentDir: string, secretsPath: string): Promise<TypevaultReconcileResult> {
46
+ const raw = existsSync(secretsPath) ? readFileSync(secretsPath, 'utf8') : ''
47
+ const markerPresent = isTypevaultMarker(raw)
48
+ const resuming = vaultExists(agentDir)
49
+
50
+ // Already enabled: the vault holds the only copy, so it is checked, never
51
+ // provisioned. Provisioning could replace keys the ciphertext still needs.
52
+ if (markerPresent) {
53
+ try {
54
+ await requireSecretsEntry(agentDir)
55
+ return { action: 'unchanged' }
56
+ } catch (error) {
57
+ return skipped(
58
+ `secrets.json points at the TypeVault vault, but its secrets cannot be read: ${describe(error)}. ` +
59
+ 'Nothing was changed. Restore .typevault/ and .typeclaw/typevault/ from a backup of this agent folder.',
60
+ )
61
+ }
62
+ }
63
+
64
+ try {
65
+ await provisionVault(agentDir)
66
+ await readSecretsEntry(agentDir)
67
+ } catch (error) {
68
+ return skipped(
69
+ `${resuming ? "The agent's TypeVault vault (.typevault/) could not be opened" : 'Could not create the TypeVault vault'}: ${describe(error)}. ` +
70
+ 'Keeping secrets.json as the credential store. If the vault came from another copy of this agent without its key, move .typevault/ aside and restart.',
71
+ )
72
+ }
73
+
74
+ const invalid = invalidEnvelope(raw)
75
+ if (invalid !== null) {
76
+ return skipped(
77
+ `secrets.json is not a valid TypeClaw secrets file (${invalid}); fix it, then restart to move it into TypeVault.`,
78
+ )
79
+ }
80
+ await writeSecretsEntry(agentDir, raw)
81
+ if ((await requireSecretsEntry(agentDir)) !== raw) {
82
+ return skipped(
83
+ 'The secrets copied into TypeVault did not read back identically; keeping secrets.json as the credential store.',
84
+ )
85
+ }
86
+ writeAtomic(secretsPath, typevaultMarkerText())
87
+ return { action: resuming ? 'resumed' : 'enabled' }
88
+ }
89
+
90
+ async function disable(agentDir: string, secretsPath: string): Promise<TypevaultReconcileResult> {
91
+ if (!isMarkerFile(secretsPath)) return { action: 'unchanged' }
92
+ let text: string
93
+ try {
94
+ text = await requireSecretsEntry(agentDir)
95
+ } catch (error) {
96
+ return skipped(
97
+ `Could not read the secrets back out of TypeVault to restore secrets.json: ${describe(error)}. The agent keeps using the vault until this is fixed.`,
98
+ )
99
+ }
100
+ writeAtomic(secretsPath, text)
101
+ return { action: 'restored' }
102
+ }
103
+
104
+ function isMarkerFile(secretsPath: string): boolean {
105
+ return existsSync(secretsPath) && isTypevaultMarker(readFileSync(secretsPath, 'utf8'))
106
+ }
107
+
108
+ function invalidEnvelope(raw: string): string | null {
109
+ if (!raw.trim()) return null
110
+ let parsed: unknown
111
+ try {
112
+ parsed = JSON.parse(raw)
113
+ } catch (error) {
114
+ return `not valid JSON: ${describe(error)}`
115
+ }
116
+ const result = parseSecretsFile(parsed)
117
+ return result.ok ? null : result.reason
118
+ }
119
+
120
+ function writeAtomic(path: string, text: string): void {
121
+ const tmp = `${path}.${process.pid}.${Date.now()}.typevault.tmp`
122
+ writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600 })
123
+ renameSync(tmp, path)
124
+ }
125
+
126
+ function skipped(warning: string): TypevaultReconcileResult {
127
+ return { action: 'skipped', warning }
128
+ }
129
+
130
+ function describe(error: unknown): string {
131
+ return error instanceof Error ? error.message : String(error)
132
+ }
@@ -0,0 +1,33 @@
1
+ import type { TunnelConfig } from '@/tunnels'
2
+
3
+ const PROMPT_TUNNEL_NAME = 'typevault'
4
+
5
+ type PromptTunnelConfig = { typevault: { enabled: boolean; promptPort: number }; tunnels: readonly TunnelConfig[] }
6
+
7
+ // The one-time secret page must be reachable from the user's phone. An
8
+ // operator's own manual tunnel wins: one to the prompt port, or one named
9
+ // `typevault` with no port (a cloudflare-named tunnel, whose upstream is set in
10
+ // Cloudflare). Otherwise an enabled vault gets a free Cloudflare quick tunnel,
11
+ // so `vault_request` works with no setup. The page carries only ciphertext
12
+ // (the browser encrypts to the tier).
13
+ export function typevaultPromptTunnel(config: PromptTunnelConfig): TunnelConfig | undefined {
14
+ const configured = config.tunnels.find(
15
+ (entry) =>
16
+ entry.for.kind === 'manual' &&
17
+ (entry.upstreamPort === config.typevault.promptPort ||
18
+ (entry.name === PROMPT_TUNNEL_NAME && entry.upstreamPort === undefined)),
19
+ )
20
+ if (configured !== undefined) return configured
21
+ if (!config.typevault.enabled) return undefined
22
+ // The tunnel manager keys tunnels by name, so a reused name would replace
23
+ // an operator's tunnel instead of adding this one.
24
+ const taken = new Set(config.tunnels.map((entry) => entry.name))
25
+ let name = PROMPT_TUNNEL_NAME
26
+ for (let suffix = 2; taken.has(name); suffix++) name = `${PROMPT_TUNNEL_NAME}-${suffix}`
27
+ return { name, provider: 'cloudflare-quick', for: { kind: 'manual' }, upstreamPort: config.typevault.promptPort }
28
+ }
29
+
30
+ export function runtimeTunnels(config: PromptTunnelConfig): TunnelConfig[] {
31
+ const prompt = typevaultPromptTunnel(config)
32
+ return prompt === undefined || config.tunnels.includes(prompt) ? [...config.tunnels] : [...config.tunnels, prompt]
33
+ }
@@ -0,0 +1,37 @@
1
+ import { entriesStamp } from './envelope-store'
2
+ import { openVault, RUNTIME_TIER } from './vault'
3
+
4
+ const READ_REASON = 'redact tool output'
5
+
6
+ const cache = new Map<string, { stamp: string; values: readonly string[] }>()
7
+ // Every value ever seen, per agent, for the life of the process (which outlives
8
+ // every session in it): a secret that was overwritten or deleted can still sit
9
+ // in a log or artifact, so it stays redacted.
10
+ const observed = new Map<string, Set<string>>()
11
+
12
+ // Every secret value stored in the vault outside the runtime tier, read with
13
+ // the agent's own key. Redacting by what the vault holds, rather than by what
14
+ // a grant reports it handed out, covers derived grants, a bash command still
15
+ // running when another tool finishes, and grants that expired or were revoked
16
+ // before their history could be read. Public `text` fields are left alone.
17
+ // Cached until the vault's entries change.
18
+ export async function vaultSecretValues(agentDir: string): Promise<readonly string[]> {
19
+ const stamp = entriesStamp(agentDir)
20
+ const cached = cache.get(agentDir)
21
+ if (cached !== undefined && cached.stamp === stamp) return cached.values
22
+ const vault = await openVault(agentDir)
23
+ const values = observed.get(agentDir) ?? new Set<string>()
24
+ observed.set(agentDir, values)
25
+ for (const summary of await vault.list()) {
26
+ if (summary.tier === RUNTIME_TIER) continue
27
+ const entry = await vault.get(summary.name, READ_REASON)
28
+ for (const field of Object.values(entry.fields)) {
29
+ if (field.type === 'text') continue
30
+ if (field.type === 'oauth') for (const part of Object.values(field.value)) values.add(part)
31
+ else values.add(field.value)
32
+ }
33
+ }
34
+ const snapshot = [...values]
35
+ if (entriesStamp(agentDir) === stamp) cache.set(agentDir, { stamp, values: snapshot })
36
+ return snapshot
37
+ }
@@ -0,0 +1,283 @@
1
+ import { createHash } from 'node:crypto'
2
+ import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs'
3
+ import { join, resolve } from 'node:path'
4
+
5
+ import { type Access, createClient, parseEntryName, TypeVaultError } from 'typevault'
6
+ import { type AdminClient, createAdmin } from 'typevault/admin'
7
+
8
+ import { typevaultCliPath } from './cli-path'
9
+
10
+ // The agent's vault and its private state both live inside the agent folder,
11
+ // so copying the folder moves the whole vault. `.typevault/` holds only
12
+ // ciphertext and signed manifests (force-committed by the backup plugin);
13
+ // `.typeclaw/typevault/` holds the agent's own machine key and typevault's
14
+ // per-checkout state (trust pin, audit log, locks), gitignored and masked
15
+ // from every role.
16
+ export const TYPEVAULT_VAULT_RELATIVE_DIR = '.typevault'
17
+ export const TYPEVAULT_STATE_RELATIVE_DIR = '.typeclaw/typevault'
18
+
19
+ // The vault's single owner: a machine identity, so nothing ever waits for a
20
+ // human to unlock it.
21
+ const MEMBER_NAME = 'typeclaw'
22
+
23
+ // Holds the whole secrets.json envelope. No grant issued to a model session
24
+ // ever reaches this tier.
25
+ export const RUNTIME_TIER = 'runtime'
26
+
27
+ const SECRETS_ENTRY = parseEntryName('typevault://typeclaw/secrets')
28
+ const READ_REASON = 'typeclaw runtime credentials'
29
+
30
+ export function typevaultDir(agentDir: string): string {
31
+ return join(agentDir, TYPEVAULT_VAULT_RELATIVE_DIR)
32
+ }
33
+
34
+ export function vaultExists(agentDir: string): boolean {
35
+ return existsSync(join(typevaultDir(agentDir), 'owner.json'))
36
+ }
37
+
38
+ // typevault lets one machine at a time use a vault's private state, and names
39
+ // the machine that holds it in a `daemon.holder` claim that survives the
40
+ // daemon. Its default name comes from the machine ID or hostname, but for TypeClaw the host-stage CLI
41
+ // and every container recreated for this agent are one owner: a new container
42
+ // can get a new name, so a claim left by the previous one (or held by the live
43
+ // container while the host CLI writes secrets) would refuse every vault open
44
+ // with `in_use`. One stable identity per agent lets typevault replace a claim
45
+ // its own flock proves stale; a claim from any other identity is still refused.
46
+ export const TYPEVAULT_HOST_ID = 'typeclaw-agent'
47
+
48
+ // typevault 0.4 requires `name` in `daemon.holder` and refuses every vault open
49
+ // on a claim without one. The runtime never stops its detached daemon, so each
50
+ // container stop under 0.3 leaves such a claim behind. typevault keys a checkout
51
+ // by the vault's absolute path, so the container's claim sits under the hash of
52
+ // /agent/.typevault, not the host path: scan every checkout in this agent's
53
+ // config root. Call this only while the container is down: a claim under this
54
+ // agent's identity then has no live owner. Any other claim stays, for typevault
55
+ // to refuse with its own error.
56
+ export function clearLegacyDaemonClaims(agentDir: string): void {
57
+ const checkouts = join(runtimeConfigRoot(agentDir), 'typevault', 'checkouts')
58
+ if (!existsSync(checkouts)) return
59
+ for (const checkout of readdirSync(checkouts)) {
60
+ const path = join(checkouts, checkout, 'run', 'daemon.holder')
61
+ if (!existsSync(path)) continue
62
+ let claim: { host?: unknown; name?: unknown } | null
63
+ try {
64
+ claim = JSON.parse(readFileSync(path, 'utf8'))
65
+ } catch {
66
+ continue
67
+ }
68
+ if (claim?.host === TYPEVAULT_HOST_ID && claim.name === undefined) rmSync(path, { force: true })
69
+ }
70
+ }
71
+
72
+ // The environment every typevault call runs under. The agent's vault is opened
73
+ // as typevault's "global" vault at an explicit TYPEVAULT_DIR, so nothing
74
+ // depends on the process cwd, and every ambient TYPEVAULT_* variable is
75
+ // dropped so an operator's own grant or key can never leak in.
76
+ export function typevaultEnv(agentDir: string, base: NodeJS.ProcessEnv = process.env): Record<string, string> {
77
+ const env: Record<string, string> = {}
78
+ for (const [key, value] of Object.entries(base)) {
79
+ if (value !== undefined && !key.startsWith('TYPEVAULT_')) env[key] = value
80
+ }
81
+ env.XDG_CONFIG_HOME = runtimeConfigRoot(agentDir)
82
+ env.TYPEVAULT_DIR = typevaultDir(agentDir)
83
+ env.TYPEVAULT_GLOBAL = '1'
84
+ env.TYPEVAULT_HOST_ID = TYPEVAULT_HOST_ID
85
+ return env
86
+ }
87
+
88
+ // Owner operations have no SDK export yet, so they go through typevault's CLI.
89
+ // `init` mints a new owner key and rewrites the manifests, so it only ever runs
90
+ // on an empty directory: anything left behind is ciphertext that only the old
91
+ // keys can open.
92
+ export async function provisionVault(agentDir: string): Promise<void> {
93
+ if (!vaultExists(agentDir)) {
94
+ const dir = typevaultDir(agentDir)
95
+ if (existsSync(dir) && readdirSync(dir).length > 0) {
96
+ throw new Error(`${dir} is not empty but has no owner.json; refusing to create a new vault over it`)
97
+ }
98
+ await runTypevaultCli(agentDir, ['init', '--machine', '--name', MEMBER_NAME])
99
+ }
100
+ await ensureTier(agentDir, RUNTIME_TIER)
101
+ }
102
+
103
+ // `undefined` only means "not stored yet". Once secrets.json points at the
104
+ // vault, use requireSecretsEntry: typevault skips entries it cannot verify, so
105
+ // a missing entry can be corruption and must never read as an empty store.
106
+ export async function readSecretsEntry(agentDir: string): Promise<string | undefined> {
107
+ const vault = await openVault(agentDir)
108
+ let fields: Awaited<ReturnType<Access['get']>>['fields']
109
+ try {
110
+ fields = (await vault.get(SECRETS_ENTRY, READ_REASON)).fields
111
+ } catch (error) {
112
+ if (error instanceof TypeVaultError && error.code === 'not_found') return undefined
113
+ throw error
114
+ }
115
+ const value = fields['$default']
116
+ if (value?.type !== 'secret') throw new Error('the TypeVault secrets entry has no secret field')
117
+ return value.value
118
+ }
119
+
120
+ export async function requireSecretsEntry(agentDir: string): Promise<string> {
121
+ const text = await readSecretsEntry(agentDir)
122
+ if (text === undefined) {
123
+ throw new Error(
124
+ 'the TypeVault vault has no readable secrets entry (typevault://typeclaw/secrets); restore .typevault/ from the agent repo history',
125
+ )
126
+ }
127
+ return text
128
+ }
129
+
130
+ export async function writeSecretsEntry(agentDir: string, text: string): Promise<void> {
131
+ const vault = await openVault(agentDir)
132
+ await vault.set({
133
+ name: SECRETS_ENTRY,
134
+ tier: RUNTIME_TIER,
135
+ fields: { $default: { type: 'secret', value: text } },
136
+ })
137
+ }
138
+
139
+ // The built-in role tower as tier includes: a grant for a role's tier reaches
140
+ // every tier below it, so a secret stored at `member` is usable by member,
141
+ // trusted and owner sessions, and never by guest.
142
+ export const ROLE_TIER_TOWER = ['owner', 'trusted', 'member', 'guest'] as const
143
+
144
+ const TIER_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
145
+
146
+ // A role reaches the tier of the same name, except the runtime tier: it holds
147
+ // the whole secrets.json envelope, so a custom role named `runtime` must never
148
+ // map onto it.
149
+ export function isRoleTier(name: string): boolean {
150
+ return TIER_NAME.test(name) && name !== RUNTIME_TIER
151
+ }
152
+
153
+ // Creates a tier per role and wires the built-in tower. Returns the roles that
154
+ // get no tier (and so no grant), for the operator log.
155
+ export async function ensureRoleTiers(agentDir: string, roles: readonly string[]): Promise<string[]> {
156
+ const tiers = await listTiers(agentDir)
157
+ const skipped: string[] = []
158
+ for (const role of new Set([...ROLE_TIER_TOWER, ...roles])) {
159
+ if (!isRoleTier(role)) {
160
+ skipped.push(role)
161
+ continue
162
+ }
163
+ if (tiers.has(role)) continue
164
+ await ensureTier(agentDir, role)
165
+ tiers.set(role, new Set())
166
+ }
167
+ for (let i = 0; i < ROLE_TIER_TOWER.length - 1; i++) {
168
+ const upper = ROLE_TIER_TOWER[i]!
169
+ const lower = ROLE_TIER_TOWER[i + 1]!
170
+ if (!tiers.get(upper)?.has(lower)) await runTypevaultCli(agentDir, ['tier', 'include', upper, lower])
171
+ }
172
+ return skipped
173
+ }
174
+
175
+ // `promptPort` reaches the daemon only when this call is what starts it; the
176
+ // runtime's first grant does, so the daemon serves `request` pages there.
177
+ export function vaultAdmin(agentDir: string, options: { promptPort?: number } = {}): AdminClient {
178
+ const env = typevaultEnv(agentDir)
179
+ if (options.promptPort !== undefined) env.TYPEVAULT_PROMPT_PORT = String(options.promptPort)
180
+ return createAdmin({ env, global: true, dir: typevaultDir(agentDir) })
181
+ }
182
+
183
+ export function grantAccess(agentDir: string, grant: string): Promise<Access> {
184
+ return createClient({ grant, global: true, dir: typevaultDir(agentDir), env: typevaultEnv(agentDir) })
185
+ }
186
+
187
+ // typevault keys a vault's private state by the hash of its directory path, so
188
+ // a client with a different config root still finds the socket for the same
189
+ // TYPEVAULT_DIR under `<configRoot>/typevault/checkouts/<hash>/run/`.
190
+ export function agentSocketPath(agentDir: string, configRoot: string): string {
191
+ const checkout = createHash('sha256')
192
+ .update(resolve(typevaultDir(agentDir)), 'utf8')
193
+ .digest('hex')
194
+ .slice(0, 16)
195
+ return join(configRoot, 'typevault', 'checkouts', checkout, 'run', 'agent.sock')
196
+ }
197
+
198
+ export function runtimeConfigRoot(agentDir: string): string {
199
+ return join(agentDir, TYPEVAULT_STATE_RELATIVE_DIR, 'config')
200
+ }
201
+
202
+ // The agent's member identity for other projects' vaults, apart from the key
203
+ // that owns its own vault: model bash gets this one, so it must never open
204
+ // the agent's vault. An owner adds it with the line `typevault join` prints.
205
+ export function projectIdentityPath(agentDir: string): string {
206
+ return join(projectConfigRoot(agentDir), 'typevault', 'identity.json')
207
+ }
208
+
209
+ export async function ensureProjectIdentity(agentDir: string, name: string): Promise<void> {
210
+ if (existsSync(projectIdentityPath(agentDir))) return
211
+ // `join` is typevault's only way to mint a machine identity. It needs some
212
+ // vault to name; the agent's own is opened public-only and left unchanged.
213
+ await runTypevaultCli(agentDir, ['join', '--machine', '--name', name], {
214
+ XDG_CONFIG_HOME: projectConfigRoot(agentDir),
215
+ })
216
+ }
217
+
218
+ // A typevault member name ([a-z0-9-]) for this agent, from its container name.
219
+ export function projectMemberName(containerName: string | undefined): string {
220
+ const name = (containerName ?? '')
221
+ .toLowerCase()
222
+ .replace(/[^a-z0-9]+/g, '-')
223
+ .replace(/^-+|-+$/g, '')
224
+ return name === '' ? MEMBER_NAME : name
225
+ }
226
+
227
+ function projectConfigRoot(agentDir: string): string {
228
+ return join(agentDir, TYPEVAULT_STATE_RELATIVE_DIR, 'project-member')
229
+ }
230
+
231
+ async function listTiers(agentDir: string): Promise<Map<string, Set<string>>> {
232
+ const tiers = new Map<string, Set<string>>()
233
+ const lines = (await runTypevaultCli(agentDir, ['tier', 'ls'])).split('\n').slice(1)
234
+ for (const line of lines) {
235
+ const [name, , ...rest] = line.trim().split(/\s+/)
236
+ if (name === undefined || name === '') continue
237
+ tiers.set(
238
+ name,
239
+ new Set(
240
+ rest
241
+ .join(' ')
242
+ .split(/[,\s]+/)
243
+ .filter(Boolean),
244
+ ),
245
+ )
246
+ }
247
+ return tiers
248
+ }
249
+
250
+ export function openVault(agentDir: string): Promise<Access> {
251
+ return createClient({ direct: true, global: true, dir: typevaultDir(agentDir), env: typevaultEnv(agentDir) })
252
+ }
253
+
254
+ async function ensureTier(agentDir: string, tier: string): Promise<void> {
255
+ try {
256
+ await runTypevaultCli(agentDir, ['tier', 'add', tier])
257
+ } catch (error) {
258
+ if (!(error instanceof Error && error.message.includes(`tier "${tier}" already exists`))) throw error
259
+ }
260
+ }
261
+
262
+ async function runTypevaultCli(
263
+ agentDir: string,
264
+ args: string[],
265
+ envOverride: Record<string, string> = {},
266
+ ): Promise<string> {
267
+ const child = Bun.spawn([process.execPath, typevaultCliPath(), ...args], {
268
+ cwd: agentDir,
269
+ env: { ...typevaultEnv(agentDir), ...envOverride },
270
+ stdin: 'ignore',
271
+ stdout: 'pipe',
272
+ stderr: 'pipe',
273
+ })
274
+ const [stdout, stderr, exitCode] = await Promise.all([
275
+ new Response(child.stdout).text(),
276
+ new Response(child.stderr).text(),
277
+ child.exited,
278
+ ])
279
+ if (exitCode !== 0) {
280
+ throw new Error(`typevault ${args.join(' ')} failed: ${stderr.trim() || `exit code ${exitCode}`}`)
281
+ }
282
+ return stdout
283
+ }