Expand the vision doc

[RhysSullivan]

Expands vision.md from the original sketch into the full product vision — the destination the codebase evolves toward incrementally, not a rewrite plan.

What this adds

• Core concepts completed: tool, source, connection, secret, scope, policy, plugin, manager/invoker.
• The model — tiny core, first-party capabilities, one open plugin seam (sources, + maybe providers), and surfaces. Plus composition via artifacts × surfaces and the kind/lifetime/origin/surface/delivery axes.
• Scope merging — ordered, merged scopes with three fixed rules (union visibility, deny-union outer-wins, innermost-wins scalars); org | user as the two-element case; placement as a direct property (dimension, not indirection).
• Connections, secrets & auth — born-wired connections, multi-account, the tool-proxy invariant (secrets never reach the agent, no escape hatch), lifecycle.
• Sources — kinds via one seam; normalized manifest; auto-refresh never auto-grants.
• Policies — attached to source and connection (connection overrides source, scope authority layered); toolkits carry no policy.
• Toolkits as pure curation; authorization via the scope()-narrowed executor membrane (transitive).
• Surfaces — MCP meta-tools shape, MCP apps with RSC UI, MCP channels, authoring tools.
• Authoring model — two paths (file+deploy and a tool over MCP) with explicit promotion.
• Storage — two substrates: git / Cloudflare Artifacts for authored artifacts, KV/SQLite/FS for agent state.
• The Run model, human-in-the-loop, sandbox/runtime, distribution/CLI/remotes, cloud plugins.
• Principles and a build discipline section (evolve not rewrite; the wedge; vision-mode vs build-mode), north-star scenarios, and open questions.

Docs-only change — no code or runtime behavior touched.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	executor-marketing	6827896	Commit Preview URL Branch Preview URL	Jun 20 2026, 06:35 PM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	executor-cloud	6827896	Jun 20 2026, 06:36 PM

[github-actions]

Cloudflare preview

Torn down — the PR is closed.

[greptile-apps]

Greptile Summary

This PR expands vision.md from a 60-line sketch into a 390-line full product vision, covering core concepts, the composition model, scope merging, connections/secrets, policies, toolkits, surfaces, authoring, storage, the Run model, and build discipline. It is a docs-only change with no runtime impact.

• Policy value names are inconsistent across sections: the Core Concepts bullet uses allow / require-approval while the Policies section uses the code-formatted approve / require_approval — a different verb and different casing/separator that implementers will have to reconcile.
• Tool address ambiguity: <source>.<scope>.<connection>.<tool> uses <connection> as a segment, but a connection is identified by three fields (scope, source, name); the segment almost certainly means the connection's name field, but that equivalence is never stated.
• run_code meta-tool has no meta-capability gate: it appears in the MCP default shape but is absent from the typed meta-capability namespace that controls other privileged operations.

Confidence Score: 4/5

Docs-only change; no code or runtime behavior is touched, so merging carries no execution risk.

The policy value naming conflict between Core concepts (allow / require-approval) and the Policies section (approve / require_approval) is the kind of precise terminology that implementers copy directly into code — leaving it inconsistent in the canonical vision doc will produce divergent interpretations as the codebase evolves toward this model.

vision.md — specifically the policy values in Core Concepts vs the Policies section, and the tool address format notation.

Important Files Changed

