typeclaw 0.46.0 → 0.46.2

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 (75) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -2
  3. package/src/agent/multimodal/looker.ts +11 -1
  4. package/src/agent/network/safe-http.ts +17 -8
  5. package/src/agent/plugin-tools.ts +1 -3
  6. package/src/agent/tool-file-safety.ts +414 -145
  7. package/src/agent/tools/webfetch/fetch.ts +22 -2
  8. package/src/agent/tools/webfetch/strategies/jq.ts +1 -2
  9. package/src/agent/tools/webfetch/strategies/readability.ts +39 -16
  10. package/src/agent/tools/webfetch/strategies/selector.ts +4 -2
  11. package/src/agent/tools/webfetch/strategies/snapshot.ts +3 -2
  12. package/src/agent/tools/webfetch/tool.ts +3 -3
  13. package/src/agent/tools-without-local-file-operands.ts +9 -6
  14. package/src/bundled-plugins/backup/README.md +23 -10
  15. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  16. package/src/bundled-plugins/backup/index.ts +104 -47
  17. package/src/bundled-plugins/backup/runner.ts +102 -5
  18. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  19. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  20. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  21. package/src/bundled-plugins/github-cli-auth/index.ts +110 -31
  22. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  23. package/src/bundled-plugins/memory/README.md +9 -0
  24. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  25. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  26. package/src/bundled-plugins/memory/vector/hybrid.ts +10 -2
  27. package/src/bundled-plugins/memory/vector/store.ts +21 -9
  28. package/src/bundled-plugins/researcher/write-report.ts +3 -3
  29. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +8 -3
  30. package/src/bundled-plugins/security/policies/private-surface-read.ts +616 -50
  31. package/src/bundled-plugins/security/policies/ssrf.ts +119 -34
  32. package/src/channels/adapters/github/inbound.ts +11 -0
  33. package/src/channels/adapters/github/index.ts +48 -54
  34. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  35. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  36. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  37. package/src/channels/adapters/slack-bot.ts +7 -2
  38. package/src/channels/adapters/slack-format.ts +245 -0
  39. package/src/channels/github-token-bridge.ts +2 -3
  40. package/src/cli/inspect.ts +16 -0
  41. package/src/container/docker-app.ts +42 -13
  42. package/src/container/shared.ts +19 -6
  43. package/src/container/start.ts +13 -0
  44. package/src/cron/bridge.ts +9 -2
  45. package/src/doctor/checks.ts +5 -2
  46. package/src/git/bound-gc-config.ts +82 -0
  47. package/src/hostd/spawn.ts +133 -47
  48. package/src/init/checkpoint.ts +4 -4
  49. package/src/init/dockerfile.ts +100 -88
  50. package/src/init/gitignore.ts +5 -6
  51. package/src/init/run-bun-install.ts +16 -2
  52. package/src/init/validate-api-key.ts +1 -0
  53. package/src/inspect/item-list.ts +12 -6
  54. package/src/inspect/replay.ts +21 -9
  55. package/src/inspect/session-list.ts +71 -33
  56. package/src/mcp/tools.ts +1 -0
  57. package/src/network/internal-destinations.ts +267 -0
  58. package/src/permissions/permissions.ts +93 -2
  59. package/src/plugin/types.ts +3 -2
  60. package/src/role-claim/code.ts +9 -5
  61. package/src/run/index.ts +45 -36
  62. package/src/sandbox/canonical-secrets.ts +6 -0
  63. package/src/sandbox/env-exposure.ts +18 -15
  64. package/src/sandbox/index.ts +1 -0
  65. package/src/sandbox/policy.ts +5 -3
  66. package/src/sandbox/privileged-runtime.ts +1 -0
  67. package/src/sandbox/symlinks.ts +1 -1
  68. package/src/secrets/export-claude-credentials-file.ts +13 -22
  69. package/src/secrets/export-codex-auth-file.ts +12 -28
  70. package/src/skills/typeclaw-config/SKILL.md +22 -6
  71. package/src/skills/typeclaw-permissions/SKILL.md +22 -9
  72. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  73. package/src/usage/scan.ts +11 -2
  74. package/typeclaw.schema.json +5 -0
  75. package/src/git/secret-history.ts +0 -371
@@ -6,12 +6,12 @@ export const GRAPHQL_AUTH_NUDGE_TAG = 'github-cli-auth:graphqlRepoHint'
6
6
 
7
7
  const NUDGE_TEXT =
8
8
  `\n\n[${GRAPHQL_AUTH_NUDGE_TAG}] That looked like a GitHub auth failure on a ` +
