diff --git a/maps/agent-access-map/README.md b/maps/agent-access-map/README.md index 9b6c576b9fd..e5d633077ff 100644 --- a/maps/agent-access-map/README.md +++ b/maps/agent-access-map/README.md @@ -53,12 +53,19 @@ REST operations use the same route authorization as legacy agent REST. Dedicated tools remain optional for those operations; protocol endpoints still need their existing clients. Board-only routes remain restricted for agent identity. -Native `search_api` / `call_api` requires operator rollout admission, a running +Native `search_api` / `call_api` is enabled by default, but explicit server, +company-allowlist and binding settings can narrow admission. It requires a running authorized native run, current task assignment and execution-run binding, company and budget authority, task privacy, and a permitted work mode. Ask and Plan retain mutation restrictions, and runs retain their admitted JWT scope during restart recovery even when task mode changes. A waiting agent does not gain independent native control just because a REST route exists. +Connection-management reads support Standard, Ask and Plan; mutations require +Standard. Skill-test runs and nonstandard task-bridge keys cannot administer +connections. These gates supplement each operation's grants, resolved resource +and target scope, and responsible-user authority. See the +[rollout policy](../../server/src/services/native-runtime/runner-api-rollout.ts) +and [connection authorization](../../server/src/services/connection-management.ts). Credential-bearing replies, including company exports and their legacy alias, stay inline under a 10 MiB limit and use encrypted mutation receipts. Other saved diff --git a/maps/agent-access-map/app-permissions.md b/maps/agent-access-map/app-permissions.md index 716fbb8a8c7..25258dcac9b 100644 --- a/maps/agent-access-map/app-permissions.md +++ b/maps/agent-access-map/app-permissions.md @@ -4,6 +4,13 @@ Product map: [app-permissions](../feature-map/app-permissions.md). Feature ID: `app-permissions`. +Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport). +Explicitly requested policy administration may target the acting agent when its +management grants, resolved resources and responsible-user authority permit it. +A denied tool call does not authorize silently relaxing policy. Governed-action +self-approval and editing one's own principal permissions remain prohibited; +see [shared guidance](../../packages/shared/src/connection-intent-guidance.ts). + Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737). Connection operations reviewed in this working tree. The inventory was reconciled diff --git a/maps/agent-access-map/chat-channels.md b/maps/agent-access-map/chat-channels.md index 458fe3745f4..fda30a0e5fb 100644 --- a/maps/agent-access-map/chat-channels.md +++ b/maps/agent-access-map/chat-channels.md @@ -4,6 +4,8 @@ Product map: [chat-channels](../feature-map/chat-channels.md). Feature ID: `chat-channels`. +Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport). + Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737). Connection operations reviewed in this working tree. The inventory was reconciled @@ -175,7 +177,7 @@ Gaps: This individual operation has source review but no recorded HTTP verificat ### `post-chat-endpoints-github-registration` API: `present` — `POST /api/chat-endpoints/{endpointId}/github/registration`; JSON REST. -Agent access: `available` — agent REST and default native `search_api` / `call_api`. +Agent access: `available` — agent REST and admitted native `search_api` / `call_api` return the saved `requiredUserAction` for human App registration and consent. Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user. Evidence: `verified` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above. [Authenticated fixtures](../../server/src/__tests__/connection-management.integration.test.ts) passed with database persistence and actual bearer/session middleware. Verification: `passed` — deterministic provider fixtures / local assembled server; no live provider qualification. @@ -202,7 +204,7 @@ Gaps: This individual operation has source review but no recorded HTTP verificat ### `post-chat-endpoints-github-setup` API: `present` — `POST /api/chat-endpoints/{endpointId}/github/setup`; JSON REST. -Agent access: `available` — agent REST and default native `search_api` / `call_api`. +Agent access: `available` — agent REST and admitted native `search_api` / `call_api` advance saved setup. Install and identity steps return `requiredUserAction` for the addressed human. Registration returns `state: "create"` without that handoff; use [the registration operation](#post-chat-endpoints-github-registration) to obtain the saved human setup link. Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user. Evidence: `source-only` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above. Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial. @@ -510,9 +512,9 @@ Gaps: Fixture evidence does not qualify live provider behavior or an empirical m API: `present` — `GET /api/chat-endpoints/{endpointId}/conversations`; JSON REST. Agent access: `available` — agent REST and default native `search_api` / `call_api`. -Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user. +Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user. Every conversation row is filtered by current access to its linked task, in addition to endpoint access. Evidence: `source-only` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above. -Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial. +Verification: `not-run` — list conversations with an actual agent that can manage the endpoint but cannot read one linked private task; omit that conversation while retaining readable rows. Revoke endpoint authority and assert denial. Gaps: This individual operation has source review but no recorded HTTP verification. Provider availability and live setup remain unqualified. ### `post-chat-endpoints-conversations-publications` @@ -845,9 +847,9 @@ Gaps: This individual operation has source review but no recorded HTTP verificat API: `present` — `GET /api/chat-endpoints/{endpointId}/test-status`; JSON REST. Agent access: `available` — agent REST and default native `search_api` / `call_api`. -Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Resolved resources and every affected target are checked; personal ownership remains the responsible user. +Policy: `tools:manage_connections`; [shared management policy](../../doc/plans/2026-10-13-connection-api-parity.md#authorization-contract). Endpoint access remains required. The responsible human's linked external principals bound the result: only the earliest qualifying received timestamp since test start is returned, or null, with no message body. See [setup probes](../../server/src/services/chat-channels/setup-probes.ts). Evidence: `source-only` — [route](../../server/src/routes/chat-channels.ts); reviewed in the working tree based on the source commit above. -Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial. +Verification: `not-run` — check a permitted agent's responsible-human link, another user's received message, and no linked principal. Only the matching human's qualifying timestamp may appear; the other cases return null without content. Revoke endpoint access and assert denial. Gaps: This individual operation has source review but no recorded HTTP verification. Provider availability and live setup remain unqualified. ### `get-chat-endpoints-activity` diff --git a/maps/agent-access-map/connection-setup.md b/maps/agent-access-map/connection-setup.md index beb87d8923b..6e36a77f2c3 100644 --- a/maps/agent-access-map/connection-setup.md +++ b/maps/agent-access-map/connection-setup.md @@ -4,6 +4,8 @@ Product map: [connection-setup](../feature-map/connection-setup.md). Feature ID: `connection-setup`. +Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport). + Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737). Connection operations reviewed in this working tree. The inventory was reconciled @@ -247,9 +249,9 @@ Gaps: Agent invocation is denied by the stated policy. The authorized human or o API: `present` — `GET /api/tools/vercel-connect/callback`; browser/provider/MCP protocol. Agent access: `restricted` — browser authentication return. -Policy: Provider state/signature or gateway-token verification, company and resource binding; browser returns require the configuring human. Agent-issued durable gateway tokens retain both issuer and responsible-user authority. +Policy: Saved, unexpired Vercel OAuth state binds the company and connection to the addressed human or initiating actor/session. State is consumed once; expired, replayed and wrong-user returns fail. Personal grants require current active non-viewer company membership and retain the human creator. See [state validation](../../server/src/services/tool-access/oauth/state.ts) and [Vercel callback](../../server/src/services/tool-access/oauth/vercel-callback.ts). Evidence: `source-only` — [route](../../server/src/routes/tool-access.ts); reviewed in the working tree based on the source commit above. -Verification: `not-run` — individual operation not executed in this audit; shared authorization and representative family flows are exercised by the authenticated integration suite. Follow the route schema, inspect persistence/audit, and assert owner, scope and revoked-authority denial. +Verification: `not-run` — return as the addressed human, inspect the saved personal grant and creator, then reject wrong-user, expired, replayed and revoked-membership callbacks. This callback has source review, without live Vercel qualification. Gaps: Agent invocation is denied by the stated policy. The authorized human or operator must perform this step; this entry does not claim delegated execution. ### `get-tools-oauth-callback` diff --git a/maps/agent-access-map/gateways-profiles.md b/maps/agent-access-map/gateways-profiles.md index 6ecd81d18fc..a21b9a65dee 100644 --- a/maps/agent-access-map/gateways-profiles.md +++ b/maps/agent-access-map/gateways-profiles.md @@ -4,6 +4,8 @@ Product map: [gateways-profiles](../feature-map/gateways-profiles.md). Feature ID: `gateways-profiles`. +Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport). + Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737). Connection operations reviewed in this working tree. The inventory was reconciled diff --git a/maps/agent-access-map/runs-adapters.md b/maps/agent-access-map/runs-adapters.md index c0578bf5178..b4dd19ddae9 100644 --- a/maps/agent-access-map/runs-adapters.md +++ b/maps/agent-access-map/runs-adapters.md @@ -4,6 +4,8 @@ Product map: [runs-adapters](../feature-map/runs-adapters.md). Feature ID: `runs-adapters`. +Delegated native entries inherit the [native admission and work-mode limits](README.md#native-rest-transport). + Review date: 2026-10-26. Source base: `a1f77821b9cd5c9c846fdf7a0fa5cc620ad2b6bb`; implementation: [#17737](https://github.com/paperclipai/paperclip/pull/17737). Connection operations reviewed in this working tree. The inventory was reconciled @@ -37,8 +39,11 @@ API: `present` — representative operation IDs: Agent access: `partial` — Agent company-model REST / native `call_api` discovery and bound runtime context; instance adapter inventory remains board-only; model-account management is enumerated below. -Policy: Run/cost visibility and agent configuration policy; adapter installation/account -login/session control require board/admin. +Policy: Company model discovery requires company access; account-backed discovery +also enforces its account/pool and target-agent rules. Instance adapter inventory +and installation retain board/admin gates. Delegated managed +AI-account login operations are enumerated under `model-accounts`; they do not +grant raw host administration or execution-session reset. Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L6608) at the reviewed commit above. @@ -100,8 +105,9 @@ API: `present` — representative operation IDs: Agent access: `partial` — Permitted agent-creation validation through REST / native `call_api` / CLI; supported account-login initiation has the delegated path below. -Policy: Run/cost visibility and agent configuration policy; adapter installation/account -login/session control require board/admin. +Policy: Environment tests follow agent creation/configuration authority. Supported +managed-account login initiation follows `model-accounts` below; human codes and +consent, raw host login and adapter installation retain their specific gates. Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L6608) at the reviewed commit above. @@ -240,9 +246,10 @@ Policy: Same company, company-scope read authority and run/task visibility still apply. Task-bound history and recovery records require task read authority. Each run-linked task is filtered by the caller's task-read predicate; a readable company run cannot expose inaccessible private task titles. Existing content -and credential redaction apply. Adapter installation, account login, session -control, recovery writes and raw provider-trace administration retain their -existing board/admin or dedicated-tool gates. +and credential redaction apply. Adapter installation, raw host login, execution +session control, recovery writes and raw provider-trace administration retain +their board/admin or dedicated-tool gates. Delegated managed AI-account setup +is separately enumerated under `model-accounts`. Evidence: `source-only` — diagnostic scope reviewed at `f10210990a3c9cad1a4359318388f237de3169dd` in the @@ -276,8 +283,9 @@ API: `present` — representative operation IDs: Agent access: `restricted` — Board session controls; native server-owned session continuation. -Policy: Run/cost visibility and agent configuration policy; adapter installation/account -login/session control require board/admin. +Policy: Task-session listing and execution-context reset require board agent +management at their HTTP routes. These controls are separate from delegated +managed AI-account authentication attempts under `model-accounts`. Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L6608) at the reviewed commit above. diff --git a/maps/feature-map/app-permissions.md b/maps/feature-map/app-permissions.md index 6404551a9c1..41da9f9496a 100644 --- a/maps/feature-map/app-permissions.md +++ b/maps/feature-map/app-permissions.md @@ -4,7 +4,7 @@ navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order # App access and action permissions -After connecting an app, an operator decides which agents may use it and whether each action is off, requires approval, or is allowed. Activity and action tests help verify the resulting access. +After connecting an app, an operator or authorized agent decides which agents may use it and whether each action is off, requires approval, or is allowed. Activity and action tests help verify the resulting access. Feature ID: `app-permissions`. @@ -30,6 +30,13 @@ Open an app at `/apps/:connectionId/permissions`; this is the default connected- Use the action test control in Permissions, then the connection’s Activity and available account/advanced controls. +### `delegated-permissions` + +Ask an agent to change access or action policy for a named connection through +the existing APIs. The responsible person's current authority, the agent's +management grants, resource scope and all affected targets bound the request. +An explicitly requested, authorized policy change may target that same agent. + ## Driving it Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Prepare a connection to a fixture or test provider, two agents, and a harmless action. Record provider and credential ownership. @@ -91,6 +98,21 @@ changed actions. [Unikraft regressions](../../server/src/__tests__/unikraft-conn cover classification, Off policies, revocation and stale contracts with fixture provider responses. +### `delegated-permissions` + +Automated: [production-authenticated integration](../../server/src/__tests__/connection-management.integration.test.ts) +covers actual key/JWT policy edits, retained targets, caller/target test policies, +human approval, scope and revocation using PostgreSQL and provider fixtures. + +Manual: Request a bounded access or policy change through an actual agent, reload +Permissions, and verify the saved audience, action choice and agent audit actor. +Include an explicitly requested self-targeted policy edit. Repeat with missing +management grants, an excluded target/resource, and Ask or Plan mode; writes +must be denied. A denied tool call must not cause an unsolicited policy relaxation. +An Ask-first action still requires the authorized human's decision; the agent +cannot approve its own governed action or edit its own principal permissions. +Verify caller and target policies both apply when testing as another agent. + ## Gotchas - Connected does not imply an agent has access or an action is allowed. diff --git a/maps/feature-map/chat-channels.md b/maps/feature-map/chat-channels.md index 4f182357314..d9d90e23599 100644 --- a/maps/feature-map/chat-channels.md +++ b/maps/feature-map/chat-channels.md @@ -181,6 +181,15 @@ covers these views, pending/failure/success, mobile, and light theme with simula provider responses. Verify actual credential validity and restored delivery separately against GitHub; a Storybook success does not establish live recovery. +For an agent-requested GitHub credential handoff, open the saved link as the +addressed human and verify it asks for exactly the requested fields and all/any +completion mode. A fresh App opens import; a configured App opens replacement +through reconnect and retains credentials omitted from the request. Interrupt +the response after a successful rotation, reload, and verify the saved rotation +resumes without replacing the key again. Wrong-user access, unchanged credentials +and missing verification must not complete the request. After OAuth, confirm the +addressed user's exact endpoint identity before expecting task continuation. + For GitHub, submit a disposable PR and verify the summary heading uses the bot's display name and the check remains **Paperclip Review**. For two separate bots on one PR, verify their App-scoped checks and comments remain independent. diff --git a/maps/feature-map/connection-setup.md b/maps/feature-map/connection-setup.md index 0b034823075..c7fdd91a0a6 100644 --- a/maps/feature-map/connection-setup.md +++ b/maps/feature-map/connection-setup.md @@ -74,6 +74,17 @@ or open `/apps/chat/connect`. Complete that provider's endpoint setup, then open its settings (`/apps/chat/:endpointId/settings`). Follow identity linking as the intended sender before messaging the agent externally. +### `delegated-configuration` + +Ask a standard agent to configure a disposable app or account from its assigned +task. The agent uses REST or admitted native `search_api` / `call_api`, reuses +saved accounts and drafts, and returns the exact saved setup link when human +authentication, consent, credential entry or identity confirmation is required. +Open that link as the addressed person. Personal ownership stays with that +person; audit attribution stays with the acting agent. Existing agents retain +their explicit grants and restrictions. See the [access companion](../agent-access-map/connection-setup.md) +and [native admission contract](../agent-access-map/README.md#native-rest-transport). + ## Driving it with Playwright and the Paperclip CLI Preconditions: follow the [baseline](./README.md#before-driving-a-journey). @@ -220,6 +231,35 @@ reply in the originating conversation. Inspect an unlinked sender's denial and the endpoint's pause behavior. Repeat independently for each provider at issue; Slack setup does not qualify Discord, Telegram, GitHub, email, or iMessage. +### `delegated-configuration` + +Automated: [agent-authenticated integration](../../server/src/__tests__/connection-management.integration.test.ts) +uses production agent creation, persistent keys, run JWTs, native tool bindings, +human sessions, PostgreSQL and deterministic provider fixtures. It covers saved +setup, ownership, attribution, scope, trust, work modes and revocation. The +[Google service picker tests](../../ui/src/features/connections/GoogleWorkspaceServices.test.tsx) +cover pending choices, consent precedence and failed grant loading with API mocks. +These are separate from live provider setup and model success. + +Manual: Have the agent perform authorized setup, then open its saved handoff as +the addressed person. Reload before completing the required human step; verify +the same resource, saved access choices, human ownership and acting-agent audit +remain. Complete the step, verify the exact task continues, and confirm that +revoked authority or cancelled work prevents continuation. An ordinary bot-token +repair or an unchanged credential must not complete a signing-key request. + +For Google, request a specific service set, leave and reopen setup, and inspect +the addressed user's pending choices. Another user's or organization grant must +not supply those choices. A newer actual consent supersedes the saved request; +a token refresh does not. A failed grant read must not broaden the selection. +For Vercel personal setup, verify the selected credential belongs to the +responsible person and new bindings record the configuring human as creator. +Agent-initiated API changes retain the acting agent in audit; the human callback +retains its actual human actor. +Use the [chat endpoint recipe](chat-channels.md#endpoint-management) for GitHub +field-specific credential entry and saved rotation recovery, and the +[model-account recipe](runs-adapters.md#managed-account-setup) for AI sign-in. + ## Gotchas - For connecting an assistant to Paperclip itself, use [Assistant connections (MCP)](./assistant-connections.md). This recipe's MCP-link journey connects Paperclip to an external app server. @@ -260,18 +300,3 @@ admission at those boundaries. Verify a served deployment and provider settings, not only the catalog action count. Vercel preview requires an existing deployment; its provider makes the first deployment production, so an empty-project preview must fail before submission and explain the explicit production prerequisite. -### `delegated-configuration` - -A fresh standard agent can use the existing REST API and default native -`search_api` / `call_api` to perform requested configuration within its responsible -user's authority. Personal ownership stays with that user; audit attribution stays -with the acting agent. Existing agents retain their explicit grants and restrictions. -Human authentication and identity confirmation open the exact saved setup; local -host administration and action approval retain their own boundaries. See the -operation inventory in the companion and the [qualification record](../../doc/plans/2026-10-13-connection-api-parity.md). - -Automated: [agent-authenticated integration](../../server/src/__tests__/connection-management.integration.test.ts) -uses normal creation defaults, persistent agent keys, run JWTs, native tool bindings, -real database persistence, and deterministic provider fixtures. It separately checks -user/agent revocation, trust, company/ownership scope, work modes and attribution. -This is API reachability evidence, not a live provider setup or an LLM success rate. diff --git a/maps/feature-map/runs-adapters.md b/maps/feature-map/runs-adapters.md index 373fdb858fa..28d3c31f6d9 100644 --- a/maps/feature-map/runs-adapters.md +++ b/maps/feature-map/runs-adapters.md @@ -26,6 +26,13 @@ Agent access: [companion](../agent-access-map/runs-adapters.md). Open an agent’s model/adapter configuration or the instance adapter settings page when permitted. +### `managed-account-setup` + +Ask an authorized agent to save or connect a managed AI account. Open its saved +`aiLogin` setup link as the responsible human when sign-in or a code is required. +The agent can inspect the saved attempt and manage authorized account/pool +bindings; human authentication and raw host administration retain their gates. + ### `run-history` Open an agent run at `/agents/:agentId/runs/:runId` from the agent or task activity. @@ -50,6 +57,21 @@ turn; do not count a nested discovery interval twice. Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Record adapter, model, account, native/legacy runtime, and environment. Capabilities vary; one harness result is not a matrix-wide qualification. +### `managed-account-setup` + +Automated: [actual-auth connection integration](../../server/src/__tests__/connection-management.integration.test.ts) +exercises account/pool persistence, responsible-user ownership, agent attribution, +saved local-login access and native secret-response protection with provider fixtures. +[Saved handoff UI tests](../../ui/src/pages/apps/AppsConnect.test.tsx) +exercise setup routing with mocked APIs. Neither establishes live provider sign-in. + +Manual: Start delegated managed-account setup, reload the exact saved human +handoff, finish the required login, and inspect the saved account and original +task continuation. Bind the account or pool only to authorized agents, reload +their configuration, and verify the selected owner and account remain correct. +Reject a different user's saved attempt, revoked management authority and Ask/Plan +mutations. Qualify a useful model task separately from saving the account. + ### `session` For `runs-adapters/session`, complete a task in a disposable warm sandbox and