typeclaw 0.50.0 → 0.51.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 (90) hide show
  1. package/dist/types/agent/bash-sandbox-env.d.ts +15 -0
  2. package/dist/types/agent/bash-sandbox-proc.d.ts +8 -0
  3. package/dist/types/agent/bash-sandbox.d.ts +94 -0
  4. package/dist/types/agent/compaction.d.ts +4 -4
  5. package/dist/types/agent/idle-compaction.d.ts +1 -0
  6. package/dist/types/agent/index.d.ts +5 -17
  7. package/dist/types/agent/output-allowance.d.ts +4 -0
  8. package/dist/types/agent/plugin-tools.d.ts +4 -75
  9. package/dist/types/agent/system-prompt-composition.d.ts +17 -0
  10. package/dist/types/agent/tools/ddg.d.ts +9 -0
  11. package/dist/types/agent/tools/stream-snapshot.d.ts +1 -1
  12. package/dist/types/agent/tools/webfetch/tool.d.ts +1 -1
  13. package/dist/types/channels/github-review-check.d.ts +1 -1
  14. package/dist/types/channels/router.d.ts +11 -49
  15. package/dist/types/config/config.d.ts +24 -11
  16. package/dist/types/config/providers.d.ts +3 -1
  17. package/dist/types/container/start.d.ts +1 -0
  18. package/dist/types/eval/cell.d.ts +26 -0
  19. package/dist/types/eval/config.d.ts +19 -0
  20. package/dist/types/eval/dispatch.d.ts +7 -0
  21. package/dist/types/eval/kernel.d.ts +28 -0
  22. package/dist/types/eval/process.d.ts +23 -0
  23. package/dist/types/eval/protocol.d.ts +34 -0
  24. package/dist/types/eval/sandbox.d.ts +10 -0
  25. package/dist/types/eval/tool.d.ts +17 -0
  26. package/dist/types/eval/wire.d.ts +33 -0
  27. package/dist/types/sandbox/env-exposure.d.ts +2 -0
  28. package/package.json +5 -5
  29. package/src/agent/bash-sandbox-env.ts +104 -0
  30. package/src/agent/bash-sandbox-proc.ts +70 -0
  31. package/src/agent/bash-sandbox.ts +225 -0
  32. package/src/agent/compaction.ts +22 -10
  33. package/src/agent/idle-compaction.ts +7 -3
  34. package/src/agent/index.ts +66 -157
  35. package/src/agent/output-allowance.ts +7 -0
  36. package/src/agent/plugin-tools.ts +29 -379
  37. package/src/agent/session-origin.ts +2 -1
  38. package/src/agent/subagent-completion-reminder.ts +2 -2
  39. package/src/agent/system-prompt-composition.ts +141 -0
  40. package/src/agent/system-prompt.ts +4 -4
  41. package/src/agent/todo/scope.ts +1 -1
  42. package/src/agent/tools/ddg.ts +71 -11
  43. package/src/agent/tools-without-local-file-operands.ts +4 -0
  44. package/src/browser/fill-secret.ts +307 -0
  45. package/src/bundled-plugins/explorer/explorer.ts +1 -1
  46. package/src/bundled-plugins/github-cli-auth/gh-review-detect.ts +40 -16
  47. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +12 -7
  48. package/src/bundled-plugins/github-cli-auth/index.ts +10 -1
  49. package/src/bundled-plugins/managed-browser/index.ts +107 -2
  50. package/src/bundled-plugins/memory/dreaming.ts +4 -1
  51. package/src/bundled-plugins/memory/load-memory.ts +2 -4
  52. package/src/bundled-plugins/memory/memory-logger.ts +74 -2
  53. package/src/bundled-plugins/memory/transcript-preload.ts +103 -0
  54. package/src/bundled-plugins/memory/vector/hybrid.ts +25 -14
  55. package/src/bundled-plugins/security/policies/private-surface-read.ts +166 -201
  56. package/src/channels/adapters/discord-bot-reference.ts +5 -4
  57. package/src/channels/adapters/discord-bot.ts +1 -0
  58. package/src/channels/adapters/discord-classify.ts +8 -3
  59. package/src/channels/adapters/discord.ts +29 -0
  60. package/src/channels/github-review-check.ts +5 -1
  61. package/src/channels/github-review-verdict-coordinator.ts +68 -2
  62. package/src/channels/router.ts +88 -107
  63. package/src/channels/subagent-completion-bridge.ts +3 -2
  64. package/src/cli/hostd.ts +3 -0
  65. package/src/config/config.ts +15 -0
  66. package/src/config/providers.ts +10 -4
  67. package/src/container/start.ts +37 -1
  68. package/src/doctor/checks.ts +25 -16
  69. package/src/doctor/index.ts +48 -12
  70. package/src/doctor/operational-incidents.ts +16 -1
  71. package/src/doctor/plugin-bridge.ts +14 -1
  72. package/src/doctor/stage.ts +14 -0
  73. package/src/doctor/types.ts +6 -0
  74. package/src/eval/cell.ts +93 -0
  75. package/src/eval/config.ts +32 -0
  76. package/src/eval/dispatch.ts +67 -0
  77. package/src/eval/entry.ts +261 -0
  78. package/src/eval/kernel.ts +154 -0
  79. package/src/eval/process.ts +113 -0
  80. package/src/eval/protocol.ts +26 -0
  81. package/src/eval/redeclare.ts +174 -0
  82. package/src/eval/sandbox.ts +114 -0
  83. package/src/eval/tool.ts +98 -0
  84. package/src/eval/wire.ts +93 -0
  85. package/src/operations/classify-tool-outcome.ts +1 -1
  86. package/src/plugin/core-tool-names.ts +6 -1
  87. package/src/sandbox/env-exposure.ts +20 -0
  88. package/src/server/index.ts +46 -11
  89. package/src/skills/typeclaw-config/SKILL.md +20 -2
  90. package/typeclaw.schema.json +52 -0
