typeclaw 0.48.1 → 0.48.3

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 (39) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +35 -9
  3. package/src/agent/plugin-tools.ts +14 -0
  4. package/src/agent/system-prompt.ts +8 -0
  5. package/src/agent/todo/continuation-policy.ts +11 -1
  6. package/src/agent/todo/continuation-state.ts +3 -1
  7. package/src/agent/todo/continuation-wiring.ts +2 -0
  8. package/src/agent/tool-file-safety.ts +7 -1
  9. package/src/agent/tools/channel-reply.ts +18 -1
  10. package/src/bundled-plugins/guard/policies/managed-config.ts +7 -20
  11. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +7 -20
  12. package/src/bundled-plugins/guard/policies/skill-authoring.ts +8 -20
  13. package/src/bundled-plugins/memory/README.md +2 -0
  14. package/src/bundled-plugins/memory/dreaming.ts +2 -0
  15. package/src/bundled-plugins/security/policies/private-surface-read.ts +98 -55
  16. package/src/channels/adapters/discord-bot-reactions.ts +1 -0
  17. package/src/channels/adapters/discord-bot.ts +11 -2
  18. package/src/channels/adapters/discord-reactions.ts +1 -0
  19. package/src/channels/adapters/discord.ts +1 -0
  20. package/src/channels/adapters/slack-bot.ts +11 -2
  21. package/src/channels/adapters/slack.ts +1 -0
  22. package/src/channels/completion-claim.ts +307 -0
  23. package/src/channels/router.ts +275 -55
  24. package/src/channels/types.ts +4 -1
  25. package/src/config/providers.ts +100 -20
  26. package/src/container/start.ts +42 -0
  27. package/src/init/models-dev.ts +25 -8
  28. package/src/mcp/client.ts +65 -7
  29. package/src/mcp/tools.ts +71 -4
  30. package/src/path-safety/real-intended-path.ts +111 -0
  31. package/src/permissions/index.ts +1 -0
  32. package/src/permissions/permissions.ts +23 -0
  33. package/src/plugin/manager.ts +19 -1
  34. package/src/sandbox/canonical-secrets.ts +24 -4
  35. package/src/sandbox/hidden-paths.ts +8 -3
  36. package/src/sandbox/index.ts +2 -0
  37. package/src/skills/typeclaw-permissions/SKILL.md +13 -1
  38. package/src/skills/typeclaw-plugins/SKILL.md +91 -11
  39. package/typeclaw.schema.json +5 -0
