paperclip/doc/connections/TASK-REVIEWS.md

Connection reviews in task history

An agent call governed by Ask human / Ask first creates a server-owned request_confirmation.payload.toolAction interaction linked to the existing tool_action_requests record. No provider call runs while this review is pending. The default approval lifetime remains one hour.

The task feed keeps one record for each review. Review request opens the composer takeover. Dismissing the takeover only hides it; the review remains pending, ordinary comments do not supersede it, and the agent is not resumed. Multiple reviews retain separate records and the existing takeover navigation. The card shows the app icon and a short request description. Destructive actions retain destructive approval styling. Audit metadata and signed arguments remain on the underlying review record.

Approve & run executes the signed, stored arguments once. Decline executes nothing in one click. Both the task and Connections queue use one decision transaction; a decision removes the pending queue item while its history remains on the task. The human decision, resolver, remembered permission, and execution outcome remain separate. Provider failure does not turn an approved decision into a decline. Successful results stay collapsed behind the status chevron; expanding it shows formatted JSON (or plain text). The resumed agent processes the recorded result in a new turn and writes the user-facing answer. Live activity invalidation refreshes both surfaces, with existing polling/reconnect reconciliation retained.

Remembered permission

Choose Always allow from the split button beside Approve & run. It atomically saves approval and an action-wide trust rule for the same agent, connection, and action, restricted to the originating project when one exists. Future argument values may differ. The menu item exposes the scope through its tooltip and accessible description; the receipt records the saved permission. If saving the rule fails, the approval transaction rolls back and no provider call runs.

The rule remains bound to the reviewed catalog definition/schema. Changed definitions require review again. Revocation, explicit denial, connection access, and formal approval requirements remain effective. Manage/revoke rules through the existing Connections trust-rule controls.

The accept/approve endpoints support optional rememberAction: true; omission continues to approve once. Trust-rule promotion supports argumentMode: "action"; its existing omitted/"exact" mode continues to bind exact argument values.

Governed waiting and recovery

The gateway returns approval_required with the linked request/interaction IDs and instructions to finish unrelated work, then yield in_review without retrying or claiming completion. Agent task completion is rejected while a linked action is pending, approved, or executing. Provider execution is server-owned.

tool_action_deliveries is a durable, content-free outbox keyed by action request. It refers to the authoritative request, invocation, and interaction instead of copying provider data. Once the originating runs have ended and no other task interactions remain pending, ready outcomes are batched into one continuation wake. The wake includes the recorded result/decline and instructions not to repeat the operation. Native runners materialize validated server-owned interaction outcomes; legacy runners receive the wake context and agent message. Existing scheduler eligibility and budget gates still apply. Closed tasks retire receipts; reassignment does not deliver the old agent's outcome to another agent.

Startup and periodic sweeps recover committed approvals, undelivered outcomes, expiry, and incomplete feed projections. An execution left in progress for ten minutes is marked failed with tool_execution_outcome_unknown. Its external outcome is uncertain: inspect the provider before retrying. It is never automatically replayed. This grace period exceeds the current approved-call timeout.

Migration 0249 adds the outbox and a partial unique wake-idempotency index. The index is built transactionally; migration can briefly block wake-table writes while PostgreSQL scans an existing large table. No external payload is added to the outbox.

Verification workflows

Run the credential-free, isolated browser suite:

PAPERCLIP_E2E_PORT=3222 pnpm exec playwright test -c tests/e2e/connection-reviews.config.ts

This starts a dedicated embedded database/server and local MCP fixture, configures Ask first through the UI, and verifies approve, decline, remembered permission with changed arguments, dismissal/reopening, ordinary comments, cross-tab queue/task updates, provider failure, and restart while waiting. Assertions include useful agent results and provider invocation counts. Screenshots, JSON journey identifiers, and traces are attached to the Playwright HTML report. The deterministic agent is a scripted process adapter; these results do not prove model-runner behavior.

Run the opt-in, local model-runner matrix with the harness's normal credentials:

PAPERCLIP_RUNNER_E2E_CONNECTION_REVIEWS=1 pnpm test:e2e:runner -- --suite connection-reviews

The 16 cells cover approve, decline, always allow, and restart/resume for native Codex, native ACPX Claude, legacy Codex CLI, and legacy Claude CLI. Qualified model settings come from the existing runner catalog. This flag does not expand the normal hosted/Daytona matrix. The fixture MCP provider is real HTTP but is not Notion; live Notion evidence must be reported separately.

For a real Notion test, start paperclipai test-drive from this checkout using valid provider credentials, verify its process checkout/port ownership, connect Notion normally, set an available read-only search/list action to Ask human, and perform the same approve/decline/always-allow journeys for all four profiles. Capture request/run IDs, screenshots, traces, and actual page results. Missing credentials or account/provider access are untested dependencies, never a pass.

Storybook

pnpm --filter @paperclipai/ui exec storybook dev -p 6018 -c storybook/.storybook --no-open --ci

Open Chat & Comments / Connection Reviews. The production task thread/card and Connections queue cover pending, dismissed/reopened, multiple requests, each submitting action, recoverable errors, concurrent resolution, approved/executing, success/failure, decline with/without a reason, expiry/cancellation, remembered scope/receipt, approval options, narrow layout, and queue/empty states. The global theme toolbar switches light/dark. Story actions simulate server responses; use the browser suite for integration proof.

Provider output, execution errors, and review notes travel in the continuation's untrustedToolResults field, separate from its control instructions. Both native and legacy wake prompts render those fields as fenced JSON with an explicit untrusted-data boundary. Embedded provider instructions cannot grant permission or change the task's continuation policy. Wake materialization redacts secrets and bounds each text field before rendering.

A continuation includes at most eight shortened result records and caps the serialized wake context at 32 KB. It links to the task interaction API for all full outcomes and instructs the agent to retrieve omitted or incomplete results before finishing. A committed receipt cutoff preserves acknowledgement of that referenced set across restart, without putting an unbounded ID list in the wake. Task review queries reconcile every 20 seconds if a live event is missed.