@@ -0,0 +1,7 @@
1
+ import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
2
+ import type { EvalDispatch } from "./cell.js";
3
+ export declare function createEvalDispatch(options: {
4
+ readonly tools: readonly ToolDefinition[];
5
+ readonly getActiveNames: () => readonly string[];
6
+ readonly context: Parameters<ToolDefinition['execute']>[4];
7
+ }): EvalDispatch;
@@ -0,0 +1,28 @@
1
+ import { type EvalDispatch } from "./cell.js";
2
+ import { type KernelLaunch } from "./process.js";
3
+ export type EvalResult = {
4
+ readonly text: string;
5
+ readonly isError: boolean;
6
+ readonly truncated: boolean;
7
+ readonly restarted: boolean;
8
+ };
9
+ export declare class EvalKernel {
10
+ private readonly prepare;
11
+ private readonly idleMs;
12
+ private worker;
13
+ private active;
14
+ private controller;
15
+ private idle;
16
+ private closed;
17
+ private used;
18
+ private stopping;
19
+ private disposal;
20
+ constructor(prepare: () => Promise<KernelLaunch>, idleMs?: number);
21
+ run(code: string, options: {
22
+ readonly dispatch: EvalDispatch;
23
+ readonly signal?: AbortSignal;
24
+ readonly timeoutMs?: number;
25
+ }): Promise<EvalResult>;
26
+ dispose(): Promise<void>;
27
+ private stopWorker;
28
+ }
@@ -0,0 +1,23 @@
1
+ import { type HostFrame, type KernelFrame } from "./protocol.js";
2
+ export type KernelLaunch = {
3
+ readonly command: string;
4
+ readonly cwd: string;
5
+ readonly env: Record<string, string>;
6
+ readonly fingerprint: string;
7
+ readonly cleanup: () => Promise<void>;
8
+ };
9
+ export declare class KernelProcess {
10
+ readonly ready: Promise<void>;
11
+ readonly exited: Promise<void>;
12
+ onFrame: (frame: KernelFrame) => void;
13
+ onOutput: (text: string) => void;
14
+ alive: boolean;
15
+ private readonly child;
16
+ constructor(launch: KernelLaunch, callbacks: {
17
+ readonly frame: (frame: KernelFrame) => void;
18
+ readonly output: (text: string) => void;
19
+ readonly failure: (error: Error) => void;
20
+ });
21
+ send(frame: HostFrame): void;
22
+ stop(): void;
23
+ }
@@ -0,0 +1,34 @@
1
+ import { z } from 'zod';
2
+ export { EVAL_LIMITS, FRAME_PREFIX, EvalError, encodeFrame, FrameLines, CellOutput } from "./wire.js";
3
+ export declare const kernelFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
4
+ type: z.ZodLiteral<"ready">;
5
+ }, z.core.$strict>, z.ZodObject<{
6
+ type: z.ZodLiteral<"output">;
7
+ cellId: z.ZodString;
8
+ text: z.ZodString;
9
+ }, z.core.$strict>, z.ZodObject<{
10
+ type: z.ZodLiteral<"tool-call">;
11
+ cellId: z.ZodString;
12
+ id: z.ZodString;
13
+ name: z.ZodString;
14
+ args: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
15
+ }, z.core.$strict>, z.ZodObject<{
16
+ type: z.ZodLiteral<"done">;
17
+ cellId: z.ZodString;
18
+ error: z.ZodOptional<z.ZodString>;
19
+ }, z.core.$strict>], "type">;
20
+ export type KernelFrame = z.infer<typeof kernelFrameSchema>;
21
+ export declare const hostFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
22
+ type: z.ZodLiteral<"run">;
23
+ cellId: z.ZodString;
24
+ code: z.ZodString;
25
+ }, z.core.$strict>, z.ZodObject<{
26
+ type: z.ZodLiteral<"tool-result">;
27
+ id: z.ZodString;
28
+ value: z.ZodUnknown;
29
+ }, z.core.$strict>, z.ZodObject<{
30
+ type: z.ZodLiteral<"tool-error">;
31
+ id: z.ZodString;
32
+ error: z.ZodString;
33
+ }, z.core.$strict>], "type">;
34
+ export type HostFrame = z.infer<typeof hostFrameSchema>;
@@ -0,0 +1,10 @@
1
+ import type { SessionOrigin } from "../agent/session-origin.js";
2
+ import type { PermissionService } from "../permissions/permissions.js";
3
+ import { EvalKernel } from "./kernel.js";
4
+ export declare function authorityOrigin(origin: SessionOrigin | undefined): unknown;
5
+ export declare function createSandboxedEvalKernel(options: {
6
+ readonly agentDir: string;
7
+ readonly sessionId: string;
8
+ readonly permissions: PermissionService;
9
+ readonly getOrigin: () => SessionOrigin | undefined;
10
+ }): EvalKernel;
@@ -0,0 +1,17 @@
1
+ import { type ToolDefinition } from '@earendil-works/pi-coding-agent';
2
+ import type { z } from 'zod';
3
+ import type { WrapSystemToolOptions } from "../agent/plugin-tools.js";
4
+ import { type BudgetState, type ToolResultBudget } from "../agent/tool-result-budget.js";
5
+ import { type evalConfigSchema } from "./config.js";
6
+ export declare const EVAL_PROMPT_HINT: string;
7
+ export declare function registerEvalTool(options: {
8
+ readonly settings: z.infer<typeof evalConfigSchema>;
9
+ readonly tools: ToolDefinition[];
10
+ readonly activeNames: string[];
11
+ readonly getActiveNames: () => readonly string[];
12
+ readonly wrappers: WrapSystemToolOptions;
13
+ readonly budget?: ToolResultBudget;
14
+ readonly budgetState?: BudgetState;
15
+ }): {
16
+ dispose(): Promise<void>;
17
+ } | undefined;
@@ -0,0 +1,33 @@
1
+ import type { HostFrame, KernelFrame } from "./protocol.js";
2
+ export declare const EVAL_LIMITS: {
3
+ readonly codeBytes: number;
4
+ readonly frameBytes: number;
5
+ readonly outputBytes: number;
6
+ readonly outputLines: 1000;
7
+ readonly outputWarnBytes: number;
8
+ readonly timeoutMs: 30000;
9
+ readonly maxTimeoutMs: 60000;
10
+ readonly idleMs: number;
11
+ readonly calls: 128;
12
+ readonly concurrency: 8;
13
+ };
14
+ export declare const FRAME_PREFIX = "@typeclaw-eval ";
15
+ export declare class EvalError extends Error {
16
+ readonly kind: 'protocol' | 'closed' | 'timeout' | 'busy' | 'refused' | 'cell';
17
+ readonly name = "EvalError";
18
+ constructor(kind: 'protocol' | 'closed' | 'timeout' | 'busy' | 'refused' | 'cell', message: string);
19
+ }
20
+ export declare function assertNever(value: never): never;
21
+ export declare function encodeFrame(frame: HostFrame | KernelFrame): string;
22
+ export declare class FrameLines {
23
+ private pending;
24
+ push(chunk: Uint8Array): string[];
25
+ }
26
+ export declare class CellOutput {
27
+ private text;
28
+ private bytes;
29
+ private lines;
30
+ truncated: boolean;
31
+ append(text: string): void;
32
+ render(): string;
33
+ }
@@ -1 +1,3 @@
1
+ export declare const SECRET_ENV_PREFIX = "TYPECLAW_SECRET_";
1
2
  export declare function resolveExposableEnvNames(declaredEnv: ReadonlyMap<string, string>, runtimeEnv?: Readonly<Record<string, string | undefined>>): string[];
