typeclaw 0.42.1 → 0.43.1

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 (42) hide show
  1. package/auth.schema.json +16 -0
  2. package/package.json +2 -2
  3. package/secrets.schema.json +16 -0
  4. package/src/agent/index.ts +9 -2
  5. package/src/agent/live-subagents.ts +4 -4
  6. package/src/agent/plugin-tools.ts +8 -2
  7. package/src/agent/session-origin.ts +6 -3
  8. package/src/agent/system-prompt.ts +41 -3
  9. package/src/agent/tools/channel-react.ts +5 -4
  10. package/src/agent/tools/spawn-subagent.ts +80 -24
  11. package/src/bundled-plugins/planner/planner.ts +1 -1
  12. package/src/bundled-plugins/researcher/researcher.ts +2 -2
  13. package/src/bundled-plugins/reviewer/reviewer.ts +1 -1
  14. package/src/channels/adapters/discord-bot-thread-room.ts +73 -0
  15. package/src/channels/adapters/discord-bot.ts +85 -4
  16. package/src/channels/adapters/discord.ts +15 -2
  17. package/src/channels/adapters/slack-bot-classify.ts +1 -0
  18. package/src/channels/adapters/slack-classify.ts +1 -0
  19. package/src/channels/engagement.ts +33 -0
  20. package/src/channels/manager.ts +9 -1
  21. package/src/channels/router.ts +500 -91
  22. package/src/channels/schema.ts +24 -0
  23. package/src/channels/types.ts +18 -5
  24. package/src/cli/channel.ts +40 -13
  25. package/src/cli/command-meta.ts +2 -0
  26. package/src/cli/index.ts +1 -0
  27. package/src/cli/mcp.ts +233 -0
  28. package/src/hostd/daemon.ts +28 -9
  29. package/src/hostd/protocol.ts +12 -9
  30. package/src/mcp/client.ts +15 -5
  31. package/src/mcp/index.ts +12 -0
  32. package/src/mcp/manager.ts +9 -4
  33. package/src/mcp/oauth.ts +212 -0
  34. package/src/run/index.ts +15 -2
  35. package/src/sandbox/hidden-paths.ts +59 -0
  36. package/src/sandbox/index.ts +1 -1
  37. package/src/secrets/index.ts +1 -1
  38. package/src/secrets/schema.ts +13 -0
  39. package/src/secrets/secrets-provider.ts +2 -2
  40. package/src/secrets/storage.ts +108 -1
  41. package/src/skills/typeclaw-channel-github/SKILL.md +2 -2
  42. package/src/skills/typeclaw-troubleshooting/SKILL.md +1 -1