9
- '`gh api graphql` call. Under a multi-owner GitHub App there is no single ' +
10
- '`GH_TOKEN`, and graphql carries its repo inside the query — not an inspectable ' +
11
- 'path — so TypeClaw cannot tell which installation token to mint. Re-run with an ' +
12
- 'explicit repo, e.g. `gh api graphql -R owner/repo -f query=...`. `gh api` does ' +
13
- 'not accept `-R/--repo`; TypeClaw consumes it as the mint hint and strips it ' +
14
- 'before running the command with the right token injected.'
9
+ '`gh api graphql` call. GitHub App credentials are not ambient process tokens, ' +
10
+ 'and graphql carries its repo inside the query — not an inspectable path — so ' +
11
+ 'TypeClaw needs a repo hint before it can mint a repo-scoped installation token. ' +
12
+ 'Re-run with an explicit repo, e.g. `gh api graphql -R owner/repo -f query=...`. ' +
13
+ '`gh api` does not accept `-R/--repo`; TypeClaw consumes it as the mint hint and ' +
14
+ 'strips it before running the command with the right token injected.'
15
15
 
16
16
  // The shell strips quotes/escapes, so we match the raw `gh ... graphql` substring
17
17
  // rather than parse — the nudge is advisory, so a loose match is acceptable and a
