History

feat: refactor v2 execute wiring around run clients

Bind PM runtime at composition time and remove runtime selection from execute inputs so MCP and AI SDK share a simpler transport contract.

Rhys Sullivan committed 8 months ago

Commit 21fcb6b1 parent 432444f18 files · +670 −454Browse files

Unified · Split

18 files
  1. v2/PLAN.md +275 −334
  2. v2/apps/convex/convex/mcp.ts +7 −1
  3. v2/apps/convex/package.json +1 −0
  4. v2/apps/pm/README.md +8 −1
  5. v2/apps/pm/package.json +1 −0
  6. v2/apps/pm/src/config.ts +26 −0
  7. v2/apps/pm/src/http-server.ts +32 −0
  8. v2/apps/pm/src/main.ts +21 −91
  9. v2/apps/pm/src/mcp-handler.ts +43 −0
  10. v2/apps/pm/src/run-executor.ts +89 −0
  11. v2/bun.lock +7 −0
  12. v2/packages/ai-sdk-adapter/package.json +7 −0
  13. v2/packages/ai-sdk-adapter/src/index.ts +51 −1
  14. v2/packages/mcp-gateway/package.json +1 −0
  15. v2/packages/mcp-gateway/src/index.ts +0 −1
  16. v2/packages/mcp-gateway/src/server.ts +28 −24
  17. v2/packages/sdk/package.json +3 −0
  18. v2/packages/sdk/src/index.ts +70 −1
