diff --git a/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md b/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md index aeeff9c0b22..4bf88523917 100644 --- a/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md +++ b/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md @@ -74,6 +74,7 @@ The essential architectural choices are: 18. **The protocol is language-neutral and independently testable.** JSON Schema, fixtures, and conformance behavior are authoritative for Rust, TypeScript, and future implementations. 19. **MCP Apps are a negotiated interactive-UI extension, not generic tool text.** Paperclip preserves app resource declarations, capability negotiation, lifecycle, tool input/results, and auditable user actions so the browser can host supported apps in a sandbox without coupling PRP to iframe transport. 20. **Remote services have an explicit connector contract.** A managed runtime can either host a PRP-speaking Paperclip gateway or use a control-plane connector that implements the same normalized session semantics without running `paperclip-runnerd`. +21. **Normal provider operation is unattended until final human review.** After an operator supplies or approves the required provider account, workload identity, and secret/key bindings, Paperclip must create, invoke, observe, steer, reconcile, and clean up local and remote execution without dashboard clicks, SSH setup, copied commands, or other human runbook steps. This applies equally to Daytona, AWS AgentCore, Cursor, and future providers; infrastructure credentials enter through governed Paperclip bindings, not per-run manual intervention. The minimal vertical slice is: @@ -743,20 +744,20 @@ The first spike needs a fake remote backend that passes conformance tests. It do #### 7.2.1 Initial hosted-provider targets -As of 2026-08-07, qualification is sorted by Paperclip priority, then by platform name within a tier. It deliberately includes both general managed agent runtimes and opinionated coding-agent services because they exercise different parts of `NativeSessionBackend`: +As of 2026-08-07, the first two qualification and implementation targets are explicit: AWS AgentCore first, then Cursor Cloud Agents. The remaining entries are later comparison targets. The list deliberately includes both general managed agent runtimes and opinionated coding-agent services because they exercise different parts of `NativeSessionBackend`: | Order | Provider/platform | Documented runtime boundary | Invoke/observe/control surface | Initial disposition | | --- | --- | --- | --- | --- | | 0 | **AWS Bedrock AgentCore Runtime** | Provider-managed, versioned container runtime with isolated sessions, workload identity, network configuration, and separate control/data planes | `CreateAgentRuntime`/endpoint APIs; `InvokeAgentRuntime`; HTTP, SSE, persistent WebSocket, MCP, A2A, and AG-UI service contracts; asynchronous/long-running processing and session IDs | **Top qualification priority and preferred first managed-runtime connector.** Its explicit runtime contract, bidirectional streaming, identity, protocol, version, endpoint, and session boundaries are the strongest reference for shaping Paperclip's provider backend and credential model. | -| 1 | **Cloudflare Agents** | Durable Object-backed agent instances with durable identity, local SQLite state, WebSockets, scheduling, queues, and recoverable fibers | Worker deployment plus `routeAgentRequest`; HTTP/SSE, WebSocket, callable methods, state sync, and application-defined control methods | **Managed-runtime qualification target.** Excellent for real-time and durable execution experiments, but the connector must define a Paperclip-specific control API because the SDK is an application framework/runtime rather than a uniform hosted-task API. Its first-party Slack/email/voice/webhook support does not change the rule that Paperclip channel ingress remains core-owned. | -| 1 | **Google Vertex AI Agent Engine** | Managed runtime, exposed under the backwards-compatible `ReasoningEngine` resource, with deploy/scale, sessions, observability, and Google Cloud identity/security integration | deployed `query`, `stream_query`, custom operations, bidirectional streaming for supported agents, and session management APIs | **Managed-runtime qualification target.** Useful for testing custom operation discovery, session reconciliation, streaming, provider-native Secret Manager bindings, and the distinction between a deployed runtime resource and a Paperclip run. | -| 1 | **Microsoft Agent Framework + Foundry Hosted Agents** | Agent Framework is a framework/hosting library; Foundry Hosted Agents is the Microsoft-managed container runtime that owns scale, session persistence, identity, and lifecycle | OpenAI-compatible `/responses`, generic `/invocations`, A2A, AG-UI, durable Azure Functions/self-hosted extensions, and Foundry-managed sessions | **Managed-runtime qualification target, with the boundary kept explicit.** Self-hosted Agent Framework belongs under a local/provider driver; Foundry Hosted Agents belongs under `RemoteAgentBackend`. Do not treat the framework package itself as a cloud runtime. | -| 2 | **Cursor Cloud Agents** | Opinionated provider-managed coding environment/session | `POST /v0/agents`; status and conversation reads; webhooks; follow-up and stop operations | **First coding-agent implementation candidate** because it exposes a session-shaped API, follow-ups, stop, status, conversation, and webhook configuration. | -| 2 | **Devin v3** | Organization-scoped provider-managed coding session | create session; session detail; cursor-paginated messages with stable `event_id`; send message; terminate/archive/delete according to RBAC | **First coding-agent implementation candidate** because it has explicit organization scoping, service-user RBAC, stable message event IDs, cursor pagination, and lifecycle controls. | -| 3 | **GitHub Copilot cloud agent tasks** | Repository task delegated to GitHub-managed execution | `POST /agents/repos/{owner}/{repo}/tasks` or issue assignment; list/get documented task states; no general follow-up/cancel primitive in the reviewed task API | **Output-oriented candidate**, not the reference interactive backend. It is useful for asynchronous issue-to-PR delegation but exposes less session control. | -| 3 | **Google Jules v1alpha** | Connected-source coding session in a provider-managed environment | create session; poll and page activities; approve plan; send message; pull-request output | **Conformance/experimental candidate** because the API is alpha and currently documents polling rather than push delivery or cancellation. | +| 1 | **Cursor Cloud Agents** | Opinionated provider-managed coding environment/session | `POST /v0/agents`; status and conversation reads; webhooks; follow-up and stop operations | **Second qualification target and preferred first coding-agent connector.** It exposes a session-shaped API, follow-ups, stop, status, conversation, and webhook configuration, making it the first test of the same normalized backend against an opinionated coding service. | +| 2 | **Cloudflare Agents** | Durable Object-backed agent instances with durable identity, local SQLite state, WebSockets, scheduling, queues, and recoverable fibers | Worker deployment plus `routeAgentRequest`; HTTP/SSE, WebSocket, callable methods, state sync, and application-defined control methods | **Later managed-runtime comparison target.** Excellent for real-time and durable execution experiments, but the connector must define a Paperclip-specific control API because the SDK is an application framework/runtime rather than a uniform hosted-task API. Its first-party Slack/email/voice/webhook support does not change the rule that Paperclip channel ingress remains core-owned. | +| 2 | **Google Vertex AI Agent Engine** | Managed runtime, exposed under the backwards-compatible `ReasoningEngine` resource, with deploy/scale, sessions, observability, and Google Cloud identity/security integration | deployed `query`, `stream_query`, custom operations, bidirectional streaming for supported agents, and session management APIs | **Later managed-runtime comparison target.** Useful for testing custom operation discovery, session reconciliation, streaming, provider-native Secret Manager bindings, and the distinction between a deployed runtime resource and a Paperclip run. | +| 2 | **Microsoft Agent Framework + Foundry Hosted Agents** | Agent Framework is a framework/hosting library; Foundry Hosted Agents is the Microsoft-managed container runtime that owns scale, session persistence, identity, and lifecycle | OpenAI-compatible `/responses`, generic `/invocations`, A2A, AG-UI, durable Azure Functions/self-hosted extensions, and Foundry-managed sessions | **Later managed-runtime comparison target, with the boundary kept explicit.** Self-hosted Agent Framework belongs under a local/provider driver; Foundry Hosted Agents belongs under `RemoteAgentBackend`. Do not treat the framework package itself as a cloud runtime. | +| 3 | **Devin v3** | Organization-scoped provider-managed coding session | create session; session detail; cursor-paginated messages with stable `event_id`; send message; terminate/archive/delete according to RBAC | **Later coding-agent comparison target** because it has explicit organization scoping, service-user RBAC, stable message event IDs, cursor pagination, and lifecycle controls. | +| 4 | **GitHub Copilot cloud agent tasks** | Repository task delegated to GitHub-managed execution | `POST /agents/repos/{owner}/{repo}/tasks` or issue assignment; list/get documented task states; no general follow-up/cancel primitive in the reviewed task API | **Output-oriented candidate**, not the reference interactive backend. It is useful for asynchronous issue-to-PR delegation but exposes less session control. | +| 4 | **Google Jules v1alpha** | Connected-source coding session in a provider-managed environment | create session; poll and page activities; approve plan; send message; pull-request output | **Conformance/experimental candidate** because the API is alpha and currently documents polling rather than push delivery or cancellation. | -The first production investigation should therefore be AWS AgentCore, even if Cursor or Devin remains the fastest first coding-agent connector. AgentCore should shape the managed-runtime conformance profile: create/version endpoint, invoke/stream, stable session identity, reconcile after Paperclip restart, provider-native identity and secrets, async work, cancellation semantics, and explicit protocol capabilities. +The first production investigation and connector attempt should therefore be AWS AgentCore. Cursor Cloud Agents should be second and should be the first opinionated coding-agent connector attempted. AgentCore should shape the managed-runtime conformance profile: create/version endpoint, invoke/stream, stable session identity, reconcile after Paperclip restart, provider-native identity and secrets, async work, cancellation semantics, and explicit protocol capabilities. Products are not initial `RemoteAgentBackend` targets when they lack a public hosted-task API even if they have a cloud UI. In particular, the Codex SDK and Claude Agent SDK are harness/runtime integrations that Paperclip can run in an environment it controls; they must not be described as hosted-provider connectors unless a separate public cloud-task API supplies create, observe, control, and reconciliation primitives. @@ -4153,7 +4154,7 @@ packages/paperclip-runner/backends/provider-conformance/ - fake-provider fixtures for polling, webhook duplication, cursor gaps, ambiguous cancellation, and provider retention expiry; - AWS AgentCore qualification spike covering runtime creation/versioning, endpoint invocation, HTTP/SSE/WebSocket behavior, session identity, async work, identity/secret binding, restart reconciliation, and cancellation gaps; - first managed-runtime connector targeting AWS AgentCore unless access validation identifies a concrete blocker; -- optional first coding-agent connector choosing Cursor or Devin after credential/access validation; +- second connector attempt targeting Cursor Cloud Agents after credential/access validation; - reconciliation and terminal-state mapping report; - explicit Paperclip-managed versus provider-managed execution ownership tests.