@@ -40,9 +40,9 @@ const AUTH_FAILURE_SIGNATURES = [
40
40
  export function checkGraphqlAuthNudge(options: { tool: string; result: ToolResult }): void {
41
41
  if (options.tool !== 'bash') return
42
42
 
43
- // Only meaningful when no usable token is seeded — the multi-owner App case.
44
- // A seeded global token (single-owner App, classic/fine-grained PAT) means
45
- // graphql already authenticates, so the advice would be wrong.
43
+ // Only meaningful when no usable process token exists. An operator token or a
44
+ // runtime-seeded PAT means graphql already authenticates, so the advice would
45
+ // be wrong.
46
46
  const tokenClass = classifyGhToken(process.env.GH_TOKEN)
47
47
  if (tokenClass !== 'none') return
48
48
 
@@ -4,6 +4,7 @@ import {
4
4
  configureReviewVerdictCoordinator,
5
5
  createSharedReviewVerdictGuard,
6
6
  } from '@/channels/github-review-verdict-coordinator'
7
+ import { hasEnvKey } from '@/init/env-file'
7
8
  import { CORE_PERMISSIONS } from '@/permissions/builtins'
8
9
  import { definePlugin } from '@/plugin'
9
10
 
@@ -14,6 +15,7 @@ import {
14
15
  effectiveGhTokensForAuthenticatedUserEndpoint,
15
16
  usesGhApiGraphqlEndpoint,
16
17
  } from './gh-command'
18
+ import { ensureGitAskPassHelper, resolveSandboxGitAskPassPath } from './git-askpass'
17
19
  import { analyzeGitCommand, defaultGitResolvers, resolveGhDefaultRepoFromCwd } from './git-command'
18
20
  import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
19
21
  import { commitReviewIfSucceeded, noteReviewCommand } from './review-recorder'
@@ -52,17 +54,38 @@ export default definePlugin({
52
54
  : undefined
53
55
  }
54
56
 
55
- // The PAT is in the container env but stripped by --clearenv for this role,
56
- // and a PAT is not re-mintable per repo, so there is no token to inject. Tell
57
- // the AGENT (model-visible block) instead of letting git/gh fail ambiguously
58
- // — the silent variant of this is exactly what caused a multi-day debugging
59
- // hunt. App auth is the supported path for low-trust roles.
57
+ // The token `gh` will actually resolve INSIDE the low-trust sandbox. Only
58
+ // `.env`-declared names survive `--clearenv` (`hasEnvKey` reads the same
59
+ // `readEnvFile(agentDir)` parse the sandbox's `resolveExposableEnvNames` uses,
60
+ // so this is congruent with what the sandbox inherits), and gh's precedence is
61
+ // GH_TOKEN > GITHUB_TOKEN. So a process-only GH_TOKEN does NOT mask an
62
+ // inheritable, operator-declared GITHUB_TOKEN: the process-only name is cleared,
63
+ // leaving the declared alias as the one gh sees. Returns the surviving PAT/App
64
+ // token (value snapshotted from process.env, which holds the declared value),
65
+ // or undefined when the operator declared no usable GitHub token in `.env`.
66
+ const sandboxInheritedGhToken = (): { envName: 'GH_TOKEN' | 'GITHUB_TOKEN'; value: string } | undefined => {
67
+ for (const envName of ['GH_TOKEN', 'GITHUB_TOKEN'] as const) {
68
+ if (!hasEnvKey(ctx.agentDir, envName)) continue
69
+ const value = process.env[envName]
70
+ if (value !== undefined && value !== '') return { envName, value }
71
+ }
72
+ return undefined
73
+ }
74
+
75
+ // A process-only PAT (runtime/App-seeded process.env, NOT declared in `.env`)
76
+ // is stripped by --clearenv for this role, and a PAT is not re-mintable per
77
+ // repo, so there is no token to inject. Tell the AGENT (model-visible block)
78
+ // instead of letting git/gh fail ambiguously — the silent variant of this is
79
+ // exactly what caused a multi-day debugging hunt. This does NOT fire for a PAT
80
+ // the operator declared in `.env`: that one is inherited into the sandbox and
81
+ // handled by the allow-path above.
60
82
  const sandboxedPatWithheldReason =
61
- 'A classic/fine-grained GitHub PAT is configured (via .env GH_TOKEN), but this command runs ' +
62
- 'in a sandboxed (low-trust) role whose environment is cleared before bash — so the PAT is ' +
63
- 'withheld here and is NOT available to git/gh. This is a deliberate guard, not missing auth: a ' +
64
- 'broad, long-lived PAT must not be reachable from a low-trust sandbox. Configure GitHub App auth ' +
65
- '(channels.github) to grant per-repo, short-lived tokens that DO work for sandboxed roles.'
83
+ 'A classic/fine-grained GitHub PAT is present in the runtime environment but was NOT declared ' +
84
+ 'in `.env`, and this command runs in a sandboxed (low-trust) role whose environment is cleared ' +
85
+ 'before bash — so the PAT is withheld here and is NOT available to git/gh. This is a deliberate ' +
86
+ 'guard, not missing auth: a broad, long-lived runtime PAT must not be reachable from a low-trust ' +
87
+ 'sandbox. Configure GitHub App auth (channels.github) for per-repo, short-lived tokens that work ' +
88
+ 'for sandboxed roles, or declare the PAT in `.env` to deliberately expose it to model bash.'
66
89
 
67
90
  let warnedSandboxedPatWithheld = false
68
91
  const warnSandboxedPatWithheldOnce = (): void => {
@@ -250,22 +273,41 @@ export default definePlugin({
250
273
  event.args.command = decision.rewrittenCommand
251
274
  }
252
275
 
276
+ // When NO per-repo App minter is available, prefer the token the operator
277
+ // deliberately exposed via `.env`: the sandbox inherits it into bash for
278
+ // EVERY role, so the validated command just runs on it — no block, no
279
+ // overlay except GH_REPO (non-secret) for a trusted-fallback repo. This runs
280
+ // BEFORE the process-token-class branches so it is independent of gh's
281
+ // GH_TOKEN>GITHUB_TOKEN process preference: an undeclared (process-only)
282
+ // GH_TOKEN — even App-class `ghs_` — never masks a declared, inheritable
283
+ // GITHUB_TOKEN, because sandboxInheritedGhToken() only considers names that
284
+ // survive --clearenv. When a minter IS available it wins (least-privilege
285
+ // short-lived per-repo token over a broad declared PAT) via the paths below.
286
+ if (!hasAppTokenResolver() && sandboxInheritedGhToken() !== undefined) {
287
+ if (decision.kind === 'inject' && fallbackRepoUsed && fallbackRepo !== undefined) {
288
+ event.args[TYPECLAW_INTERNAL_BASH_ENV] = { GH_REPO: fallbackRepo }
289
+ }
290
+ return
291
+ }
292
+
253
293
  // PAT classes (classic = cross-owner, fine-grained) are not re-minted per
254
294
  // repo; the seeded GH_TOKEN is the only token we have. App minting, when
255
- // available, is preferred for roles without credential-use permission,
256
- // so a PAT must not suppress minting there. An entitled role receives the
257
- // PAT through the narrow overlay; raw process.env and credential files
258
- // remain unavailable inside bash. Sandboxed PAT-only:
259
- // block with guidance instead of failing silently.
295
+ // available, is preferred for ALL roles (least-privilege per-repo token over
296
+ // a broad PAT), so a PAT must not suppress minting. An entitled role with NO
297
+ // minter receives the PAT through the narrow overlay; raw process.env and
298
+ // credential files remain unavailable inside bash. Sandboxed PAT-only with no
299
+ // minter and no `.env` declaration: block with guidance instead of failing
300
+ // silently.
260
301
  // Set when a sandboxed PAT falls through to App minting: the tail's
261
302
  // shouldMintAppToken(process.env.GH_TOKEN) re-check would see the PAT and
262
303
  // bail, so this flag forces the mint that the PAT must not suppress.
263
304
  let mintForSandboxedPat = false
264
305
  if (tokenClass === 'cross-owner' || tokenClass === 'fine-grained-pat') {
265
- // Credential-entitled role: for a repo-targeting command, inject the PAT
266
- // through the runtime-owned overlay. The same literal-repo and
267
- // credential-safe argv gates apply to PATs and App tokens.
268
- if (canUsePat(event.origin)) {
306
+ // Credential-entitled role, NO App minter: inject the PAT through the
307
+ // runtime-owned overlay. Gated on `!hasAppTokenResolver()` — when a minter
308
+ // is available it wins, so a declared/entitled PAT does not beat the
309
+ // least-privilege per-repo App token; execution falls through to minting.
310
+ if (canUsePat(event.origin) && !hasAppTokenResolver()) {
269
311
  if (decision.kind === 'inject') {
270
312
  event.args[TYPECLAW_INTERNAL_BASH_ENV] = {
271
313
  [processToken?.envName ?? 'GH_TOKEN']: processToken?.value ?? '',
@@ -274,9 +316,10 @@ export default definePlugin({
274
316
  }
275
317
  return
276
318
  }
277
- // Sandboxed: the PAT is stripped by --clearenv. Prefer App minting when
278
- // available (a PAT must NOT suppress it, or the original silent-failure
279
- // bug returns); otherwise block with guidance rather than failing mute.
319
+ // Sandboxed PAT, no minter, not declared in `.env`: the sandbox clears it
320
+ // for this role, so there is no inheritable token. Block with guidance
321
+ // rather than failing mute. (A declared `.env` PAT already returned via the
322
+ // sandbox-inherited allow-path above; an available minter falls through.)
280
323
  if (!shouldMintAppToken(undefined, hasAppTokenResolver())) {
281
324
  warnSandboxedPatWithheldOnce()
282
325
  return blockAfterLease({ block: true, reason: sandboxedPatWithheldReason })
@@ -304,18 +347,54 @@ export default definePlugin({
304
347
  return
305
348
  }
306
349
 
307
- const handleGitCommand = async (params: { command: string; agentDir: string }): Promise<HookResult> => {
308
- const { command, agentDir } = params
350
+ const handleGitCommand = async (params: {
351
+ event: { args: Record<string, unknown> }
352
+ command: string
353
+ agentDir: string
354
+ }): Promise<HookResult> => {
355
+ const { event, command, agentDir } = params
309
356
  const decision = await analyzeGitCommand(command, { cwd: agentDir, resolvers: defaultGitResolvers })
310
357
  if (decision.kind === 'pass-through') return
311
358
  if (decision.kind === 'block') return { block: true, reason: decision.reason }
312
- const token = effectiveProcessToken()
313
- if (token === undefined && !hasAppTokenResolver()) return
314
- return {
315
- block: true,
316
- reason:
317
- 'Authenticated git is unavailable to model-driven bash because git can invoke repository hooks and credential helpers that inherit reusable credentials. Local git commands still work; use a first-class GitHub action or run network git host-side.',
359
+
360
+ // Only a per-repo GitHub App token is brokered to git — never a PAT (git,
361
+ // unlike gh, runs repo-local hooks/helpers, and a PAT is not repo-confined).
362
+ // With no App minter, pass through so git fails honestly.
363
+ if (!hasAppTokenResolver()) return
364
+ const result = await resolveTokenForRepo(decision.repoSlug)
365
+ if (result.kind === 'unavailable') return { block: true, reason: result.reason }
366
+
367
+ // Deliver the token via GIT_ASKPASS (env, never argv/config). The analyzer
368
+ // already constrained this to a single bare github git command, so the token
369
+ // env reaches only this git. hooksPath=/dev/null + credential.helper= stop the
370
+ // two highest-value ways a repo could capture the token; insteadOf folds
371
+ // ssh/scp remotes to https so the credential applies. This is defense-in-depth
372
+ // WITHIN one trust domain, not a wall against a hostile repo — untrusted repos
373
+ // belong in a separate agent (see docs/internals/sandbox.mdx).
374
+ // Sandboxed bash: the helper must be on a sandbox-visible path (baked /usr),
375
+ // not the unsandboxed /tmp default the tmpfs would hide.
376
+ const askpass = await ensureGitAskPassHelper(resolveSandboxGitAskPassPath())
377
+ const existing = event.args[TYPECLAW_INTERNAL_BASH_ENV]
378
+ const overlay = existing !== null && typeof existing === 'object' ? (existing as Record<string, string>) : {}
379
+ event.args[TYPECLAW_INTERNAL_BASH_ENV] = {
380
+ ...overlay,
381
+ GIT_ASKPASS: askpass,
382
+ TYPECLAW_GIT_TOKEN: result.token,
383
+ GIT_TERMINAL_PROMPT: '0',
384
+ GIT_CONFIG_COUNT: '4',
385
+ GIT_CONFIG_KEY_0: 'core.hooksPath',
386
+ GIT_CONFIG_VALUE_0: '/dev/null',
387
+ GIT_CONFIG_KEY_1: 'credential.helper',
388
+ GIT_CONFIG_VALUE_1: '',
389
+ // Both ssh remote spellings fold to https so the askpass credential applies:
390
+ // the scp short form (git@github.com:owner/repo) and the ssh:// URL form.
391
+ GIT_CONFIG_KEY_2: 'url.https://github.com/.insteadOf',
392
+ GIT_CONFIG_VALUE_2: 'git@github.com:',
393
+ GIT_CONFIG_KEY_3: 'url.https://github.com/.insteadOf',
394
+ GIT_CONFIG_VALUE_3: 'ssh://git@github.com/',
318
395
  }
396
+ if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
397
+ return
319
398
  }
320
399
 
321
400
  return {
@@ -331,7 +410,7 @@ export default definePlugin({
331
410
  }
332
411
 
333
412
  if (command.includes('git')) {
334
- return await handleGitCommand({ command, agentDir: ctx.agentDir })
413
+ return await handleGitCommand({ event, command, agentDir: ctx.agentDir })
335
414
  }
336
415
  return
337
416
  },
@@ -11,12 +11,10 @@ export function classifyGhToken(token: string | undefined): GhTokenClass {
11
11
  }
12
12
 
13
13
  // Whether the per-repo App minter should fire for a repo-targeting command.
14
- // App auth is detected via EITHER a seeded App-class GH_TOKEN OR a live App
15
- // token resolver — the latter is the authority because multi-owner / no-repos
16
- // App configs intentionally leave GH_TOKEN unseeded (the prefix would read
17
- // 'none'), yet the per-repo minter is still registered and able to mint. Classic
18
- // and fine-grained PATs are never re-minted: they pass through with whatever
19
- // GH_TOKEN is seeded, exactly as before.
14
+ // App auth is detected via EITHER an operator-supplied App-class GH_TOKEN OR a
15
+ // live App token resolver. The resolver is authoritative for channel App auth,
16
+ // whose credentials are never seeded into process.env. Classic and fine-grained
17
+ // PATs are never re-minted: they pass through with the effective process token.
20
18
  export function shouldMintAppToken(token: string | undefined, hasAppTokenResolver: boolean): boolean {
21
19
  const tokenClass = classifyGhToken(token)
22
20
  if (tokenClass === 'cross-owner' || tokenClass === 'fine-grained-pat') return false
@@ -160,6 +160,15 @@ The embedding model (`Xenova/multilingual-e5-base`) caps inputs at **512 tokens*
160
160
  1. **Deterministic bound at embed time (primary, always on).** `embed()` calls `boundEmbeddableText` on every input before the tokenizer sees it, trimming to a character budget derived from the same conservative per-script token estimate (CJK counted 1:1, Latin ~3.5 chars/token; the tokenizer is never loaded, preserving the embedder's lazy-load). The cut is now explicit and owned, not a hidden tokenizer side effect, and the leading heading/belief sentence — the load-bearing retrieval signal — always survives because it comes first. This guarantees no silent loss even for inputs nothing ever rewrites (raw legacy prose, long queries).
161
161
  2. **Compaction routed to dreaming (remediation).** Bounding keeps retrieval correct but the bounded tail is still not embedded. The real fix is to make the shard fit. On each run the dreaming handler computes which topic shards are over budget (measuring `topicPassage(...).text` — the same citation-stripped string the embedder bounds — so the flag matches what is actually truncated) and renders an "Over the embedding budget" table into the subagent's prompt, alongside the strength-signal table. Dreaming rule 8 instructs it to compact those shards into the one-belief-sentence form **while preserving every `fragments:`/`superseded:` citation** — shrinking prose, never dropping a citation (a dropped citation would trip the citation-superset revert, leaving the shard both reverted and still over budget). The signal is gated on the vector index (`memory/.vectors/index.db`) existing; before the first index exists, the table is suppressed. The `over_budget=N` count rides the `[dreaming] done` line.
162
162
 
163
+ ## Embedder resource tuning
164
+
165
+ The embedding model is a single onnxruntime-node session shared process-wide (`vector/embedder.ts`, `getEmbedder()` singleton). Two session options bound its memory footprint, since the container runs with no docker `--cpus` limit:
166
+
167
+ - **Adaptive intra-op threads** (`vector/embed-threads.ts`). ORT's default (`intraOpNumThreads: 0`) sizes the shared session's intra-op thread pool to one worker per visible host core, each holding its own activation workspace for the singleton's lifetime. `resolveEmbedThreadCount()` caps this at half the visible cores, clamped to `[1, 4]`. The pool is session-level and shared — the transformers.js Node path calls `session.run()` directly (concurrent `Run()` is allowed; the serialization only applies to the web backend), so concurrent embeds contend for it. Capping trades some potential intra-op parallelism (per embed and across overlapping embeds) for RSS bounded by the cap rather than by host core count; for this workload of short per-turn query embeds that trade is worth it.
168
+ - **CPU mem arena off** (`enableCpuMemArena: false`). ORT's arena never returns memory to the OS; for the intermittent per-turn query embed it would inflate steady-state RSS. Disabling frees per-embed at a negligible per-call malloc cost.
169
+
170
+ Neither is configurable — the adaptive default is intended to be correct on any host.
171
+
163
172
  ## How `session.idle` works
164
173
 
165
174
  Core fires `session.idle` immediately after every `session.prompt()` completion. The plugin owns the debounce: a `Map<sessionId, Timeout>` reset on every event. When the timer fires, the plugin spawns `memory-logger` for that session — unless the min-delta gate suppresses the spawn (see below).
@@ -0,0 +1,36 @@
1
+ import { availableParallelism, cpus } from 'node:os'
2
+
3
+ // The container is launched with no docker `--cpus` limit, so onnxruntime-node's
4
+ // default `intraOpNumThreads` (0 = auto) sizes the shared session's intra-op
5
+ // thread pool to one worker PER visible host core — each with its own activation
6
+ // workspace, held for the life of the embedder singleton. On an 11-core host
7
+ // that is ~11 thread-local buffers, a real contributor to the container's RSS.
8
+ // The pool is session-level and shared: the transformers.js Node path calls
9
+ // `session.run()` directly (concurrent `Run()` is allowed — serialization only
10
+ // applies to the web backend), so concurrent embeds from overlapping turns
11
+ // contend for it. Capping is a deliberate trade: it caps intra-op parallelism
12
+ // (per embed and across overlapping embeds) in exchange for RSS bounded by the
13
+ // cap instead of by host core count. The workload is short per-turn query embeds
14
+ // (tens of ms each), so bounding memory is the priority over peak parallelism.
15
+ export const DEFAULT_MAX_EMBED_THREADS = 4
16
+
17
+ // Halve the visible cores (leaves headroom for the event loop and concurrent
18
+ // sessions), then clamp into [1, cap]. `min 1` handles a single-core box; the
19
+ // cap stops the many-core blowup.
20
+ export function resolveEmbedThreadCount(input?: { cap?: number; parallelism?: number }): number {
21
+ const cap = input?.cap ?? DEFAULT_MAX_EMBED_THREADS
22
+ const parallelism = input?.parallelism ?? detectParallelism()
23
+ const halved = Math.floor(parallelism / 2)
24
+ return Math.min(Math.max(halved, 1), cap)
25
+ }
26
+
27
+ function detectParallelism(): number {
28
+ try {
29
+ const n = availableParallelism()
30
+ if (Number.isInteger(n) && n >= 1) return n
31
+ } catch {
32
+ // availableParallelism is Node 18.14+/20+; fall back to cpus() on older runtimes.
33
+ }
34
+ const count = cpus().length
35
+ return count >= 1 ? count : 1
36
+ }
@@ -16,6 +16,7 @@ import {
16
16
  import { getResolvedTransformersVersion } from '@/models/transformers-version'
17
17
 
18
18
  import { homeRoot } from '../../../hostd/paths'
19
+ import { resolveEmbedThreadCount } from './embed-threads'
19
20
  import { type BoundedText, boundEmbeddableText, MAX_MODEL_TOKENS } from './truncation'
20
21
 
21
22
  // Re-exported for the vector subsystem's existing imports. The canonical
@@ -99,7 +100,24 @@ export class Embedder {
99
100
  // miss, or silently loads a stale variant. Fails loudly with a refresh hint.
100
101
  await verifyModelCache()
101
102
  configureTransformers(env)
102
- const extractor = await pipeline('feature-extraction', MODEL_NAME, { local_files_only: true, dtype: MODEL_DTYPE })
103
+ const extractor = await pipeline('feature-extraction', MODEL_NAME, {
104
+ local_files_only: true,
105
+ dtype: MODEL_DTYPE,
106
+ // onnxruntime-node session tuning (transformers.js forwards session_options
107
+ // straight into the native InferenceSession). Two memory levers:
108
+ // - intraOpNumThreads: capped adaptively instead of ORT's default (0 =
109
+ // one worker per visible host core), each of which holds its own
110
+ // activation workspace for the singleton's lifetime.
111
+ // - enableCpuMemArena: off — ORT's arena never returns memory to the OS,
112
+ // so for the intermittent per-turn query embed it inflates steady-state
113
+ // RSS with no benefit. Disabling frees per-embed, at a small per-call
114
+ // malloc cost that is negligible next to the ~tens-of-ms forward pass.
115
+ session_options: {
116
+ intraOpNumThreads: resolveEmbedThreadCount(),
117
+ interOpNumThreads: 1,
118
+ enableCpuMemArena: false,
119
+ },
120
+ })
103
121
  return new Embedder(extractor)
104
122
  }
105
123
 
@@ -24,7 +24,7 @@ import { embed, EMBEDDING_MODEL_ID, type EmbedType } from './embedder'
24
24
  import type { Passage } from './passages'
25
25
  import { clearsBaseline, gateRelevance, MARGIN, streamAdmissionBaseline } from './relevance-gate'
26
26
  import { crossScriptMarginScale, dominantScript, type ScriptClass } from './script'
27
- import { VectorStore, type ScoredVectorRow, type VectorRow } from './store'
27
+ import { scoreRows, VectorStore, type ScoredVectorRow, type VectorRow } from './store'
28
28
  import { chunkEmbeddableText } from './truncation'
29
29
 
30
30
  export { collectPassages, findMissingPassages, type Passage } from './passages'
@@ -241,9 +241,17 @@ function maxScoreAcrossChunks(
241
241
  queryEmbeddings: Float32Array[],
242
242
  store: VectorStore,
243
243
  ): { scored: ScoredVectorRow[]; winnerChunkByRowId: Map<string, number> } {
244
+ // Decode the compatible corpus ONCE and score every chunk against it, instead
245
+ // of re-reading and re-decoding the whole table per chunk (queryScored did a
246
+ // full SELECT + BLOB decode on each call). Same MAX-across-chunks result, but
247
+ // the O(rows) decode runs once per turn instead of once per chunk.
248
+ const dims = queryEmbeddings[0]?.length
249
+ if (dims === undefined) return { scored: [], winnerChunkByRowId: new Map() }
250
+ const rows = store.loadRows(EMBEDDING_MODEL_ID, dims)
251
+
244
252
  const best = new Map<string, { scored: ScoredVectorRow; chunkIndex: number }>()
245
253
  queryEmbeddings.forEach((embedding, chunkIndex) => {
246
- for (const scoredRow of store.queryScored(embedding, EMBEDDING_MODEL_ID)) {
254
+ for (const scoredRow of scoreRows(rows, embedding)) {
247
255
  const existing = best.get(scoredRow.row.id)
248
256
  if (existing === undefined || scoredRow.score > existing.scored.score) {
249
257
  best.set(scoredRow.row.id, { scored: scoredRow, chunkIndex })
@@ -95,24 +95,28 @@ export class VectorStore {
95
95
  // Same cosine scan as `query` but returns every compatible row WITH its score
96
96
  // and unsliced, so a caller can reason about the full score distribution (the
97
97
  // relevance gate's per-query baseline) before deciding how many to keep.
98
+ queryScored(embedding: Float32Array, modelId: string): ScoredVectorRow[] {
99
+ return scoreRows(this.loadRows(modelId, embedding.length), embedding).sort((a, b) => b.score - a.score)
100
+ }
101
+
102
+ // Decodes every compatible row's embedding BLOB into a Float32Array ONCE. A
103
+ // multi-chunk query scores many embeddings against the SAME corpus, so callers
104
+ // that decode here once and reuse the result across chunks avoid re-reading and
105
+ // re-decoding the whole table per chunk (the per-turn allocation hot path). The
106
+ // returned rows are transient — held only for the current search, never cached
107
+ // across turns (that would trade collectable garbage for permanent resident
108
+ // memory, the opposite of what we want).
98
109
  //
99
110
  // Filter by embedding identity, not dims alone: a stale row from a different
100
111
  // model/dtype variant can share the same dims but lives in an incompatible
101
112
  // vector space, so cosine against it is garbage. Excluding it here keeps a
102
113
  // partial re-embed (mixed variants mid-rebuild) at reduced recall, never
103
114
  // wrong scores.
104
- queryScored(embedding: Float32Array, modelId: string): ScoredVectorRow[] {
105
- // The query vector's magnitude is identical for every row in this scan, so
106
- // hoist it out of the per-row cosine instead of recomputing N times (each
107
- // recompute is 768 multiply-adds + a sqrt). Behavior is unchanged — same
108
- // cosine values, fewer operations on the brute-force hot path.
109
- const queryMagnitude = magnitude(embedding)
115
+ loadRows(modelId: string, dims: number): VectorRow[] {
110
116
  return this.db
111
117
  .query<StoredVectorRow, [string, number]>('SELECT * FROM vectors WHERE model = ? AND dims = ?')
112
- .all(modelId, embedding.length)
118
+ .all(modelId, dims)
113
119
  .map(toVectorRow)
114
- .map((row) => ({ row, score: cosineSimilarity(embedding, queryMagnitude, row.embedding) }))
115
- .sort((a, b) => b.score - a.score)
116
120
  }
117
121
 
118
122
  deleteOtherModels(modelId: string): void {
@@ -160,6 +164,14 @@ export class VectorStore {
160
164
  }
161
165
  }
162
166
 
167
+ // Scores pre-decoded rows against one query embedding. The query vector's
168
+ // magnitude is identical for every row, so hoist it out of the per-row cosine
169
+ // instead of recomputing N times (each recompute is 768 multiply-adds + a sqrt).
170
+ export function scoreRows(rows: VectorRow[], embedding: Float32Array): ScoredVectorRow[] {
171
+ const queryMagnitude = magnitude(embedding)
172
+ return rows.map((row) => ({ row, score: cosineSimilarity(embedding, queryMagnitude, row.embedding) }))
173
+ }
174
+
163
175
  function toVectorRow(row: StoredVectorRow): VectorRow {
164
176
  return {
165
177
  id: row.id,
@@ -31,8 +31,8 @@ const writtenBySession = new Map<string, true>()
31
31
  // - the parent dir's realpath must equal the real workspace/public dir, which
32
32
  // blocks `workspace -> /agent/.env` style symlink escapes that a lexical
33
33
  // check would follow,
34
- // - the file is created with O_EXCL, so an existing file or a planted
35
- // final-path symlink is rejected rather than clobbered or followed,
34
+ // - the runtime descriptor-anchors the parent, then the file is created with
35
+ // O_EXCL, so an existing file or planted final-path symlink is rejected,
36
36
  // - a second write in the same session is rejected (one report per spawn),
37
37
  // - the schema is strict, so an `acknowledgeGuards` field is rejected, not
38
38
  // silently stripped.
@@ -52,7 +52,7 @@ Write to \`public/\` instead of \`workspace/\` when your resolved role lacks \`f
52
52
  .describe('Absolute path: <agent>/workspace/research-<slug>.md or <agent>/public/research-<slug>.md'),
53
53
  content: z.string().describe('The full markdown report body.'),
54
54
  }),
55
- fileOperands: { output: ['path'] },
55
+ fileOperands: { create: ['path'] },
56
56
  async execute(args: WriteReportArgs, ctx: ToolContext) {
57
57
  if (writtenBySession.has(ctx.sessionId)) {
58
58
  throw new Error('A report has already been written for this session. You may write exactly one report.')
@@ -88,6 +88,12 @@ const ENV_KEY_RECON_TARGETS: ReadonlyArray<string> = [
88
88
 
89
89
  const ENV_KEY_RECON_THRESHOLD = 3
90
90
 
91
+ // Names are fixed literals, so these boundary regexes are constant. Compile
92
+ // once at module load, not ~30 RegExps per outbound message (guard is per-send).
93
+ const ENV_KEY_RECON_MATCHERS: ReadonlyArray<readonly [name: string, pattern: RegExp]> = ENV_KEY_RECON_TARGETS.map(
94
+ (name) => [name, new RegExp(`\\b${name}\\b`)] as const,
95
+ )
96
+
91
97
  const TEXT_KEYS = ['text', 'message', 'content', 'body']
92
98
 
93
99
  export type OutboundSecretMatch = {
@@ -137,9 +143,8 @@ export function findOutboundSecrets(text: string, env: NodeJS.ProcessEnv = proce
137
143
 
138
144
  function findReconEnvKeys(text: string): string[] {
139
145
  const out: string[] = []
140
- for (const name of ENV_KEY_RECON_TARGETS) {
141
- const re = new RegExp(`\\b${name}\\b`)
142
- if (re.test(text)) out.push(name)
146
+ for (const [name, pattern] of ENV_KEY_RECON_MATCHERS) {
147
+ if (pattern.test(text)) out.push(name)
143
148
  }
144
149
  return out
145
150
  }