Filename	Overview
vision.md	Expanded from 60-line sketch to a 390-line comprehensive product vision; contains one policy-value naming inconsistency (allow/approve) that will affect implementers, and two smaller clarity gaps around the tool address format and the run_code meta-capability.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client / Agent] -->|execute path args| B[Surface Host MCP / HTTP / CLI]
    B -->|authenticate + resolve toolkit| C[scope narrowed executor]
    C -->|catalog lookup| D[Tool in Scope]
    D -->|policy check| E{Policy Gate}
    E -->|block| F[Rejected]
    E -->|require_approval| G[Pending Run + resume reference]
    E -->|approve| H[Invoker]
    H -->|SecretRef lookup| I[Secret Provider]
    I -->|resolved credential| J[Tool Proxy]
    J -->|call| K[Upstream API / Plugin]
    K -->|result| L{Output size}
    L -->|fits inline| M[Inline value Run record]
    L -->|too large| N[Storage Handle Run record]
    L -->|UI| O{Client capability}
    O -->|renders RSC| P[Embedded UI resource]
    O -->|no RSC| Q[Deep link Web app]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Client / Agent] -->|execute path args| B[Surface Host MCP / HTTP / CLI]
    B -->|authenticate + resolve toolkit| C[scope narrowed executor]
    C -->|catalog lookup| D[Tool in Scope]
    D -->|policy check| E{Policy Gate}
    E -->|block| F[Rejected]
    E -->|require_approval| G[Pending Run + resume reference]
    E -->|approve| H[Invoker]
    H -->|SecretRef lookup| I[Secret Provider]
    I -->|resolved credential| J[Tool Proxy]
    J -->|call| K[Upstream API / Plugin]
    K -->|result| L{Output size}
    L -->|fits inline| M[Inline value Run record]
    L -->|too large| N[Storage Handle Run record]
    L -->|UI| O{Client capability}
    O -->|renders RSC| P[Embedded UI resource]
    O -->|no RSC| Q[Deep link Web app]

Loading

_{Reviews (1): Last reviewed commit: "Expand vision.md into the full product v..." | Re-trigger Greptile}

[greptile-apps]

Policy value naming conflict between sections

The "Core concepts" bullet defines the policy values as allow / require-approval / block (with a hyphen), but the "Policies" section below uses code-formatted literals approve / require_approval / block (different verb, underscore). These appear to describe the same discriminated enum, but "allow" ≠ "approve" and "require-approval" ≠ "require_approval". Any implementation driven from this doc will have to pick one set, and the inconsistency creates real ambiguity about what the canonical value names are — especially since the Policies section uses backtick formatting that signals actual code values.

[greptile-apps]

<connection> in the address format is ambiguous

The tool address is defined as <source>.<scope>.<connection>.<tool>, but "connection" as a concept is identified by (scope, source, name) — three fields, two of which (scope and source) already appear in the address. The <connection> segment here almost certainly means the name field (the account handle: work, personal, prod), but that isn't stated. Renaming the segment to <name> and adding a one-line note tying it to the connection's name field would remove the ambiguity.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

run_code meta-tool has no corresponding meta-capability entry

The MCP default shape lists four meta-tools: search, describe, execute, and run_code. The Authorization & capabilities section enumerates meta-capability kinds that gate access (author-tools, generate-UI, allocate-storage, deploy, trigger-register, egress), but run_code — which triggers the sandbox runtime — has no corresponding capability kind listed. The authoring tools are gated on author-tools, so the omission of a run-code or sandbox capability may be an oversight rather than intentional "always available".

[pkg-pr-new]

Open in StackBlitz

@executor-js/cli

npm i https://pkg.pr.new/@executor-js/cli@1055

@executor-js/config

npm i https://pkg.pr.new/@executor-js/config@1055

@executor-js/execution

npm i https://pkg.pr.new/@executor-js/execution@1055

@executor-js/sdk

npm i https://pkg.pr.new/@executor-js/sdk@1055

@executor-js/codemode-core

npm i https://pkg.pr.new/@executor-js/codemode-core@1055

@executor-js/runtime-quickjs

npm i https://pkg.pr.new/@executor-js/runtime-quickjs@1055

@executor-js/plugin-file-secrets

npm i https://pkg.pr.new/@executor-js/plugin-file-secrets@1055

@executor-js/plugin-graphql

npm i https://pkg.pr.new/@executor-js/plugin-graphql@1055

@executor-js/plugin-keychain

npm i https://pkg.pr.new/@executor-js/plugin-keychain@1055

@executor-js/plugin-mcp

npm i https://pkg.pr.new/@executor-js/plugin-mcp@1055

@executor-js/plugin-onepassword

npm i https://pkg.pr.new/@executor-js/plugin-onepassword@1055

@executor-js/plugin-openapi

npm i https://pkg.pr.new/@executor-js/plugin-openapi@1055

executor

npm i https://pkg.pr.new/executor@1055

commit: 6827896