RFC-0060: Starlark Session Initialization for vMCP

[jerm-dro]

Introduce a Starlark-based session initialization script for vMCP. A single script runs once per session, receives discovered backends and their capabilities, and calls publish() to declare what the agent sees — optionally wrapping handlers with additional logic. Existing config knobs remain fully supported, but customization of vMCP behavior can now be exactly tailored to the use case without adding more knobs. Increasing configurability no longer means decreasing maintainability.

[yrobla]

Strong RFC overall — the problem framing, prior art, and alternatives section are all excellent. The backends() + publish() model is clean, and the default preset sketch makes backward compatibility concrete rather than aspirational.

Filing 3 blockers, 3 should-address items, 2 questions, and 2 nits.

[yrobla]

[Blocker] priority_order.index(backend_name) will raise if backend_name isn't in the list — which is likely for any backend the admin didn't explicitly rank. Starlark has no try/except so this needs explicit handling:

Suggested change

	if priority_order.index(backend_name) > priority_order.index(existing_backend):
	if backend_name not in priority_order or existing_backend not in priority_order:
	continue # skip priority resolution if backend not ranked
	if priority_order.index(backend_name) > priority_order.index(existing_backend):

Also worth building a reverse-lookup dict upfront to avoid O(n) .index() on every collision.

[jerm-dro]

Good catch — Starlark has no try/except, so .index() on an unranked backend would halt the script with no recovery path. I've added an explicit in check and skip priority resolution for backends not in the priority list. For the reverse-lookup dict optimization: good idea for the production implementation, but I'll keep the sketch simple for readability since the POC will validate and optimize the exact implementation.

[yrobla]

[Blocker] FIND_TOOL_SCHEMA and CALL_TOOL_SCHEMA are used throughout the RFC and appendix (lines 233, 393, 398, 759, 771) but never defined anywhere. Are these Go-defined constants injected into the Starlark global scope? Must users define them in custom scripts? This is a gap in the built-in spec that every optimizer script author will hit immediately.

[jerm-dro]

Good question — these are JSON Schema dicts defining the parameters for the optimizer's find_tool and call_tool synthetic tools. Rather than injecting them as Go-defined globals, I've inlined them at the top of the default preset sketch so they're visible and editable. Custom scripts that use the optimizer pattern can define their own schemas.

[yrobla]

[Blocker] elicit() calls MCP elicitation, which is optional — many clients don't implement it. The RFC doesn't specify the fallback. For Use Case 2 (elicitation gate for write ops), the choice matters a lot:

1. Return struct(action="accept") — permissive, but silently bypasses the entire security gate for non-elicitation clients
2. Return struct(action="reject") — fail-closed, potentially very disruptive
3. Raise an error — forces script authors to handle it explicitly

This should be a deliberate, documented choice rather than an implementation detail.

[jerm-dro]

Thanks for raising this — elicit() is optional in MCP and many clients don't implement it. I've added a when_unavailable parameter to the elicit() built-in that makes the fallback behavior explicit. Accepted values are "accept", "reject", and "error". There is no default — the parameter is required, so script authors must make a deliberate choice.

[yrobla]

[Should address] "If both are set, vMCP logs a warning" is too weak for a mutual-exclusion constraint. Silently ignoring one of preset/script/scriptFile when two are set will cause confusing behavior where the user edits the wrong source. This should be a hard config load error, consistent with describing the fields as "mutually exclusive."

[jerm-dro]

Agreed — this should be a hard validation error at config load time, not a warning. Updated: if more than one of preset, script, or scriptFile is set, vMCP rejects the configuration.

[yrobla]

[Should address] Open Question 1 has a natural resolution via the MCP spec: handler failures should surface as {"isError": true, "content": [{"type": "text", "text": "..."}]} dicts — the same shape backend servers use today. The engine catches Go errors from backend calls and converts them to this shape; scripts use if result.get("isError") for decorator-style recovery. Worth resolving before implementation since error semantics affect how every handler is written.

[jerm-dro]

I like this proposal — the explicit behavior matches MCP semantics cleanly. Backend call failures are caught by the Go engine and returned as {"isError": true, "content": [...]} dicts rather than halting the script. Scripts can inspect result.get("isError") for decorator-style error recovery. This keeps the other patterns (fallback decorators, retry wrappers) available as userland Starlark — no special built-ins needed. Resolved the open question and added an error handling section to the programming model with a with_fallback example.

[yrobla]

[Should address] Phase 1 says to delete the existing decorator-based code as part of the POC. That ties a production deletion to a proof-of-concept — if the POC surfaces a design flaw, there's no fallback. Suggest keeping the decorators through Phase 1 and deleting them only after Phase 2's preset equivalence tests pass. The POC goal should be validating the design, not gating production functionality on the outcome.

[jerm-dro]

Fair point — deleting production code during a POC is risky. Moved the deletion to later phases where it's gated behind preset equivalence tests. Phase 1 now keeps existing decorators intact and runs the Starlark engine alongside them for comparison testing.

[yrobla]

[Question] The RFC says "runs once per session" but doesn't define session scope. Is it per-connection? Per-user? If the MultiSession is reused across multiple users of the same persona, current_user() (line 283) can't work as described in Open Question 2 and Use Cases 5/6 — it would be stale from session construction time. This matters for understanding the design ceiling, especially given that Open Question 2 explores pulling authz into Starlark.