@@ -0,0 +1,212 @@
1
+ import { randomUUID } from 'node:crypto'
2
+
3
+ import type { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js'
4
+ import type {
5
+ OAuthClientInformationMixed,
6
+ OAuthClientMetadata,
7
+ OAuthTokens,
8
+ } from '@modelcontextprotocol/sdk/shared/auth.js'
9
+
10
+ import { sendHttp } from '@/hostd/client'
11
+ import type { Request } from '@/hostd/protocol'
12
+ import type { McpCredential, McpSlice } from '@/secrets/schema'
13
+ import { SecretsBackend } from '@/secrets/storage'
14
+
15
+ export type McpOAuthInvalidateScope = Parameters<NonNullable<OAuthClientProvider['invalidateCredentials']>>[0]
16
+
17
+ export interface McpOAuthStore {
18
+ get(server: string): McpCredential | undefined | Promise<McpCredential | undefined>
19
+ saveClient(server: string, client: OAuthClientInformationMixed): Promise<void>
20
+ saveTokens(server: string, tokens: OAuthTokens): Promise<void>
21
+ saveDiscovery(server: string, state: OAuthDiscoveryState): Promise<void>
22
+ invalidate(server: string, scope: McpOAuthInvalidateScope): Promise<void>
23
+ }
24
+
25
+ export type TypeClawMcpOAuthProviderOptions = {
26
+ mode: 'host' | 'container'
27
+ redirectUrl: string
28
+ clientName: string
29
+ scope?: string
30
+ onRedirect?: (url: URL) => void
31
+ }
32
+
33
+ export class TypeClawMcpOAuthProvider implements OAuthClientProvider {
34
+ private verifier: string | undefined
35
+ private oauthState: string | undefined
36
+
37
+ constructor(
38
+ private readonly serverName: string,
39
+ private readonly store: McpOAuthStore,
40
+ private readonly opts: TypeClawMcpOAuthProviderOptions,
41
+ ) {}
42
+
43
+ get redirectUrl(): string {
44
+ return this.opts.redirectUrl
45
+ }
46
+
47
+ get clientMetadata(): OAuthClientMetadata {
48
+ return {
49
+ client_name: this.opts.clientName,
50
+ redirect_uris: [this.opts.redirectUrl],
51
+ grant_types: ['authorization_code', 'refresh_token'],
52
+ response_types: ['code'],
53
+ token_endpoint_auth_method: 'none',
54
+ ...(this.opts.scope === undefined ? {} : { scope: this.opts.scope }),
55
+ }
56
+ }
57
+
58
+ async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
59
+ return (await this.store.get(this.serverName))?.client as OAuthClientInformationMixed | undefined
60
+ }
61
+
62
+ async saveClientInformation(info: OAuthClientInformationMixed): Promise<void> {
63
+ await this.store.saveClient(this.serverName, info)
64
+ }
65
+
66
+ async tokens(): Promise<OAuthTokens | undefined> {
67
+ return (await this.store.get(this.serverName))?.tokens as OAuthTokens | undefined
68
+ }
69
+
70
+ async saveTokens(tokens: OAuthTokens): Promise<void> {
71
+ await this.store.saveTokens(this.serverName, tokens)
72
+ }
73
+
74
+ async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
75
+ return (await this.store.get(this.serverName))?.discovery as OAuthDiscoveryState | undefined
76
+ }
77
+
78
+ async saveDiscoveryState(state: OAuthDiscoveryState): Promise<void> {
79
+ await this.store.saveDiscovery(this.serverName, state)
80
+ }
81
+
82
+ async saveCodeVerifier(verifier: string): Promise<void> {
83
+ this.verifier = verifier
84
+ }
85
+
86
+ async codeVerifier(): Promise<string> {
87
+ if (this.verifier === undefined) throw new Error(`MCP server "${this.serverName}" OAuth verifier is missing`)
88
+ return this.verifier
89
+ }
90
+
91
+ async state(): Promise<string> {
92
+ this.oauthState ??= randomUUID()
93
+ return this.oauthState
94
+ }
95
+
96
+ async redirectToAuthorization(url: URL): Promise<void> {
97
+ if (this.opts.mode === 'container') {
98
+ throw new Error(
99
+ `MCP server "${this.serverName}" needs OAuth. Run on the host: typeclaw mcp auth ${this.serverName}`,
100
+ )
101
+ }
102
+ this.opts.onRedirect?.(url)
103
+ }
104
+
105
+ async invalidateCredentials(scope: McpOAuthInvalidateScope): Promise<void> {
106
+ await this.store.invalidate(this.serverName, scope)
107
+ }
108
+ }
109
+
110
+ export function createFileMcpOAuthStore(secretsPath: string): McpOAuthStore {
111
+ const backend = new SecretsBackend(secretsPath)
112
+ return {
113
+ get(server) {
114
+ return backend.readMcpCredentialSync(server)
115
+ },
116
+ async saveClient(server, client) {
117
+ await patchMcp(backend, server, { client })
118
+ },
119
+ async saveTokens(server, tokens) {
120
+ await patchMcp(backend, server, { tokens })
121
+ },
122
+ async saveDiscovery(server, discovery) {
123
+ await patchMcp(backend, server, { discovery })
124
+ },
125
+ async invalidate(server, scope) {
126
+ await invalidateMcp(backend, server, scope)
127
+ },
128
+ }
129
+ }
130
+
131
+ export type HostdMcpOAuthStoreOptions = {
132
+ hostdUrl: string
133
+ restartToken: string
134
+ containerName: string
135
+ secretsPath: string
136
+ }
137
+
138
+ export function createHostdMcpOAuthStore(options: HostdMcpOAuthStoreOptions): McpOAuthStore {
139
+ const backend = new SecretsBackend(options.secretsPath)
140
+ const write = async (server: string, credential: McpCredential): Promise<void> => {
141
+ const request: Extract<Request, { kind: 'secrets-patch' }> = {
142
+ kind: 'secrets-patch',
143
+ containerName: options.containerName,
144
+ patch: { mcp: { server, credential } },
145
+ }
146
+ const response = await sendHttp(request, { url: options.hostdUrl, token: options.restartToken })
147
+ if (!response.ok) throw new Error(`secrets-patch failed: ${response.reason}`)
148
+ }
149
+ const patch = async (server: string, fieldPatch: McpCredential): Promise<void> => {
150
+ await write(server, { ...backend.readMcpCredentialSync(server), ...fieldPatch })
151
+ }
152
+ return {
153
+ get(server) {
154
+ return backend.readMcpCredentialSync(server)
155
+ },
156
+ async saveClient(server, client) {
157
+ await patch(server, { client })
158
+ },
159
+ async saveTokens(server, tokens) {
160
+ await patch(server, { tokens })
161
+ },
162
+ async saveDiscovery(server, discovery) {
163
+ await patch(server, { discovery })
164
+ },
165
+ async invalidate(server, scope) {
166
+ const credential = invalidateCredential(backend.readMcpCredentialSync(server), scope)
167
+ if (credential === undefined) return
168
+ await write(server, credential)
169
+ },
170
+ }
171
+ }
172
+
173
+ async function patchMcp(backend: SecretsBackend, server: string, fieldPatch: McpCredential): Promise<void> {
174
+ await backend.updateMcpAsync(async (mcp) => ({
175
+ result: undefined,
176
+ next: { ...mcp, [server]: { ...mcp[server], ...fieldPatch } },
177
+ }))
178
+ }
179
+
180
+ async function invalidateMcp(backend: SecretsBackend, server: string, scope: McpOAuthInvalidateScope): Promise<void> {
181
+ await backend.updateMcpAsync(async (mcp) => {
182
+ const credential = invalidateCredential(mcp[server], scope)
183
+ if (credential === undefined) return { result: undefined }
184
+ return { result: undefined, next: { ...mcp, [server]: credential } }
185
+ })
186
+ }
187
+
188
+ function invalidateCredential(
189
+ credential: McpCredential | undefined,
190
+ scope: McpOAuthInvalidateScope,
191
+ ): McpCredential | undefined {
192
+ if (credential === undefined) return undefined
193
+ const next: McpCredential = { ...credential }
194
+ if (scope === 'tokens' || scope === 'all') delete next.tokens
195
+ if (scope === 'client' || scope === 'all') delete next.client
196
+ if (scope === 'all') delete next.discovery
197
+ return next
198
+ }
199
+
200
+ export function resolveContainerMcpOAuthStore(env: NodeJS.ProcessEnv, secretsPath: string): McpOAuthStore {
201
+ const hostdUrl = env.TYPECLAW_HOSTD_URL
202
+ const restartToken = env.TYPECLAW_HOSTD_TOKEN
203
+ const containerName = env.TYPECLAW_CONTAINER_NAME
204
+ if (hostdUrl && restartToken && containerName) {
205
+ return createHostdMcpOAuthStore({ hostdUrl, restartToken, containerName, secretsPath })
206
+ }
207
+ return createFileMcpOAuthStore(secretsPath)
208
+ }
209
+
210
+ export function listMcpCredentials(secretsPath: string): McpSlice {
211
+ return new SecretsBackend(secretsPath).tryReadMcpSync()
212
+ }
package/src/run/index.ts CHANGED
@@ -54,7 +54,7 @@ import {
54
54
  type Scheduler,
55
55
  } from '@/cron'