3
+ export declare function resolveFillableEnvNames(declaredEnv: ReadonlyMap<string, string>, runtimeEnv?: Readonly<Record<string, string | undefined>>): string[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.50.0",
3
+ "version": "0.51.0",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -52,10 +52,10 @@
52
52
  "dependencies": {
53
53
  "@clack/core": "^1.2.0",
54
54
  "@clack/prompts": "^1.2.0",
55
- "@earendil-works/pi-agent-core": "^0.99.2",
56
- "@earendil-works/pi-ai": "^0.99.2",
57
- "@earendil-works/pi-coding-agent": "^0.99.2",
58
- "@earendil-works/pi-tui": "^0.99.2",
55
+ "@earendil-works/pi-agent-core": "^1.4.0",
56
+ "@earendil-works/pi-ai": "^1.4.0",
57
+ "@earendil-works/pi-coding-agent": "^1.4.0",
58
+ "@earendil-works/pi-tui": "^1.4.0",
59
59
  "@huggingface/transformers": "4.2.0",
60
60
  "@modelcontextprotocol/sdk": "^1.29.0",
61
61
  "@mozilla/readability": "^0.6.0",
@@ -0,0 +1,104 @@
1
+ import { join } from 'node:path'
2
+
3
+ import { readEnvFile } from '@/init/env-file'
4
+ import { resolveExposableEnvNames } from '@/sandbox/env-exposure'
5
+ type BashEnvOverlay = Record<string, string>
6
+ const SECRET_BASH_ENV_NAMES = new Set(['GH_TOKEN', 'GITHUB_TOKEN'])
7
+ // Transport classifier for the TRUSTED hook-injected overlay only (e.g.
8
+ // github-cli-auth's per-repo GH_TOKEN). Token/secret-shaped names use `inherit`
9
+ // so their value never renders into the bwrap argv; plain names (GH_REPO) go
10
+ // via `set`. This is NOT a .env exposure filter — the overlay is populated by
11
+ // trusted runtime hooks, not operator .env.
12
+ const OVERLAY_SECRET_NAME_PATTERN = /(?:^|_)(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|AUTH)$/i
13
+ function isOverlaySecretName(name: string): boolean {
14
+ return SECRET_BASH_ENV_NAMES.has(name) || OVERLAY_SECRET_NAME_PATTERN.test(name)
15
+ }
16
+
17
+ export function buildSandboxEnvPolicy(
18
+ overlay: BashEnvOverlay | undefined,
19
+ runtimeEnv: Record<string, string> | undefined,
20
+ exposableEnvNames: readonly string[] = [],
21
+ withhold: readonly string[] = [],
22
+ ): { inherit?: string[]; set?: Record<string, string>; withhold?: string[] } {
23
+ const requestedWithhold = new Set(withhold)
24
+ const overlayNames = new Set(Object.keys(overlay ?? {}))
25
+ // The overlay is a deliberate command-scoped replacement, while withholding
26
+ // only removes ambient values; an overlay therefore wins for the same name.
27
+ const effectiveWithhold = [...requestedWithhold].filter((name) => !overlayNames.has(name))
28
+ const effectiveWithholdSet = new Set(effectiveWithhold)
29
+ const set = Object.fromEntries(Object.entries(runtimeEnv ?? {}).filter(([key]) => !requestedWithhold.has(key)))
30
+ const inherit: string[] = []
31
+ const inheritSeen = new Set<string>()
32
+ const pushInherit = (key: string): void => {
33
+ if (effectiveWithholdSet.has(key) || Object.hasOwn(set, key) || inheritSeen.has(key)) return
34
+ inheritSeen.add(key)
35
+ inherit.push(key)
36
+ }
37
+ for (const [key, value] of Object.entries(overlay ?? {})) {
38
+ if (Object.hasOwn(set, key)) continue
39
+ if (isOverlaySecretName(key)) pushInherit(key)
40
+ else set[key] = value
41
+ }
42
+ // Operator-declared .env vars pass through by NAME (inherit), keeping values
43
+ // out of the rendered bwrap argv. Sandbox-integrity names were already dropped
44
+ // in resolveExposableEnvNames — these are the survivors.
45
+ for (const key of exposableEnvNames) pushInherit(key)
46
+ // Pass the entrypoint-exported Xvfb display (start_xvfb: `export DISPLAY=:99`)
47
+ // through --clearenv, else sandboxed `agent-browser --headed` dies with
48
+ // "Missing X server or $DISPLAY". Passing the runtime's OWN value (not a fixed
49
+ // ":99") keeps `docker.file.xvfb=false` advertising no display. Rendered via
50
+ // `set` (a display number is neither a credential nor shell-injectable), and no
51
+ // /tmp/.X11-unix bind is needed: Chrome reaches Xvfb over the netns-scoped
52
+ // abstract X11 socket while bash keeps network:'inherit'.
53
+ const display = process.env['DISPLAY']
54
+ if (
55
+ display !== undefined &&
56
+ display !== '' &&
57
+ !effectiveWithholdSet.has('DISPLAY') &&
58
+ !Object.hasOwn(set, 'DISPLAY') &&
59
+ !inheritSeen.has('DISPLAY')
60
+ ) {
61
+ set['DISPLAY'] = display
62
+ }
63
+ return {
64
+ ...(inherit.length > 0 ? { inherit } : {}),
65
+ ...(Object.keys(set).length > 0 ? { set } : {}),
66
+ ...(effectiveWithhold.length > 0 ? { withhold: effectiveWithhold } : {}),
67
+ }
68
+ }
69
+
70
+ export function spreadSandboxEnv(policy: ReturnType<typeof buildSandboxEnvPolicy>): {
71
+ env?: ReturnType<typeof buildSandboxEnvPolicy>
72
+ } {
73
+ return Object.keys(policy).length > 0 ? { env: policy } : {}
74
+ }
75
+
76
+ export function resolveExposableBashEnvNames(agentDir: string): { exposable: string[]; withheld: string[] } {
77
+ const declaredEnv = readEnvFile(agentDir)
78
+ const exposable = resolveExposableEnvNames(declaredEnv, process.env)
79
+ const exposableSet = new Set(exposable)
80
+ const withheld = [...declaredEnv]
81
+ .filter(([name, value]) => value.length > 0 && !exposableSet.has(name))
82
+ .map(([name]) => name)
83
+ return { exposable, withheld }
84
+ }
85
+
86
+ export function buildRoleScopedConfigEnv(
87
+ agentDir: string,
88
+ hiddenDirs: string[],
89
+ envOverlay: BashEnvOverlay | undefined,
90
+ ): BashEnvOverlay | undefined {
91
+ // Low-trust roles have workspace/ masked. Do not let container-global config
92
+ // env vars point CLIs back at that private surface: apps that honor XDG should
93
+ // still run, but their config must land in the sandbox's per-session /tmp.
94
+ // Trusted/owner have only the unconditional credential-dir masks, not the
95
+ // workspace root mask, so their command broker decides whether to set GWS.
96
+ const workspaceHidden = hiddenDirs.includes(join(agentDir, 'workspace'))
97
+ if (!workspaceHidden) return envOverlay
98
+
99
+ return {
100
+ ...envOverlay,
101
+ XDG_CONFIG_HOME: '/tmp/.config',
102
+ GWS_CONFIG_HOME: '/tmp/.config/gws',
103
+ }
104
+ }
@@ -0,0 +1,70 @@
1
+ import { config } from '@/config/config'
2
+ import { canMountRealProc, getProcBindSafetyVerdict, resolveProcBindSafetyWithRetry } from '@/sandbox'
3
+ // Picks the /proc strategy for a sandboxed bash call. The branch order is:
4
+ // 'real-proc' ONLY when the operator explicitly opted in (sandbox.realProc) AND
5
+ // the kernel permits the mount (canMountRealProc) — it adds PID isolation but
6
+ // needs CAP_SYS_ADMIN (unshare --mount-proc), so it is a deliberate, narrow
7
+ // opt-in; else 'proc-bind' (--ro-bind /proc, NO CAP_SYS_ADMIN) when its userns
8
+ // leak-block is verified safe; else 'tmpfs'. Because sandbox.realProc DEFAULTS
9
+ // FALSE, the first branch is normally skipped and proc-bind is the de-facto
10
+ // default — which is the point: the common path needs no broad outer capability.
11
+ // 'tmpfs' is the last-resort degraded mode where external packages can't run;
12
+ // reached only when proc-bind is DEFINITIVELY unavailable (a real cross-userns
13
+ // environ leak → fail closed) or its safety stays unverifiable after retries.
14
+ //
15
+ // Read from the boot-time `config` snapshot, NOT live getConfig(): sandbox is
16
+ // restart-required, and the strategy MUST track the boot-time CAP_SYS_ADMIN
17
+ // grant. A `typeclaw reload` flipping realProc would otherwise emit `unshare
18
+ // --mount-proc` in a container booted WITHOUT the cap (or vice versa). Both
19
+ // probes are cached process-globally, so this resolves to one spawn per
20
+ // container lifetime regardless of how many bash calls hit it.
21
+ // A tmpfs degrade carries WHY it happened so the caller can pick a permanent vs
22
+ // retryable error. 'definitive': the probe returned a real cross-userns leak
23
+ // ('unsafe') — the ONLY verdict proven permanent, so it fails closed for good.
24
+ // 'unverified': the safety probe never reached a definitive verdict within its
25
+ // retry budget. That covers BOTH a transient load spike AND a durable
26
+ // incapability (no usable namespaces, a bwrap that starts but cannot set up its
27
+ // sandbox): the probe cannot prove a NEGATIVE capability — only a leak is
28
+ // definitive — so a genuinely incapable host also lands here and simply keeps
29
+ // re-degrading on each call. Since 'inconclusive' is never cached, that costs a
30
+ // re-probe but is correct: the only false case is "capable but briefly
31
+ // saturated", which recovers; an incapable host stays degraded either way.
32
+ // Absent when the strategy is not tmpfs.
33
+ export type ProcStrategyResolution =
34
+ | { strategy: 'real-proc' | 'proc-bind'; degradeReason?: undefined }
35
+ | { strategy: 'tmpfs'; degradeReason: 'definitive' | 'unverified' }
36
+
37
+ export async function resolveProcStrategy(): Promise<ProcStrategyResolution> {
38
+ if (config.sandbox.realProc && (await canMountRealProc())) return { strategy: 'real-proc' }
39
+ // Retry an 'inconclusive' proc-bind probe (transient under load) before
40
+ // degrading — a single such hiccup must not break external-package runs on a
41
+ // capable host. 'unsafe' still fails closed with no retry.
42
+ const verdict = await resolveProcBindSafetyWithRetry(
43
+ () => getProcBindSafetyVerdict(),
44
+ (ms) => Bun.sleep(ms),
45
+ )
46
+ if (verdict === 'safe') return { strategy: 'proc-bind' }
47
+ // Degraded last resort: no working /proc strategy. External package runners
48
+ // (bunx/bun run <pkg-bin>) will fail with Bun's opaque "NotDir" because
49
+ // /proc/self/{fd,maps} are absent. Only a proven 'unsafe' (a real cross-userns
50
+ // leak) is DEFINITIVE — warn once (a real operator-facing limit). An
51
+ // 'inconclusive' is reported as retryable upstream and NOT warned (it would cry
52
+ // wolf every boot storm); a durably-incapable host re-degrades quietly here,
53
+ // since the probe cannot distinguish it from transient load.
54
+ if (verdict === 'unsafe') {
55
+ warnTmpfsProcFallbackOnce()
56
+ return { strategy: 'tmpfs', degradeReason: 'definitive' }
57
+ }
58
+ return { strategy: 'tmpfs', degradeReason: 'unverified' }
59
+ }
60
+
61
+ let tmpfsProcFallbackWarned = false
62
+ function warnTmpfsProcFallbackOnce(): void {
63
+ if (tmpfsProcFallbackWarned) return
64
+ tmpfsProcFallbackWarned = true
65
+ console.warn(
66
+ '[sandbox] degraded /proc mode: neither real-proc nor proc-bind is available on this host, ' +
67
+ 'so sandboxed external package runners (bunx / bun run <pkg-bin>) will fail. ' +
68
+ 'This needs a runtime with working user namespaces.',
69
+ )
70
+ }
@@ -0,0 +1,225 @@
1
+ import { join } from 'node:path'
2
+
3
+ import { config, getSandboxWritablePathSpecs } from '@/config/config'
4
+ import type { PermissionService } from '@/permissions/permissions'
5
+ import {
6
+ buildSandboxedCommand,
7
+ canWriteAgentRootInSandbox,
8
+ cleanupPrivilegedSandboxRuntime,
9
+ commandNeedsRealProc,
10
+ DEFAULT_SANDBOX_ENV,
11
+ DEPENDENCY_BIN_SANDBOX_DIR,
12
+ ensureBwrapAvailable,
13
+ ensureHiddenMaskTargets,
14
+ ensureSessionTmpDir,
15
+ reconcileDependencyBinWrappers,
16
+ resolveHiddenPaths,
17
+ resolvePrivilegedSandboxRuntime,
18
+ resolveProcSelfExe,
19
+ resolveProtectedZones,
20
+ resolveSandboxSymlinks,
21
+ resolveWritableZones,
22
+ SandboxDegradedProcError,
23
+ SandboxProcProbeUnverifiedError,
24
+ subtractMasked,
25
+ verifyHiddenMaskTargets,
26
+ verifyPrivilegedSandboxRuntime,
27
+ type SandboxMount,
28
+ type SandboxNetwork,
29
+ type SandboxPolicy,
30
+ type DependencyBinReconciliation,
31
+ } from '@/sandbox'
32
+ import { resolveDevSourceMount } from '@/sandbox/dev-source'
33
+
34
+ import {
35
+ buildRoleScopedConfigEnv,
36
+ buildSandboxEnvPolicy,
37
+ resolveExposableBashEnvNames,
38
+ spreadSandboxEnv,
39
+ } from './bash-sandbox-env'
40
+ import { resolveProcStrategy, type ProcStrategyResolution } from './bash-sandbox-proc'
41
+ import type { SessionOrigin } from './session-origin'
42
+ export type DeferredBashPreparationResult = {
43
+ command: string
44
+ env?: Record<string, string>
45
+ mount: Extract<SandboxMount, { type: 'ro-bind' }>
46
+ cleanup: () => Promise<void>
47
+ }
48
+ export type DeferredBashPreparation = () => Promise<DeferredBashPreparationResult>
49
+ export type BashSandboxBoundary = {
50
+ ensureAvailable: () => Promise<void>
51
+ buildCommand: typeof buildSandboxedCommand
52
+ resolveProcStrategy?: () => Promise<ProcStrategyResolution>
53
+ resolveRuntime?: typeof resolvePrivilegedSandboxRuntime
54
+ verifyRuntime?: typeof verifyPrivilegedSandboxRuntime
55
+ cleanupRuntime?: typeof cleanupPrivilegedSandboxRuntime
56
+ }
57
+
58
+ const DEFAULT_BASH_SANDBOX_BOUNDARY: BashSandboxBoundary = {
59
+ ensureAvailable: ensureBwrapAvailable,
60
+ buildCommand: buildSandboxedCommand,
61
+ }
62
+
63
+ type BashFilesystemPolicyOptions = {
64
+ agentDir: string
65
+ canWriteAgentRoot: boolean
66
+ masks: { dirs: string[]; files: string[] }
67
+ writable: { dirs: string[]; files: string[] }
68
+ protected: { dirs: string[]; files: string[] }
69
+ }
70
+
71
+ export type PreparedBashSandbox = {
72
+ commandString: string
73
+ policy: SandboxPolicy
74
+ verify: () => Promise<void>
75
+ cleanup: () => Promise<void>
76
+ spawnEnv: Record<string, string>
77
+ dependencyBins?: DependencyBinReconciliation
78
+ withheld: {
79
+ paths: { dirs: string[]; files: string[] }
80
+ envNames: string[]
81
+ }
82
+ }
83
+
84
+ export function buildBashFilesystemPolicy(options: BashFilesystemPolicyOptions) {
85
+ const { agentDir, canWriteAgentRoot, masks, writable, protected: protectedZones } = options
86
+ if (canWriteAgentRoot) {
87
+ return { writableRoot: { dir: agentDir }, masks, protected: protectedZones }
88
+ }
89
+ return { masks, writable, protected: protectedZones }
90
+ }
91
+
92
+ export type BashSandboxRequest = {
93
+ readonly command: string
94
+ readonly permissions: PermissionService
95
+ readonly origin: SessionOrigin | undefined
96
+ readonly agentDir: string
97
+ readonly sessionId: string
98
+ readonly envOverlay?: Record<string, string>
99
+ readonly envWithhold?: string[]
100
+ readonly deferredPreparation?: DeferredBashPreparation
101
+ readonly boundary?: BashSandboxBoundary
102
+ readonly network?: SandboxNetwork
103
+ }
104
+
105
+ // Shared preparation for model bash and eval. The caller owns verification
106
+ // immediately before spawn and cleanup after the process has exited.
107
+ export async function prepareBashSandbox(options: BashSandboxRequest): Promise<PreparedBashSandbox> {
108
+ const {
109
+ command: originalCommand,
110
+ permissions,
111
+ origin,
112
+ agentDir,
113
+ sessionId,
114
+ envOverlay,
115
+ envWithhold,
116
+ deferredPreparation,
117
+ } = options
118
+ const boundary = options.boundary ?? DEFAULT_BASH_SANDBOX_BOUNDARY
119
+ let preparation: DeferredBashPreparationResult | undefined
120
+ let privilegedRuntime: Awaited<ReturnType<typeof resolvePrivilegedSandboxRuntime>> | undefined
121
+ const cleanup = async (): Promise<void> => {
122
+ const tasks: Promise<void>[] = []
123
+ if (privilegedRuntime !== undefined) {
124
+ tasks.push((boundary.cleanupRuntime ?? cleanupPrivilegedSandboxRuntime)(privilegedRuntime))
125
+ }
126
+ if (preparation !== undefined) tasks.push(preparation.cleanup())
127
+ const outcomes = await Promise.allSettled(tasks)
128
+ const failure = outcomes.find((outcome) => outcome.status === 'rejected')
129
+ if (failure?.status === 'rejected') throw failure.reason
130
+ }
131
+ try {
132
+ preparation = await deferredPreparation?.()
133
+ const command = preparation?.command ?? originalCommand
134
+ const preparedEnvOverlay = preparation?.env === undefined ? envOverlay : { ...envOverlay, ...preparation.env }
135
+ const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
136
+ const envNames = resolveExposableBashEnvNames(agentDir)
137
+ const sandboxEnvOverlay = buildRoleScopedConfigEnv(agentDir, dirs, preparedEnvOverlay)
138
+ const effectiveEnvWithhold = (envWithhold ?? []).filter((name) => !Object.hasOwn(sandboxEnvOverlay ?? {}, name))
139
+ const maskTargets = await ensureHiddenMaskTargets({ dirs, files })
140
+ await boundary.ensureAvailable()
141
+ const sessionTmp = await ensureSessionTmpDir(sessionId)
142
+ const dependencyBins = await reconcileDependencyBinWrappers({ agentDir, sessionTmp })
143
+ const writable = subtractMasked(await resolveWritableZones(agentDir, getSandboxWritablePathSpecs(config)), {
144
+ dirs,
145
+ files,
146
+ })
147
+ const writableRoot = canWriteAgentRootInSandbox(permissions, origin)
148
+ const baseProtectedZones =
149
+ writableRoot || writable.dirs.includes(join(agentDir, '.git'))
150
+ ? subtractMasked(await resolveProtectedZones(agentDir), { dirs, files })
151
+ : { dirs: [], files: [] }
152
+ const protectedZones = {
153
+ dirs: baseProtectedZones.dirs,
154
+ files: [...new Set([...baseProtectedZones.files, ...dependencyBins.protectedFiles])],
155
+ }
156
+ const writableDirSet = new Set(writable.dirs)
157
+ const sandboxHome = DEFAULT_SANDBOX_ENV.HOME ?? '/tmp'
158
+ const symlinks = resolveSandboxSymlinks(agentDir, config.sandbox.symlinks, sandboxHome).filter((op) =>
159
+ writableDirSet.has(op.target),
160
+ )
161
+ const { strategy: proc, degradeReason } = await (boundary.resolveProcStrategy ?? resolveProcStrategy)()
162
+ if (proc === 'tmpfs' && commandNeedsRealProc(command)) {
163
+ throw degradeReason === 'unverified' ? new SandboxProcProbeUnverifiedError() : new SandboxDegradedProcError()
164
+ }
165
+ privilegedRuntime = await (boundary.resolveRuntime ?? resolvePrivilegedSandboxRuntime)({
166
+ agentDir,
167
+ command,
168
+ env: sandboxEnvOverlay,
169
+ })
170
+ await verifyHiddenMaskTargets(maskTargets)
171
+ const devSourceMount = await resolveDevSourceMount(agentDir)
172
+ const policy: SandboxPolicy = {
173
+ mounts: [
174
+ { type: 'ro-bind', source: agentDir, dest: agentDir },
175
+ { type: 'bind', source: sessionTmp, dest: '/tmp' },
176
+ // `/tmp` is writable, but PATH entries must remain runtime-owned for
177
+ // the lifetime of this command. Last-op-wins makes this narrow re-bind
178
+ // read-only without adding any broader filesystem exposure.
179
+ { type: 'ro-bind', source: dependencyBins.wrapperDir, dest: DEPENDENCY_BIN_SANDBOX_DIR },
180
+ // The running Bun ELF is runtime-owned, not a model-selected path.
181
+ // Dev/CI installations may place it outside /usr; expose only the
182
+ // executable, never its parent directory, under every proc strategy.
183
+ { type: 'ro-bind', source: process.execPath, dest: process.execPath },
184
+ ...(devSourceMount === undefined ? [] : [devSourceMount]),
185
+ ...(privilegedRuntime?.mounts ?? []),
186
+ ...(preparation === undefined ? [] : [preparation.mount]),
187
+ ],
188
+ ...buildBashFilesystemPolicy({
189
+ agentDir,
190
+ canWriteAgentRoot: writableRoot,
191
+ masks: maskTargets,
192
+ writable,
193
+ protected: protectedZones,
194
+ }),
195
+ symlinks,
196
+ network: options.network ?? 'inherit',
197
+ cwd: agentDir,
198
+ proc,
199
+ procSelfExe: resolveProcSelfExe(),
200
+ ...spreadSandboxEnv(
201
+ buildSandboxEnvPolicy(sandboxEnvOverlay, privilegedRuntime?.env, envNames.exposable, envWithhold),
202
+ ),
203
+ }
204
+ const { commandString, spawnEnv } = boundary.buildCommand(command, policy)
205
+ // The overlay carries command-scoped secret VALUES (e.g. a per-repo GH_TOKEN)
206
+ // that live in neither process.env nor argv; resolveSpawnEnv snapshots
207
+ // inherited names from process.env only, so merge the overlay values in here
208
+ // to complete the exact bwrap-parent env.
209
+ const mergedSpawnEnv =
210
+ spawnEnv !== undefined && sandboxEnvOverlay !== undefined ? { ...spawnEnv, ...sandboxEnvOverlay } : spawnEnv
211
+ const runtimeForResult = privilegedRuntime
212
+ return {
213
+ commandString,
214
+ policy,
215
+ verify: async () => (boundary.verifyRuntime ?? verifyPrivilegedSandboxRuntime)(runtimeForResult),
216
+ cleanup,
217
+ spawnEnv: mergedSpawnEnv,
218
+ dependencyBins,
219
+ withheld: { paths: maskTargets, envNames: [...new Set([...envNames.withheld, ...effectiveEnvWithhold])] },
220
+ }
221
+ } catch (error) {
222
+ await cleanup()
223
+ throw error
224
+ }
225
+ }
@@ -9,35 +9,47 @@ import { SettingsManager } from '@earendil-works/pi-coding-agent'
9
9
  // drifts to ~94% on a 256K window and ~98% on 1M.
10
10
  export const COMPACTION_TRIGGER_PERCENT = 0.8
11
11
 
12
- // Absolute ceiling on the compaction trigger, independent of window size. The
12
+ // Default ceiling on the compaction trigger, independent of window size. The
13
13
  // window-relative trigger alone optimizes for overflow avoidance, not token
14
14
  // cost: at 80% of a large window a session accumulates ~160K (200K window) to
15
15
  // ~800K (1M window) tokens of history that get re-shipped as `cacheRead` every
16
16
  // turn before compaction ever fires. Capping the trigger bounds that
17
17
  // steady-state re-read on big-window models; `min()` keeps the 80% behavior on
18
- // small ones. 64K is 3x keepRecent (invariant asserted in the test), leaving
19
- // growth room after a compaction so it does not retrigger immediately.
20
- export const COMPACTION_ABSOLUTE_TRIGGER_TOKENS = 64_000
18
+ // small ones. The ceiling was 64K and is now 200K: at 64K a long investigation
19
+ // compacted every few turns (six times in forty minutes in one production
20
+ // channel session), and each summary dropped the raw evidence later turns had
21
+ // to reason over. Cached re-reads are cheap; losing the working set costs
22
+ // correctness. 200K stays 10x keepRecent (the >=3x invariant is asserted in
23
+ // the test), so a compaction never retriggers immediately. Each agent can set
24
+ // its own ceiling for its workload with `compaction.maxTriggerTokens` in
25
+ // typeclaw.json; this value is the default.
26
+ export const COMPACTION_ABSOLUTE_TRIGGER_TOKENS = 200_000
21
27
 
22
28
  // Tokens to keep in the recent window after compaction. Fixed (not a
23
29
  // percentage) because "recent context" is a property of conversation shape, not
24
30
  // model capacity. Mirrors pi's DEFAULT_COMPACTION_SETTINGS.keepRecentTokens.
25
31
  export const COMPACTION_KEEP_RECENT_TOKENS = 20_000
26
32
 
27
- export function compactionTriggerTokens<TApi extends KnownApi>(model: Model<TApi>): number {
33
+ export function compactionTriggerTokens<TApi extends KnownApi>(
34
+ model: Model<TApi>,
35
+ maxTriggerTokens: number = COMPACTION_ABSOLUTE_TRIGGER_TOKENS,
36
+ ): number {
28
37
  const windowRelative = Math.round(model.contextWindow * COMPACTION_TRIGGER_PERCENT)
29
- return Math.min(windowRelative, COMPACTION_ABSOLUTE_TRIGGER_TOKENS)
38
+ return Math.min(windowRelative, maxTriggerTokens)
30
39
  }
31
40
 
32
- export function reserveTokensForModel<TApi extends KnownApi>(model: Model<TApi>): number {
33
- return Math.max(1, model.contextWindow - compactionTriggerTokens(model))
41
+ export function reserveTokensForModel<TApi extends KnownApi>(model: Model<TApi>, maxTriggerTokens?: number): number {
42
+ return Math.max(1, model.contextWindow - compactionTriggerTokens(model, maxTriggerTokens))
34
43
  }
35
44
 
36
- export function createCompactionSettingsManager<TApi extends KnownApi>(model: Model<TApi>): SettingsManager {
45
+ export function createCompactionSettingsManager<TApi extends KnownApi>(
46
+ model: Model<TApi>,
47
+ maxTriggerTokens?: number,
48
+ ): SettingsManager {
37
49
  return SettingsManager.inMemory({
38
50
  compaction: {
39
51
  enabled: true,
40
- reserveTokens: reserveTokensForModel(model),
52
+ reserveTokens: reserveTokensForModel(model, maxTriggerTokens),
41
53
  keepRecentTokens: COMPACTION_KEEP_RECENT_TOKENS,
42
54
  },
43
55
  })