typeclaw 0.45.1 → 0.46.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 (142) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -1
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +44 -30
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/multimodal/index.ts +1 -1
  7. package/src/agent/multimodal/look-at.ts +78 -44
  8. package/src/agent/multimodal/looker.ts +151 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +198 -0
  11. package/src/agent/plugin-tools.ts +379 -157
  12. package/src/agent/provider-error.ts +52 -1
  13. package/src/agent/restart/index.ts +61 -40
  14. package/src/agent/restart-handoff/index.ts +73 -4
  15. package/src/agent/reviewer-bash-policy.ts +42 -1
  16. package/src/agent/session-origin.ts +2 -0
  17. package/src/agent/subagent-drain.ts +117 -7
  18. package/src/agent/subagents.ts +49 -16
  19. package/src/agent/throttle-circuit.ts +25 -5
  20. package/src/agent/tool-error-remediation.ts +72 -0
  21. package/src/agent/tool-file-safety.ts +1050 -0
  22. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  23. package/src/agent/tools/ddg.ts +16 -2
  24. package/src/agent/tools/post-github-review.ts +199 -0
  25. package/src/agent/tools/spawn-subagent.ts +21 -18
  26. package/src/agent/tools/webfetch/fetch.ts +143 -183
  27. package/src/agent/tools/webfetch/tool.ts +2 -3
  28. package/src/agent/tools/websearch.ts +23 -2
  29. package/src/agent/tools-without-local-file-operands.ts +27 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/index.ts +2 -1
  32. package/src/bundled-plugins/backup/runner.ts +2 -1
  33. package/src/bundled-plugins/doc-render/render.ts +93 -12
  34. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  35. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  36. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  37. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  38. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  39. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  40. package/src/bundled-plugins/memory/README.md +23 -11
  41. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  42. package/src/bundled-plugins/memory/citations.ts +22 -9
  43. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  44. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  45. package/src/bundled-plugins/memory/index.ts +0 -4
  46. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  47. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  48. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  49. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  50. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  51. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  52. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  53. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  54. package/src/bundled-plugins/reviewer/index.ts +2 -2
  55. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  56. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  57. package/src/bundled-plugins/scout/scout.ts +8 -0
  58. package/src/bundled-plugins/security/index.ts +4 -4
  59. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  60. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  61. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  62. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  63. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  64. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  65. package/src/channels/adapters/discord-bot.ts +66 -6
  66. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  67. package/src/channels/adapters/discord-id.ts +4 -0
  68. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  69. package/src/channels/adapters/discord.ts +57 -7
  70. package/src/channels/adapters/github/auth-app.ts +41 -12
  71. package/src/channels/adapters/github/index.ts +23 -11
  72. package/src/channels/adapters/github/review-submitter.ts +302 -0
  73. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  74. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  75. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  76. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  77. package/src/channels/adapters/slack-bot.ts +19 -8
  78. package/src/channels/adapters/slack-classify.ts +21 -2
  79. package/src/channels/adapters/slack.ts +59 -7
  80. package/src/channels/adapters/telegram-bot.ts +18 -5
  81. package/src/channels/adapters/webex-bot.ts +8 -3
  82. package/src/channels/adapters/webex.ts +8 -3
  83. package/src/channels/fetch-attachment.ts +43 -0
  84. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  85. package/src/channels/github-token-bridge.ts +10 -3
  86. package/src/channels/manager.ts +9 -0
  87. package/src/channels/router.ts +248 -6
  88. package/src/channels/types.ts +28 -1
  89. package/src/cli/channel.ts +1 -1
  90. package/src/cli/init.ts +1 -1
  91. package/src/cli/model.ts +57 -7
  92. package/src/compose/stop.ts +17 -5
  93. package/src/config/config.ts +6 -6
  94. package/src/config/models-mutation.ts +13 -1
  95. package/src/config/providers.ts +176 -0
  96. package/src/container/start.ts +49 -10
  97. package/src/doctor/checks.ts +3 -1
  98. package/src/doctor/commit.ts +2 -1
  99. package/src/doctor/file-ownership.ts +52 -0
  100. package/src/dreams/git.ts +2 -1
  101. package/src/git/hookless.ts +5 -0
  102. package/src/git/reconcile-ignored.ts +18 -5
  103. package/src/git/secret-history.ts +371 -0
  104. package/src/git/system-commit.ts +12 -6
  105. package/src/init/dockerfile.ts +86 -5
  106. package/src/init/index.ts +17 -5
  107. package/src/init/models-dev.ts +4 -0
  108. package/src/init/validate-api-key.ts +2 -0
  109. package/src/mcp/tools.ts +16 -3
  110. package/src/permissions/builtins.ts +3 -1
  111. package/src/plugin/context.ts +2 -0
  112. package/src/plugin/index.ts +1 -0
  113. package/src/plugin/manager.ts +4 -0
  114. package/src/plugin/types.ts +21 -0
  115. package/src/run/index.ts +40 -0
  116. package/src/run/llm-fetch-observer.ts +41 -4
  117. package/src/sandbox/build.ts +37 -15
  118. package/src/sandbox/canonical-secrets.ts +18 -0
  119. package/src/sandbox/env-exposure.ts +80 -0
  120. package/src/sandbox/errors.ts +13 -6
  121. package/src/sandbox/hidden-paths.ts +102 -44
  122. package/src/sandbox/index.ts +22 -4
  123. package/src/sandbox/package-install.ts +3 -27
  124. package/src/sandbox/policy.ts +11 -25
  125. package/src/sandbox/privileged-runtime.ts +255 -0
  126. package/src/sandbox/session-tmp.ts +8 -2
  127. package/src/sandbox/writable-zones.ts +204 -140
  128. package/src/secrets/index.ts +8 -0
  129. package/src/secrets/refresh-provider-oauth.ts +128 -0
  130. package/src/server/command-runner.ts +48 -4
  131. package/src/server/index.ts +4 -0
  132. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  133. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  134. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  135. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  136. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  137. package/src/skills/typeclaw-config/SKILL.md +5 -5
  138. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  139. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  140. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  141. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  142. package/typeclaw.schema.json +20 -0
