typeclaw 0.45.0 → 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 (147) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +67 -25
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/loop-guard.ts +208 -10
  7. package/src/agent/multimodal/index.ts +1 -1
  8. package/src/agent/multimodal/look-at.ts +78 -44
  9. package/src/agent/multimodal/looker.ts +151 -39
  10. package/src/agent/network/response-body.ts +26 -0
  11. package/src/agent/network/safe-http.ts +198 -0
  12. package/src/agent/plugin-tools.ts +438 -162
  13. package/src/agent/provider-error.ts +62 -4
  14. package/src/agent/restart/index.ts +61 -40
  15. package/src/agent/restart-handoff/index.ts +73 -4
  16. package/src/agent/retry-same-ref.ts +66 -0
  17. package/src/agent/reviewer-bash-policy.ts +42 -1
  18. package/src/agent/session-origin.ts +2 -0
  19. package/src/agent/subagent-drain.ts +117 -7
  20. package/src/agent/subagents.ts +77 -18
  21. package/src/agent/throttle-circuit.ts +25 -5
  22. package/src/agent/tool-error-remediation.ts +72 -0
  23. package/src/agent/tool-file-safety.ts +1050 -0
  24. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  25. package/src/agent/tools/channel-reply.ts +15 -1
  26. package/src/agent/tools/channel-send.ts +17 -1
  27. package/src/agent/tools/ddg.ts +16 -2
  28. package/src/agent/tools/post-github-review.ts +199 -0
  29. package/src/agent/tools/spawn-subagent.ts +21 -18
  30. package/src/agent/tools/webfetch/fetch.ts +143 -183
  31. package/src/agent/tools/webfetch/tool.ts +2 -3
  32. package/src/agent/tools/websearch.ts +23 -2
  33. package/src/agent/tools-without-local-file-operands.ts +27 -0
  34. package/src/agent/turn-runner.ts +109 -15
  35. package/src/bundled-plugins/backup/index.ts +2 -1
  36. package/src/bundled-plugins/backup/runner.ts +2 -1
  37. package/src/bundled-plugins/doc-render/render.ts +93 -12
  38. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  39. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  40. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  41. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  42. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  43. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  44. package/src/bundled-plugins/memory/README.md +23 -11
  45. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  46. package/src/bundled-plugins/memory/citations.ts +22 -9
  47. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  48. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  49. package/src/bundled-plugins/memory/index.ts +0 -4
  50. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  51. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  52. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  53. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  54. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  55. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  56. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  57. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  58. package/src/bundled-plugins/reviewer/index.ts +2 -2
  59. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  60. package/src/bundled-plugins/reviewer/skills/code-review.ts +24 -9
  61. package/src/bundled-plugins/scout/scout.ts +8 -0
  62. package/src/bundled-plugins/security/index.ts +4 -4
  63. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  64. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  65. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  66. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  67. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  68. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  69. package/src/channels/adapters/discord-bot.ts +91 -10
  70. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  71. package/src/channels/adapters/discord-id.ts +4 -0
  72. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  73. package/src/channels/adapters/discord.ts +57 -7
  74. package/src/channels/adapters/github/auth-app.ts +41 -12
  75. package/src/channels/adapters/github/index.ts +23 -11
  76. package/src/channels/adapters/github/review-submitter.ts +302 -0
  77. package/src/channels/adapters/kakaotalk-channel-resolver.ts +12 -1
  78. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  79. package/src/channels/adapters/kakaotalk-typing.ts +127 -0
  80. package/src/channels/adapters/kakaotalk.ts +19 -0
  81. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  82. package/src/channels/adapters/slack-bot.ts +19 -8
  83. package/src/channels/adapters/slack-classify.ts +21 -2
  84. package/src/channels/adapters/slack.ts +59 -7
  85. package/src/channels/adapters/telegram-bot.ts +18 -5
  86. package/src/channels/adapters/webex-bot.ts +8 -3
  87. package/src/channels/adapters/webex.ts +8 -3
  88. package/src/channels/fetch-attachment.ts +43 -0
  89. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  90. package/src/channels/github-token-bridge.ts +10 -3
  91. package/src/channels/manager.ts +9 -0
  92. package/src/channels/router.ts +568 -12
  93. package/src/channels/types.ts +28 -1
  94. package/src/cli/channel.ts +1 -1
  95. package/src/cli/init.ts +1 -1
  96. package/src/cli/model.ts +57 -7
  97. package/src/compose/stop.ts +17 -5
  98. package/src/config/config.ts +6 -6
  99. package/src/config/models-mutation.ts +13 -1
  100. package/src/config/providers.ts +176 -0
  101. package/src/container/start.ts +49 -10
  102. package/src/doctor/checks.ts +3 -1
  103. package/src/doctor/commit.ts +2 -1
  104. package/src/doctor/file-ownership.ts +52 -0
  105. package/src/dreams/git.ts +2 -1
  106. package/src/git/hookless.ts +5 -0
  107. package/src/git/reconcile-ignored.ts +18 -5
  108. package/src/git/secret-history.ts +371 -0
  109. package/src/git/system-commit.ts +12 -6
  110. package/src/init/dockerfile.ts +86 -5
  111. package/src/init/index.ts +17 -5
  112. package/src/init/models-dev.ts +4 -0
  113. package/src/init/validate-api-key.ts +2 -0
  114. package/src/mcp/tools.ts +16 -3
  115. package/src/permissions/builtins.ts +3 -1
  116. package/src/plugin/context.ts +2 -0
  117. package/src/plugin/index.ts +1 -0
  118. package/src/plugin/manager.ts +4 -0
  119. package/src/plugin/types.ts +21 -0
  120. package/src/run/index.ts +40 -0
  121. package/src/run/llm-fetch-observer.ts +188 -13
  122. package/src/sandbox/build.ts +37 -15
  123. package/src/sandbox/canonical-secrets.ts +18 -0
  124. package/src/sandbox/env-exposure.ts +80 -0
  125. package/src/sandbox/errors.ts +13 -6
  126. package/src/sandbox/hidden-paths.ts +102 -44
  127. package/src/sandbox/index.ts +22 -4
  128. package/src/sandbox/package-install.ts +3 -27
  129. package/src/sandbox/policy.ts +11 -25
  130. package/src/sandbox/privileged-runtime.ts +255 -0
  131. package/src/sandbox/session-tmp.ts +8 -2
  132. package/src/sandbox/writable-zones.ts +204 -140
  133. package/src/secrets/index.ts +8 -0
  134. package/src/secrets/refresh-provider-oauth.ts +128 -0
  135. package/src/server/command-runner.ts +48 -4
  136. package/src/server/index.ts +4 -0
  137. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  138. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  139. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  140. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  141. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  142. package/src/skills/typeclaw-config/SKILL.md +5 -5
  143. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  144. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  145. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  146. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  147. package/typeclaw.schema.json +20 -0