[jerm-dro]

Good question. The session initialization script runs once per session — either when a session is created or when it's restored from Redis. The Starlark state is in-memory and not serialized, but can be recreated by re-running the script. Even though the script output could technically be shared across sessions today, running it once per session is a deliberate choice — it enables safe adoption of user-centric built-ins like current_user() in the future without requiring an architectural change. Added this clarification to the RFC.

[yrobla]

[Question] The RFC says "publishing a tool does not bypass authorization" which is technically true, but the call_tool handler pattern recommended throughout (default preset, Use Case 1, Use Case 6) dispatches via saved Go function references that go directly to the backend, completely bypassing Cedar authz middleware. This is the root cause of #4374. Should there be an explicit warning at the point where the pattern is introduced, not just in this section? Every optimizer user will write this pattern and hit the same bug.

[jerm-dro]

Great question — this motivates a change to the scope and migration plan. The call_tool handler pattern dispatches directly to backends, bypassing Cedar authz middleware, which is the same root cause as #4374. Alejandro's PR #4385 fixes the immediate bug but intentionally takes on tech debt. Rather than recreating this foot-gun in Starlark, I think we should update the rollout plan to ship optimizer + authz together so the relationship between them is explicit. Safe capabilities (name resolution, filtering, rate limiting) ship first, then optimizer + authz integration ships together in a later phase.

I've restructured the implementation phases accordingly and updated the default preset sketch to show how authz integration would look (e.g. enforce_cedar_policies(all_published)). I've also adjusted the scope of this RFC — it now establishes the phases at a high level and how they fit together. The exact nature of the authz built-ins is open to discussion and doesn't need to be resolved here for more distant phases.

[yrobla]

[Nit] thv vmcp show-preset default is great for transparency, but there's no mention of a thv vmcp list-presets command. Users need to discover what presets exist before they know to inspect them.

[jerm-dro]

Good point — added thv vmcp list-presets alongside show-preset.

[JAORMX]

I like the proposal and think that overall this is a good step to provide more customizability and programmability to vMCP. I'd be wary of fully relying on this mechanism for vMCP's programmability, API Gateways tend to offer programming languages as pluggability options (as you mentioned, Envoy's usage of Lua) but they often don't recommend them for critical paths and instead opt for other type of programmability or extensions. e.g. ext_proc via a sidecar which is quite standard to see in the wild or even c++ extensions since they support that too. For us it's a little tricky to know without previous data. So I'd say let's start getting it by adding this addition, but still opt for built-in middleware for extensibility since that's the paved path we have today. e.g. rate limiting should still be implemented via dedicated middleware IMO.

[yrobla]

Good RFC overall — the core argument (config knob interactions grow quadratically, Starlark + built-ins inverts this) is solid and the prior art section grounds it well. Comments below on a few specific areas.

[yrobla]

Restructuring to ship optimizer + authz together makes sense — the bypass isn't a "we'll fix it later" trade-off, it's a correctness bug. find_tool's dispatch table hands out access to tools Cedar would block (#4374). The interim fix in #4385 plugs one hole but the model is still broken, so shipping the optimizer alone would be knowingly shipping a privilege escalation.

On rate limiting: have you considered just implementing THV-0057 as a check_rate_limit() built-in rather than standalone middleware? Mechanism is identical (Redis token bucket), the default preset reads the same rateLimiting config block so non-script users see zero difference, and you avoid writing middleware that you're going to replace anyway. The main gap is that without current_user() you can only key on tool name — no per-user limits yet. That's fine as long as the Phase 2 scope note is explicit about it, otherwise it'll land as a disappointment.

[yrobla]

Worth nailing down the semantics before this ships: is current_user() meant to be called at script top-level only (gives you the session-creation user), or also inside handler closures (gives you the request-time user)? Use Case 5 calls it inside a wrapper function that runs per-request — that only works if it reflects the current request's identity. Those are two pretty different contracts and threading request context into handler calls has real implementation implications. If you leave this ambiguous now you'll probably end up with a breaking change to handler semantics when current_user() actually lands.

[yrobla]

The RFC is careful to separate "script controls what tools exist" from "Cedar controls who can use them" — but current_user() makes that line leaky. An admin can write if "admin" in current_user().groups: publish(admin_tool, fn) and now you've got authz logic in two places. That might be totally fine given the trust model (admins write scripts), but it's worth one sentence in the security section saying whether identity-based tool filtering in scripts is intentional or something you want to steer people away from in favor of Cedar.

[yrobla]

Replacing the existing code paths with the default preset is clean, but it also means the preset is now a single point of failure for everyone who hasn't written a custom script. The equivalence tests cover correctness, but what about a bug that ships mid-upgrade? Is there a way to pin to a preset version, or is "fork it via show-preset" the intended escape hatch? Just worth thinking through — a subtle behavior change in the preset silently affects all existing deployments at once.

[yrobla]

The "put current_user() logic at the end" heuristic is going to confuse people. If sessionless MCP is a real possibility, I'd just commit to a two-hook model now: on_session_init() for what tools exist and how they're shaped, on_request() for per-request concerns like rate limiting and user-specific filtering. It maps directly onto the distinction the RFC already makes, survives the sessionless transition cleanly, and removes a footgun where script ordering determines correctness in a non-obvious way.