56
56
  import { CLI_VERSION } from '@/init/cli-version'
57
- import { createMcpManager } from '@/mcp'
57
+ import { createMcpManager, resolveContainerMcpOAuthStore, TypeClawMcpOAuthProvider } from '@/mcp'
58
58
  import { runStartupMigrations } from '@/migrations'
59
59
  import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
60
60
  import { createPluginLogger } from '@/plugin/context'
@@ -239,8 +239,21 @@ async function startAgentRuntime(
239
239
 
240
240
  const { config: cwdConfig, pluginConfigs: pluginConfigsByName } = loadConfigBundleSync(cwd)
241
241
  const githubTokenBridge = createGithubTokenBridge()
242
+ const mcpOAuthStore = resolveContainerMcpOAuthStore(process.env, join(cwd, 'secrets.json'))
242
243
  const mcpManager =
243
- cwdConfig.mcpServers.length > 0 ? createMcpManager(cwdConfig.mcpServers, { env: process.env }) : null
244
+ cwdConfig.mcpServers.length > 0
245
+ ? createMcpManager(cwdConfig.mcpServers, {
246
+ env: process.env,
247
+ authProvider: (server) =>
248
+ server.url === undefined
249
+ ? undefined
250
+ : new TypeClawMcpOAuthProvider(server.name, mcpOAuthStore, {
251
+ mode: 'container',
252
+ redirectUrl: 'http://localhost:1456/callback',
253
+ clientName: 'typeclaw',
254
+ }),
255
+ })
256
+ : null
244
257
  const mcpManagerOpt = mcpManager !== null ? { mcpManager } : {}
245
258
 
246
259
  // Warm up MCP connections in the BACKGROUND so boot doesn't block on each
@@ -1,3 +1,4 @@
1
+ import { lstat, mkdir, writeFile } from 'node:fs/promises'
1
2
  import { join } from 'node:path'
2
3
 
3
4
  import type { SessionOrigin } from '@/agent/session-origin'
@@ -39,3 +40,61 @@ export function resolveHiddenPaths(
39
40
  const files = seesSecrets ? [] : SECRET_FILES.map((f) => join(agentDir, f))
40
41
  return { dirs, files }
41
42
  }
43
+
44
+ // SECURITY / bwrap contract: the mask ops REQUIRE a pre-existing target.
45
+ // `--ro-bind-data` (secret files) and `--tmpfs` (private dirs) create their
46
+ // mount point under the agent-folder bind, which fails "Read-only file system"
47
+ // on a virtiofs/OrbStack bind (bwrap cannot create it from its child user
48
+ // namespace). An agent whose folder legitimately lacks `.env` (keys live in
49
+ // secrets.json) would otherwise have EVERY sandboxed bash call abort at setup.
50
+ // Ensure each target on the REAL host FS first — the runtime owns agentDir RW
51
+ // here (only sandboxed bash sees it RO), so an empty placeholder is harmless and
52
+ // the mask binds over a real empty file, leaking nothing.
53
+ //
54
+ // ENSURE, not FILTER: package-install mode makes the jail root RW
55
+ // (`writableRoot: agentDir`), so dropping an absent secret would let sandboxed
56
+ // code CREATE `.env`/`secrets.json` for real (planting) or expose one created
57
+ // mid-session (TOCTOU). A guaranteed target keeps the mask always rendered over
58
+ // it (last-op-wins), closing that hole for both jail modes. A symlink squatting
59
+ // a target is refused and dropped (a bind would follow it out), and each target
60
+ // is best-effort so one bad entry degrades that mask, never aborts sandboxing.
61
+ export async function ensureHiddenMaskTargets(hidden: HiddenPaths): Promise<HiddenPaths> {
62
+ const dirs = await ensureMaskTargets(hidden.dirs, 'dir')
63
+ const files = await ensureMaskTargets(hidden.files, 'file')
64
+ return { dirs, files }
65
+ }
66
+
67
+ async function ensureMaskTargets(targets: string[], kind: 'dir' | 'file'): Promise<string[]> {
68
+ const results = await Promise.all(targets.map((target) => ensureMaskTarget(target, kind)))
69
+ return targets.filter((_, i) => results[i])
70
+ }
71
+
72
+ async function ensureMaskTarget(target: string, kind: 'dir' | 'file'): Promise<boolean> {
73
+ try {
74
+ if (kind === 'dir') await mkdir(target, { recursive: true })
75
+ else await ensureEmptyFile(target)
76
+ return await isRealEntry(target, kind)
77
+ } catch {
78
+ return false
79
+ }
80
+ }
81
+
82
+ async function ensureEmptyFile(target: string): Promise<void> {
83
+ try {
84
+ await writeFile(target, '', { flag: 'wx' })
85
+ } catch {
86
+ // Already exists or lost a creation race; isRealEntry re-validates the kind
87
+ // and rejects a symlink, so an existing regular file passes and anything
88
+ // else is dropped from the mask.
89
+ }
90
+ }
91
+
92
+ async function isRealEntry(target: string, kind: 'dir' | 'file'): Promise<boolean> {
93
+ try {
94
+ const stats = await lstat(target)
95
+ if (stats.isSymbolicLink()) return false
96
+ return kind === 'dir' ? stats.isDirectory() : stats.isFile()
97
+ } catch {
98
+ return false
99
+ }
100
+ }
@@ -13,7 +13,7 @@ export {
13
13
  _resetProcBindProbeCacheForTests,
14
14
  _resetRealProcProbeCacheForTests,
15
15
  } from './availability'
16
- export { resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
16
+ export { ensureHiddenMaskTargets, resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
17
17
  export {
18
18
  resolvePackageInstallZones,
19
19
  resolveProtectedZones,
@@ -1,4 +1,4 @@
1
- export { type Channels, type GithubSecretsBlock } from './schema'
1
+ export { type Channels, type GithubSecretsBlock, type McpCredential, type McpSlice } from './schema'
2
2
 
3
3
  export { createSecretsStoreForAgent, SecretsBackend } from './storage'
4
4
 
@@ -22,6 +22,16 @@ export const providerCredentialSchema = z.discriminatedUnion('type', [apiKeyProv
22
22
 
23
23
  export const providersSchema = z.record(z.string(), providerCredentialSchema)
24
24
 
25
+ export const mcpCredentialSchema = z
26
+ .object({
27
+ client: z.unknown().optional(),
28
+ tokens: z.unknown().optional(),
29
+ discovery: z.unknown().optional(),
30
+ })
31
+ .catchall(z.unknown())
32
+
33
+ export const mcpSliceSchema = z.record(z.string(), mcpCredentialSchema)
34
+
25
35
  // Per-adapter channel slots use named fields (`botToken`, `appToken`, `token`)
26
36
  // instead of env-var-name keys. The Secret union per field carries the env-var
27
37
  // override. Unknown adapter ids pass through via catchall so a future
@@ -224,10 +234,13 @@ export const secretsFileSchema = z.object({
224
234
  version: z.literal(SECRETS_FILE_VERSION),
225
235
  providers: providersSchema.default({}),
226
236
  channels: channelsSchema.default({}),
237
+ mcp: mcpSliceSchema.default({}),
227
238
  })
228
239
 
229
240
  export type ProviderCredential = z.infer<typeof providerCredentialSchema>
230
241
  export type Providers = z.infer<typeof providersSchema>
242
+ export type McpCredential = z.infer<typeof mcpCredentialSchema>
243
+ export type McpSlice = z.infer<typeof mcpSliceSchema>
231
244
  export type Channels = z.infer<typeof channelsSchema>
232
245
  export type GithubPatAuthBlock = z.infer<typeof githubPatAuthSchema>
233
246
  export type GithubAppAuthBlock = z.infer<typeof githubAppAuthSchema>
@@ -1,5 +1,5 @@
1
1
  import { sendHttp } from '@/hostd/client'
2
- import type { Request } from '@/hostd/protocol'
2
+ import type { SecretsPatchChannels } from '@/hostd/protocol'
3
3
 
4
4
  import type { Channels } from './schema'
5
5
  import { SecretsBackend } from './storage'
@@ -8,7 +8,7 @@ import { SecretsBackend } from './storage'
8
8
  // Identical to the `secrets-patch` RPC's `patch.channels` union so the hostd
9
9
  // implementation forwards it verbatim — the on-the-wire contract is unchanged
10
10
  // by this abstraction.
11
- export type ChannelBlockPatch = Extract<Request, { kind: 'secrets-patch' }>['patch']['channels']
11
+ export type ChannelBlockPatch = SecretsPatchChannels
12
12
 
13
13
  // The container-stage secrets seam. Named for what the runtime NEEDS, not the
14
14
  // transport that serves it. Two halves:
@@ -13,6 +13,8 @@ import { registerXaiOAuthProvider } from './oauth-xai'
13
13
  import { resolveSecret, type Secret } from './resolve'
14
14
  import {
15
15
  type Channels,
16
+ type McpCredential,
17
+ type McpSlice,
16
18
  type ProviderCredential,
17
19
  type Providers,
18
20
  type SecretsFile,
@@ -191,6 +193,111 @@ export class SecretsBackend implements AuthStorageBackend {
191
193
  }
192
194
  }
193
195
 
196
+ tryReadMcpSync(): McpSlice {
197
+ if (!existsSync(this.secretsPath)) return {}
198
+ let release: (() => void) | undefined
199
+ try {
200
+ release = this.acquireSyncLockWithRetry()
201
+ return { ...this.readEnvelope().mcp }
202
+ } finally {
203
+ release?.()
204
+ }
205
+ }
206
+
207
+ readMcpCredentialSync(serverName: string): McpCredential | undefined {
208
+ if (!existsSync(this.secretsPath)) return undefined
209
+ let release: (() => void) | undefined
210
+ try {
211
+ release = this.acquireSyncLockWithRetry()
212
+ return this.readEnvelope().mcp[serverName]
213
+ } finally {
214
+ release?.()
215
+ }
216
+ }
217
+
218
+ writeMcpCredentialSync(serverName: string, credential: McpCredential): void {
219
+ this.ensureParentDir()
220
+ this.ensureFileExists()
221
+ let release: (() => void) | undefined
222
+ try {
223
+ release = this.acquireSyncLockWithRetry()
224
+ const envelope = this.readEnvelope()
225
+ const next: SecretsFile = {
226
+ ...envelope,
227
+ $schema: envelope.$schema ?? SCHEMA_REL,
228
+ version: SECRETS_FILE_VERSION,
229
+ mcp: { ...envelope.mcp, [serverName]: credential },
230
+ }
231
+ this.writeEnvelopeAtomic(next)
232
+ } finally {
233
+ release?.()
234
+ }
235
+ }
236
+
237
+ async updateMcpAsync<T>(fn: (current: McpSlice) => Promise<{ result: T; next?: McpSlice }>): Promise<T> {
238
+ this.ensureParentDir()
239
+ this.ensureFileExists()
240
+ let release: (() => Promise<void>) | undefined
241
+ let lockCompromised = false
242
+ let lockCompromisedError: Error | undefined
243
+ const throwIfCompromised = (): void => {
244
+ if (lockCompromised) {
245
+ throw lockCompromisedError ?? new Error('Secrets store lock was compromised')
246
+ }
247
+ }
248
+ try {
249
+ release = await lockfile.lock(this.secretsPath, {
250
+ ...ASYNC_LOCK_OPTIONS,
251
+ onCompromised: (err: Error) => {
252
+ lockCompromised = true
253
+ lockCompromisedError = err
254
+ },
255
+ })
256
+ throwIfCompromised()
257
+ const envelope = this.readEnvelope()
258
+ const { result, next } = await fn(envelope.mcp)
259
+ throwIfCompromised()
260
+ if (next !== undefined) {
261
+ const merged: SecretsFile = {
262
+ ...envelope,
263
+ $schema: envelope.$schema ?? SCHEMA_REL,
264
+ version: SECRETS_FILE_VERSION,
265
+ mcp: next,
266
+ }
267
+ this.writeEnvelopeAtomic(merged)
268
+ }
269
+ throwIfCompromised()
270
+ return result
271
+ } finally {
272
+ if (release) {
273
+ try {
274
+ await release()
275
+ } catch {}
276
+ }
277
+ }
278
+ }
279
+
280
+ removeMcpCredentialSync(serverName: string): boolean {
281
+ if (!existsSync(this.secretsPath)) return false
282
+ let release: (() => void) | undefined
283
+ try {
284
+ release = this.acquireSyncLockWithRetry()
285
+ const envelope = this.readEnvelope()
286
+ if (!(serverName in envelope.mcp)) return false
287
+ const { [serverName]: _removed, ...rest } = envelope.mcp
288
+ const next: SecretsFile = {
289
+ ...envelope,
290
+ $schema: envelope.$schema ?? SCHEMA_REL,
291
+ version: SECRETS_FILE_VERSION,
292
+ mcp: rest,
293
+ }
294
+ this.writeEnvelopeAtomic(next)
295
+ return true
296
+ } finally {
297
+ release?.()
298
+ }
299
+ }
300
+
194
301
  // Atomic provider credential write. Idempotent at the type level: callers
195
302
  // pass the full `ProviderCredential` (api_key or oauth), and the entry is
196
303
  // merged into `providers.<id>` verbatim — same shape the schema accepts on
@@ -407,7 +514,7 @@ export function createSecretsStoreForAgent(secretsPath: string): AuthStorage {
407
514
  }
408
515
 
409
516
  function newEmptyEnvelope(): SecretsFile {
410
- return { $schema: SCHEMA_REL, version: SECRETS_FILE_VERSION, providers: {}, channels: {} }
517
+ return { $schema: SCHEMA_REL, version: SECRETS_FILE_VERSION, providers: {}, channels: {}, mcp: {} }
411
518
  }
412
519
 
413
520
  function stringifyEnvelope(envelope: SecretsFile): string {
@@ -132,11 +132,11 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
132
132
  - **Filter to _decision_ states, not the latest review row.** GitHub's sticky block is cleared only by a later `APPROVED` (or a dismissal) from the same reviewer — a later `COMMENTED` review does **not** clear it. So a history of `CHANGES_REQUESTED` → `COMMENTED` is _still blocked_, even though the latest row is `COMMENTED`. Selecting `last` over the raw review list would misread that as "not a re-review". Filtering to `{CHANGES_REQUESTED, APPROVED}` first, then taking `last`, asks the right question: "what is my latest _blocking decision_, ignoring non-deciding comments?" (Dismissed reviews surface as `state: "DISMISSED"`, so they're correctly excluded from the decision set too.)
133
133
  - **`--paginate --slurp` is mandatory.** GitHub returns reviews 30 per page; a bot on a long-lived PR can have its blocking `CHANGES_REQUESTED` past the first page. Without paginating, that review is invisible and a genuine re-review silently falls back to the plain-comment path. `--slurp` collects every page into one array of arrays; the `add` concatenates them before filtering.
134
134
 
135
- 2. **Spawn the `reviewer` subagent with the PR target.** Use `run_in_background: true` so you stay responsive while the deep model works. Pass the PR URL (or `owner/repo#N`) plus any context the requester gave you (focus areas, specific files, etc.). The reviewer fetches the diff itself (`gh pr diff`, `gh api /repos/.../pulls/<n>`), loads the `code-review` skill, and returns a `<review>` block whose code findings carry `location="path:line"`.
135
+ 2. **Spawn the `reviewer` subagent with the PR target.** The reviewer runs on the deep profile, so it always runs in the background — you stay responsive while it works. Pass the PR URL (or `owner/repo#N`) plus any context the requester gave you (focus areas, specific files, etc.). The reviewer fetches the diff itself (`gh pr diff`, `gh api /repos/.../pulls/<n>`), loads the `code-review` skill, and returns a `<review>` block whose code findings carry `location="path:line"`.
136
136
 
137
137
  **If step 1 found an unresolved blocking obligation — a formal `CHANGES_REQUESTED` _or_ an unretracted flat-comment blocker — say so in the spawn payload** — e.g. _"This is a re-review: you previously blocked this PR (the prior blockers were …; the block was a formal `CHANGES_REQUESTED` / a flat PR comment). Verify they are resolved and return `approve` or `request-changes` — a re-review must re-decide the blocking state, not return `comment`."_ The reviewer's `code-review` skill enforces the same rule, but telling it the prior blockers (and which form they took) is what lets it apply that rule; a fresh reviewer session has no memory of your earlier block. The flat-comment case especially must be passed through — the reviewer cannot recover it from review state, so omitting it would silently drop the re-review context the moment the flow starts.
138
138
 
139
- Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer with `run_in_background: true`; the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
139
+ Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer (it runs in the background); the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
140
140
 
141
141
  After spawning, **end your turn** — the background reviewer wakes you with a completion `<system-reminder>` (step 3). "Stay responsive" means you remain free to handle _other_ chats meanwhile; it does **not** license you to keep working _this_ PR. Do not poll `subagent_output` in a busy-wait, and do not fill the wait by reviewing the diff yourself (see the exclusivity rule at the top of this flow). The next thing you do on this PR is read the reviewer's `<review>` block when the reminder arrives.
142
142
 
@@ -28,7 +28,7 @@ Two failure patterns show up over and over when an agent debugs inline, and both
28
28
 
29
29
  ## The hand-off: spawn operator in background
30
30
 
31
- Spawn `operator` with `run_in_background: true` so your session stays free, then keep talking to the user. Give operator everything it needs — it does **not** see this conversation, and it does **not** see this skill. Operator runs on a fixed tool set (`read`, `grep`, `find`, `ls`, `bash`, `write`, `edit`) with no skill loading, so any mechanic below that you want it to follow has to be spelled out in the `[REQUEST]` block — don't assume it knows the tmux/PID/polling patterns:
31
+ Spawn `operator` (background by default) so your session stays free, then keep talking to the user. Give operator everything it needs — it does **not** see this conversation, and it does **not** see this skill. Operator runs on a fixed tool set (`read`, `grep`, `find`, `ls`, `bash`, `write`, `edit`) with no skill loading, so any mechanic below that you want it to follow has to be spelled out in the `[REQUEST]` block — don't assume it knows the tmux/PID/polling patterns:
32
32
 
33
33
  ```
34
34
  [CONTEXT]: <what you were doing, the file/process/command involved, the environment>