@@ -1,8 +1,13 @@
1
- import type { ModelRef } from '@/config/providers'
1
+ import { providerForModelRef, type ModelRef } from '@/config/providers'
2
2
 
3
3
  import type { AgentSession } from './index'
4
- import { detectProviderError, isRetryableSameRef, subscribeProviderErrors } from './provider-error'
5
- import { RETRIES_PER_REF, retryTurnOnPersistentSession } from './retry-same-ref'
4
+ import {
5
+ detectProviderError,
6
+ isObserverTtfbTimeout,
7
+ isRetryableSameRef,
8
+ subscribeProviderErrors,
9
+ } from './provider-error'
10
+ import { RETRIES_PER_REF, retryTurnAfterCompletedToolResult, retryTurnOnPersistentSession } from './retry-same-ref'
6
11
  import { modelThrottleCircuit, type ThrottleCircuit } from './throttle-circuit'
7
12
 
8
13
  export type PersistentTurnAttempt = {
@@ -23,6 +28,12 @@ type AttemptActivity = {
23
28
  startedToolExecution: boolean
24
29
  }
25
30
 
31
+ // SDK-level attempts already contain pi-ai's internal fetch recovery. Bounding
32
+ // only repeated no-header outcomes limits dead air without timing out healthy
33
+ // reasoning or tool execution.
34
+ const MAX_NO_PROGRESS_ATTEMPTS = 3
35
+ const MAX_CUMULATIVE_NO_PROGRESS_MS = 60_000
36
+
26
37
  export async function promptPersistentTurnWithFallback(opts: {
27
38
  refs: ModelRef[]
28
39
  currentModelRef: ModelRef
@@ -34,13 +45,26 @@ export async function promptPersistentTurnWithFallback(opts: {
34
45
  circuit?: ThrottleCircuit
35
46
  skipProviderErrorSubscription?: boolean
36
47
  detectSoftErrorFromLeaf?: boolean
48
+ authorizeRetryAfterCompletedToolResult?: () => boolean
49
+ retryRandom?: () => number
50
+ onRetryBackoffStart?: () => void
37
51
  beforeAttempt?: (ref: ModelRef) => void
38
52
  onAttemptFailed?: (attempt: PersistentTurnAttempt) => void
53
+ now?: () => number
39
54
  }): Promise<PersistentTurnResult> {
40
55
  if (opts.refs.length === 0) throw new Error('promptPersistentTurnWithFallback: refs[] must be non-empty')
41
56
  const attempts: PersistentTurnAttempt[] = []
42
57
  let lastError: Error | undefined
43
58
  const circuit = opts.circuit ?? modelThrottleCircuit
59
+ // Monotonic clock for the no-progress budget: it only ever measures elapsed
60
+ // (now() - attemptStartedAt), and performance.now() can't jump backward on an
61
+ // NTP/system-clock correction the way Date.now() can, which would otherwise
62
+ // prematurely trip or stall the 60s cap.
63
+ const now = opts.now ?? (() => performance.now())
64
+ const hasNonCodexFallback = opts.refs.some((ref) => !isCodexRef(ref))
65
+ let noHeaderAttempts = 0
66
+ let cumulativeNoProgressMs = 0
67
+ let noProgressEnvelopeExhausted = false
44
68
  // The model the session currently has loaded; only call setModel when the
45
69
  // chosen ref differs from it. Tracked locally so successive setModel calls
46
70
  // within a single turn stay coherent.
@@ -52,9 +76,13 @@ export async function promptPersistentTurnWithFallback(opts: {
52
76
  // re-test the primary.
53
77
  for (let i = 0; i < opts.refs.length; i++) {
54
78
  const ref = opts.refs[i]!
55
- const isLast = i === opts.refs.length - 1
56
- // Skip a ref whose circuit is open, but never skip the last one — there is
57
- // nowhere left to fall, so we try it regardless and let the result speak.
79
+ const codexProviderOpen = isCodexRef(ref) && circuit.isProviderOpen({ profile: opts.profile, ref })
80
+ if (codexProviderOpen && hasNonCodexFallback) continue
81
+ const isLast = !opts.refs
82
+ .slice(i + 1)
83
+ .some((candidate) => isRefUsable(candidate, opts.profile, circuit, hasNonCodexFallback))
84
+ // The last usable ref remains a safety probe. Codex refs stop being usable
85
+ // together only when the chain has transport-diverse credentials to use.
58
86
  if (!isLast && circuit.isOpen({ profile: opts.profile, ref })) continue
59
87
  if (ref !== loadedRef) {
60
88
  await opts.setModelForRef(ref)
@@ -78,14 +106,23 @@ export async function promptPersistentTurnWithFallback(opts: {
78
106
  // advancing the chain. `retry === 0` is the first, prompt()-driven attempt;
79
107
  // later iterations resume via agent.continue() (no user-message re-append).
80
108
  let outcome: AttemptOutcome | undefined
109
+ let retryAfterCompletedToolResult = false
81
110
  for (let retry = 0; ; retry++) {
82
111
  softError = undefined
112
+ const attemptStartedAt = now()
83
113
  let outcomeThisAttempt: AttemptOutcome | undefined
84
114
  try {
85
115
  if (retry === 0) {
86
116
  await opts.session.prompt(opts.text)
87
117
  } else {
88
- const retried = await retryTurnOnPersistentSession(opts.session, { attempt: retry - 1 })
118
+ const retried = retryAfterCompletedToolResult
119
+ ? await retryTurnAfterCompletedToolResult(opts.session, {
120
+ attempt: retry - 1,
121
+ authorize: () => opts.authorizeRetryAfterCompletedToolResult?.() === true,
122
+ ...(opts.retryRandom !== undefined ? { random: opts.retryRandom } : {}),
123
+ ...(opts.onRetryBackoffStart !== undefined ? { onBackoffStart: opts.onRetryBackoffStart } : {}),
124
+ })
125
+ : await retryTurnOnPersistentSession(opts.session, { attempt: retry - 1 })
89
126
  // The safe continue-recipe couldn't apply: keep the PREVIOUS failure
90
127
  // outcome (never cleared) and let it drive the advance/return below.
91
128
  if (!retried) break
@@ -96,13 +133,25 @@ export async function promptPersistentTurnWithFallback(opts: {
96
133
  }
97
134
  outcome = outcomeThisAttempt
98
135
  if (outcome === undefined) break
99
- // Only keep retrying while the failure is same-ref retryable, the turn
100
- // stayed idempotent (no output/tool-exec yet), and budget remains.
101
- const mayRetry =
102
- retry < RETRIES_PER_REF &&
103
- isRetryableSameRef(outcome.error.message) &&
104
- !activity.producedAssistantOutput &&
105
- !activity.startedToolExecution
136
+ if (isObserverTtfbTimeout(outcome.error.message)) {
137
+ noHeaderAttempts++
138
+ cumulativeNoProgressMs += Math.max(0, now() - attemptStartedAt)
139
+ noProgressEnvelopeExhausted =
140
+ noHeaderAttempts >= MAX_NO_PROGRESS_ATTEMPTS || cumulativeNoProgressMs >= MAX_CUMULATIVE_NO_PROGRESS_MS
141
+ }
142
+ // A fallback reached before the cap may still recover; once the cap is
143
+ // reached, no same-ref replay or later ref may start.
144
+ if (noProgressEnvelopeExhausted) break
145
+ // Retry within budget only when the failure is same-ref retryable and
146
+ // either no visible/tool activity occurred, or the caller explicitly
147
+ // authorizes the strict post-tool-result resume recipe.
148
+ const retryableWithinBudget = retry < RETRIES_PER_REF && isRetryableSameRef(outcome.error.message)
149
+ const mayRetryWithoutActivity = !activity.producedAssistantOutput && !activity.startedToolExecution
150
+ retryAfterCompletedToolResult =
151
+ retryableWithinBudget &&
152
+ activity.startedToolExecution &&
153
+ opts.authorizeRetryAfterCompletedToolResult?.() === true
154
+ const mayRetry = retryableWithinBudget && (mayRetryWithoutActivity || retryAfterCompletedToolResult)
106
155
  if (!mayRetry) break
107
156
  }
108
157
 
@@ -119,7 +168,32 @@ export async function promptPersistentTurnWithFallback(opts: {
119
168
  attempts.push(attempt)
120
169
  lastError = outcome.error
121
170
  if (opts.shouldFailover(outcome.error)) circuit.recordThrottle({ profile: opts.profile, ref })
122
- if (isLast || !canAdvance(outcome.error, activity, opts.shouldFailover)) {
171
+ if (isCodexRef(ref) && isObserverTtfbTimeout(outcome.error.message)) {
172
+ circuit.recordProviderTrip({ profile: opts.profile, ref })
173
+ }
174
+ // A codex-only chain surfaces after one attempt once its breaker is open
175
+ // (no transport-diverse ref to fall to). isRefUsable can't express this —
176
+ // with no non-codex fallback every codex ref reads as "usable" — so it stays
177
+ // an explicit condition.
178
+ const codexOnlyProviderOpen =
179
+ !hasNonCodexFallback && isCodexRef(ref) && circuit.isProviderOpen({ profile: opts.profile, ref })
180
+ // `isLast` was computed BEFORE this attempt, but recordProviderTrip above
181
+ // may have just opened the codex breaker and made every trailing candidate
182
+ // unusable (all remaining refs are codex the loop would now skip). Re-derive
183
+ // "is there a ref left worth advancing to" from the post-trip circuit state,
184
+ // so we finish on the CURRENT outcome (throw hard / return soft) instead of
185
+ // falling through the loop and returning success:false for a ref that was
186
+ // skipped and never attempted.
187
+ const noUsableCandidateRemains = !opts.refs
188
+ .slice(i + 1)
189
+ .some((next) => isRefUsable(next, opts.profile, circuit, hasNonCodexFallback))
190
+ if (
191
+ noProgressEnvelopeExhausted ||
192
+ isLast ||
193
+ codexOnlyProviderOpen ||
194
+ noUsableCandidateRemains ||
195
+ !canAdvance(outcome.error, activity, opts.shouldFailover)
196
+ ) {
123
197
  if (outcome.kind === 'hard') throw outcome.error
124
198
  return { success: false, refUsed: ref, attempts, lastError }
125
199
  }
@@ -152,6 +226,26 @@ function canAdvance(error: Error, activity: AttemptActivity, shouldFailover: (er
152
226
  return shouldFailover(error) && !activity.producedAssistantOutput && !activity.startedToolExecution
153
227
  }
154
228
 
229
+ function isCodexRef(ref: ModelRef): boolean {
230
+ return providerForModelRef(ref) === 'openai-codex'
231
+ }
232
+
233
+ // A ref is still worth advancing to iff the loop wouldn't skip it at the top: a
234
+ // codex ref is dropped only once the codex provider breaker is open AND the chain
235
+ // has a transport-diverse (non-codex) fallback to use instead. Shared by the
236
+ // `isLast` safety-probe check and the post-trip terminal decision so both read
237
+ // the SAME circuit state and can't diverge.
238
+ function isRefUsable(
239
+ ref: ModelRef,
240
+ profile: string | undefined,
241
+ circuit: ThrottleCircuit,
242
+ hasNonCodexFallback: boolean,
243
+ ): boolean {
244
+ if (!isCodexRef(ref)) return true
245
+ if (!hasNonCodexFallback) return true
246
+ return !circuit.isProviderOpen({ profile, ref })
247
+ }
248
+
155
249
  function subscribeAttemptActivity(session: AgentSession, activity: AttemptActivity): () => void {
156
250
  const subscribe = (session as { subscribe?: unknown }).subscribe
157
251
  if (typeof subscribe !== 'function') return () => {}
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod'
2
2
 
3
+ import { hooklessGitArgs } from '@/git/hookless'
3
4
  import { withGitLock } from '@/git/mutex'
4
5
  import { resolveAgentGit } from '@/git/resolve-agent-git'
5
6
  import { definePlugin, type PluginContext, type SpawnSubagentOptions, type Subagent } from '@/plugin'
@@ -265,7 +266,7 @@ export async function resolveOriginPushUrl(cwd: string): Promise<string | null>
265
266
  if (!repo) return null
266
267
  try {
267
268
  const proc = bun.spawn({
268
- cmd: ['git', '-C', cwd, ...repo.gitArgs, 'remote', 'get-url', '--push', 'origin'],
269
+ cmd: ['git', ...hooklessGitArgs(['-C', cwd, ...repo.gitArgs, 'remote', 'get-url', '--push', 'origin'])],
269
270
  stdout: 'pipe',
270
271
  stderr: 'ignore',
271
272
  env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' },
@@ -1,6 +1,7 @@
1
1
  import { existsSync } from 'node:fs'
2
2
  import { join } from 'node:path'
3
3
 
4
+ import { hooklessGitArgs } from '@/git/hookless'
4
5
  import { type AgentGit, resolveAgentGit } from '@/git/resolve-agent-git'
5
6
 
6
7
  export const COMMIT_TIMEOUT_MS = 30_000
@@ -328,7 +329,7 @@ export function makeDefaultGitSpawn(): GitSpawn {
328
329
  // GIT_TERMINAL_PROMPT wins; NONINTERACTIVE_ENV's pager/GCM settings still
329
330
  // apply to every call. Local commands pass no `env` and stay token-free.
330
331
  const proc = bun.spawn({
331
- cmd: ['git', ...args],
332
+ cmd: ['git', ...hooklessGitArgs(args)],
332
333
  cwd,
333
334
  stdout: 'pipe',
334
335
  stderr: 'pipe',
@@ -1,8 +1,11 @@
1
1
  #!/usr/bin/env bun
2
+ import { readFile, realpath } from 'node:fs/promises'
3
+ import { isAbsolute, join, relative, sep } from 'node:path'
4
+
2
5
  // Bundled `bun run`-able render script for the doc-render plugin: the agent runs
3
6
  // `bun run <this> <main.typ> <out.pdf>`. Lives as a script (not a registered
4
7
  // tool) so it costs zero always-on system-prompt context, and the agent
5
- // dynamic-imports the Typst compiler from its own /agent/node_modules — installed
8
+ // dynamic-imports the Typst compiler from writable per-session scratch — installed
6
9
  // on first use, never baked into the image. Its on-disk path is published to a
7
10
  // /tmp hint at boot (see index.ts) so the skill can resolve it.
8
11
  //
@@ -16,6 +19,7 @@
16
19
  // 0.7.0 embeds Typst 0.14.2; bumping is a deliberate, re-validated edit.
17
20
  export const COMPILER_PACKAGE = '@myriaddreamin/typst-ts-node-compiler'
18
21
  export const COMPILER_VERSION = '0.7.0'
22
+ export const COMPILER_RUNTIME_DIR = '/tmp/typeclaw-doc-render-runtime'
19
23
 
20
24
  // NodeCompiler does not auto-discover system font dirs the way the Typst CLI
21
25
  // does; without these, CJK glyphs render as .notdef tofu. Filtered by existence
@@ -26,9 +30,10 @@ export function missingCompilerGuidance(): string {
26
30
  return [
27
31
  `doc-render: ${COMPILER_PACKAGE} is not installed.`,
28
32
  '',
29
- 'One-time PDF toolchain install. Run from the agent root (writes node_modules',
30
- '+ package.json + bun.lock, which survive restarts), then re-run this render:',
33
+ 'Install the PDF toolchain in this session’s writable scratch runtime, then',
34
+ 're-run the render from the document directory:',
31
35
  '',
36
+ ` mkdir -p ${COMPILER_RUNTIME_DIR} && cd ${COMPILER_RUNTIME_DIR}`,
32
37
  ` bun add ${COMPILER_PACKAGE}@${COMPILER_VERSION}`,
33
38
  '',
34
39
  'Do NOT fall back to jsPDF, pdfkit, a canvas text dump, a headless-browser',
@@ -67,15 +72,91 @@ type NodeCompilerModule = {
67
72
  }
68
73
  }
69
74
 
70
- // Resolve from the CALLER's cwd, not this script's location: the agent installs
71
- // the compiler into its own /agent/node_modules and runs `bun run <this>` from
72
- // the agent root, but bare `import(pkg)` resolves relative to this file (under
73
- // node_modules/typeclaw/...), which need not see the agent's deps. Resolving
74
- // against cwd, then importing the absolute path, makes the lookup independent of
75
- // where the bundled script physically lives.
76
- export async function loadCompilerModule(cwd: string = process.cwd()): Promise<NodeCompilerModule> {
77
- const resolved = Bun.resolveSync(COMPILER_PACKAGE, cwd)
78
- return (await import(resolved)) as NodeCompilerModule
75
+ async function isMuslLinux(): Promise<boolean> {
76
+ try {
77
+ if ((await readFile('/usr/bin/ldd', 'utf8')).includes('musl')) return true
78
+ } catch {
79
+ // Continue with the same process-report fallback used by the package loader.
80
+ }
81
+ const report = process.report?.getReport() as
82
+ | { header?: { glibcVersionRuntime?: string }; sharedObjects?: string[] }
83
+ | undefined
84
+ if (report?.header?.glibcVersionRuntime) return false
85
+ return report?.sharedObjects?.some((file) => file.includes('libc.musl-') || file.includes('ld-musl-')) ?? false
86
+ }
87
+
88
+ export async function requiredCompilerPlatformPackage(): Promise<string> {
89
+ const prefix = `${COMPILER_PACKAGE}-`
90
+ if (process.platform === 'darwin' && (process.arch === 'x64' || process.arch === 'arm64')) {
91
+ return `${prefix}darwin-${process.arch}`
92
+ }
93
+ if (process.platform === 'win32' && (process.arch === 'x64' || process.arch === 'arm64')) {
94
+ return `${prefix}win32-${process.arch}-msvc`
95
+ }
96
+ if (process.platform === 'android' && process.arch === 'arm64') return `${prefix}android-arm64`
97
+ if (process.platform === 'android' && process.arch === 'arm') return `${prefix}android-arm-eabi`
98
+ if (process.platform === 'linux') {
99
+ const libc = (await isMuslLinux()) ? 'musl' : 'gnu'
100
+ if (process.arch === 'x64' || process.arch === 'arm64') return `${prefix}linux-${process.arch}-${libc}`
101
+ if (process.arch === 'arm' && libc === 'gnu') return `${prefix}linux-arm-gnueabihf`
102
+ }
103
+ throw new Error(
104
+ `doc-render: ${COMPILER_PACKAGE}@${COMPILER_VERSION} has no published platform package for ${process.platform}/${process.arch}`,
105
+ )
106
+ }
107
+
108
+ type ValidatedRuntimePackage = {
109
+ entry: string
110
+ }
111
+
112
+ async function validateRuntimePackage(
113
+ runtimeDir: string,
114
+ packageName: string,
115
+ version: string,
116
+ ): Promise<ValidatedRuntimePackage> {
117
+ const packageDir = join(runtimeDir, 'node_modules', ...packageName.split('/'))
118
+ const manifestPath = join(packageDir, 'package.json')
119
+ let manifest: { name?: unknown; version?: unknown }
120
+ try {
121
+ manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as { name?: unknown; version?: unknown }
122
+ } catch {
123
+ throw new Error(`doc-render: ${packageName}@${version} is not installed in ${runtimeDir}`)
124
+ }
125
+ if (manifest.name !== packageName || manifest.version !== version) {
126
+ throw new Error(
127
+ `doc-render: expected ${packageName}@${version} in ${runtimeDir}, found ${String(manifest.name)}@${String(manifest.version)}`,
128
+ )
129
+ }
130
+
131
+ const resolved = Bun.resolveSync(packageDir, packageDir)
132
+ const [realRuntimeDir, realPackageDir, realEntry] = await Promise.all([
133
+ realpath(runtimeDir),
134
+ realpath(packageDir),
135
+ realpath(resolved),
136
+ ])
137
+ for (const [candidate, label] of [
138
+ [realPackageDir, 'package'],
139
+ [realEntry, 'entry'],
140
+ ] as const) {
141
+ const fromRuntime = relative(realRuntimeDir, candidate)
142
+ if (fromRuntime === '..' || fromRuntime.startsWith(`..${sep}`) || isAbsolute(fromRuntime)) {
143
+ throw new Error(`doc-render: ${packageName} ${label} resolves outside the scratch runtime`)
144
+ }
145
+ }
146
+ const fromPackage = relative(realPackageDir, realEntry)
147
+ if (fromPackage === '..' || fromPackage.startsWith(`..${sep}`) || isAbsolute(fromPackage)) {
148
+ throw new Error(`doc-render: ${packageName} entry resolves outside its runtime-local package directory`)
149
+ }
150
+ return { entry: realEntry }
151
+ }
152
+
153
+ // Resolve only from the pinned scratch runtime. A document may contain an
154
+ // attacker-controlled node_modules tree, so its cwd must never enter resolution.
155
+ export async function loadCompilerModule(runtimeDir: string = COMPILER_RUNTIME_DIR): Promise<NodeCompilerModule> {
156
+ const platformPackage = await requiredCompilerPlatformPackage()
157
+ const compiler = await validateRuntimePackage(runtimeDir, COMPILER_PACKAGE, COMPILER_VERSION)
158
+ await validateRuntimePackage(runtimeDir, platformPackage, COMPILER_VERSION)
159
+ return (await import(compiler.entry)) as NodeCompilerModule
79
160
  }
80
161
 
81
162
  export async function renderPdf(mainFile: string, outFile: string): Promise<number> {
@@ -9,8 +9,8 @@ You can produce professional PDFs from Markdown. The bundled `doc-render` plugin
9
9
  ships two things: a **themed report library** (`lib.typ`) that does all the
10
10
  styling, and a **render script** that does the compile. The only thing installed
11
11
  on demand is the [Typst](https://typst.app) compiler — a single npm package the
12
- agent `bun add`s into its own `node_modules` the **first time** you need a PDF,
13
- then reuses. No Pandoc, no LaTeX, no headless browser, no PDF toolchain baked
12
+ agent `bun add`s into writable session scratch the **first time** you need a PDF,
13
+ then reuses for that session. No Pandoc, no LaTeX, no headless browser, no PDF toolchain baked
14
14
  into the image.
15
15
 
16
16
  The flow is: **(1)** install the compiler once (`bun add`), **(2)** have your
@@ -44,16 +44,15 @@ which theme fits the document.**
44
44
  When plain markdown in chat is fine, **don't** make a PDF. This is for when a
45
45
  _file_ is the deliverable.
46
46
 
47
- ## Step 0 — install the Typst compiler (once per container)
47
+ ## Step 0 — install the Typst compiler (once per session)
48
48
 
49
49
  The PDF compiler is not baked into the image — install it on first use. It is a
50
50
  single version-pinned npm package (npm pulls only this platform's prebuilt
51
- binary — Linux x64/arm64, glibc or musl). It writes to the agent's
52
- `node_modules` + `package.json` + `bun.lock`, all of which survive restarts, so
53
- this only runs once per container life:
51
+ binary — Linux x64/arm64, glibc or musl). Install it in the session's writable
52
+ `/tmp` runtime; the agent-root dependency tree is protected read-only:
54
53
 
55
54
  ```sh
56
- # Idempotent: bun add is a no-op if it's already the installed version.
55
+ mkdir -p /tmp/typeclaw-doc-render-runtime && cd /tmp/typeclaw-doc-render-runtime
57
56
  bun add @myriaddreamin/typst-ts-node-compiler@0.7.0
58
57
  ```
59
58
 
@@ -61,10 +60,11 @@ The `@0.7.0` pin embeds Typst 0.14.2 and keeps the toolchain reproducible. If yo
61
60
  forget this step, the render script in Step 3 stops with the exact `bun add` line
62
61
  to run, so you can also just try the render and follow its guidance.
63
62
 
64
- > **Where it goes:** the agent's own `node_modules` — the canonical home for
65
- > executable dependencies, gitignored, not user-facing. Do **not** create a
66
- > `package.json` or `node_modules` under `workspace/` for this; let `bun add`
67
- > manage it at the agent root like any other dependency.
63
+ > **Where it goes:** `/tmp/typeclaw-doc-render-runtime`, backed by TypeClaw's
64
+ > per-session scratch directory. It is writable to model-driven bash and reused
65
+ > across calls in the same session, but not promised across container restarts.
66
+ > Do **not** modify `/agent/node_modules` or create a dependency tree under
67
+ > `workspace/`.
68
68
 
69
69
  ## Step 1 — have the markdown ready
70
70
 
@@ -313,8 +313,8 @@ might expect:
313
313
  first (Typst's workspace sandbox won't resolve an import from outside the
314
314
  render's working directory).
315
315
  - **Don't** build a `package.json` / `node_modules` / a render script under
316
- `workspace/`. The compiler installs at the agent root via `bun add`; the render
317
- script and theme library are bundled with the plugin (under
316
+ `workspace/` or modify the protected agent-root dependencies. The compiler
317
+ installs in `/tmp/typeclaw-doc-render-runtime`; the render script and theme library are bundled with the plugin (under
318
318
  `/agent/node_modules/typeclaw/src/bundled-plugins/doc-render/`).
319
319
  - **Don't** attach a PDF to a GitHub channel — that adapter rejects attachments.
320
320
  Link or inline instead.
@@ -1,6 +1,11 @@
1
1
  import { GITHUB_API_BASE, githubJsonHeaders } from '@/channels/adapters/github/auth-pat'
2
+ import type {
3
+ EffectiveApprovalResolver,
4
+ EffectiveVerdict,
5
+ HeadShaResolver,
6
+ } from '@/channels/github-review-verdict-coordinator'
2
7
 
3
- import type { EffectiveApprovalResolver, EffectiveVerdict, HeadShaResolver } from './approve-idempotency'
8
+ type GithubFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
4
9
 
5
10
  // Resolves THIS bot's standing decisive review on a PR, used by the review
6
11
  // verdict guard to stop a second formal verdict after a restart (the in-process
@@ -9,7 +14,9 @@ import type { EffectiveApprovalResolver, EffectiveVerdict, HeadShaResolver } fro
9
14
  // error must never permanently block a genuine first verdict.
10
15
  export function createGithubEffectiveApprovalResolver(deps: {
11
16
  resolveToken: (workspace: string) => Promise<string | null>
12
- fetchImpl?: typeof fetch
17
+ selfLogin?: () => string | null
18
+ isAppAuth?: () => boolean
19
+ fetchImpl?: GithubFetch
13
20
  }): EffectiveApprovalResolver {
14
21
  const fetchImpl = deps.fetchImpl ?? fetch
15
22
  return async ({ workspace, prNumber }) => {
@@ -19,7 +26,10 @@ export function createGithubEffectiveApprovalResolver(deps: {
19
26
  const token = await deps.resolveToken(workspace).catch(() => null)
20
27
  if (token === null || token === '') return { ok: false }
21
28
 
22
- const self = await fetchSelfLogin(fetchImpl, token)
29
+ const configuredSelf = deps.selfLogin?.() ?? null
30
+ if ((configuredSelf === '' || configuredSelf === null) && deps.isAppAuth?.() === true) return { ok: false }
31
+ const self =
32
+ configuredSelf !== '' && configuredSelf !== null ? configuredSelf : await fetchSelfLogin(fetchImpl, token)
23
33
  if (self === null) return { ok: false }
24
34
 
25
35
  const reviews = await fetchReviews(fetchImpl, token, owner, repo, prNumber)
@@ -36,7 +46,7 @@ export function createGithubEffectiveApprovalResolver(deps: {
36
46
  // landed-verdict cache degrades to verdict-only matching rather than stranding.
37
47
  export function createGithubHeadShaResolver(deps: {
38
48
  resolveToken: (workspace: string) => Promise<string | null>
39
- fetchImpl?: typeof fetch
49
+ fetchImpl?: GithubFetch
40
50
  }): HeadShaResolver {
41
51
  const fetchImpl = deps.fetchImpl ?? fetch
42
52
  return async ({ workspace, prNumber }) => {
@@ -80,7 +90,7 @@ function isDecisive(state: string): boolean {
80
90
 
81
91
  type ReviewRow = { state: string; login: string; isBot: boolean }
82
92
 
83
- async function fetchSelfLogin(fetchImpl: typeof fetch, token: string): Promise<string | null> {
93
+ async function fetchSelfLogin(fetchImpl: GithubFetch, token: string): Promise<string | null> {
84
94
  try {
85
95
  const response = await fetchImpl(`${GITHUB_API_BASE}/user`, { headers: githubJsonHeaders(token) })
86
96
  if (!response.ok) return null
@@ -92,7 +102,7 @@ async function fetchSelfLogin(fetchImpl: typeof fetch, token: string): Promise<s
92
102
  }
93
103
 
94
104
  async function fetchReviews(
95
- fetchImpl: typeof fetch,
105
+ fetchImpl: GithubFetch,
96
106
  token: string,
97
107
  owner: string,
98
108
  repo: string,