v2/PLAN.md+275−334
@@ -1,488 +1,429 @@
1−What is executor:
2−
3−- Approvals
4−- Permission model
5−- Code execution
6− - Support abitrary tool targets (API / GraphQL / MCP / in memory)
7−- Authentication
8−
9−Usage locally:
10−
11−- Approvals are stored in memory
12−- Permissions are stored to file system
13−- Auth creds are stored to file system
14−
15−Usage via AI SDK
16−
17−const executor = new Executor({
18−runtime: deno() | nodevm() | cloudflare-dynamic-worker(),
19−// all the same RPC?
20−approvals:
21−authentication:
22−permissions:
23−})
24−
25−Usage via Cloud:
26−
27−- Everything in Convex
28−- Runtime is cloudflare dynamic worker
29−-
30−
311 # Executor v2 Plan
322
333 Reference implementations and inspiration for this plan:
344 `../AnswerOverflow`
355 `../quickhub`
366 `../create-epoch-app`
37−
387 ## 1) Why v2 exists
398
409 Executor today is optimized for enterprise/team correctness (workspaces, org flows, cloud control), but has too much friction for per-user adoption.
4110
4211 v2 changes the default:
4312
44−- **First-run must be local and immediate** (`npx executor <agent>` works fast).
45−- **No database dependency** in local-lite mode.
46−- **Cloud/self-host are upgrade targets**, not prerequisites.
47−- **One architecture for all modes** via adapters and shared contracts.
13+- First run is local and immediate (`npx executor <agent>` works fast).
14+- No database dependency in local-lite mode.
15+- Cloud/self-host are upgrade targets, not prerequisites.
16+- One architecture for local and remote via shared contracts and thin adapters.
4817
4918 ---
5019
5120 ## 2) Product principles
5221
53−1. **Local-first**
22+1. Local-first
5423 - User gets value without login, org setup, or web onboarding.
55−2. **One mental model**
56− - Same commands, same execution semantics across local and remote targets.
57−3. **Schema-first**
58− - Effect Schema is the single source of truth for persisted/domain models.
59−4. **Execute-first tooling**
60− - Top-level model tool surface is minimal; code execution is primary.
61−5. **Progressive complexity**
62− - Advanced controls exist but are hidden until needed.
63−6. **Service-first Effect architecture**
64− - Effectful orchestration is exposed as `Context.Tag` services + Layers; plain functions are for pure transforms.
24+2. One mental model
25+ - Same execution semantics across local and remote.
26+3. Schema-first
27+ - Effect Schema is canonical for domain and persistence contracts.
28+4. Execute-first
29+ - Keep top-level model-facing surface minimal (`execute` first).
30+5. Service-first architecture
31+ - Effect orchestration is exposed via services and layers.
32+6. Progressive complexity
33+ - Advanced control and infra stay out of the default happy path.
6534
6635 ---
6736
68−## 3) Product modes and targets
69−
70−### Modes
71−
72−- **local-lite**: PM daemon + in-memory hot state + file persistence. No DB.
73−- **remote**: Convex-backed target (applies to both cloud and self-hosted).
74−
75−### Key simplification
37+## 3) The architecture (locked)
7638
77−- `cloud` and `self-hosted` are not separate architecture branches.
78−- They are both **remote Convex targets**; only URL/auth/deployment ownership differs.
39+v2 is split into three planes. This is the key simplification.
7940
80−### Runtime targets (adapter-based)
41+### Execution plane
8142
82−- **`deno-subprocess`**: local sandbox runtime (current local secure target in v2).
83−- **`cloudflare-worker-loader`**: production cloud runtime target.
84−- **`node:vm`**: explicit unsafe/dev fallback only, not default.
43+Runs code and resolves `tools.*` calls.
8544
86−---
87−
88−## 4) Control + execution model
45+- run lifecycle
46+- runtime dispatch
47+- tool invocation pipeline
48+- approvals/policy enforcement
49+- credential resolution for tool calls
8950
90−### Control role (conceptual)
51+### Control plane
9152
92−Control includes source registry, policies, approvals/input workflow, identity/link state, and sync metadata.
53+Mutates and queries executor configuration/state.
9354
94−- In local-lite: handled by `apps/pm`.
95−- In remote: handled by Convex + web stack.
55+- source registration/removal
56+- tool artifact refresh/rebuild
57+- policy management
58+- sync metadata
9659
97−### Execution role
60+Control is optional capability, not required for execute-only environments.
9861
99−Execution is provider-based: the runtime engine runs generated TypeScript, resolves `tools.*` calls, and routes invocation through source/tool providers (OpenAPI, MCP, GraphQL, in-memory, and future formats).
62+### Transport plane
10063
101−---
64+How clients talk to executor.
10265
103−## 5) Monorepo shape (Executor-only)
66+- MCP server/gateway
67+- OpenAPI/RPC control API
68+- AI SDK tool bridge
10469
105−```text
106−v2/
107− apps/
108− cli/
109− pm/
110− web/
111− convex/
112−
113− packages/
114− confect/ # imported from quickhub; Effect<->Convex schema bridge
115− schema/ # canonical Effect schemas
116− persistence-ports/
117− persistence-local/
118− persistence-convex/
119− domain/
120− approvals/
121− source-manager/
122− engine/
123− mcp-gateway/
124− oauth/
125− secrets/
126− sync/
127− rpc/
128− sdk/
129− ai-sdk-adapter/
130−```
70+Transport does not own core execution semantics.
13171
13272 ---
13373
134−## 6) Dependency order (high-level)
135−
136−```text
137−confect -> schema -> persistence-ports
74+## 4) Core contracts
13875
139−persistence-ports -> persistence-local
140−persistence-ports -> persistence-convex
76+We do not need a mandatory public `new Executor()` product surface.
14177
142−schema + persistence-ports + oauth + secrets -> domain
78+Primary internal shape is a kernel service (name can vary, e.g. `createExecutorKernel`).
14379
144−domain -> approvals/source-manager/engine
145−approvals/source-manager/engine -> mcp-gateway
80+### Kernel contract
14681
147−domain/features -> rpc -> sdk -> ai-sdk-adapter
82+- `execute(request) -> terminal result` (or async run id if configured)
83+- `handleRuntimeToolCall(call) -> encoded tool-call result`
84+- optional `control` capability
14885
149−apps/pm -> mcp-gateway + domain + persistence-local + rpc
150−apps/convex -> mcp-gateway + domain + persistence-convex + rpc
151−apps/cli/web -> sdk
152−```
86+### Adapter contracts
15387
154−Rules:
88+- RuntimeDispatchAdapter
89+ - only decides where code runs (`local-inproc`, `deno-subprocess`, `cloudflare-worker-loader`)
90+- ToolInvocationService
91+ - resolves tool path and invokes tool with policy/approval checks
92+- CredentialResolver
93+ - resolves credential headers during tool invocation callback
94+- ControlService (optional)
95+ - source/tool/policy management commands
15596
156−- `schema` has no dependency on feature/runtime packages.
157−- `domain` depends on interfaces, not concrete state adapters.
158−- apps are leaves; packages do not import apps.
159−- packages expose effectful orchestration through services (`Context.Tag`), with Layers wiring implementations.
97+Important boundary:
98+- Credential resolution is not part of runtime dispatch.
99+- Credential resolution happens in callback-time tool invocation.
160100
161101 ---
162102
163−## 7) Local-lite PM architecture
164−
165−`apps/pm` is the local daemon and source of hot truth.
166−
167−Responsibilities:
103+## 5) Modes and targets
168104
169−- MCP endpoint surface
170−- source registration and status lifecycle
171−- approvals/input broker
172−- task orchestration and runtime execution coordination
173−- persistence (snapshot + event log)
174−
175−### Persistence model
105+### Modes
176106
177−- Hot state: in-memory
178−- Durable: file-based
179− - `snapshot.json`
180− - `events.jsonl` (WAL)
181− - `artifacts/` (compiled tool manifests)
182− - secrets in secure store / dedicated protected file
107+- local-lite: PM daemon + in-memory hot state + file durability
108+- remote: Convex-backed target (cloud and self-host are deployment variants of same target)
183109
184−Crash/restart behavior:
110+### Runtime targets
185111
186−- Rehydrate from snapshot + events.
187−- Rebuild derived indexes in memory.
188−- Mark previously running tasks terminally with restart reason.
112+- `deno-subprocess`: local secure default
113+- `cloudflare-worker-loader`: remote production default
114+- `node:vm`: explicit unsafe/dev fallback only
189115
190116 ---
191117
192−## 8) Data model strategy
193−
194−Effect Schema is canonical (`packages/schema`).
118+## 6) Local and cloud runtime flows
119+
120+### Local flow
121+
122+1. Request starts run (`execute`).
123+2. Runtime dispatch executes locally (`inproc` or `deno-subprocess`).
124+3. Runtime `tools.*` call hits local callback handler.
125+4. Callback handler invokes shared tool invocation pipeline:
126+ - resolve tool
127+ - policy check
128+ - approval gating
129+ - credential resolution (if needed)
130+ - provider invoke
131+5. Runtime resumes and completes.
132+6. Run/events persisted locally.
133+
134+### Cloud flow (Convex + Cloudflare worker loader)
135+
136+1. Request starts run in Convex.
137+2. Convex dispatches run to Cloudflare loader.
138+3. Worker `tools.*` call hits Convex runtime callback action (`handleToolCall`).
139+4. Callback action invokes shared tool invocation pipeline:
140+ - resolve tool
141+ - policy check
142+ - approval gating
143+ - credential resolution from Convex/vault
144+ - provider invoke
145+5. Worker resumes and returns terminal status.
146+6. Convex marks run terminal and emits events.
147+
148+Serverless note:
149+- There is no long-lived in-memory `onToolCall` loop in cloud.
150+- Callback requests are stateless/durable and reconstruct context per request.
195151
196−Current scaffold includes:
197−
198−- domain IDs (`src/ids.ts`)
199−- enums/common primitives
200−- model schemas:
201− - profile, workspace
202− - source, tool artifact
203− - credential ref, oauth token
204− - policy, approval
205− - task run, sync state
206− - event envelope
207−- local snapshot/WAL schemas in `persistence-local`
152+---
208153
209−### Convex ID compatibility
154+## 7) Blocking and non-blocking execution
210155
211−IDs are now intentionally split by layer:
156+Both are first-class and share one implementation path.
212157
213−- **Domain IDs** live in `packages/schema` as portable branded IDs.
214−- **Convex table IDs** live in `packages/persistence-convex/src/convex-ids.ts` via `Id("table")` from `@executor-v2/confect`.
158+- Async canonical path:
159+ - submit run -> return `runId`
160+ - query/watch run status -> terminal result
161+- Blocking convenience path:
162+ - submit run
163+ - wait/watch internally
164+ - return terminal result
215165
216−This keeps canonical schema backend-agnostic while preserving strict table-typed IDs inside the Convex adapter boundary.
166+This is mostly transport/API behavior; core runtime pipeline stays the same.
217167
218168 ---
219169
220−## 9) Tooling, providers, and MCP surface
170+## 8) MCP, RPC, and AI SDK strategy
221171
222−### Top-level model-facing tools
172+### MCP
223173
224−Keep top-level surface minimal:
174+MCP remains the main execution transport surface.
225175
176+Top-level model-facing tools stay minimal:
226177 - `execute` (primary)
227−- optional diagnostics (`health`, `version`) only if needed
228−
229−### Configuration model
178+- optional diagnostics (`health`, `version`)
230179
231−Executor config is handled as tool calls from inside `execute` via built-in namespace:
180+### Control API
232181
233−- `tools.executor.sources.add(...)`
234−- `tools.executor.sources.list(...)`
235−- `tools.executor.sources.remove(...)`
236−- other `tools.executor.*` controls as needed
182+Control is exposed through Executor OpenAPI/RPC contracts.
237183
238−No mandatory top-level `set_enabled` in v1 (remove/add is enough for initial UX).
184+- Host/app control calls should use control API directly.
185+- Model control calls can use `tools.executor.*` inside `execute` code.
186+- Both host and model control paths must hit the same underlying control handlers.
239187
240−### Provider architecture (source-agnostic)
188+### AI SDK
241189
242−Use a provider registry, not format-specific execution in core runtime.
190+AI SDK is a bridge over executor execute capability.
243191
244−- Each provider implements:
245− - `discover(source) -> ToolManifest`
246− - `invoke(call) -> ToolResult`
247−- Core runtime stays source-format agnostic; it resolves tool identity and dispatches to provider.
248−- Initial provider kinds:
249− - `openapi`
250− - `mcp`
251− - `graphql`
252− - `in_memory` (host-registered tools; AI-SDK style)
253−- Future source formats are added as new providers, without changing core execution semantics.
192+- `toAiSdkTools(executorLike)` maps to regular AI SDK tools.
193+- Local and remote both work if they expose `execute(...)` semantics.
194+- If client is MCP-native, AI SDK bridge is optional.
254195
255−### Canonical tool descriptor
196+AI SDK should not become a second control-plane abstraction.
256197
257−All providers publish into one canonical descriptor used by runtime and SDK:
198+---
258199
259−- stable tool id
260−- display metadata (name, description)
261−- invocation metadata (kind + provider payload)
262−- availability metadata (`local_only` vs `remote_capable`)
200+## 9) Tooling and provider model
263201
264−Provider-specific details remain in a typed payload at the edge.
202+Provider registry is canonical.
265203
266−### Execution semantics
204+Each provider implements:
205+- discover(source) -> ToolManifest
206+- invoke(call) -> ToolResult
267207
268−- Agent writes TS using `tools.*`.
269−- Runtime proxy resolves tool calls against the canonical registry.
270−- Provider receives invocation and returns canonical result envelope.
271−- Credentials/policies/approvals are applied server-side during invocation.
208+Initial provider kinds:
209+- `openapi`
210+- `in_memory`
211+- `mcp` (planned)
212+- `graphql` (planned)
272213
273−---
214+Canonical descriptor includes:
215+- stable tool id/path
216+- display metadata
217+- invocation metadata
218+- capability metadata
274219
275−## 10) Dynamic source registration
220+Provider-specific details remain in provider payload types.
276221
277−Goal: user can ask the agent to use a service; agent can register the source through Executor tooling.
222+---
278223
279−- Discovery itself may happen outside Executor (model/web).
280−- Registration happens via Executor control tools (`tools.executor.sources.add`).
281−- `source.kind` selects provider (`openapi`, `mcp`, `graphql`, etc.).
282−- In-memory tools are host-registered (runtime side), not persisted remote source records by default.
224+## 10) Persistence and registry model
283225
284−Registration flow states (networked providers):
226+Persistence is source of truth. Runtime registry is derived.
285227
286−- `draft -> probing -> auth_required -> connected | error`
228+### Persisted
287229
288−Registration flow states (in-memory provider):
230+- sources
231+- tool artifacts/manifests
232+- runs/events
233+- approvals/policies
234+- credential references (secret values in secure backing store)
289235
290−- `registered -> connected | error`
236+### Derived
291237
292−Auth handling:
238+- in-memory runnable tool index/registry
239+- discovery indexes
293240
294−- MCP: dynamic auth/OAuth detection, client registration where needed
295−- OpenAPI/GraphQL: inspect auth schemes, prompt for API key/OAuth when required
241+Mutation rule:
242+1. persist authoritative record
243+2. refresh/rebuild derived artifact/index
244+3. bump registry version
296245
297−Secrets are entered through host UX, not model transcript.
246+Run rule:
247+- each run snapshots tool registry version at start
248+- in-flight runs keep snapshot semantics
249+- new runs see newest version
298250
299251 ---
300252
301−## 11) Approvals and elicitation/input
302−
303−Use one internal broker for human-required inputs:
253+## 11) Approval and secret boundaries
304254
255+Approvals/input are host UX concerns, not model tools.
305256 - approval
306257 - confirm
307258 - form input
308259 - secret input
309−
310−### Capability-aware delivery
311−
312−- If client supports MCP elicitation: inline prompt.
313−- If not: out-of-band path (tmux pane, local web, notifications).
314−
315−### Terminal UX
316−
317−For fullscreen terminal clients:
318−
319−- tmux split/popup watcher
320−- auto-show when pending approvals appear
321−- auto-hide after queue drains (with debounce)
322−
323−### Important boundary
324−
325−Approval/input actions are **host UX callbacks**, not AI SDK model tools.
260+Secrets/credentials:
261+- never emitted to model transcript
262+- resolved server-side during invocation
263+- converted to headers/token material for provider calls
326264
327265 ---
328266
329−## 12) AI SDK strategy
330−
331−API shape should be Executor session/adapters, not single-source helper APIs.
332−
333−### Adapter-first target design
334−
335−`Executor.create({ adapter })` with adapters such as:
336−
337−- `inproc` (embedded runtime, no install)
338−- `pm` (local daemon transport)
339−- `remote` (Convex target transport)
340−
341−### Public SDK shape
342−
343−Primary operations:
344−
345−- execute code
346−- register/list/remove sources
347−- register/list/remove in-memory tools (AI-SDK style)
348−- stream run status/results
349−
350−Do not expose approval/input-response as model tools.
351−Use host callbacks (e.g. `onInputRequest`) instead.
267+## 12) Security posture
268+- PM binds to loopback by default.
269+- Runtime callbacks require internal token validation.
270+- Secrets do not pass through model args/transcripts.
271+- Credential refs in state; secret values in secure stores.
272+- Audit events store actions/decisions, not raw secret material.
352273
353274 ---
354275
355−## 13) Security posture
276+## 13) Monorepo shape (Executor v2)
356277
357−- PM binds to loopback by default.
358−- Secrets never pass through model args/transcripts.
359−- Credential references in state; secret values in secure store.
360−- Strict origin/token checks if hosted web talks to localhost target.
361−- Audit events store decisions/actions, not raw secret material.
362−
363−---
278+```text
279+v2/
280+ apps/
281+ cli/
282+ pm/
283+ web/
284+ convex/
285+ packages/
286+ confect/
287+ schema/
288+ state-contracts/
289+ state-local-file/
290+ state-convex/
291+ domain/
292+ approvals/
293+ source-manager/
294+ engine/
295+ mcp-gateway/
296+ oauth/
297+ secrets/
298+ sync/
299+ rpc/
300+ sdk/
301+ ai-sdk-adapter/
302+```
364303
365−## 14) Upgrade and sync
304+Planned follow-up split (after behavior stabilizes):
305+- runtime adapters as dedicated packages
306+- transport adapters as dedicated packages
366307
367−Primary path:
308+---
368309
369−- `local-lite -> remote`
310+## 14) Dependency direction
370311
371−Optional reverse:
312+```text
313+confect -> schema -> state-contracts
372314
373−- `remote -> local-lite` export/backup
315+state-contracts -> state-local-file
316+state-contracts -> state-convex
374317
375−Sync principles:
318+schema + state-contracts + oauth + secrets -> domain
319+domain -> approvals/source-manager/engine
320+approvals/source-manager/engine -> mcp-gateway
321+domain/features -> rpc -> sdk -> ai-sdk-adapter
376322
377−- deterministic source identity
378−- idempotent imports
379−- explicit credential migration policy
380−- migration cursor/mapping persisted in local state
323+apps/pm -> mcp-gateway + domain + state-local-file + rpc
324+apps/convex -> mcp-gateway + domain + state-convex + rpc
325+apps/cli/web -> sdk (and/or ai-sdk bridge)
326+```
327+Rules:
328+- `schema` is backend-agnostic.
329+- apps are leaves.
330+- packages do not import apps.
331+- orchestration services are injected via interfaces/tags/layers.
381332
382333 ---
383334
384335 ## 15) Rollout phases
385336
386−### Phase 0: Architecture + contracts
337+### Phase 0: lock contracts
387338
388−- finalize package boundaries
389−- finalize schema model set and invariants
390−- define state/repository interfaces
339+- finalize kernel + adapter contracts
340+- finalize execution/control/transport boundaries
341+- align package names/imports to current v2 structure
391342
392−### Phase 1: Local-lite core
343+### Phase 1: local-lite execute vertical slice
393344
394−- PM daemon skeleton
395−- file persistence (snapshot + WAL)
396−- execute path with runtime proxy integration
397−- provider registry + canonical tool descriptor
398−- basic source add/list/remove through `tools.executor.*`
399−- first provider slices: `openapi` + `in_memory`
345+- PM execute path with persisted run lifecycle
346+- runtime callback path wired through shared invocation service
347+- openapi + in_memory providers
400348
401−### Phase 2: Input/approval UX
349+### Phase 2: control vertical slice
402350
403−- InputBroker + pending state persistence
404−- tmux watcher + local web fallback
405−- capability-aware elicitation fallback paths
351+- source add/list/remove via control handlers
352+- same handlers callable from host control API and `tools.executor.*`
353+- artifact refresh + registry versioning
406354
407−### Phase 3: Remote parity
355+### Phase 3: approvals and credentials hardening
408356
409−- persistence-convex adapter and Convex app wiring
410−- shared RPC contracts for pm/convex
411−- target switching in CLI/web
412−- runtime/provider capability checks for local vs remote
357+- persisted pending/resume/deny flow
358+- capability-aware UX fallbacks
359+- callback-time credential resolver implementations (local + convex)
413360
414−### Phase 4: Sync + upgrades
361+### Phase 4: remote parity
415362
416−- local->remote promotion pipeline
417−- idempotent mapping/cursor strategy
418−- conflict handling and dry-run reporting
363+- Convex adapter wiring for kernel and control
364+- cloudflare loader integration through runtime dispatch adapter
365+- parity/conformance suite across local and remote
419366
420−### Phase 5: AI SDK adapters
367+### Phase 5: transport polish
421368
422−- inproc adapter
423−- pm transport adapter
424−- remote transport adapter
425−- host callback API for inputs
369+- MCP surface stabilization
370+- OpenAPI/RPC control surface stabilization
371+- AI SDK bridge (`toAiSdkTools`) and docs/examples
426372
427373 ---
428374
429375 ## 16) Success criteria
430376
431−- First successful `npx executor <agent>` run with no login in <2 minutes.
432−- No required database for local-lite mode.
433−- Same execution semantics across local and remote targets.
434−- Agent can add sources and execute against them in one flow.
435−- Provider-based execution works for at least `openapi` + `in_memory` in local-lite.
436−- Approval/input is usable in fullscreen terminal clients.
377+- First successful local run with no login in under 2 minutes.
378+- No required DB in local-lite mode.
379+- Same execution semantics across local and remote.
380+- Callback-time approvals/policy/credentials work in both local and cloud.
381+- Control operations are callable both by host API and from inside execute namespace.
382+- Blocking and non-blocking execution both available via shared run pipeline.
437383
438384 ---
439385
440386 ## 17) Non-goals (initial)
441387
442−- Recreating all enterprise admin UX in local-lite.
443−- Exposing huge top-level tool catalogs to the model by default.
388+- Recreating full enterprise admin UX in local-lite.
389+- Expanding model-facing top-level tool catalog by default.
444390 - Maintaining separate cloud vs self-host architecture branches.
391+- Coupling runtime adapters with credential/secrets responsibilities.
445392
446393 ---
447394
448395 ## 18) Current scaffold status
449396
450397 Implemented in `v2` so far:
451−
452398 - monorepo app/package skeleton
453399 - `confect` imported from quickhub
454−- schema package scaffold with Effect models and event envelope
455−- schema-driven runtime tool models (canonical descriptor + OpenAPI invocation/manifest)
456−- domain ID groundwork in `schema/src/ids.ts`
457−- Convex table ID groundwork in `persistence-convex/src/convex-ids.ts`
458−- shared persistence ports for `SourceStore` and `ToolArtifactStore`
459−- local persistence adapters for source/tool artifacts
460−- local-only snapshot/WAL contract and persistence implementation
461−- OpenAPI extraction + artifact refresh/reuse flow
462−- provider registry contracts and routing in `engine`
400+- schema package scaffold with Effect models/event envelope
401+- shared state contracts for source/tool artifacts
402+- local file adapters for source/tool artifacts + snapshot/WAL state store
403+- source manager OpenAPI extraction + artifact refresh/reuse
404+- provider registry contracts and routing in engine
463405 - OpenAPI provider invocation + in-memory provider path through registry
464−- local in-process JS runner with `tools.*` proxy dispatch
406+- local in-process JS runner with `tools.*` proxy
465407 - Deno subprocess runtime path with IPC tool-call proxying and tests
466−- runtime adapter contract + registry scaffold in `engine` with mapped adapters (`local-inproc`, `deno-subprocess`, `cloudflare-worker-loader`)
467−- minimal PM execute lifecycle wired through MCP `executor.execute` -> runtime adapter registry (single run, no persisted run state yet)
468−- vertical test: OpenAPI spec -> manifest -> execute code -> HTTP tool call
469−- service-first wiring (`Context.Tag` + Layer) across source manager and persistence/local runtime orchestration
408+- runtime adapter contract + registry scaffold
409+- PM execute lifecycle scaffold via MCP execute path
470410
471−Not implemented yet:
411+Still missing:
472412
473−- `tools.executor.sources.add/list/remove` end-to-end PM + MCP gateway wiring
474−- approval adapter/state machine integration (pending/resume/deny persistence) in v2 runtime path
475−- provider/runtime conformance suite beyond current baseline tests (timeouts, cancellation, pending approval)
476−- Cloudflare worker loader adapter execution integration (current adapter is explicit scaffold/not-implemented)
477−- MCP/GraphQL provider implementations
478−- full rpc/sdk adapter wiring and sync engine
413+- fully wired control handlers (`tools.executor.sources.add/list/remove`) end-to-end
414+- shared tool invocation service wired with persisted approval lifecycle in v2 path
415+- cloudflare-worker-loader runtime adapter implementation in v2 runtime path
416+- parity conformance tests for runtime/provider/pending-approval/cancel flows
417+- full rpc/sdk/ai-sdk adapter wiring and usage examples
479418
480419 ---
481420
482421 ## 19) Immediate next steps
483422
484−1. Add first `tools.executor.sources.add/list/remove` control operations end-to-end in PM + MCP gateway.
485−2. Implement approval adapter contract with persisted pending/resume/deny flow for runtime tool calls.
486−3. Add provider/runtime conformance tests (invoke success/failure, timeout, pending approval, cancel).
487−4. Add Cloudflare worker loader adapter integration against the runtime adapter contract.
488−5. Extend PM execute lifecycle from single-run scaffold to persisted run state + streaming status.
423+1. Land shared `ToolInvocationService` contract in v2 and wire PM execute callback path through it.
424+2. Add `CredentialResolver` interfaces and local/convex implementations; integrate at invocation-time only.
425+3. Implement control handlers for sources (`add/list/remove`) and route both host API and `tools.executor.*` through same code path.
426+4. Implement cloudflare-worker-loader runtime dispatch adapter in v2 and wire Convex callback endpoints.
427+5. Add run API split for async + blocking convenience (`submit` + `wait/watch`) without duplicating execution logic.
428+6. Add conformance tests that run same scenarios across local and remote adapters.
429+
v2/apps/convex/convex/mcp.ts+7−1
@@ -1,9 +1,15 @@
11 import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";
2+import { createExecutorRunClient } from "@executor-v2/sdk";
23 import { httpAction } from "./_generated/server";
3−
4+const runClient = createExecutorRunClient(async () => ({
5+ runId: `run_${Date.now()}`,
6+ status: "failed" as const,
7+ error: "Convex run client is not wired yet",
8+}));
49 export const mcpHandler = httpAction(async (_ctx, request) =>
510 handleMcpHttpRequest(request, {
611 target: "remote",
712 serverName: "executor-v2-convex",
813 serverVersion: "0.0.0",
14+ runClient,
915 }));
v2/apps/convex/package.json+1−0
@@ -10,6 +10,7 @@ · 9 unmodified lines
1010 "dependencies": {
1111 "@executor-v2/mcp-gateway": "workspace:*",
1212 "@executor-v2/persistence-convex": "workspace:*",
13+ "@executor-v2/sdk": "workspace:*",
1314 "convex": "catalog:"
1415 }
1516 }
v2/apps/pm/README.md+8−1
@@ -6,4 +6,11 @@ Current scaffold includes: · 5 unmodified lines
66 - local MCP endpoint at `POST /mcp`
77 - health endpoint at `GET /healthz`
88 - MCP tool routing via `@executor-v2/mcp-gateway`
9−- `executor.execute` wired to engine runtime adapters (`local-inproc` default, `deno-subprocess` optional)
9+- local runtime adapter injection (`makeLocalInProcessRuntimeAdapter()` in entry wiring)
10+
11+App wiring is now split by responsibility:
12+- `src/config.ts`: Effect config service (`PORT`)
13+- `src/run-executor.ts`: run execution service for an injected runtime adapter
14+- `src/mcp-handler.ts`: MCP transport wiring to run client
15+- `src/http-server.ts`: Bun server startup
16+- `src/main.ts`: Layer composition + process entrypoint
v2/apps/pm/package.json+1−0
@@ -10,6 +10,7 @@ · 9 unmodified lines
1010 "dependencies": {
1111 "@executor-v2/engine": "workspace:*",
1212 "@executor-v2/mcp-gateway": "workspace:*",
13+ "@executor-v2/sdk": "workspace:*",
1314 "effect": "catalog:"
1415 }
1516 }
v2/apps/pm/src/config.ts+26−0
@@ -0,0 +1,26 @@
1+import * as Config from "effect/Config";
2+import * as Context from "effect/Context";
3+import * as Effect from "effect/Effect";
4+import * as Layer from "effect/Layer";
5+
6+export type PmConfigService = {
7+ port: number;
8+};
9+
10+export class PmConfig extends Context.Tag("@executor-v2/app-pm/PmConfig")<
11+ PmConfig,
12+ PmConfigService
13+>() {}
14+
15+export const PmConfigLive = Layer.effect(
16+ PmConfig,
17+ Effect.gen(function* () {
18+ const port = yield* Config.integer("PORT").pipe(
19+ Config.orElse(() => Config.succeed(8787)),
20+ );
21+
22+ return PmConfig.of({
23+ port,
24+ });
25+ }),
26+);
v2/apps/pm/src/http-server.ts+32−0
@@ -0,0 +1,32 @@
1+import * as Effect from "effect/Effect";
2+
3+import { PmConfig } from "./config";
4+import { PmMcpHandler } from "./mcp-handler";
5+
6+export const startPmHttpServer = Effect.fn("@executor-v2/app-pm/http.start")(function* () {
7+ const { port } = yield* PmConfig;
8+ const { handleMcp } = yield* PmMcpHandler;
9+
10+ const server = Bun.serve({
11+ port,
12+ routes: {
13+ "/healthz": {
14+ GET: () => Response.json({ ok: true, service: "pm" }, { status: 200 }),
15+ },
16+ "/mcp": {
17+ GET: handleMcp,
18+ POST: handleMcp,
19+ DELETE: handleMcp,
20+ },
21+ "/v1/mcp": {
22+ GET: handleMcp,
23+ POST: handleMcp,
24+ DELETE: handleMcp,
25+ },
26+ },
27+ });
28+
29+ yield* Effect.logInfo(`executor-v2 PM listening on http://127.0.0.1:${server.port}`);
30+
31+ return server;
32+});
v2/apps/pm/src/main.ts+21−91
@@ -1,97 +1,27 @@
1−import {
2− makeCloudflareWorkerLoaderRuntimeAdapter,
3− makeDenoSubprocessRuntimeAdapter,
4− makeLocalInProcessRuntimeAdapter,
5− makeRuntimeAdapterRegistry,
6− makeToolProviderRegistry,
7− ToolProviderRegistryService,
8−} from "@executor-v2/engine";
9−import {
10− handleMcpHttpRequest,
11− type ExecuteToolInput,
12− type ExecuteToolResult,
13−} from "@executor-v2/mcp-gateway";
14−import * as Effect from "effect/Effect";
15−import * as Either from "effect/Either";
16−
17−const port = Number(Bun.env.PORT ?? 8787);
18−
19−const runtimeRegistry = makeRuntimeAdapterRegistry([
20− makeLocalInProcessRuntimeAdapter(),
21− makeDenoSubprocessRuntimeAdapter(),
22− makeCloudflareWorkerLoaderRuntimeAdapter(),
23−]);
24−
25−const toolRegistry = makeToolProviderRegistry([]);
1+import { makeLocalInProcessRuntimeAdapter } from "@executor-v2/engine";
262
27−const errorToText = (error: unknown): string => {
28− if (error instanceof Error) {
29− return error.message;
30− }
31−
32− if (
33− typeof error === "object" &&
34− error !== null &&
35− "message" in error &&
36− typeof error.message === "string"
37− ) {
38− return error.message;
39− }
40−
41− return String(error);
42−};
43−
44−const executeTool = async (input: ExecuteToolInput): Promise<ExecuteToolResult> => {
45− const result = await Effect.runPromise(
46− Effect.either(
47− runtimeRegistry
48− .execute({
49− runtimeKind: input.runtimeKind ?? "local-inproc",
50− code: input.code,
51− tools: [],
52− })
53− .pipe(Effect.provideService(ToolProviderRegistryService, toolRegistry)),
54− ),
55− );
3+import * as Effect from "effect/Effect";
4+import * as Layer from "effect/Layer";
565
57− if (Either.isLeft(result)) {
58− return {
59− isError: true,
60− error: errorToText(result.left),
61− };
62− }
6+import { PmConfigLive } from "./config";
7+import { startPmHttpServer } from "./http-server";
8+import { PmMcpHandlerLive } from "./mcp-handler";
9+import {
10+ PmRunExecutorLive,
11+ PmToolProviderRegistryLive,
12+} from "./run-executor";
6313
64− return {
65− isError: false,
66− output: result.right,
67− };
68−};
14+const runtimeAdapter = makeLocalInProcessRuntimeAdapter();
15+const PmMcpDependenciesLive = Layer.merge(
16+ PmRunExecutorLive(runtimeAdapter),
17+ PmToolProviderRegistryLive,
18+);
6919
70−const handleMcp = async (request: Request): Promise<Response> =>
71− handleMcpHttpRequest(request, {
72− target: "local",
73− serverName: "executor-v2-pm",
74− serverVersion: "0.0.0",
75− execute: executeTool,
76− });
20+const PmAppLive = Layer.merge(
21+ PmConfigLive,
22+ PmMcpHandlerLive.pipe(Layer.provide(PmMcpDependenciesLive)),
23+);
7724
78−const server = Bun.serve({
79− port,
80− routes: {
81− "/healthz": {
82− GET: () => Response.json({ ok: true, service: "pm" }, { status: 200 }),
83− },
84− "/mcp": {
85− GET: handleMcp,
86− POST: handleMcp,
87− DELETE: handleMcp,
88− },
89− "/v1/mcp": {
90− GET: handleMcp,
91− POST: handleMcp,
92− DELETE: handleMcp,
93− },
94− },
95−});
25+const program = startPmHttpServer().pipe(Effect.provide(PmAppLive));
9626
97−console.log(`executor-v2 PM listening on http://127.0.0.1:${server.port}`);
27+await Effect.runPromise(program);
v2/apps/pm/src/mcp-handler.ts+43−0
@@ -0,0 +1,43 @@
1+import { ToolProviderRegistryService } from "@executor-v2/engine";
2+import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";
3+import { createExecutorRunClient } from "@executor-v2/sdk";
4+import * as Context from "effect/Context";
5+import * as Effect from "effect/Effect";
6+import * as Layer from "effect/Layer";
7+import * as Runtime from "effect/Runtime";
8+
9+import { PmRunExecutor } from "./run-executor";
10+
11+export type PmMcpHandlerService = {
12+ handleMcp: (request: Request) => Promise<Response>;
13+};
14+
15+export class PmMcpHandler extends Context.Tag("@executor-v2/app-pm/PmMcpHandler")<
16+ PmMcpHandler,
17+ PmMcpHandlerService
18+>() {}
19+
20+export const PmMcpHandlerLive = Layer.effect(
21+ PmMcpHandler,
22+ Effect.gen(function* () {
23+ const runExecutor = yield* PmRunExecutor;
24+ const runtime = yield* Effect.runtime<ToolProviderRegistryService>();
25+ const runPromise = Runtime.runPromise(runtime);
26+
27+ const runClient = createExecutorRunClient((input) =>
28+ runPromise(runExecutor.executeRun(input)),
29+ );
30+
31+ const handleMcp = (request: Request): Promise<Response> =>
32+ handleMcpHttpRequest(request, {
33+ target: "local",
34+ serverName: "executor-v2-pm",
35+ serverVersion: "0.0.0",
36+ runClient,
37+ });
38+
39+ return PmMcpHandler.of({
40+ handleMcp,
41+ });
42+ }),
43+);
v2/apps/pm/src/run-executor.ts+89−0
@@ -0,0 +1,89 @@
1+import {
2+ makeToolProviderRegistry,
3+ ToolProviderRegistryService,
4+ type RuntimeAdapter,
5+} from "@executor-v2/engine";
6+import type { ExecuteRunInput, ExecuteRunResult } from "@executor-v2/sdk";
7+import * as Context from "effect/Context";
8+import * as Effect from "effect/Effect";
9+import * as Layer from "effect/Layer";
10+
11+export type PmRunExecutorService = {
12+ executeRun: (
13+ input: ExecuteRunInput,
14+ ) => Effect.Effect<ExecuteRunResult, never, ToolProviderRegistryService>;
15+};
16+
17+export class PmRunExecutor extends Context.Tag("@executor-v2/app-pm/PmRunExecutor")<
18+ PmRunExecutor,
19+ PmRunExecutorService
20+>() {}
21+
22+const errorToText = (error: unknown): string => {
23+ if (error instanceof Error) {
24+ return error.message;
25+ }
26+
27+ if (
28+ typeof error === "object" &&
29+ error !== null &&
30+ "message" in error &&
31+ typeof error.message === "string"
32+ ) {
33+ return error.message;
34+ }
35+
36+ return String(error);
37+};
38+
39+const makeExecuteRun = (runtimeAdapter: RuntimeAdapter) =>
40+ Effect.fn("@executor-v2/app-pm/run-executor.executeRun")(function* (
41+ input: ExecuteRunInput,
42+ ) {
43+ const runId = `run_${crypto.randomUUID()}`;
44+
45+ const isAvailable = yield* runtimeAdapter.isAvailable();
46+ if (!isAvailable) {
47+ return {
48+ runId,
49+ status: "failed",
50+ error: `Runtime '${runtimeAdapter.kind}' is not available in this PM process.`,
51+ } satisfies ExecuteRunResult;
52+ }
53+
54+ return yield* runtimeAdapter
55+ .execute({
56+ code: input.code,
57+ timeoutMs: input.timeoutMs,
58+ tools: [],
59+ })
60+ .pipe(
61+ Effect.map(
62+ (result): ExecuteRunResult => ({
63+ runId,
64+ status: "completed",
65+ result,
66+ }),
67+ ),
68+ Effect.catchAll((error) =>
69+ Effect.succeed({
70+ runId,
71+ status: "failed",
72+ error: errorToText(error),
73+ } satisfies ExecuteRunResult),
74+ ),
75+ );
76+ });
77+
78+export const PmRunExecutorLive = (runtimeAdapter: RuntimeAdapter) =>
79+ Layer.succeed(
80+ PmRunExecutor,
81+ PmRunExecutor.of({
82+ executeRun: makeExecuteRun(runtimeAdapter),
83+ }),
84+ );
85+
86+export const PmToolProviderRegistryLive = Layer.succeed(
87+ ToolProviderRegistryService,
88+ makeToolProviderRegistry([]),
89+);
v2/bun.lock+7−0
@@ -19,6 +19,7 @@ · 18 unmodified lines
1919 "dependencies": {
2020 "@executor-v2/mcp-gateway": "workspace:*",
2121 "@executor-v2/persistence-convex": "workspace:*",
22+ "@executor-v2/sdk": "workspace:*",
2223 "convex": "catalog:",
2324 },
2425 },
@@ -27,6 +28,7 @@ · 2 unmodified lines
2728 "dependencies": {
2829 "@executor-v2/engine": "workspace:*",
2930 "@executor-v2/mcp-gateway": "workspace:*",
31+ "@executor-v2/sdk": "workspace:*",
3032 "effect": "catalog:",
3133 },
3234 },
@@ -35,6 +37,10 @@ · 2 unmodified lines
3537 },
3638 "packages/ai-sdk-adapter": {
3739 "name": "@executor-v2/ai-sdk-adapter",
40+ "dependencies": {
41+ "@executor-v2/sdk": "workspace:*",
42+ "zod": "^4.3.6",
43+ },
3844 },
3945 "packages/approvals": {
4046 "name": "@executor-v2/approvals",
@@ -76,6 +82,7 @@ · 35 unmodified lines
7682 "packages/mcp-gateway": {
7783 "name": "@executor-v2/mcp-gateway",
7884 "dependencies": {
85+ "@executor-v2/sdk": "workspace:*",
7986 "@modelcontextprotocol/sdk": "^1.26.0",
8087 "zod": "^4.3.6",
8188 },
v2/packages/ai-sdk-adapter/package.json+7−0
@@ -2,7 +2,14 @@ · 1 unmodified line
22 "name": "@executor-v2/ai-sdk-adapter",
33 "private": true,
44 "type": "module",
5+ "exports": {
6+ ".": "./src/index.ts"
7+ },
58 "scripts": {
69 "typecheck": "bunx tsc --noEmit -p tsconfig.json"
10+ },
11+ "dependencies": {
12+ "@executor-v2/sdk": "workspace:*",
13+ "zod": "^4.3.6"
714 }
815 }
v2/packages/ai-sdk-adapter/src/index.ts+51−1
@@ -1 +1,51 @@
1−export {};
1+import type {
2+ ExecuteRunInput,
3+ ExecuteRunResult,
4+ ExecutorRunClient,
5+} from "@executor-v2/sdk";
6+import { z } from "zod";
7+
8+export const ExecuteToolInputSchema = z.object({
9+ code: z.string(),
10+ timeoutMs: z.number().int().positive().optional(),
11+});
12+
13+export type ExecuteToolInput = z.infer<typeof ExecuteToolInputSchema>;
14+
15+export type ExecuteToolOutput = ExecuteRunResult;
16+
17+export type AiToolFactory<TTool, TInput, TOutput> = (definition: {
18+ description: string;
19+ inputSchema: z.ZodType<TInput>;
20+ execute: (input: TInput) => Promise<TOutput>;
21+}) => TTool;
22+
23+export type ToAiSdkToolsOptions<TTool> = {
24+ runClient: ExecutorRunClient;
25+ makeTool: AiToolFactory<TTool, ExecuteToolInput, ExecuteToolOutput>;
26+ defaults?: {
27+ timeoutMs?: number;
28+ };
29+};
30+const withDefaults = (
31+ input: ExecuteToolInput,
32+ defaults?: {
33+ timeoutMs?: number;
34+ },
35+): ExecuteRunInput => ({
36+ code: input.code,
37+ timeoutMs: input.timeoutMs ?? defaults?.timeoutMs,
38+});
39+
40+export const toAiSdkTools = <TTool>(
41+ options: ToAiSdkToolsOptions<TTool>,
42+): {
43+ execute: TTool;
44+} => ({
45+ execute: options.makeTool({
46+ description: "Execute JavaScript against configured Executor runtime",
47+ inputSchema: ExecuteToolInputSchema,
48+ execute: async (input) =>
49+ options.runClient.execute(withDefaults(input, options.defaults)),
50+ }),
51+});
v2/packages/mcp-gateway/package.json+1−0
@@ -9,6 +9,7 @@ · 8 unmodified lines
99 "typecheck": "bunx tsc --noEmit -p tsconfig.json"
1010 },
1111 "dependencies": {
12+ "@executor-v2/sdk": "workspace:*",
1213 "@modelcontextprotocol/sdk": "^1.26.0",
1314 "zod": "^4.3.6"
1415 }
v2/packages/mcp-gateway/src/index.ts+0−1
@@ -2,7 +2,6 @@ export { · 1 unmodified line
22 handleMcpHttpRequest,
33 type ExecuteToolInput,
44 type ExecuteToolResult,
5− type GatewayRuntimeKind,
65 type GatewayTarget,
76 type McpGatewayOptions,
87 } from "./server";
v2/packages/mcp-gateway/src/server.ts+28−24
@@ -1,17 +1,13 @@
1+import type { ExecuteRunResult, ExecutorRunClient } from "@executor-v2/sdk";
12 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
23 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
34 import { z } from "zod";
45
56 export type GatewayTarget = "local" | "remote";
67
7−export type GatewayRuntimeKind =
8− | "local-inproc"
9− | "deno-subprocess"
10− | "cloudflare-worker-loader";
11−
128 export type ExecuteToolInput = {
139 code: string;
14− runtimeKind?: GatewayRuntimeKind;
10+ timeoutMs?: number;
1511 };
1612
1713 export type ExecuteToolResult = {
@@ -20,11 +16,27 @@ export type ExecuteToolResult = { · 2 unmodified lines
2016 isError: boolean;
2117 };
2218
19+const toGatewayExecuteResult = (
20+ result: ExecuteRunResult,
21+): ExecuteToolResult => {
22+ if (result.status === "completed") {
23+ return {
24+ isError: false,
25+ output: result.result,
26+ };
27+ }
28+
29+ return {
30+ isError: true,
31+ error: result.error ?? `Run ${result.runId} ended with status ${result.status}`,
32+ };
33+};
34+
2335 export type McpGatewayOptions = {
2436 target: GatewayTarget;
2537 serverName?: string;
2638 serverVersion?: string;
27− execute?: (input: ExecuteToolInput) => Promise<ExecuteToolResult>;
39+ runClient: ExecutorRunClient;
2840 };
2941
3042 const DEFAULT_SERVER_NAME = "executor-v2";
@@ -38,9 +50,7 @@ const PingToolInput = z.object({ · 7 unmodified lines
3850
3951 const ExecuteToolInputSchema = z.object({
4052 code: z.string(),
41− runtimeKind: z
42− .enum(["local-inproc", "deno-subprocess", "cloudflare-worker-loader"])
43− .optional(),
53+ timeoutMs: z.number().int().positive().optional(),
4454 });
4555
4656 const contentText = (value: unknown): string => {
@@ -87,24 +97,18 @@ const createStubMcpServer = (options: McpGatewayOptions): McpServer => { · 40 unmodified lines
8797 mcp.registerTool(
8898 EXECUTE_TOOL_NAME,
8999 {
90− description: "Execute JavaScript against configured runtime adapter",
100+ description: "Execute JavaScript against configured runtime",
91101 inputSchema: ExecuteToolInputSchema,
92102 },
93103 async (input: ExecuteToolInput) => {
94− if (!options.execute) {
95− return {
96− content: [
97− {
98− type: "text" as const,
99− text: "executor.execute is not configured for this gateway target",
100− },
101− ],
102− isError: true,
103− };
104− }
105−
106104 try {
107− const result = await options.execute(input);
105+ const result = toGatewayExecuteResult(
106+ await options.runClient.execute({
107+ code: input.code,
108+ timeoutMs: input.timeoutMs,
109+ }),
110+ );
111+
108112 return {
109113 content: [
110114 {
v2/packages/sdk/package.json+3−0
@@ -2,6 +2,9 @@ · 1 unmodified line
22 "name": "@executor-v2/sdk",
33 "private": true,
44 "type": "module",
5+ "exports": {
6+ ".": "./src/index.ts"
7+ },
58 "scripts": {
69 "typecheck": "bunx tsc --noEmit -p tsconfig.json"
710 }
v2/packages/sdk/src/index.ts+70−1
@@ -1 +1,70 @@
1−export {};
1+export type RunTerminalStatus =
2+ | "completed"
3+ | "failed"
4+ | "timed_out"
5+ | "denied";
6+
7+export type ExecuteRunInput = {
8+ code: string;
9+ timeoutMs?: number;
10+};
11+
12+export type ExecuteRunResult = {
13+ runId: string;
14+ status: RunTerminalStatus;
15+ result?: unknown;
16+ error?: string;
17+ exitCode?: number;
18+ durationMs?: number;
19+};
20+
21+export interface ExecutorRunClient {
22+ execute(input: ExecuteRunInput): Promise<ExecuteRunResult>;
23+}
24+
25+export type RuntimeToolCallRequest = {
26+ runId: string;
27+ callId: string;
28+ toolPath: string;
29+ input?: Record<string, unknown>;
30+};
31+
32+export type RuntimeToolCallResult =
33+ | {
34+ ok: true;
35+ value: unknown;
36+ }
37+ | {
38+ ok: false;
39+ kind: "pending";
40+ approvalId: string;
41+ retryAfterMs: number;
42+ error?: string;
43+ }
44+ | {
45+ ok: false;
46+ kind: "denied";
47+ error: string;
48+ }
49+ | {
50+ ok: false;
51+ kind: "failed";
52+ error: string;
53+ };
54+
55+export interface RuntimeToolCallHandler {
56+ handleToolCall(input: RuntimeToolCallRequest): Promise<RuntimeToolCallResult>;
57+}
58+
59+export type ExecutorServer = {
60+ runClient: ExecutorRunClient;
61+ toolCallHandler: RuntimeToolCallHandler;
62+};
63+
64+export const createExecutorRunClient = (
65+ execute: ExecutorRunClient["execute"],
66+): ExecutorRunClient => ({
67+ execute,
68+});
69+
70+

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t