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.
- package/package.json +1 -1
- package/src/agent/index.ts +35 -9
- package/src/agent/plugin-tools.ts +14 -0
- package/src/agent/system-prompt.ts +8 -0
- package/src/agent/todo/continuation-policy.ts +11 -1
- package/src/agent/todo/continuation-state.ts +3 -1
- package/src/agent/todo/continuation-wiring.ts +2 -0
- package/src/agent/tool-file-safety.ts +7 -1
- package/src/agent/tools/channel-reply.ts +18 -1
- package/src/bundled-plugins/guard/policies/managed-config.ts +7 -20
- package/src/bundled-plugins/guard/policies/non-workspace-write.ts +7 -20
- package/src/bundled-plugins/guard/policies/skill-authoring.ts +8 -20
- package/src/bundled-plugins/memory/README.md +2 -0
- package/src/bundled-plugins/memory/dreaming.ts +2 -0
- package/src/bundled-plugins/security/policies/private-surface-read.ts +98 -55
- package/src/channels/adapters/discord-bot-reactions.ts +1 -0
- package/src/channels/adapters/discord-bot.ts +11 -2
- package/src/channels/adapters/discord-reactions.ts +1 -0
- package/src/channels/adapters/discord.ts +1 -0
- package/src/channels/adapters/slack-bot.ts +11 -2
- package/src/channels/adapters/slack.ts +1 -0
- package/src/channels/completion-claim.ts +307 -0
- package/src/channels/router.ts +275 -55
- package/src/channels/types.ts +4 -1
- package/src/config/providers.ts +100 -20
- package/src/container/start.ts +42 -0
- package/src/init/models-dev.ts +25 -8
- package/src/mcp/client.ts +65 -7
- package/src/mcp/tools.ts +71 -4
- package/src/path-safety/real-intended-path.ts +111 -0
- package/src/permissions/index.ts +1 -0
- package/src/permissions/permissions.ts +23 -0
- package/src/plugin/manager.ts +19 -1
- package/src/sandbox/canonical-secrets.ts +24 -4
- package/src/sandbox/hidden-paths.ts +8 -3
- package/src/sandbox/index.ts +2 -0
- package/src/skills/typeclaw-permissions/SKILL.md +13 -1
- package/src/skills/typeclaw-plugins/SKILL.md +91 -11
- package/typeclaw.schema.json +5 -0
package/src/config/providers.ts
CHANGED
|
@@ -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
|
|
785
|
-
//
|
|
786
|
-
// solar-
|
|
787
|
-
//
|
|
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-
|
|
823
|
-
//
|
|
824
|
-
// there; solar-mini
|
|
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
|
-
//
|
|
827
|
-
//
|
|
828
|
-
//
|
|
829
|
-
//
|
|
830
|
-
//
|
|
831
|
-
//
|
|
832
|
-
//
|
|
833
|
-
//
|
|
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: {
|
|
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: {
|
|
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: {
|
|
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:
|
|
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:
|
|
994
|
+
contextWindow: 32768,
|
|
915
995
|
maxTokens: 8000,
|
|
916
996
|
compat: {
|
|
917
997
|
supportsStore: false,
|
package/src/container/start.ts
CHANGED
|
@@ -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',
|
package/src/init/models-dev.ts
CHANGED
|
@@ -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
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
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:
|
|
329
|
-
reasoning:
|
|
330
|
-
contextWindow: opts.upstream?.limit?.context ??
|
|
331
|
-
maxTokens: opts.upstream?.limit?.output ??
|
|
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
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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(
|
|
21
|
-
|
|
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
|
+
}
|