package/README.md CHANGED
@@ -33,7 +33,7 @@
33
33
  ## Web & research — reads the web like a person
34
34
 
35
35
  - 🔍 **Live web search & fetch** — pull a page as a readable article, a JSON query, a selected slice, a grep, or raw
36
- - 🪪 **Browser-like fetching** — replays a Chrome-like TLS/HTTP fingerprint to get past many generic-client blocks; CAPTCHA and IP-reputation gates can still fail
36
+ - 🛡️ **Rebinding-safe page fetching** — validates every A/AAAA answer on the socket lookup and every redirect hop; private and mixed-address targets fail closed
37
37
  - 🌐 **Interactive browser sessions** — drives a browser on live pages, with a dashboard you can step into for logins, 2FA, or CAPTCHA
38
38
 
39
39
  ## Security — defense-in-depth for risky actions
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.45.1",
3
+ "version": "0.46.0",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -58,6 +58,7 @@
58
58
  "jsdom": "^29.0.2",
59
59
  "proper-lockfile": "^4.1.2",
60
60
  "qrcode": "^1.5.4",
61
+ "tough-cookie": "^6.0.2",
61
62
  "turndown": "^7.2.4",
62
63
  "zod": "^4.3.6"
63
64
  },
@@ -1,3 +1,4 @@
1
+ import { hooklessGitArgs } from '@/git/hookless'
1
2
  import { resolveAgentGit } from '@/git/resolve-agent-git'
2
3
 
3
4
  const MAX_LISTED_PATHS = 10