@@ -781,10 +781,20 @@ export const KNOWN_PROVIDERS = {
781
781
  // the console, the OpenAI-SDK example, and the agent docs all use bare `/v1`.
782
782
  //
783
783
  // Model lineup spans two families on the same Console API + key:
784
- // * Closed chat models from the official agent API reference
785
- // (console.upstage.ai/api/docs/for-agents) as of 2026-03-23:
786
- // solar-pro3 (102B MoE / 12B active, 128K, flagship), solar-pro2
787
- // (31B, 65K), solar-mini (10.7B, 32K, cheap/fast).
784
+ // * Closed chat models, per the live model pages under
785
+ // console.upstage.ai/docs/models — solar-pro-4, solar-pro-3,
786
+ // solar-pro-2, solar-mini (the slugs are hyphenated; the unhyphenated
787
+ // form 404s): solar-pro4 (524288 context / 131072 output, released
788
+ // 2026-08-06, current flagship), solar-pro3 (102B MoE / 12B active,
789
+ // 128000), solar-pro2 (31B, 65536), solar-mini (10.7B, 32768,
790
+ // cheap/fast). The contextWindow values below are those exact
791
+ // documented figures. Upstage publishes NO maximum output length for
792
+ // pro3/pro2/mini, so their maxTokens are deliberate conservative
793
+ // choices of ours rather than sourced numbers — do not "correct" them
794
+ // against a third-party catalog that states one. The older agent API
795
+ // reference (console.upstage.ai/api/docs/for-agents) is stale
796
+ // (self-dated 2026-03-07) and omits pro4 — its absence there is not
797
+ // evidence the model is unavailable.
788
798
  // * The open-weight Solar Open family: solar-open2 (Solar Open 2), a 102B
789
799
  // MoE / 12B active model with a 128K context. It launched on the Console
790
800
  // API for the Solar Agent Partner program (Stage 1, from 2026-07-17) —
@@ -799,6 +809,7 @@ export const KNOWN_PROVIDERS = {
799
809
  // versioned release.
800
810
  //
801
811
  // Costs are USD per 1M tokens from upstage.ai/pricing/api (VAT-exclusive).
812
+ // solar-pro4 is $0.30 in / $1.20 out with a $0.06 "Input(Cached)" rate.
802
813
  // solar-pro3/pro2 publish an "Input(Cached)" cache-read rate ($0.015); no
803
814
  // cache-write surcharge is published, so cacheWrite is 0. solar-mini
804
815
  // publishes a single flat $0.15 rate with no cache line, so cacheRead and
@@ -819,18 +830,37 @@ export const KNOWN_PROVIDERS = {
819
830
  // definitions are both undocumented, so supportsUsageInStreaming and
820
831
  // supportsStrictMode are false (both conservative — pi-ai defaults them to
821
832
  // true, and Upstage only documents `strict` inside response_format.json_schema,
822
- // never on tool defs). `reasoning_effort` IS documented for solar-pro3/pro2
823
- // (and the solar-open2 chat template), so supportsReasoningEffort stays true
824
- // there; solar-mini ignores it, so it is false and reasoning is off.
833
+ // never on tool defs). `reasoning_effort` IS documented for solar-pro4,
834
+ // solar-open2, solar-pro3 and solar-pro2, so supportsReasoningEffort stays
835
+ // true there; solar-mini rejects it, so it is false and reasoning is off.
825
836
  //
826
- // Upstage documents reasoning_effort values minimal/low/medium/high only. pi
827
- // adds an `xhigh` level that typeclaw's attention escalation can select
828
- // (src/agent/attention-escalation.ts), and pi-ai passes the pi level straight
829
- // through as reasoning_effort when no map is set — which would send the
830
- // unsupported `xhigh`. `thinkingLevelMap` clamps xhigh -> high (and maps off ->
831
- // null so nothing is sent) on the reasoning models so every emitted
832
- // reasoning_effort is a value Upstage accepts. solar-mini needs no map (it
833
- // never sends reasoning_effort).
837
+ // Reasoning splits the lineup into two groups with OPPOSITE defaults, per
838
+ // Upstage's reasoning table (console.upstage.ai/docs/capabilities/generate/
839
+ // reasoning). pi adds an `xhigh` level that typeclaw's attention escalation
840
+ // can select (src/agent/attention-escalation.ts), and pi-ai passes the pi
841
+ // level straight through as reasoning_effort when no map is set, so each
842
+ // group needs a different `thinkingLevelMap`:
843
+ //
844
+ // * solar-pro4 and solar-open2 — omitted reasoning_effort means reasoning
845
+ // is ON; `none`/`minimal` turn it OFF; low/medium/high/xhigh/max turn it
846
+ // on. So `off` maps to the string 'none', NOT null: pi-ai emits a string
847
+ // off value verbatim and omits the field only when it is null, and
848
+ // omitting it here would silently leave reasoning enabled (and billed) on
849
+ // every non-reasoning turn. `xhigh` is documented, so it passes through
850
+ // unclamped. Upstage's `max` sits above xhigh, but pi has no level above
851
+ // xhigh to reach it, so `max` is intentionally unreachable.
852
+ // * solar-pro3 and solar-pro2 — omitted means reasoning is OFF, `minimal`
853
+ // and `low` ALSO turn it off, and only `medium`/`high` turn it on. So
854
+ // `off` maps to null (nothing sent) and xhigh clamps to high.
855
+ //
856
+ // Note the trap in both rows: Upstage's `minimal` is an OFF value, but pi's
857
+ // `minimal` is an enabled level meaning "reason a little". Forwarding it
858
+ // verbatim would silently disable reasoning on a request that asked for it.
859
+ // Each group therefore floors pi's enabled levels at its own lowest
860
+ // reasoning-ON value — `low` for pro4/open2, `medium` for pro3/pro2 (which is
861
+ // why pi's `low` also maps to `medium` there). Every level pi can select thus
862
+ // emits a value Upstage treats as reasoning-on. solar-mini needs no map: it
863
+ // does not accept reasoning_effort at all (any value returns HTTP 400).
834
864
  upstage: {
835
865
  id: 'upstage',
836
866
  name: 'Upstage (Solar)',
@@ -839,6 +869,35 @@ export const KNOWN_PROVIDERS = {
839
869
  apiKeyEnv: 'UPSTAGE_API_KEY',
840
870
  oauthProviderId: null,
841
871
  models: {
872
+ 'solar-pro4': {
873
+ id: 'solar-pro4',
874
+ name: 'Solar Pro 4',
875
+ api: 'openai-completions',
876
+ provider: 'upstage',
877
+ baseUrl: 'https://api.upstage.ai/v1',
878
+ reasoning: true,
879
+ // pro4 and open2 reason by DEFAULT — see the reasoning-group note above.
880
+ thinkingLevelMap: {
881
+ off: 'none',
882
+ minimal: 'low',
883
+ low: 'low',
884
+ medium: 'medium',
885
+ high: 'high',
886
+ xhigh: 'xhigh',
887
+ },
888
+ input: ['text'],
889
+ cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
890
+ contextWindow: 524288,
891
+ maxTokens: 131072,
892
+ compat: {
893
+ supportsStore: false,
894
+ supportsDeveloperRole: false,
895
+ supportsReasoningEffort: true,
896
+ supportsUsageInStreaming: false,
897
+ supportsStrictMode: false,
898
+ maxTokensField: 'max_tokens',
899
+ },
900
+ },
842
901
  'solar-open2': {
843
902
  id: 'solar-open2',
844
903
  name: 'Solar Open 2',
@@ -846,7 +905,14 @@ export const KNOWN_PROVIDERS = {
846
905
  provider: 'upstage',
847
906
  baseUrl: 'https://api.upstage.ai/v1',
848
907
  reasoning: true,
849
- thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
908
+ thinkingLevelMap: {
909
+ off: 'none',
910
+ minimal: 'low',
911
+ low: 'low',
912
+ medium: 'medium',
913
+ high: 'high',
914
+ xhigh: 'xhigh',
915
+ },
850
916
  input: ['text'],
851
917
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
852
918
  contextWindow: 128000,
@@ -867,7 +933,14 @@ export const KNOWN_PROVIDERS = {
867
933
  provider: 'upstage',
868
934
  baseUrl: 'https://api.upstage.ai/v1',
869
935
  reasoning: true,
870
- thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
936
+ thinkingLevelMap: {
937
+ off: null,
938
+ minimal: 'medium',
939
+ low: 'medium',
940
+ medium: 'medium',
941
+ high: 'high',
942
+ xhigh: 'high',
943
+ },
871
944
  input: ['text'],
872
945
  cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
873
946
  contextWindow: 128000,
@@ -888,10 +961,17 @@ export const KNOWN_PROVIDERS = {
888
961
  provider: 'upstage',
889
962
  baseUrl: 'https://api.upstage.ai/v1',
890
963
  reasoning: true,
891
- thinkingLevelMap: { off: null, minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'high' },
964
+ thinkingLevelMap: {
965
+ off: null,
966
+ minimal: 'medium',
967
+ low: 'medium',
968
+ medium: 'medium',
969
+ high: 'high',
970
+ xhigh: 'high',
971
+ },
892
972
  input: ['text'],
893
973
  cost: { input: 0.15, output: 0.6, cacheRead: 0.015, cacheWrite: 0 },
894
- contextWindow: 65000,
974
+ contextWindow: 65536,
895
975
  maxTokens: 16000,
896
976
  compat: {
897
977
  supportsStore: false,
@@ -911,7 +991,7 @@ export const KNOWN_PROVIDERS = {
911
991
  reasoning: false,
912
992
  input: ['text'],
913
993
  cost: { input: 0.15, output: 0.15, cacheRead: 0, cacheWrite: 0 },
914
- contextWindow: 32000,
994
+ contextWindow: 32768,
915
995
  maxTokens: 8000,
916
996
  compat: {
917
997
  supportsStore: false,
@@ -724,6 +724,47 @@ export async function planStart({
724
724
  // misattribute to bot detection. 2g matches the Playwright/Puppeteer
725
725
  // canonical recommendation and is a memory cap, not an allocation (only
726
726
  // used pages count against the host).
727
+ // `--init` puts Docker's bundled `docker-init` (tini) at PID 1 and demotes
728
+ // the entrypoint shim to PID 2. It is load-bearing, not hygiene: without it
729
+ // the container leaks a kernel user namespace on every aborted or timed-out
730
+ // model bash call, until every `bwrap` in the container — and in every other
731
+ // typeclaw container on the same host — dies with
732
+ // `unshare user ns: No space left on device`.
733
+ //
734
+ // The chain: each model bash call runs the sandbox under `bash -c`, and the
735
+ // sandbox mints a fresh user namespace per call on BOTH strategies — under
736
+ // the default `proc-bind`/`tmpfs` it is `bwrap --unshare-all`, while
737
+ // `sandbox.realProc` splits the pid namespace out into `unshare --pid --fork
738
+ // --mount --mount-proc` and has bwrap take the user namespace via an
739
+ // explicit `--unshare-user` (see buildArgv in src/sandbox/build.ts). On
740
+ // timeout or abort the upstream bash tool SIGKILLs the process GROUP, then
741
+ // reaps its own direct `bash` child by waiting on the handle it holds. The
742
+ // sandbox descendant it holds no handle for is re-parented to PID 1 instead.
743
+ // Since the shim `exec`s into bun, PID 1 was the Bun runtime — and a JS
744
+ // runtime never `wait()`s on orphans it did not spawn, so that descendant
745
+ // stays a zombie for the life of the container. A zombie drops its
746
+ // `nsproxy` at `do_exit()` (so
747
+ // mount/net namespaces are freed early) but keeps its `struct cred` until
748
+ // it is reaped, and `cred->user_ns` pins the user namespace; its surviving
749
+ // `struct pid` pins the pid namespace, which pins that same user namespace
750
+ // again. The `UCOUNT_USER_NAMESPACES` charge is only returned by
751
+ // `free_user_ns()`, so it is never returned at all.
752
+ //
753
+ // That charge is accounted against the ANCESTOR (host) user namespace, so
754
+ // the exhausted resource is the host kernel's `user.max_user_namespaces`,
755
+ // shared across every container on the box. Raising the host sysctl only
756
+ // buys time; reaping is the fix. tini reaps re-parented orphans, which
757
+ // releases the creds and returns the ucount.
758
+ //
759
+ // Chosen over baking `tini` into the image because the per-agent Dockerfile
760
+ // pins a PUBLISHED `typeclaw-base:X.Y.Z` (see refreshDockerfile): a new
761
+ // baseline apt package would not exist in already-released base tags. This
762
+ // flag needs no image change and takes effect on the next container create.
763
+ // `--init` is create-time state, so a container launched before this flag
764
+ // existed keeps leaking: `start()` deliberately no-ops on a live container.
765
+ // Operators must `typeclaw restart` (removes and recreates), not
766
+ // `docker restart` (reuses the old HostConfig).
767
+ //
727
768
  // `seccomp=unconfined` lets `bwrap(1)` (installed in baseline; see
728
769
  // BASELINE_APT_PACKAGES in src/init/dockerfile.ts) create user/pid/mount
729
770
  // namespaces from inside the container. Docker's default seccomp profile
@@ -742,6 +783,7 @@ export async function planStart({
742
783
  const runArgs = [
743
784
  'run',
744
785
  '-d',
786
+ '--init',
745
787
  '--name',
746
788
  containerName,
747
789
  '--shm-size=2g',
@@ -38,9 +38,12 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string | null> = {
38
38
  xai: 'xai',
39
39
  minimax: 'minimax',
40
40
  deepseek: 'deepseek',
41
- // Upstage is not listed on models.dev (checked api.json — no `upstage` lab
42
- // entry, only HuggingFace open-model ids). Mapping to `upstage` is harmless:
43
- // the upstream lookup misses and the curated Solar entries surface anyway.
41
+ // models.dev has listed Upstage since 2025-07-09 (solar-pro2 + solar-mini,
42
+ // then solar-pro3 on 2026-01-13 and solar-pro4 on 2026-08-06), so this
43
+ // mapping hits rather than misses — harmless either way, since `buildOption`
44
+ // lets upstream fill gaps but never override the curated Solar records, and
45
+ // those specify every field. solar-open2 is partner-program only and still
46
+ // absent upstream, so it surfaces curated.
44
47
  upstage: 'upstage',
45
48
  moonshot: 'moonshot',
46
49
  // moonshot-coding (Kimi Code subscription) is a billing surface, not a
@@ -303,6 +306,19 @@ type BuildOptionOpts = {
303
306
  upstream?: ModelsDevModel
304
307
  }
305
308
 
309
+ // The curated record wins every field it specifies; upstream only fills gaps.
310
+ // A known ref always resolves to the curated record at runtime — `resolveModel`
311
+ // reads `KNOWN_PROVIDERS`, never models.dev, and `customModelMetaFromOption`
312
+ // declines to persist metadata for known refs — so letting upstream win here
313
+ // only desynchronized the picker from the model it was describing. It showed in
314
+ // what `formatModelLabel`/`formatModelHint` render (name, context, reasoning):
315
+ // models.dev names solar-pro3/pro2/mini with their bare ids, so the picker
316
+ // offered "solar-pro3" where the curated record says "Solar Pro 3". maxTokens
317
+ // and cost reach no surface today, so aligning them is consistency within the
318
+ // record, not a visible fix. `supportsVision` already resolved this way (see
319
+ // `resolveInput`, and the note on `ModelOption.supportsVision`); this extends
320
+ // the rule to the rest. Refs we do not curate still take everything from
321
+ // upstream, which is the whole point of merging it in.
306
322
  function buildOption(ref: ModelRef | string, opts: BuildOptionOpts): ModelOption {
307
323
  const providerId = providerForModelRef(ref)
308
324
  const modelId = ref.slice(providerId.length + 1)
@@ -316,6 +332,7 @@ function buildOption(ref: ModelRef | string, opts: BuildOptionOpts): ModelOption
316
332
  maxTokens?: number
317
333
  reasoning?: boolean
318
334
  input?: ReadonlyArray<string>
335
+ cost?: ModelOptionCost
319
336
  }
320
337
  >
321
338
  )[modelId]
@@ -325,11 +342,11 @@ function buildOption(ref: ModelRef | string, opts: BuildOptionOpts): ModelOption
325
342
  providerId,
326
343
  providerName: provider.name,
327
344
  modelId,
328
- modelName: opts.upstream?.name ?? curatedModel?.name ?? modelId,
329
- reasoning: opts.upstream?.reasoning ?? curatedModel?.reasoning ?? false,
330
- contextWindow: opts.upstream?.limit?.context ?? curatedModel?.contextWindow ?? null,
331
- maxTokens: opts.upstream?.limit?.output ?? curatedModel?.maxTokens ?? null,
332
- cost: resolveCost(opts.upstream?.cost),
345
+ modelName: curatedModel?.name ?? opts.upstream?.name ?? modelId,
346
+ reasoning: curatedModel?.reasoning ?? opts.upstream?.reasoning ?? false,
347
+ contextWindow: curatedModel?.contextWindow ?? opts.upstream?.limit?.context ?? null,
348
+ maxTokens: curatedModel?.maxTokens ?? opts.upstream?.limit?.output ?? null,
349
+ cost: curatedModel?.cost ?? resolveCost(opts.upstream?.cost),
333
350
  curated: opts.curated,
334
351
  supportsVision: input.includes('image'),
335
352
  }
package/src/mcp/client.ts CHANGED
@@ -7,14 +7,24 @@ import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
7
7
  import { CallToolResultSchema, type CallToolResult, type ListToolsRequest } from '@modelcontextprotocol/sdk/types.js'
8
8
 
9
9
  import type { McpServer } from '@/config/config'
10
+ import type { ToolFileOperands } from '@/plugin'
10
11
  import { resolveSecret } from '@/secrets/resolve'
11
12
 
12
13
  export type McpToolInfo = {
13
14
  name: string
14
15
  description: string
15
16
  inputSchema: unknown
17
+ // Declared by MCP servers via the tool's `_meta['x-file-operands']`; consumed
18
+ // by the mcp_call dispatcher so the file-operand scanner honors tool-authored
19
+ // nonFile operand paths instead of rejecting free-text args that look path-shaped.
20
+ fileOperands?: ToolFileOperands
16
21
  }
17
22
 
23
+ // The wire key an MCP server sets on a tool's `_meta` to declare its operands.
24
+ // `_meta` is an arbitrary record in the MCP spec and survives the server → wire
25
+ // → client round-trip through the official SDK unchanged.
26
+ export const MCP_FILE_OPERANDS_META_KEY = 'x-file-operands'
27
+
18
28
  // The SDK defaults each request to 60s; typeclaw boot should fail fast enough
19
29
  // that one dead MCP server does not make the agent feel hung at startup.
20
30
  export const DEFAULT_MCP_REQUEST_TIMEOUT_MS = 30_000
@@ -23,17 +33,56 @@ export const DEFAULT_MCP_CONNECT_TIMEOUT_MS = 15_000
23
33
  export type McpConnection = {
24
34
  name: string
25
35
  listTools(): Promise<McpToolInfo[]>
36
+ // Cache-only view of the last successful listTools(). Returns undefined until
37
+ // the catalog has been fetched once, and never performs I/O — the pre-execution
38
+ // file-operand preflight reads target metadata through this so resolving it can
39
+ // never spawn a stdio server or open an HTTP session before the security hooks run.
40
+ peekTools(): McpToolInfo[] | undefined
26
41
  refresh(): Promise<McpToolInfo[]>
27
42
  callTool(toolName: string, args?: Record<string, unknown>): Promise<CallToolResult>
28
43
  close(): Promise<void>
29
44
  }
30
45
 
46
+ const FILE_OPERAND_CATEGORIES = ['input', 'output', 'create', 'destructive', 'nonFile'] as const
47
+
48
+ // Wire metadata is server-controlled, so it is parsed rather than cast: a
49
+ // declaration like `{ nonFile: 'query' }` would otherwise reach the scanner as a
50
+ // string and have `.includes()` grant a substring-wide exemption. Any malformed
51
+ // recognized category discards the WHOLE declaration (fail closed) instead of
52
+ // honoring the well-formed remainder, so a partially-corrupt payload can never
53
+ // silently widen the scanned surface.
54
+ export function parseDeclaredFileOperands(meta: Record<string, unknown> | undefined): ToolFileOperands | undefined {
55
+ if (typeof meta !== 'object' || meta === null) return undefined
56
+ const declared = meta[MCP_FILE_OPERANDS_META_KEY]
57
+ if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) return undefined
58
+
59
+ const parsed: Record<string, readonly string[]> = {}
60
+ const claimed = new Set<string>()
61
+ for (const category of FILE_OPERAND_CATEGORIES) {
62
+ const value = (declared as Record<string, unknown>)[category]
63
+ if (value === undefined) continue
64
+ if (!Array.isArray(value)) return undefined
65
+ if (!value.every((entry) => typeof entry === 'string' && entry.trim() !== '')) return undefined
66
+ // One operand path cannot be two things at once, and the combinations are
67
+ // not merely redundant but contradictory: `nonFile` claims a value is never
68
+ // dereferenced locally while `input` claims it is a real file to snapshot.
69
+ // Resolving such a conflict by precedence would make the effective policy
70
+ // depend on category order, so reject the declaration instead.
71
+ for (const operandPath of value as string[]) {
72
+ if (claimed.has(operandPath)) return undefined
73
+ claimed.add(operandPath)
74
+ }
75
+ parsed[category] = [...(value as string[])]
76
+ }
77
+ return Object.keys(parsed).length === 0 ? undefined : (parsed as ToolFileOperands)
78
+ }
79
+
31
80
  export type McpSdkClient = {
32
81
  listTools(
33
82
  params?: ListToolsRequest['params'],
34
83
  options?: RequestOptions,
35
84
  ): Promise<{
36
- tools: { name: string; description?: string; inputSchema: unknown }[]
85
+ tools: { name: string; description?: string; inputSchema: unknown; _meta?: Record<string, unknown> }[]
37
86
  nextCursor?: string
38
87
  }>
39
88
  callTool(
@@ -108,11 +157,15 @@ export function createMcpConnection(
108
157
  signal: opts.signal,
109
158
  })
110
159
  tools.push(
111
- ...result.tools.map((tool) => ({
112
- name: tool.name,
113
- description: tool.description ?? '',
114
- inputSchema: tool.inputSchema,
115
- })),
160
+ ...result.tools.map((tool) => {
161
+ const fileOperands = parseDeclaredFileOperands(tool._meta)
162
+ return {
163
+ name: tool.name,
164
+ description: tool.description ?? '',
165
+ inputSchema: tool.inputSchema,
166
+ ...(fileOperands === undefined ? {} : { fileOperands }),
167
+ }
168
+ }),
116
169
  )
117
170
  cursor = result.nextCursor
118
171
  } while (cursor !== undefined)
@@ -127,8 +180,13 @@ export function createMcpConnection(
127
180
  if (cachedTools !== undefined) return cachedTools
128
181
  return fetchTools()
129
182
  },
183
+ peekTools(): McpToolInfo[] | undefined {
184
+ return cachedTools
185
+ },
186
+ // fetchTools never reads the cache, so the previous catalog is kept until a
187
+ // replacement is in hand: a failed or in-flight refresh must not blank out the
188
+ // metadata that peekTools() serves to the pre-execution operand preflight.
130
189
  refresh(): Promise<McpToolInfo[]> {
131
- cachedTools = undefined
132
190
  return fetchTools()
133
191
  },
134
192
  callTool(toolName: string, args?: Record<string, unknown>): Promise<CallToolResult> {
package/src/mcp/tools.ts CHANGED
@@ -2,8 +2,10 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
2
2
  import { z } from 'zod'
3
3
 
4
4
  import { enforceAndPinToolFiles } from '@/agent/tool-file-safety'
5
+ import { checkPrivateSurfaceReadGuard } from '@/bundled-plugins/security/policies/private-surface-read'
5
6
  import { defineTool } from '@/plugin/define'
6
- import type { ContentPart, Tool, ToolResult } from '@/plugin/types'
7
+ import type { ContentPart, Tool, ToolFileOperands, ToolResult } from '@/plugin/types'
8
+ import type { HiddenPaths } from '@/sandbox'
7
9
 
8
10
  import type { McpConnection, McpToolInfo } from './client'
9
11
  import type { McpManager } from './manager'
@@ -17,8 +19,45 @@ export type McpCallArgs = { server: string; tool: string; args?: Record<string,
17
19
  export type McpDispatcherTool = Tool<McpListToolsArgs> | Tool<McpDescribeArgs> | Tool<McpCallArgs>
18
20
  export type McpDispatcherTools = [Tool<McpListToolsArgs>, Tool<McpDescribeArgs>, Tool<McpCallArgs>]
19
21
 
20
- export function createMcpDispatcherTools(manager: McpManager): McpDispatcherTools {
21
- return [createListToolsTool(manager), createDescribeTool(manager), createCallTool(manager)]
22
+ export function createMcpDispatcherTools(
23
+ manager: McpManager,
24
+ opts: { resolveHidden: () => HiddenPaths },
25
+ ): McpDispatcherTools {
26
+ return [createListToolsTool(manager), createDescribeTool(manager), createCallTool(manager, opts)]
27
+ }
28
+
29
+ // `wrapSystemTool` runs the security hooks — including the fail-closed
30
+ // private-surface-read scan — against the whole `{ server, tool, args }` envelope
31
+ // BEFORE the dispatcher body resolves the target, so without this preflight a
32
+ // target-declared free-text operand is scanned as an undeclared path and blocked
33
+ // for a restricted role.
34
+ //
35
+ // EVERY category is surfaced, not just `nonFile`. `nonFile` relaxes the scan, so
36
+ // alone it could only ever weaken the guard; the local categories are what let
37
+ // the guard scan a declared real-file operand that a prose-named key (`query`,
38
+ // `content`, ...) would otherwise exempt. Surfacing one without the other is the
39
+ // bypass. This is security metadata only: it is never forwarded to a pinning
40
+ // boundary, so pinning still happens exactly once, at the dispatcher's inner-args
41
+ // boundary below.
42
+ //
43
+ // The lookup is cache-only. Connecting here would spawn an MCP server before the
44
+ // security hooks have run; a cold catalog yields undefined, which keeps the
45
+ // existing fail-closed scan.
46
+ export function resolveMcpCallPreflightFileOperands(
47
+ manager: McpManager,
48
+ args: Record<string, unknown>,
49
+ ): ToolFileOperands | undefined {
50
+ if (typeof args.server !== 'string' || typeof args.tool !== 'string') return undefined
51
+ const resolved = resolveToolArgs(args.server, args.tool)
52
+ const declared = manager.getConnection(resolved.server)?.peekTools()
53
+ const fileOperands = declared?.find((item) => item.name === resolved.tool)?.fileOperands
54
+ if (fileOperands === undefined) return undefined
55
+ const rebased: Record<string, readonly string[]> = {}
56
+ for (const [category, paths] of Object.entries(fileOperands)) {
57
+ if (paths === undefined || paths.length === 0) continue
58
+ rebased[category] = paths.map((operandPath) => `args.${operandPath}`)
59
+ }
60
+ return Object.keys(rebased).length === 0 ? undefined : (rebased as ToolFileOperands)
22
61
  }
23
62
 
24
63
  function createListToolsTool(manager: McpManager): Tool<McpListToolsArgs> {
@@ -80,7 +119,7 @@ function createDescribeTool(manager: McpManager): Tool<McpDescribeArgs> {
80
119
  })
81
120
  }
82
121
 
83
- function createCallTool(manager: McpManager): Tool<McpCallArgs> {
122
+ function createCallTool(manager: McpManager, opts: { resolveHidden: () => HiddenPaths }): Tool<McpCallArgs> {
84
123
  return defineTool<McpCallArgs>({
85
124
  description: 'Call an MCP tool on a connected server. Use mcp_describe first to learn the input schema.',
86
125
  parameters: z.object({
@@ -94,11 +133,28 @@ function createCallTool(manager: McpManager): Tool<McpCallArgs> {
94
133
  if (connection === undefined) return textResult(unknownServerMessage(manager, resolved.server))
95
134
 
96
135
  const toolArgs = args.args ?? {}
136
+ const targetFileOperands = await declaredFileOperands(connection, resolved.tool)
137
+ // Scoped to targets that actually declare operands. The cold-catalog gap
138
+ // this closes requires a declaration by definition: without one the outer
139
+ // envelope guard already scanned these values under the same role, and the
140
+ // generic fail-closed scan below stays the authority on undeclared ones —
141
+ // including its more precise "ambiguous local file operand" rejection.
142
+ if (targetFileOperands !== undefined) {
143
+ const blocked = checkPrivateSurfaceReadGuard({
144
+ tool: 'mcp_call',
145
+ args: toolArgs,
146
+ agentDir: ctx.agentDir,
147
+ hidden: opts.resolveHidden(),
148
+ fileOperands: targetFileOperands,
149
+ })
150
+ if (blocked !== undefined) throw new Error(`blocked: ${blocked.reason}`)
151
+ }
97
152
  const pinned = await enforceAndPinToolFiles({
98
153
  tool: 'mcp_call',
99
154
  args: toolArgs,
100
155
  agentDir: ctx.agentDir,
101
156
  genericInputs: true,
157
+ ...(targetFileOperands === undefined ? {} : { fileOperands: targetFileOperands }),
102
158
  logger: ctx.logger,
103
159
  signal: ctx.signal,
104
160
  })
@@ -129,6 +185,17 @@ function unknownServerMessage(manager: McpManager, server: string): string {
129
185
  return `Unknown MCP server ${JSON.stringify(server)}. Available servers: ${available || 'none'}.`
130
186
  }
131
187
 
188
+ // Operand paths here are relative to the target's own schema, matching the inner
189
+ // `args.args` scan; a catalog failure degrades to the fail-closed generic scan
190
+ // rather than aborting, and safeCallTool surfaces the real transport error.
191
+ async function declaredFileOperands(connection: McpConnection, tool: string): Promise<ToolFileOperands | undefined> {
192
+ try {
193
+ return (await connection.listTools()).find((item) => item.name === tool)?.fileOperands
194
+ } catch {
195
+ return undefined
196
+ }
197
+ }
198
+
132
199
  async function safeListTools(connection: McpConnection): Promise<McpToolInfo[]> {
133
200
  try {
134
201
  return await connection.listTools()
@@ -0,0 +1,111 @@
1
+ import path from 'node:path'
2
+
3
+ // Canonicalizes the longest RESOLVABLE prefix of an absolute path, then re-appends
4
+ // the remainder lexically. A bare realpath throws on a path that does not exist yet
5
+ // (a write target, or a read of a not-yet-created file), so we walk up to the nearest
6
+ // resolvable ancestor, realpath THAT — collapsing every symlinked component, including
7
+ // a planted one — and rejoin the tail. This is what catches `public/leak/x` where
8
+ // `public/leak` is a symlink into a hidden dir even though `public/leak/x` itself does
9
+ // not exist.
10
+ //
11
+ // Which errnos may be walked past is the security-sensitive part, so it is the
12
+ // CALLER's decision, not a default. See the two exported sets below.
13
+
14
+ // The historical, strictest set: only a missing component is walked past.
15
+ // Correct for allowlist/authorization policies, where an unresolvable component must
16
+ // never widen what is permitted.
17
+ export const RECOVER_MISSING: ReadonlySet<string> = new Set(['ENOENT'])
18
+
19
+ // Adds EACCES for denylist matching. A realpath of a path under a directory the
20
+ // runtime cannot search fails with EACCES, not ENOENT — e.g. resolving
21
+ // `/root/.config/...` while running as a non-root uid when `/root` is mode 700.
22
+ // Treating that as fatal blocks reads of paths that are neither secret nor denied.
23
+ // Walking past it is sound for a DENYLIST because the tail is still matched against
24
+ // the denied surface after rejoining: a masked directory still matches lexically and
25
+ // still blocks. It is NOT sound for an allowlist — see RECOVER_MISSING.
26
+ export const RECOVER_MISSING_OR_UNSEARCHABLE: ReadonlySet<string> = new Set(['ENOENT', 'EACCES'])
27
+
28
+ export type RealIntendedPathOptions = {
29
+ // Defaults to RECOVER_MISSING: callers must opt in to the broader set.
30
+ readonly recoverable?: ReadonlySet<string>
31
+ // What to do when even the filesystem root is unresolvable. Callers that treat an
32
+ // unresolvable path as a hard failure use 'throw'; callers that fall back to the
33
+ // lexical input use 'return-input'.
34
+ readonly onExhausted?: 'throw' | 'return-input'
35
+ }
36
+
37
+ export function realIntendedPathSync(
38
+ absolutePath: string,
39
+ realpath: (candidate: string) => string,
40
+ options: RealIntendedPathOptions = {},
41
+ ): string {
42
+ const walk = createAncestorWalk(absolutePath, options)
43
+ while (true) {
44
+ let resolved: string
45
+ try {
46
+ resolved = realpath(walk.target())
47
+ } catch (error) {
48
+ const exhausted = walk.retreat(error)
49
+ if (exhausted !== undefined) return exhausted
50
+ continue
51
+ }
52
+ return walk.rejoin(resolved)
53
+ }
54
+ }
55
+
56
+ export async function realIntendedPath(
57
+ absolutePath: string,
58
+ realpath: (candidate: string) => Promise<string>,
59
+ options: RealIntendedPathOptions = {},
60
+ ): Promise<string> {
61
+ const walk = createAncestorWalk(absolutePath, options)
62
+ while (true) {
63
+ let resolved: string
64
+ try {
65
+ resolved = await realpath(walk.target())
66
+ } catch (error) {
67
+ const exhausted = walk.retreat(error)
68
+ if (exhausted !== undefined) return exhausted
69
+ continue
70
+ }
71
+ return walk.rejoin(resolved)
72
+ }
73
+ }
74
+
75
+ type AncestorWalk = {
76
+ target(): string
77
+ rejoin(resolvedTarget: string): string
78
+ // Returns the final result when the walk cannot retreat further, or undefined to
79
+ // keep walking. Rethrows anything the caller did not declare recoverable.
80
+ retreat(error: unknown): string | undefined
81
+ }
82
+
83
+ function createAncestorWalk(absolutePath: string, options: RealIntendedPathOptions): AncestorWalk {
84
+ const recoverable = options.recoverable ?? RECOVER_MISSING
85
+ const onExhausted = options.onExhausted ?? 'return-input'
86
+ const pending: string[] = []
87
+ let current = absolutePath
88
+
89
+ return {
90
+ target: () => current,
91
+ // Copy before reversing: the caller may hold this array across iterations.
92
+ rejoin: (resolvedTarget) => path.join(resolvedTarget, ...[...pending].reverse()),
93
+ retreat(error) {
94
+ if (!isRecoverableErrno(error, recoverable)) throw error
95
+ const parent = path.dirname(current)
96
+ if (parent === current) {
97
+ if (onExhausted === 'throw') throw new Error(`could not resolve existing parent for ${absolutePath}`)
98
+ return absolutePath
99
+ }
100
+ pending.push(path.basename(current))
101
+ current = parent
102
+ return undefined
103
+ },
104
+ }
105
+ }
106
+
107
+ function isRecoverableErrno(error: unknown, recoverable: ReadonlySet<string>): boolean {
108
+ if (!(error instanceof Error) || !('code' in error)) return false
109
+ const code = (error as { code: unknown }).code
110
+ return typeof code === 'string' && recoverable.has(code)
111
+ }
@@ -18,6 +18,7 @@ export {
18
18
  } from './match-rule'
19
19
  export {
20
20
  createPermissionService,
21
+ findUngrantedPluginPermissions,
21
22
  findUnknownPermissions,
22
23
  noopPermissionService,
23
24
  type CreatePermissionServiceOptions,