@@ -71,7 +72,7 @@ const defaultDeps: GitNudgeDeps = {
71
72
  if (!bun) return null
72
73
  try {
73
74
  const proc = bun.spawn({
74
- cmd: ['git', ...gitArgs, 'status', '--porcelain=v1'],
75
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, 'status', '--porcelain=v1'])],
75
76
  cwd: agentDir,
76
77
  stdout: 'pipe',
77
78
  stderr: 'pipe',
@@ -24,7 +24,7 @@ import { defaultThinkingLevelForRef, isOpenAiFamilyRef, providerForModelRef, typ
24
24
  import { renderMcpCatalog } from '@/mcp/catalog'
25
25
  import type { McpManager } from '@/mcp/manager'
26
26
  import { createMcpDispatcherTools, MCP_DISPATCHER_TOOL_NAMES } from '@/mcp/tools'
27
- import type { PermissionService, RolesConfig } from '@/permissions'
27
+ import { noopPermissionService, type PermissionService, type RolesConfig } from '@/permissions'
28
28
  import type {
29
29
  BuiltinToolRef,
30
30
  HookBus,
@@ -44,7 +44,7 @@ import { renderGitNudge } from './git-nudge'
44
44
  import type { LiveSubagentRegistry } from './live-subagents'
45
45
  import { sanitizeMessagesForLlmReplay } from './llm-replay-sanitizer'
46
46
  import { applyModelRuntimeOverrides } from './model-overrides'
47
- import { createChannelLookAtTool, lookAtTool } from './multimodal'
47
+ import { createChannelLookAtTool, createLookAtTool } from './multimodal'
48
48
  import {
49
49
  buildBuiltinPiToolOverrides,
50
50
  isPiCodingBuiltinName,
@@ -80,6 +80,7 @@ import { createChannelReadTool } from './tools/channel-read'
80
80
  import { createChannelReplyTool } from './tools/channel-reply'
81
81
  import { createChannelSendTool } from './tools/channel-send'
82
82
  import { createGrantRoleTool } from './tools/grant-role'
83
+ import { createPostGithubReviewTool } from './tools/post-github-review'
83
84
  import { createRestartTool } from './tools/restart'
84
85
  import { createSkipResponseTool } from './tools/skip-response'
85
86
  import { createSpawnSubagentTool, renderPublicSubagentRoster } from './tools/spawn-subagent'
@@ -323,8 +324,15 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
323
324
  const subagentBuiltinNames = resolvedSubagentBuiltins.map((t) => t.name)
324
325
  const subagentTypeclawToolDefinitions = resolvedSubagentBuiltins.filter((t) => !isPiCodingBuiltinName(t.name))
325
326
  const pluginCustomTools = options.pluginSubagent
326
- ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin, getAbort, getLoopGuardTurn)
327
- : wrapRegistryTools(options.plugins, getOrigin, getAbort, getLoopGuardTurn)
327
+ ? wrapSubagentCustomTools(
328
+ options.pluginSubagent,
329
+ options.plugins,
330
+ getOrigin,
331
+ getAbort,
332
+ getLoopGuardTurn,
333
+ options.permissions,
334
+ )
335
+ : wrapRegistryTools(options.plugins, getOrigin, getAbort, getLoopGuardTurn, options.permissions)
328
336
 
329
337
  // Per-run budget state for the tool-result byte ceiling. Allocated once per
330
338
  // session creation and threaded into every wrapped tool so they share the
@@ -398,7 +406,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
398
406
  : [
399
407
  webSearchTool,
400
408
  webFetchTool,
401
- lookAtTool,
409
+ createLookAtTool(options.permissions),
402
410
  ...(options.mcpManager ? buildMcpDispatcherToolDefinitions(options.mcpManager) : []),
403
411
  ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
404
412
  ...(options.stream ? [createStreamSnapshotTool({ stream: options.stream })] : []),
@@ -445,7 +453,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
445
453
  // unwrapped copies are never the active implementation. Built unconditionally
446
454
  // — the sandbox and bash policy are security behavior independent of whether
447
455
  // any plugin registered a tool hook, so gating on hooks would leave an
448
- // unsandboxed bash path. `wrapBuiltinToolDefinition` no-ops the optional
456
+ // unwrapped bash path. `wrapBuiltinToolDefinition` no-ops the optional
449
457
  // stages (plugin hooks, permissions, bashPolicy) when they are absent.
450
458
  const builtinPiToolOverrides = buildBuiltinPiToolOverrides({
451
459
  agentDir: options.plugins?.agentDir ?? process.cwd(),
@@ -454,16 +462,17 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
454
462
  getOrigin,
455
463
  getAbort,
456
464
  getLoopGuardTurn,
457
- ...(options.permissions ? { permissions: options.permissions } : {}),
465
+ permissions: options.permissions ?? noopPermissionService,
458
466
  ...(options.bashPolicy !== undefined ? { bashPolicy: options.bashPolicy } : {}),
459
467
  })
460
- const wrappedCustomSystemTools = wrapSystemTools(
461
- customSystemTools,
462
- options.plugins,
468
+ const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, {
469
+ agentDir: options.plugins?.agentDir ?? process.cwd(),
470
+ sessionId: options.plugins?.sessionId ?? sessionManager.getSessionId(),
471
+ hooks: options.plugins?.hooks ?? createHookBus(),
463
472
  getOrigin,
464
473
  getAbort,
465
474
  getLoopGuardTurn,
466
- )
475
+ })
467
476
  const customToolsPreBudget = [...wrappedCustomSystemTools, ...pluginCustomTools, ...builtinPiToolOverrides]
468
477
  const customTools =
469
478
  sessionBudget && sessionBudgetState
@@ -726,6 +735,8 @@ export function buildChannelTools(
726
735
  ...(sessionId !== undefined ? { sessionId } : {}),
727
736
  }),
728
737
  )
738
+ if (origin.adapter === 'github' && sessionId !== undefined)
739
+ tools.push(createPostGithubReviewTool({ router: channelRouter, origin: channelOrigin, sessionId }))
729
740
  tools.push(createChannelHistoryTool({ router: channelRouter, origin: channelOrigin }))
730
741
  tools.push(createChannelReadTool({ router: channelRouter }))
731
742
  tools.push(
@@ -754,12 +765,13 @@ export function buildChannelTools(
754
765
  createChannelFetchAttachmentTool({
755
766
  router: channelRouter,
756
767
  origin: channelOrigin,
768
+ ...(agentDir !== undefined ? { agentDir } : {}),
757
769
  ...(permissions !== undefined && agentDir !== undefined
758
770
  ? { resolveBaseDir: () => resolveInboxBaseDir(permissions, getOrigin?.() ?? origin, agentDir) }
759
771
  : {}),
760
772
  }),
761
773
  )
762
- tools.push(createChannelLookAtTool(channelRouter, channelOrigin))
774
+ tools.push(createChannelLookAtTool(channelRouter, channelOrigin, permissions))
763
775
  tools.push(createChannelDisengageTool({ router: channelRouter, origin: channelOrigin }))
764
776
  if (sessionId !== undefined) {
765
777
  tools.push(createSkipResponseTool({ router: channelRouter, sessionId }))
@@ -886,6 +898,7 @@ function wrapRegistryTools(
886
898
  getOrigin: () => SessionOrigin | undefined,
887
899
  getAbort: () => ((reason?: string) => void) | undefined,
888
900
  getLoopGuardTurn: () => number | undefined,
901
+ permissions: PermissionService | undefined,
889
902
  ): ToolDefinition[] {
890
903
  if (!plugins) return []
891
904
  return plugins.registry.tools.map((t: PluginRegisteredTool) =>
@@ -899,41 +912,41 @@ function wrapRegistryTools(
899
912
  getOrigin,
900
913
  getAbort,
901
914
  getLoopGuardTurn,
915
+ ...(permissions !== undefined ? { permissions } : {}),
902
916
  }),
903
917
  )
904
918
  }
905
919
 
906
- function wrapSystemTools(
920
+ export function wrapSystemTools(
907
921
  tools: ToolDefinition[],
908
- plugins: PluginSessionWiring | undefined,
909
- getOrigin: () => SessionOrigin | undefined,
910
- getAbort: () => ((reason?: string) => void) | undefined,
911
- getLoopGuardTurn: () => number | undefined,
922
+ options: {
923
+ agentDir: string
924
+ sessionId: string
925
+ hooks: HookBus
926
+ getOrigin: () => SessionOrigin | undefined
927
+ getAbort: () => ((reason?: string) => void) | undefined
928
+ getLoopGuardTurn?: () => number | undefined
929
+ },
912
930
  ): ToolDefinition[] {
913
- if (!hasToolHooks(plugins)) return tools
914
931
  return tools.map((tool) =>
915
932
  wrapSystemTool(tool, {
916
- agentDir: plugins.agentDir,
917
- sessionId: plugins.sessionId,
918
- hooks: plugins.hooks,
919
- getOrigin,
920
- getAbort,
921
- getLoopGuardTurn,
933
+ agentDir: options.agentDir,
934
+ sessionId: options.sessionId,
935
+ hooks: options.hooks,
936
+ getOrigin: options.getOrigin,
937
+ getAbort: options.getAbort,
938
+ getLoopGuardTurn: options.getLoopGuardTurn,
922
939
  }),
923
940
  )
924
941
  }
925
942
 
926
- function hasToolHooks(plugins: PluginSessionWiring | undefined): plugins is PluginSessionWiring {
927
- if (!plugins) return false
928
- return plugins.hooks.count('tool.before') > 0 || plugins.hooks.count('tool.after') > 0
929
- }
930
-
931
- function wrapSubagentCustomTools(
943
+ export function wrapSubagentCustomTools(
932
944
  selection: PluginSubagentSelection,
933
945
  plugins: PluginSessionWiring | undefined,
934
946
  getOrigin: () => SessionOrigin | undefined,
935
947
  getAbort: () => ((reason?: string) => void) | undefined,
936
948
  getLoopGuardTurn: () => number | undefined,
949
+ permissions: PermissionService | undefined,
937
950
  ): ToolDefinition[] {
938
951
  if (!selection.customTools || !plugins) return []
939
952
  const logger = makePluginLogger(selection.pluginName)
@@ -948,6 +961,7 @@ function wrapSubagentCustomTools(
948
961
  getOrigin,
949
962
  getAbort,
950
963
  getLoopGuardTurn,
964
+ ...(permissions !== undefined ? { permissions } : {}),
951
965
  }),
952
966
  )
953
967
  }
@@ -143,6 +143,24 @@ export class LiveSubagentRegistry {
143
143
  entry.status = completion.ok ? 'completed' : 'failed'
144
144
  }
145
145
 
146
+ // First-writer-wins settlement, returning whether THIS caller won. A subagent
147
+ // has two racing settlement producers — its real completion (spawn_subagent's
148
+ // `completion.then`) and the parent drain's timeout ceiling — and both must
149
+ // not overwrite each other's terminal state, or the registry/broadcast would
150
+ // disagree with a reminder already delivered. There is no `await` between the
151
+ // status check and the mutation, so under JS run-to-completion this compare-
152
+ // and-set is atomic: a promise `.then` producer that races in on a later
153
+ // microtask sees `status !== 'running'` and loses. Production settlement paths
154
+ // MUST use this, not the unconditional `recordCompletion` (which stays for
155
+ // tests that seed terminal state directly).
156
+ recordCompletionIfRunning(taskId: string, completion: SubagentCompletion): boolean {
157
+ const entry = this.entries.get(taskId)
158
+ if (entry === undefined || entry.status !== 'running') return false
159
+ entry.completion = completion
160
+ entry.status = completion.ok ? 'completed' : 'failed'
161
+ return true
162
+ }
163
+
146
164
  snapshot(taskId: string, now: number = Date.now()): StatusSnapshot | undefined {
147
165
  const entry = this.entries.get(taskId)
148
166
  if (entry === undefined) return undefined
@@ -1,4 +1,4 @@
1
- export { createChannelLookAtTool, lookAtTool } from './look-at'
1
+ export { createChannelLookAtTool, createLookAtTool, lookAtTool } from './look-at'
2
2
  export {
3
3
  buildMultimodalLookerSystemPrompt,
4
4
  imageInputSchema,
@@ -5,15 +5,23 @@ import type { ImageContent } from '@mariozechner/pi-ai'
5
5
  import { defineTool } from '@mariozechner/pi-coding-agent'
6
6
 
7
7
  import { createSessionWithDispose, type SessionOrigin } from '@/agent'
8
+ import { readResponseBodyBounded } from '@/agent/network/response-body'
8
9
  import type { ChannelRouter } from '@/channels/router'
9
10
  import type { AdapterId } from '@/channels/schema'
10
11
  import { getConfig, resolveModel, resolveProfile } from '@/config'
11
12
  import { providerForModelRef } from '@/config/providers'
13
+ import type { PermissionService } from '@/permissions'
12
14
  import { LLM_FETCH_OBSERVER_TIMEOUTS, type LlmFetchObservedRequestInit } from '@/run/llm-fetch-observer'
13
15
  import { SecretsBackend } from '@/secrets'
14
16
 
15
17
  import { promptWithSameRefRetryOnly } from '../retry-same-ref'
16
- import { buildMultimodalLookerSystemPrompt, resolveImage, type ImageInput } from './looker'
18
+ import {
19
+ buildMultimodalLookerSystemPrompt,
20
+ LOOK_AT_MAX_BYTES,
21
+ LOOK_AT_MAX_IMAGES,
22
+ resolveImagesBounded,
23
+ type ImageInput,
24
+ } from './looker'
17
25
 
18
26
  type ImageParam = { url: string } | { path: string } | { data: string; mimeType: string }
19
27
 
@@ -46,52 +54,62 @@ export type ChannelLookAtOrigin = {
46
54
  // Output is the subagent's text response. The subagent itself decides whether
47
55
  // to answer the user's question (when `prompt` is supplied) or describe the
48
56
  // image (when `prompt` is omitted) via its dynamic system prompt.
49
- export const lookAtTool = defineTool({
50
- name: 'look_at',
51
- label: 'Look at images',
52
- description:
53
- 'Route image(s) through a vision-capable subagent and get a text result. ' +
54
- 'Use this when you need to see an image: a screenshot the user shared, a diagram in a doc, a photo, a chart, etc. ' +
55
- 'Each image is specified by ONE of `url` (https://...), `path` (absolute filesystem path), or `data`+`mimeType` (base64). ' +
56
- 'The optional `prompt` is a question to ask about the image(s); without it, the subagent returns a faithful description. ' +
57
- 'The image bytes never enter your context — only the resulting text comes back.',
58
- parameters: Type.Object({
59
- images: Type.Array(
60
- Type.Object({
61
- url: Type.Optional(Type.String({ description: 'https:// URL to fetch the image from.' })),
62
- path: Type.Optional(Type.String({ description: 'Absolute filesystem path (inside /agent or a mounted dir).' })),
63
- data: Type.Optional(Type.String({ description: 'Base64-encoded image bytes (pair with mimeType).' })),
64
- mimeType: Type.Optional(Type.String({ description: 'MIME type when using `data` (e.g. "image/png").' })),
65
- }),
66
- { minItems: 1, description: 'One or more images to look at.' },
67
- ),
68
- prompt: Type.Optional(
69
- Type.String({
70
- description:
71
- 'Optional question to ask about the image(s). When omitted, the subagent returns a faithful description.',
72
- }),
73
- ),
74
- }),
75
-
76
- async execute(_toolCallId, params, signal) {
77
- const args = params as LookAtArgs
78
- try {
79
- const imageInputs = args.images.map(toImageInput)
80
- const resolved = await Promise.all(imageInputs.map((i) => resolveImage(i, signal)))
81
- const imageContents: ImageContent[] = resolved.map((r) => toImageContent(r.data, r.mimeType))
82
- return await runLookAtImages(imageContents, args.prompt)
83
- } catch (error) {
84
- const message = error instanceof Error ? error.message : String(error)
85
- return errorResult(message, { count: args.images.length, prompt: args.prompt })
86
- }
87
- },
88
- })
57
+ export function createLookAtTool(permissions?: PermissionService) {
58
+ return defineTool({
59
+ name: 'look_at',
60
+ label: 'Look at images',
61
+ description:
62
+ 'Route image(s) through a vision-capable subagent and get a text result. ' +
63
+ 'Use this when you need to see an image: a screenshot the user shared, a diagram in a doc, a photo, a chart, etc. ' +
64
+ 'Each image is specified by ONE of `url` (https://...), `path` (absolute filesystem path), or `data`+`mimeType` (base64). ' +
65
+ 'The optional `prompt` is a question to ask about the image(s); without it, the subagent returns a faithful description. ' +
66
+ 'The image bytes never enter your context — only the resulting text comes back.',
67
+ parameters: Type.Object({
68
+ images: Type.Array(
69
+ Type.Object({
70
+ url: Type.Optional(Type.String({ description: 'https:// URL to fetch the image from.' })),
71
+ path: Type.Optional(
72
+ Type.String({ description: 'Absolute filesystem path (inside /agent or a mounted dir).' }),
73
+ ),
74
+ data: Type.Optional(Type.String({ description: 'Base64-encoded image bytes (pair with mimeType).' })),
75
+ mimeType: Type.Optional(Type.String({ description: 'MIME type when using `data` (e.g. "image/png").' })),
76
+ }),
77
+ { minItems: 1, maxItems: LOOK_AT_MAX_IMAGES, description: 'One or more images to look at.' },
78
+ ),
79
+ prompt: Type.Optional(
80
+ Type.String({
81
+ description:
82
+ 'Optional question to ask about the image(s). When omitted, the subagent returns a faithful description.',
83
+ }),
84
+ ),
85
+ }),
86
+
87
+ async execute(_toolCallId, params, signal) {
88
+ const args = params as LookAtArgs
89
+ try {
90
+ const imageInputs = args.images.map(toImageInput)
91
+ const resolved = await resolveImagesBounded(imageInputs, signal)
92
+ const imageContents: ImageContent[] = resolved.map((r) => toImageContent(r.data, r.mimeType))
93
+ return await runLookAtImages(imageContents, args.prompt, permissions)
94
+ } catch (error) {
95
+ const message = error instanceof Error ? error.message : String(error)
96
+ return errorResult(message, { count: args.images.length, prompt: args.prompt })
97
+ }
98
+ },
99
+ })
100
+ }
101
+
102
+ export const lookAtTool = createLookAtTool()
89
103
 
90
104
  // Channel attachments intentionally use a separate tool instead of adding
91
105
  // channel-only dependencies to the global look_at implementation. This keeps
92
106
  // non-channel sessions' image source validation unchanged while channel
93
107
  // sessions get router-validated attachment_id lookup.
94
- export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLookAtOrigin) {
108
+ export function createChannelLookAtTool(
109
+ router: ChannelRouter,
110
+ origin: ChannelLookAtOrigin,
111
+ permissions?: PermissionService,
112
+ ) {
95
113
  return defineTool({
96
114
  name: 'look_at_channel_attachment',
97
115
  label: 'Look at channel attachment',
@@ -130,12 +148,14 @@ export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLo
130
148
  }
131
149
  const result = await router.fetchAttachment(origin.adapter, {
132
150
  ref: found.ref,
151
+ maxBytes: LOOK_AT_MAX_BYTES,
133
152
  ...(found.filename !== undefined ? { filename: found.filename } : {}),
134
153
  })
135
154
  if (!result.ok) return errorResult(result.error, { count: 0, prompt: params.prompt })
136
155
  return await runLookAtImages(
137
156
  [toImageContent(result.buffer.toString('base64'), result.mimetype ?? 'image/jpeg')],
138
157
  params.prompt,
158
+ permissions,
139
159
  )
140
160
  },
141
161
  })
@@ -145,7 +165,11 @@ function toImageContent(data: string, mimeType: string): ImageContent {
145
165
  return { type: 'image', data, mimeType }
146
166
  }
147
167
 
148
- async function runLookAtImages(imageContents: ImageContent[], prompt: string | undefined) {
168
+ async function runLookAtImages(
169
+ imageContents: ImageContent[],
170
+ prompt: string | undefined,
171
+ permissions?: PermissionService,
172
+ ) {
149
173
  // Exception for text-only GLM Coding Plan models: the subagent below would
150
174
  // resolve to the same image-blind model and silently fail. GLM-4.6V vision is
151
175
  // reachable on the coding-plan endpoint with the same key (POST
@@ -176,6 +200,7 @@ async function runLookAtImages(imageContents: ImageContent[], prompt: string | u
176
200
  const { session, dispose } = await createSessionWithDispose({
177
201
  systemPromptOverride: systemPrompt,
178
202
  origin,
203
+ ...(permissions !== undefined ? { permissions } : {}),
179
204
  profile: 'vision',
180
205
  // Both knobs are required to fully disarm the subagent's tool surface:
181
206
  // `customTools: []` blocks typeclaw's system tools (web_search/web_fetch/
@@ -208,6 +233,7 @@ const GLM_VISION_PROVIDER = 'zai-coding'
208
233
  const GLM_VISION_MODEL = 'glm-4.6v'
209
234
  const GLM_VISION_ENDPOINT = 'https://api.z.ai/api/coding/paas/v4/chat/completions'
210
235
  const GLM_VISION_MAX_TOKENS = 32768
236
+ export const GLM_VISION_MAX_RESPONSE_BYTES = 2 * 1024 * 1024
211
237
 
212
238
  // Vision requests carry a base64 image body the server must decode before it can
213
239
  // send response headers, so the observer's 15s default TTFB (tuned for ~1s text
@@ -254,10 +280,18 @@ async function analyzeWithGlmCodingPlanVision(imageContents: ImageContent[], pro
254
280
  }
255
281
 
256
282
  if (!response.ok) {
283
+ await response.body?.cancel().catch(() => undefined)
257
284
  return errorResult(`GLM vision request failed: HTTP ${response.status}`, details)
258
285
  }
259
286
 
260
- const text = extractGlmVisionText(await response.json().catch(() => null))
287
+ let body: unknown
288
+ try {
289
+ const bytes = await readResponseBodyBounded(response, GLM_VISION_MAX_RESPONSE_BYTES)
290
+ body = JSON.parse(bytes.toString('utf8'))
291
+ } catch (error) {
292
+ return errorResult(`GLM vision response failed: ${error instanceof Error ? error.message : String(error)}`, details)
293
+ }
294
+ const text = extractGlmVisionText(body)
261
295
  if (text === null) {
262
296
  return errorResult('GLM vision returned no text response', details)
263
297
  }